Module fog_crypto::lock

source ·
Expand description

Public-Key encryption.

This module lets you create a LockKey (a private key), which comes with a corresponding LockId (the public key). The LockId can be used to encrypt data and export keys, while the LockKey can decrypt those keys and data.

All LockKey structs are backed by some struct that implements the LockInterface trait; this can be an in-memory private key, an interface to an OS-managed keystore, an interface to a hardware security module, or something else.

Example


// Make a new temporary key
let key = LockKey::new();
let id = key.id().clone();

println!("LockId(Base58): {}", key.id());

// Encrypt some data with the public ID, then turn it into a byte vector
let data = b"I am sensitive information, about to be encrypted";
let lockbox = id.encrypt_data(data.as_ref());
let mut encoded = Vec::new();
encoded.extend_from_slice(lockbox.as_bytes());

// Decrypt that data with the private key
let dec_lockbox = DataLockboxRef::from_bytes(encoded.as_ref())?;
let dec_data = key.decrypt_data(&dec_lockbox)?;

Algorithms

The current (and only) algorithm for public-key encryption is X25519 for calculation of the shared secret. The private key is handled by a LockKey, while the public key is available as a LockId.

An ephemeral key pair is generated for each new lockbox, and the shared secret is calculated on encryption with the ephemeral private key and the LockId through Diffie-Hellman key exchange. On decryption, the ephemeral public key is recovered from the lockbox and is combined with the recipient’s LockKey.

In all cases, the 32-byte shared secret is directly used as the symmetric key in XChaCha20Poly1305.

Format

A LockId is encoded as a version byte followed by the contained public key, whose length may be dependant on the version. For X25519, it is 32 bytes (plus the version byte).

A LockKey is encoded as a version byte followed by the contained private key, whose length may be dependant on the version. For X25519, it is 32 bytes (plus the version byte). This encoding is only ever used for the payload of a LockLockbox.

For details on the lockbox formatting, see the submodule documentation.

Structs

  • BareLockKey
    A self-contained implementor of LockInterface. It’s expected this will be used unless the decryption key is being managed by the OS or a hardware module.
  • LockId
    An identifier for a corresponding LockKey that can be used to encrypt data for that key.
  • LockKey
    A key that allows decrypting data meant for a particular LockId.

Constants

Traits

  • LockInterface
    A decryption interface, implemented by anything that can hold a private cryptographic decryption key.

Functions