Module dryoc::onetimeauth

source ·
Expand description

One-time authentication

OnetimeAuth implements libsodium’s one-time authentication, based on the Poly1305 message authentication code.

Use OnetimeAuth to authenticate messages when:

  • you want to exchange many small messages, such as in an online protocol
  • you can generate a unique key for each message you’re authenticating, i.e., using a key and a nonce

Do not reuse the same key for difference messages with OnetimeAuth, as it provides an opportunity for an attacker to discover the key.

Rustaceous API example, one-time interface

use dryoc::onetimeauth::*;
use dryoc::types::*;

// Generate a random key
let key = Key::gen();

// Compute the mac in one shot. Here we clone the key for the purpose of this
// example, but normally you would not do this as you never want to re-use a
// key.
let mac = OnetimeAuth::compute_to_vec(key.clone(), b"Data to authenticate");

// Verify the mac
OnetimeAuth::compute_and_verify(&mac, key, b"Data to authenticate").expect("verify failed");

Rustaceous API example, incremental interface

use dryoc::onetimeauth::*;
use dryoc::types::*;

// Generate a random key
let key = Key::gen();

// Initialize the MAC, clone the key (don't do this)
let mut mac = OnetimeAuth::new(key.clone());
mac.update(b"Multi-part");
mac.update(b"data");
let mac = mac.finalize_to_vec();

// Verify it's correct, clone the key (don't do this)
let mut verify_mac = OnetimeAuth::new(key.clone());
verify_mac.update(b"Multi-part");
verify_mac.update(b"data");
verify_mac.verify(&mac).expect("verify failed");

// Check that invalid data fails, consume the key
let mut verify_mac = OnetimeAuth::new(key);
verify_mac.update(b"Multi-part");
verify_mac.update(b"bad data");
verify_mac
    .verify(&mac)
    .expect_err("verify should have failed");

Modules

Structs

  • OnetimeAuth
    One-time authentication implementation based on Poly1305, compatible with libsodium’s crypto_onetimeauth_* functions.

Type Definitions

  • Key
    Stack-allocated key for one-time authentication.
  • Mac
    Stack-allocated message authentication code for one-time authentication.