Crate coffio

Source
Expand description

§Supported use case

Coffio has been made to encrypt data of moderate size (less than 1/3 of the available memory) using a secret key.

§Unsupported use cases

Coffio cannot:

  • encrypt data using a password
  • handle files that cannot fit into 1/3 of the available memory
  • be used in a communication protocol
  • be used as a key exchange
  • etc.

§The IKM list

The encryption keys are automatically derived from a random seed called input key material (IKM). Because an IKM is bound to a specific encryption algorithm, is limited to a time period and can be revoked, Coffio requires a list of IKM, although the list could have only one.

Therefore, before encrypting data, you have to generate an IKM list. Most of the time, you might want to generate it outside of your application and handle it as you would handle a secret key.

§Features

The following features allows you to control which interfaces are exposed.

  • encryption (default): interfaces related to data encryption and decryption
  • ikm-management (default): interfaces related to the IKM list management
  • encrypt-at: add a function allowing to encrypt data using a specified timestamp

The following features allows you to control which encryption algorithms are activated.

Other features are:

  • benchmark: useful only to run the benchmark

§Examples

§Generating an IKM list.

use coffio::InputKeyMaterialList;

let mut ikml = InputKeyMaterialList::new();
let _ = ikml.add_ikm()?;
let ikml_str = ikml.export()?;

println!("Generated IKM list: {ikml_str}");

§Encrypting and decrypting data.

use coffio::{Coffio, DataContext, InputKeyMaterialList, KeyContext};

let ikml_raw = "ikml-v1:AQAAAA:AQAAAAEAAAC_vYEw1ujVG5i-CtoPYSzik_6xaAq59odjPm5ij01-e6zz4mUAAAAALJGBiwAAAAAA";
let ikm_list = InputKeyMaterialList::import(ikml_raw)?;
let my_key_ctx: KeyContext = [
    "db name",
    "table name",
    "column name",
].into();
let my_data_ctx: DataContext = [
    "694c721a-29e8-4793-b7a4-46a4a0bf1a70",
    "some username",
].into();
let data = b"Hello, World!";

let coffio = Coffio::new(&ikm_list);
let encrypted_data = coffio.encrypt(&my_key_ctx, &my_data_ctx, data)?;
let decrypted_data = coffio.decrypt(&my_key_ctx, &my_data_ctx, &encrypted_data)?;

assert_eq!(data, decrypted_data.as_slice());

Structs§

Coffio
Base structure used to encrypt and decrypt data.
DataContext
The context in which some data is encrypted.
InputKeyMaterial
An input key material (IKM) is a secret random seed that is used to derive cryptographic keys.
InputKeyMaterialList
A list of InputKeyMaterial (IKM). This is where you should manage your secrets.
KeyContext
The context in which a key is used.

Enums§

Error
An error type representing all the things that can go wrong.
Scheme
The cryptographic primitives used to encrypt the data.

Constants§

DEFAULT_IKM_DURATION
Default amount of time during which the input key material will be considered valid once it has been generated. This value is expressed in seconds.
DEFAULT_KEY_CTX_PERIODICITY
Default amount of time during which a key is valid. This is used for automatic periodic key rotation. This value is expressed in seconds.
DEFAULT_SCHEME
Default scheme used when adding a new IKM. The value is XChaCha20Poly1305WithBlake3 if the chacha feature is enabled, then Aes128GcmWithSha256 if the aes feature is enabled.

Type Aliases§

IkmId
Abstract type representing the identifier of an InputKeyMaterial.