Concepts Specifications API Downloads


Envelopes are used to encrypt and sign data. They are usually at the top of an encrypted tree.

Private box and message envelopes

An envelope for private data is a record with following structure:

    empty # content hash
    store URL # sender hash
encrypted key
  recipient hash 1
    RSA/OAEP(public key 1, AES key)
  recipient hash 2
    RSA/OAEP(public key 2, AES key)

The order of the nodes does not matter.

The content hash points to the content object or tree. The content can be retrieved from the sender's store.

Store URL and sender hash point to the public key of the sender. If the content is on the same store as the envelope, the store URL may be omitted. Envelopes on the sender's account may omit sender section altogether.

The AES key of the content object is RSA/OAEP encrypted for all recipients, and stored as unsigned big-endian integer. Recipient hashes are stored as byte sequences, and do not link the recipient's public key.

The signature is generated as follows:

Signature Private key ofsender Serialize Calculate hash Sign using RSA/PSS Object Hash Subrecord signedof envelope

The resulting RSA/PSS signature is stored as unsigned big-endian integer.

Note that the signature covers the content and the sender, but not the recipient list.

Public box envelopes

A public box envelope follows the same structure, but omits the encrypted key section, since the content is not encrypted. In addition, the sender is always the account holder, and can therefore be omitted:

    empty # content hash

The content hash points to the public card, and the account hash points to the public key of the account holder. Content and public key are always on the same store as the envelope.


An application may add hints to the signed section which may allow the recipient classify messages before retrieving their content.

Hints should be kept short, as message envelopes are limited to 16 kB.

Hints may be encrypted using the AES key provided by the envelope. For that, hints must use large CTR values to prevent colliding with the content object's AES encryption.