Concepts Specifications API Downloads
SpecificationsEnvelope

Envelope

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:

signed
  content
    empty # content hash
  sender
    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)
  …
signature
  signature

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:

signed
  content
    empty # content hash
signature
  signature

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.

Hinting

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.