Stores Actors Data Tree Downloads
Architecture Records Public keys Envelopes

Actors incomplete, should mention peers

Condensation is based on actor-message-passing. Actors can store private data, announce public data, and send messages to each other. Each actor holds a RSA 2048 key pair, and uses one or more stores.

A group of one or more actors representing the same user or service is a peer. Within the same peer, actors unconditionally share all data with each other.


Set of actors sharing all private data with each other, receiving messaging together

Implicit creation: every actor is a peer on its own, may team up with other actors

Implicit deletion: a peer disappears once the last of its actors disappears

Creating an actor

To create an actor, generate a RSA 2048 key pair.

Upload the public key

Optionally announce the public data

Associating a new actor to a peer

Association with another actor of the peer

Sending messages to each other, or through a third party (depending on application scenario)

Adding each others accounts to the public data

Removing an actor from a peer

Removing the accounts of the actor

Optionally add the accounts as "idle accounts" for a certain amount of time

Announcing public data

Storing private data

Sending a message

Discovering a peer

Recursively check the public cards of all actors associated with each other

Keep the newest card

Head actor = actor with the newest card

When changing the head actor, the new head actor must mention the old head actor among the accounts or idle accounts

Actor accounts on the public card

accounts: Active accounts belonging to this peer. Use these accounts to send messages, and check these accounts for more recent public data.

idle accounts: Idle accounts belonging to this peer. These accounts belong to the peer, but are not actively used at the moment, or not used any more. Do not send messages to these accounts (as they may not be read), and do not check these accounts for newer public data.

entrusted accounts: Accounts that this peer entrusts, such as the company's main account, or a backup account. Encrypt all messages for these accounts. Do not send messages to these accounts, as they do not belong to the peer. The public cards of these accounts belong to the respective actor, and not to the peer.


To take part in Condensation, a user generates a RSA 2048 key pair on his device. The private key is stored locally, and never leaves the device. The public key is serialized as record:

  public exponent, unsigned big-endian integer
  modulus, unsigned big-endian integer

and published on all stores. Its object hash is a unique identifier of this actor:

Actor hash ⇐ SHA-256 of Public key 0

If a user owns multiple devices, he/she repeats the above procedure to create one Condensation actor per device, and configures these actors to belong together.


An actor uses one or more Condensation stores. On each store, the actor uses the account corresponding to its actor hash. Actors belonging together may use different stores.

Each account may be used for storage, messaging, or both.

Storing private data

To store private data, an actor serializes and encrypts the data, and uploads it onto the store. It then links it to its private box through an envelope:

Envelope Private data(encrypted) public private in-queue content #d18a2f..b6signatures da1b0e..52 #5f3738..41encrypted keys 5f3738..41 db3635..54 2b0622..9a a58040..05 Account5f3738..41 d18a2f..b6

If the actor uses multiple stores for storage, data and envelope are uploaded onto all of them, and linked from all private boxes. The encryption key of the root object is encrypted for all actors of the user.

Once the data is stored, previous versions can be removed from the private boxes, and fused messages can be removed from the in-queue boxes.

Retrieving private data

To retrieve private data, an actor checks all private boxes of the user. For each (unique) box entry, it reads the envelope, verifies the signature, decrypts the AES key, and then decrypts the data.

If multiple versions of the data are available, the actor merges them into a single version, and optionally stores this new version.

Announcing public data

An actor announces a public card record – comparable to a business card – on its own public boxes:

Envelope Public card public private in-queue content #4e7841..d7signatures da1b0e..52 #5f3738..41 Account5f3738..41 revision 2015-11-12 22:57:31.000accounts #5f3738..41 #5f3738..41 #2b0622..9aname John Smithemail e 010001n 4b29a0..f4 e 010001n f1ef76..6b Public keys 5f3738..41 2b0622..9a 4e7841..d7

The public card lists the user's messaging accounts (in order of preference), and references its public keys. It may contain additional public information, such as the user's name, or a description of its services. The card is signed, but not encrypted.

Each card contains a revision timestamp. Only the newest card is valid.

If a user owns multiple devices, each actor publishes its own public card.

Collecting public data

To gather information about a peer, an actor checks all public boxes of the peer. For each public box, it reads the envelope, verifies the signature, and reads the public card.

Only the newest card of the peer is kept. If this card mentions new stores, the above procedure is repeated.

Sending a message

To send a message to a peer, an actor serializes and encrypts the message data, and uploads it onto one of its own messaging stores. By convention, the root object of a message is a record. It then creates and uploads an envelope addressed to all actors mentioned on the peer's public card, and signed using its own private key.

Finally, the actor posts a reference to the envelope (store URL, envelope hash) onto one of the peer's in-queue boxes, trying them in the order they appear on the peer's public card:

Envelope Message recordand data(encrypted) public private in-queue content #763cde..5fsignatures c8f1ea..19 #5f3738..41encrypted keys 6a1fcf..07 3c92f1..6c Account of peer 6a1fcf..07 763cde..5f On a messaging store of 5f3738..41

To prevent a message from being garbage-collected too soon, the actor should link it to its own private data for some time.

To send a message to multiple peers, the actor addresses the envelope to all actors mentioned on the public cards of all peers, and posts it onto one in-queue box of each peer. An actor may add itself as receiver.

To reply to a message, an actor may use the account from which he received the message, rather than the accounts indicated on the public card. This is particularly useful for messages that concern the actor rather than the peer.

Reading messages

An actor regularly checks the in-queue boxes of the user for new messages. For each (unique) entry, it reads the envelope, verifies the signature, decrypts the AES key, and then decrypts the message.

Once the actor has processed the message, it removes it from all in-queue boxes.