Module orion::auth

source ·
Available on crate feature safe_api only.
Expand description

Message authentication.

Use case:

orion::auth can be used to ensure message integrity and authenticity by using a secret key.

An example of this could be securing APIs by having a user of a given API sign their API request and having the API server verify these signed API requests.

About:

  • Uses BLAKE2b-256 in keyed mode.

Parameters:

  • secret_key: Secret key used to authenticate data.
  • data: Data to be authenticated.
  • expected: The expected authentication Tag.

Errors:

An error will be returned if:

  • The calculated Tag does not match the expected.
  • The SecretKey supplied is less than 32 bytes or greater than 64 bytes.
  • The expected Tag is not 32 bytes when verifying.

Panics:

A panic will occur if:

  • More than 2*(2^64-1) bytes of data are authenticated.

Security:

  • The secret key should always be generated using a CSPRNG. SecretKey::default() can be used for this; it will generate a SecretKey of 32 bytes.
  • The required minimum length for a SecretKey is 32 bytes.

Example:

use orion::auth;

// There exists a shared key between the user and API server
let key = auth::SecretKey::default();

// User generates message and authentication tag
let msg = "Some message.".as_bytes();
let expected_tag = auth::authenticate(&key, msg)?;

// API server verifies the authenticity of the message with the tag
assert!(auth::authenticate_verify(&expected_tag, &key, &msg).is_ok());

Re-exports

  • pub use crate::hazardous::mac::blake2b::Tag;

Structs

Functions