Module fog_crypto::lockbox

Encrypted data.

This submodule provides “lockboxes”, which are byte sequences holding encrypted information. There are 4 different types of lockboxes:

• IdentityLockbox: Stores an IdentityKey
• StreamLockbox: Stores a StreamKey
• LockLockbox: Stores a LockKey
• DataLockbox: Stores an arbitrary byte sequence

Each lockbox is encoded in a similar way. The lockbox type should be known when attempting to decode it, though if necessary it is also possible to determine the type through decoding (see determine_lockbox_type).

A lockbox is created with a specific LockId or StreamKey as the intended recipient. A DataLockbox can be created by calling the encrypt function on a StreamKey or LockId, while the others can be created by calling the appropriate “export” function on the key to be exported.

For decoding, each lockbox has a corresponding reference type, which will parse a byte slice and return a reference on success. These can be turned into their corresponding owned variants if needed, or can be used directly for decryption. These reference types are:

• IdentityLockboxRef
• StreamLockboxRef
• LockLockboxRef
• DataLockboxRef

Algorithms

The current (and only) algorithm is XChaCha20 with a Poly1305 AEAD construction. For StreamKey recipients, the secret XChaCha20 key is used for encryption. For LockId recipients, an ephemeral X25519 keypair is generated and DH key agreement is used to generate the key.

Lockbox Types

The different types of lockboxes each have 2 subtypes: one for LockId-recipient lockboxes, and one for StreamKey-recipient lockboxes. The encoded type byte is thus:

Type	Recipient	Byte Value
IdentityLockbox	LockId	0
IdentityLockbox	StreamId	1
StreamLockbox	LockId	2
StreamLockbox	StreamId	3
LockLockbox	LockId	4
LockLockbox	StreamId	5
DataLockbox	LockId	6
DataLockbox	StreamId	7

Alternately, the Type byte can be considered to have two bitfields: bit 0 encodes the recipient, and bits 2 & 1 encode the main lockbox type.

Format

The first lockbox format is for LockId-recipient lockboxes. It consists of the version byte, a byte set to the lockbox type, the encoded LockId, an ephemeral X25519 public key (without a version byte), a 24-byte nonce, the ciphertext, and the 16-byte Poly1305 authentication tag.

The second lockbox format is for StreamKey-recipient lockboxes. It consists of the version byte, a byte set to the lockbox type, the encoded StreamId, a 24-byte nonce, the ciphertext, and the 16-byte Poly1305 authentication tag.

+----------+----------+==========+==========+==========+==============+=====+
| Version  |   Type   | SignKey  |  EphKey  |  Nonce   |  Ciphertext  | Tag |
+----------+----------+==========+==========+==========+==============+=====+

+----------+----------+==========+==========+==============+=====+
| Version  |   Type   | StreamId |  Nonce   |  Ciphertext  | Tag |
+----------+----------+==========+==========+==============+=====+

- Version indicates what version of symmetric-key encryption was used for this lockbox.
- Type indicates the lockbox type and recipient type. If bit 0 is cleared, the first format
  (with SignKey & EphKey) is used. If bit 1 is set, the second format (with StreamId) is used.
- SignKey is a LockId. This is a version byte followed by the encoded public key.
- EphKey is a raw public key, of the same version as SignKey.
- StreamId is an identifier for the StreamKey that created the lockbox.
- Nonce is a random byte sequence matching the nonce length specified by the symmetric
  encryption version used.
- Ciphertext is the internal data, encrypted with the chosen algorithm.
- Tag is the authentication tag produced using the chosen algorithm.

In the AEAD construction, the additional data consists of every byte prior to the nonce.

Structs

• DataLockbox
  General encrypted data.
• DataLockboxRef
  General encrypted data.
• IdentityLockbox
  An encrypted IdentityKey.
• IdentityLockboxRef
  An encrypted IdentityKey.
• LockLockbox
  An encrypted LockKey.
• LockLockboxRef
  An reference to an encrypted LockKey.
• LockboxParts
  A lockbox byte stream, sliced into its component parts
• StreamLockbox
  An encrypted StreamKey.
• StreamLockboxRef
  An encrypted StreamKey.

Enums

• LockboxRecipient
  Lockboxes can be meant for one of two types of recipients: a LockId (public key), or a StreamId (symmetric key). The corresponding LockKey or StreamKey is needed for decryption of the lockbox.
• LockboxType
  Encodes the various types of lockboxes that may be decoded.

Functions

• data_lockbox_from_parts
  Directly take parts to construct a DataLockbox. Should only be used by implementors of the encrypt functions.
• determine_lockbox_type
  Determine what type of lockbox is in the encoded sequence. This only checks the first two bytes, and doesn’t guarantee the whole raw byte slice contains a valid encoded lockbox.
• identity_lockbox_from_parts
  Directly take parts to construct a IdentityLockbox. Should only be used by implementors of the encrypt functions.
• lock_lockbox_from_parts
  Directly take parts to construct a LockLockbox. Should only be used by implementors of the encrypt functions.
• stream_lockbox_from_parts
  Directly take parts to construct a StreamLockbox. Should only be used by implementors of the encrypt functions.