kryptos - v1.4.0

kryptos/aead

Authenticated Encryption with Associated Data (AEAD).

AEAD provides both confidentiality and integrity for data, with optional authenticated additional data (AAD) that is integrity-protected but not encrypted.

Example

import kryptos/aead
import kryptos/block
import kryptos/crypto

let assert Ok(cipher) = block.aes_256(crypto.random_bytes(32))
let ctx = aead.gcm(cipher)
let nonce = crypto.random_bytes(aead.nonce_size(ctx))
let assert Ok(#(ciphertext, tag)) = aead.seal(ctx, nonce:, plaintext: <<"secret":utf8>>)

Types

AeadContext

opaque </>

AEAD context with its configuration.

Use the provided constructor functions to create contexts:

  • gcm() / gcm_with_nonce_size() for AES-GCM
  • ccm() / ccm_with_sizes() for AES-CCM
  • chacha20_poly1305() for ChaCha20-Poly1305
  • xchacha20_poly1305() for XChaCha20-Poly1305
pub opaque type AeadContext

Values

ccm

</> 
pub fn ccm(cipher: block.BlockCipher) -> AeadContext

Creates an AES-CCM context with the given block cipher.

Uses standard parameters: 16-byte (128-bit) authentication tag and 13-byte (104-bit) nonce, which allows messages up to 64KB.

ccm_with_sizes

</> 
pub fn ccm_with_sizes(
  cipher: block.BlockCipher,
  nonce_size nonce_size: Int,
  tag_size tag_size: Int,
) -> Result(AeadContext, Nil)

Creates an AES-CCM context with custom nonce and tag sizes.

CCM allows flexible nonce and tag sizes per RFC 3610:

  • Nonce size affects maximum message length (larger nonce = smaller max message)
  • Tag size affects authentication strength (larger tag = stronger)

Nonce must be 7-13 bytes. Tag must be 4, 6, 8, 10, 12, 14, or 16 bytes.

chacha20_poly1305

</> 
pub fn chacha20_poly1305(
  key: BitArray,
) -> Result(AeadContext, Nil)

Creates a ChaCha20-Poly1305 AEAD context with the given key.

Uses standard parameters per RFC 8439: 12-byte (96-bit) nonce and 16-byte (128-bit) authentication tag. The key must be exactly 32 bytes.

gcm

</> 
pub fn gcm(cipher: block.BlockCipher) -> AeadContext

Creates an AES-GCM context with the given block cipher.

Uses standard parameters: 16-byte (128-bit) authentication tag and 12-byte (96-bit) nonce.

Note: This library only supports the full 16-byte authentication tag. Truncated tags (as permitted by NIST SP 800-38D) are not supported due to their reduced security guarantees.

gcm_with_nonce_size

</> 
pub fn gcm_with_nonce_size(
  cipher: block.BlockCipher,
  nonce_size: Int,
) -> Result(AeadContext, Nil)

Creates an AES-GCM context with a custom nonce size.

GCM supports variable nonce sizes, though 12 bytes is strongly recommended. This function is primarily useful for compatibility testing with test vectors.

nonce_size

</> 
pub fn nonce_size(ctx: AeadContext) -> Int

Returns the required nonce size in bytes for an AEAD context.

open

</> 
pub fn open(
  ctx: AeadContext,
  nonce nonce: BitArray,
  tag tag: BitArray,
  ciphertext ciphertext: BitArray,
) -> Result(BitArray, Nil)

Decrypts and verifies AEAD-encrypted data.

Example

import kryptos/aead
import kryptos/block
import kryptos/crypto

let assert Ok(cipher) = block.aes_256(crypto.random_bytes(32))
let ctx = aead.gcm(cipher)
let nonce = crypto.random_bytes(aead.nonce_size(ctx))
let assert Ok(#(ciphertext, tag)) = aead.seal(ctx, nonce:, plaintext: <<"secret":utf8>>)
let assert Ok(plaintext) = aead.open(ctx, nonce:, tag:, ciphertext:)

open_with_aad

</> 
pub fn open_with_aad(
  ctx: AeadContext,
  nonce nonce: BitArray,
  tag tag: BitArray,
  ciphertext ciphertext: BitArray,
  additional_data aad: BitArray,
) -> Result(BitArray, Nil)

Decrypts and verifies AEAD-encrypted data with additional authenticated data.

The AAD must match exactly what was provided during encryption.

Example

import kryptos/aead
import kryptos/block
import kryptos/crypto

let assert Ok(cipher) = block.aes_256(crypto.random_bytes(32))
let ctx = aead.gcm(cipher)
let nonce = crypto.random_bytes(aead.nonce_size(ctx))
let aad = <<"header":utf8>>
let assert Ok(#(ciphertext, tag)) =
  aead.seal_with_aad(ctx, nonce:, plaintext: <<"secret":utf8>>, additional_data: aad)
let assert Ok(plaintext) =
  aead.open_with_aad(ctx, nonce:, tag:, ciphertext:, additional_data: aad)

seal

</> 
pub fn seal(
  ctx: AeadContext,
  nonce nonce: BitArray,
  plaintext plaintext: BitArray,
) -> Result(#(BitArray, BitArray), Nil)

Encrypts and authenticates plaintext using AEAD.

The nonce must be exactly nonce_size bytes. Never reuse a nonce with the same key.

seal_with_aad

</> 
pub fn seal_with_aad(
  ctx: AeadContext,
  nonce nonce: BitArray,
  plaintext plaintext: BitArray,
  additional_data aad: BitArray,
) -> Result(#(BitArray, BitArray), Nil)

Encrypts and authenticates plaintext with additional authenticated data.

The AAD is authenticated but not encrypted. It can be used for headers, metadata, or context that should be tamper-proof but remain readable.

tag_size

</> 
pub fn tag_size(ctx: AeadContext) -> Int

Returns the authentication tag size in bytes for an AEAD context.

xchacha20_poly1305

</> 
pub fn xchacha20_poly1305(
  key: BitArray,
) -> Result(AeadContext, Nil)

Creates an XChaCha20-Poly1305 AEAD context with the given key.

Uses extended parameters: 24-byte (192-bit) nonce and 16-byte (128-bit) authentication tag. The extended nonce provides better collision resistance when generating random nonces. The key must be exactly 32 bytes.

✨ Search Document