Module fog_crypto::lockbox
source · [−]Expand description
Encrypted data.
This submodule provides “lockboxes”, which are byte sequences holding encrypted information. There are 4 different types of lockboxes:
IdentityLockbox
: Stores anIdentityKey
StreamLockbox
: Stores aStreamKey
LockLockbox
: Stores aLockKey
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:
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
General encrypted data.
General encrypted data.
An encrypted IdentityKey
.
An encrypted IdentityKey
.
An encrypted LockKey
.
An reference to an encrypted LockKey
.
A lockbox byte stream, sliced into its component parts
An encrypted StreamKey
.
An encrypted StreamKey
.
Enums
Encodes the various types of lockboxes that may be decoded.
Functions
Directly take parts to construct a DataLockbox
. Should only be used by implementors of the
encrypt
functions.
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.
Directly take parts to construct a IdentityLockbox
. Should only be used by implementors of the
encrypt
functions.
Directly take parts to construct a LockLockbox
. Should only be used by implementors of the
encrypt
functions.
Directly take parts to construct a StreamLockbox
. Should only be used by implementors of the
encrypt
functions.