silk/hmac

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.

Portable HMAC authentication with SHA-256 and SHA-384.

When to use

Use HmacSha256 or HmacSha384 when a protocol requires a keyed authentication tag. Use silk.hkdf to derive keys from secret input material.

Details

Each actor supports make, incremental update, consuming finish, and one-shot authenticate. Inputs are borrowed. States use fixed storage and allocate no memory.

Gotchas

These actors compute tags but do not verify them or provide constant-time comparison. Secret state is not guaranteed to be erased. The SHA input limit includes the initial key pad.

Import as HmacSha256 with import silk.hmac { HmacSha256 }.

Public declarations: 2.

HmacSha256

pub struct HmacSha256

An incremental HMAC-SHA-256 state that returns a 32-byte authentication tag.

Details

The state owns fixed storage. finish consumes the state. Secret state is not guaranteed to be erased.

Associated function HmacSha256.make

pub fn make<'life0>(key: &'life0 [u8]) -> HmacSha256

Creates an HMAC-SHA-256 state from a borrowed key. An empty key is valid.

Details

Keys longer than 64 bytes are hashed before use. The state does not retain the input borrow.

Gotchas

If the key exceeds the SHA-256 64-bit bit-length domain, the program traps.

Method HmacSha256.update

pub fn update<'life0, 'life1>(self: &'life0 mut HmacSha256, bytes: &'life1 [u8]) -> ()

Adds borrowed bytes to the HMAC-SHA-256 message in order. An empty update has no effect.

Details

Any segmentation of the same message produces the same tag.

Gotchas

If the message plus the 64-byte key pad exceeds the 64-bit bit-length domain, the program traps.

Method HmacSha256.finish

pub fn finish(self: HmacSha256) -> Array<u8, 32>

Consumes the HMAC-SHA-256 state and returns its complete 32-byte authentication tag.

Associated function HmacSha256.authenticate

pub fn authenticate<'life0, 'life1>(key: &'life0 [u8], message: &'life1 [u8]) -> Array<u8, 32>

Returns the complete 32-byte HMAC-SHA-256 tag for a borrowed key and message.

Details

Empty keys and messages are valid. This operation computes a tag; it does not verify a received tag.

Gotchas

If the key exceeds the 64-bit bit-length domain, the program traps. If the message plus the 64-byte key pad exceeds that domain, the program traps.

HmacSha384

pub struct HmacSha384

An incremental HMAC-SHA-384 state that returns a 48-byte authentication tag.

Details

The state owns fixed storage. finish consumes the state. Secret state is not guaranteed to be erased.

Associated function HmacSha384.make

pub fn make<'life0>(key: &'life0 [u8]) -> HmacSha384

Creates an HMAC-SHA-384 state from a borrowed key. An empty key is valid.

Details

Keys longer than 128 bytes are hashed before use. The state does not retain the input borrow.

Gotchas

If the key exceeds the SHA-384 128-bit bit-length domain, the program traps.

Method HmacSha384.update

pub fn update<'life0, 'life1>(self: &'life0 mut HmacSha384, bytes: &'life1 [u8]) -> ()

Adds borrowed bytes to the HMAC-SHA-384 message in order. An empty update has no effect.

Details

Any segmentation of the same message produces the same tag.

Gotchas

If the message plus the 128-byte key pad exceeds the 128-bit bit-length domain, the program traps.

Method HmacSha384.finish

pub fn finish(self: HmacSha384) -> Array<u8, 48>

Consumes the HMAC-SHA-384 state and returns its complete 48-byte authentication tag.

Associated function HmacSha384.authenticate

pub fn authenticate<'life0, 'life1>(key: &'life0 [u8], message: &'life1 [u8]) -> Array<u8, 48>

Returns the complete 48-byte HMAC-SHA-384 tag for a borrowed key and message.

Details

Empty keys and messages are valid. This operation computes a tag; it does not verify a received tag.

Gotchas

If the key exceeds the 128-bit bit-length domain, the program traps. If the message plus the 128-byte key pad exceeds that domain, the program traps.