1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
//! # Secret-key message authentication
//!
//! [`Auth`] implements libsodium's secret-key authentication, based on
//! HMAC-SHA512-256.
//!
//! Use [`Auth`] to authenticate messages when:
//!
//! * you want to authenticate arbitrary messages
//! * you have a pre-shared key between both parties
//! * (optionally) you want to share the authentication tag publicly
//!
//! # Rustaceous API example, one-time interface
//!
//! ```
//! use dryoc::auth::*;
//! 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 = Auth::compute_to_vec(key.clone(), b"Data to authenticate");
//!
//! // Verify the mac
//! Auth::compute_and_verify(&mac, key, b"Data to authenticate").expect("verify failed");
//! ```
//!
//! # Rustaceous API example, incremental interface
//!
//! ```
//! use dryoc::auth::*;
//! use dryoc::types::*;
//!
//! // Generate a random key
//! let key = Key::gen();
//!
//! // Initialize the MAC, clone the key (don't do this)
//! let mut mac = Auth::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 = Auth::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 = Auth::new(key);
//! verify_mac.update(b"Multi-part");
//! verify_mac.update(b"bad data");
//! verify_mac
//! .verify(&mac)
//! .expect_err("verify should have failed");
//! ```
use subtle::ConstantTimeEq;
use crate::classic::crypto_auth::{
crypto_auth, crypto_auth_final, crypto_auth_init, crypto_auth_update, crypto_auth_verify,
AuthState,
};
use crate::constants::{CRYPTO_AUTH_BYTES, CRYPTO_AUTH_KEYBYTES};
use crate::error::Error;
use crate::types::*;
/// Stack-allocated key for secret-key authentication.
pub type Key = StackByteArray<CRYPTO_AUTH_KEYBYTES>;
/// Stack-allocated message authentication code for secret-key authentication.
pub type Mac = StackByteArray<CRYPTO_AUTH_BYTES>;
#[cfg(any(feature = "nightly", all(doc, not(doctest))))]
#[cfg_attr(all(feature = "nightly", doc), doc(cfg(feature = "nightly")))]
pub mod protected {
//! # Protected memory type aliases for [`Auth`]
//!
//! This mod provides re-exports of type aliases for protected memory usage
//! with [`Auth`]. These type aliases are provided for
//! convenience.
//!
//! ## Example
//!
//! ```
//! use dryoc::auth::protected::*;
//! use dryoc::auth::Auth;
//!
//! // Create a randomly generated key, lock it, protect it as read-only
//! let key = Key::gen_readonly_locked().expect("gen failed");
//! let input =
//! HeapBytes::from_slice_into_readonly_locked(b"super secret input").expect("input failed");
//! // Compute the message authentication code, consuming the key.
//! let mac: Locked<Mac> = Auth::compute(key, &input);
//! ```
use super::*;
pub use crate::protected::*;
/// Heap-allocated, page-aligned secret key for the generic hash algorithm,
/// for use with protected memory.
pub type Key = HeapByteArray<CRYPTO_AUTH_KEYBYTES>;
/// Heap-allocated, page-aligned hash output for the generic hash algorithm,
/// for use with protected memory.
pub type Mac = HeapByteArray<CRYPTO_AUTH_BYTES>;
}
/// secret-key authentication implementation based on Poly1305, compatible with
/// libsodium's `crypto_Auth_*` functions.
pub struct Auth {
state: AuthState,
}
impl Auth {
/// Single-part interface for [`Auth`]. Computes (and returns) the
/// message authentication code for `input` using `key`. The `key` is
/// consumed to prevent accidental re-use of the same key.
pub fn compute<
Key: ByteArray<CRYPTO_AUTH_KEYBYTES>,
Input: Bytes,
Output: NewByteArray<CRYPTO_AUTH_BYTES>,
>(
key: Key,
input: &Input,
) -> Output {
let mut output = Output::new_byte_array();
crypto_auth(output.as_mut_array(), input.as_slice(), key.as_array());
output
}
/// Convience wrapper around [`Auth::compute`]. Returns the message
/// authentication code as a [`Vec`]. The `key` is
/// consumed to prevent accidental re-use of the same key.
pub fn compute_to_vec<Key: ByteArray<CRYPTO_AUTH_KEYBYTES>, Input: Bytes>(
key: Key,
input: &Input,
) -> Vec<u8> {
Self::compute(key, input)
}
/// Verifies the message authentication code `other_mac` matches the
/// expected code for `key` and `input`. The `key` is
/// consumed to prevent accidental re-use of the same key.
pub fn compute_and_verify<
OtherMac: ByteArray<CRYPTO_AUTH_BYTES>,
Key: ByteArray<CRYPTO_AUTH_KEYBYTES>,
Input: Bytes,
>(
other_mac: &OtherMac,
key: Key,
input: &Input,
) -> Result<(), Error> {
crypto_auth_verify(other_mac.as_array(), input.as_slice(), key.as_array())
}
/// Returns a new secret-key authenticator for `key`. The `key` is
/// consumed to prevent accidental re-use of the same key.
pub fn new<Key: ByteArray<CRYPTO_AUTH_KEYBYTES>>(key: Key) -> Self {
Self {
state: crypto_auth_init(key.as_array()),
}
}
/// Updates the secret-key authenticator at `self` with `input`.
pub fn update<Input: Bytes>(&mut self, input: &Input) {
crypto_auth_update(&mut self.state, input.as_slice())
}
/// Finalizes this secret-key authenticator, returning the message
/// authentication code.
pub fn finalize<Output: NewByteArray<CRYPTO_AUTH_BYTES>>(self) -> Output {
let mut output = Output::new_byte_array();
crypto_auth_final(self.state, output.as_mut_array());
output
}
/// Finalizes this secret-key authenticator, returning the message
/// authentication code as a [`Vec`]. Convenience wrapper around
/// [`Auth::finalize`].
pub fn finalize_to_vec(self) -> Vec<u8> {
self.finalize()
}
/// Finalizes this authenticator, and verifies that the computed code
/// matches `other_mac` using a constant-time comparison.
pub fn verify<OtherMac: ByteArray<CRYPTO_AUTH_BYTES>>(
self,
other_mac: &OtherMac,
) -> Result<(), Error> {
let computed_mac: Mac = self.finalize();
if other_mac
.as_array()
.ct_eq(computed_mac.as_array())
.unwrap_u8()
== 1
{
Ok(())
} else {
Err(dryoc_error!("authentication codes do not match"))
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_single_part() {
let key = Key::gen();
let mac = Auth::compute_to_vec(key.clone(), b"Data to authenticate");
Auth::compute_and_verify(&mac, key, b"Data to authenticate").expect("verify failed");
}
#[test]
fn test_multi_part() {
let key = Key::gen();
let mut mac = Auth::new(key.clone());
mac.update(b"Multi-part");
mac.update(b"data");
let mac = mac.finalize_to_vec();
let mut verify_mac = Auth::new(key.clone());
verify_mac.update(b"Multi-part");
verify_mac.update(b"data");
verify_mac.verify(&mac).expect("verify failed");
let mut verify_mac = Auth::new(key);
verify_mac.update(b"Multi-part");
verify_mac.update(b"bad data");
verify_mac
.verify(&mac)
.expect_err("verify should have failed");
}
}