Skip to content

Commit

Permalink
Update design_overview.md
Browse files Browse the repository at this point in the history
  • Loading branch information
balzack authored Mar 22, 2024
1 parent b47a4d8 commit 4188a09
Showing 1 changed file with 12 additions and 0 deletions.
12 changes: 12 additions & 0 deletions doc/design_overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,20 @@ The revision mechanism allows for the efficient synchronization for both new and

While the profile describes the account holder, the identity is determined by a public/private key. Regardless of what may be stored in the profile, a fingerprint of the public key uniquely identifies the account. At account creation time a key pair is generated which becomes the identity of the account for its lifetime. The private key never leaves the server and all signing of data happens within the server.

<div align="center">
<a href="#"><img src="/doc/overview_fig4.png" width="50%" style="border-radius:50%"></a>
</div>

The discovery of other contacts in the system is achieved through a signed profile message. When enabled the profile message can be accessed through a public endpoint on the node. One of the fields in the profile is the public key fingerprint so the receiving client and server can verify the integrity of the profile. When a new profile message is received at the node, a new card object is created with the profile contents for future reference.

## Access Tokens

Databag clients are used to access a subject’s account. When a client authenticates on behalf of the subject, a unique token is generated at the server and returned to the client. Internally this token is referred to as the agent token, and is included on all communication between the client and the account hosted on the subject’s node. Any account may have multiple clients actively connected.

<div align="center">
<a href="#"><img src="/doc/overview_fig5.png" width="50%" style="border-radius:50%"></a>
</div>

Connected contacts also have access to shared attributes and channels, but this is done through a different contact token. Contact connection is established through a mutual exchange of signed connect messages. The connect message contains the profile details, but also a token for incoming requests from that contact. The token is stored in the card for all future interactions with that contact.

## E2E Encryption
Expand All @@ -66,5 +74,9 @@ The E2E algorithm implemented in Databag follows the approach of web servers, wh

E2E encryption keys are generated within the client as a public/private key pair, referred to as the sealing key. The public key is published as part of the account profile and is thereby shared with all contacts in the system. The private key is encrypted with a key derived from a pbkdf2 function and stored within the account node. Other clients connecting to the same account can retrieve the encrypted key and restore the private key using the pbkdf2 function. Multiple clients for one account can then access the same E2E encrypted content.

<div align="center">
<a href="#"><img src="/doc/overview_fig6.png" width="60%" style="border-radius:50%"></a>
</div>

When using E2E encryption, each channel is independently encrypted. The channel object will contain a list of the symmetric key encrypted with the public key of each participating account. Each client can unwrap their copy of the symmetric key with the account sealing key and view the contents of the channel.

0 comments on commit 4188a09

Please sign in to comment.