silk/aes_gcm

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Detached AES-128-GCM and AES-256-GCM authenticated encryption.

When to use

Use AesGcm to encrypt with an explicit nonce and associated data. Use open to verify and decrypt.

Details

Operations borrow inputs and write separate caller-owned destinations. They allocate no memory and require no provider. Keys contain 16 or 32 bytes, nonces contain 12 bytes, and detached tags contain 16 bytes. Every failure leaves all destinations unchanged. Successful operations preserve an unused output suffix.

Gotchas

The caller must ensure nonce uniqueness for each key and enforce per-key usage limits. These operations do not implement TLS. Functional vectors do not prove side-channel resistance or production security. Secret copies are not guaranteed to be erased.

Import as AesGcm with import silk.aes_gcm { AesGcm }.

Public declarations: 2.

AesGcmError

pub union AesGcmError

A rejected AES-GCM operation that leaves all caller-owned destinations unchanged.

InvalidKeyLength

AesGcmError.InvalidKeyLength: AesGcmError

A key whose length is neither 16 nor 32 bytes.

InvalidNonceLength

AesGcmError.InvalidNonceLength: AesGcmError

A nonce whose length is not 12 bytes.

InvalidTagLength

AesGcmError.InvalidTagLength: AesGcmError

A tag input or destination whose length is not 16 bytes.

OutputTooSmall

AesGcmError.OutputTooSmall: AesGcmError

A destination shorter than the plaintext or ciphertext input.

LimitExceeded

AesGcmError.LimitExceeded: AesGcmError

A message or associated-data length beyond the GCM domain.

AuthenticationFailed

AesGcmError.AuthenticationFailed: AesGcmError

A tag that does not authenticate the key, nonce, associated data and ciphertext.

AesGcm

pub struct AesGcm

The owner of allocation-free AES-128/256-GCM seal and open operations.

Associated function AesGcm.seal

pub fn seal<'life0, 'life1, 'life2, 'life3, 'life4, 'life5>(key: &'life0 [u8], nonce: &'life1 [u8], aad: &'life2 [u8], plaintext: &'life3 [u8], ciphertext: &'life4 mut [u8], tag: &'life5 mut [u8]) -> silk/result.Result<(), silk/aes_gcm.AesGcmError>

Encrypts plaintext and writes its detached authentication tag, or leaves both destinations unchanged.

Details

Keys contain 16 or 32 bytes, nonces contain 12 bytes, and the tag destination contains exactly 16 bytes. The ciphertext destination must hold the plaintext. An unused suffix remains unchanged. Plaintext is limited to 2^36−32 bytes and AAD to 2^61−1 bytes, also bounded by target addressability. Invalid widths, short output and excess lengths return distinct AesGcmError variants before any write. Inputs and exclusive destinations must not alias. No input is retained and no allocator or provider is required.

Gotchas

The caller must use a unique nonce for each encryption under one key and enforce per-key usage limits. The operation does not generate a nonce or guarantee physical erasure of secret copies.

Associated function AesGcm.open

pub fn open<'life0, 'life1, 'life2, 'life3, 'life4, 'life5>(key: &'life0 [u8], nonce: &'life1 [u8], aad: &'life2 [u8], ciphertext: &'life3 [u8], tag: &'life4 [u8], plaintext: &'life5 mut [u8]) -> silk/result.Result<(), silk/aes_gcm.AesGcmError>

Verifies a detached tag before writing plaintext, or leaves the whole destination unchanged.

Details

Keys contain 16 or 32 bytes, nonces contain 12 bytes, and tags contain exactly 16 bytes. The plaintext destination must hold the ciphertext. An unused suffix remains unchanged. Ciphertext is limited to 2^36−32 bytes and AAD to 2^61−1 bytes, also bounded by target addressability. Invalid widths, short output and excess lengths return distinct AesGcmError variants before any write. A wrong tag returns AuthenticationFailed without publishing plaintext. All 16 tag bytes participate in comparison. Inputs and the exclusive destination must not alias. No input is retained and no allocator or provider is required.

Gotchas

Authentication does not detect replay or establish peer identity. The caller owns nonce and per-key usage policy. Secret copies are not guaranteed to be erased.