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
|
// MIT License
// Copyright (c) 2020-2023 The orion Developers
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//! 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:
//! ```rust
//! 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());
//! # Ok::<(), orion::errors::UnknownCryptoError>(())
//! ```
#![cfg_attr(docsrs, doc(cfg(feature = "safe_api")))]
pub use super::hltypes::SecretKey;
pub use crate::hazardous::mac::blake2b::Tag;
use crate::{
errors::UnknownCryptoError,
hazardous::mac::blake2b::{self, Blake2b},
};
/// The Tag size (bytes) to be output by BLAKE2b in keyed mode.
const BLAKE2B_TAG_SIZE: usize = 32;
/// The minimum `SecretKey` size (bytes) to be used by BLAKE2b in keyed mode.
const BLAKE2B_MIN_KEY_SIZE: usize = 32;
#[must_use = "SECURITY WARNING: Ignoring a Result can have real security implications."]
/// Authenticate a message using BLAKE2b-256 in keyed mode.
pub fn authenticate(secret_key: &SecretKey, data: &[u8]) -> Result<Tag, UnknownCryptoError> {
if secret_key.len() < BLAKE2B_MIN_KEY_SIZE {
return Err(UnknownCryptoError);
}
let blake2b_secret_key = blake2b::SecretKey::from_slice(secret_key.unprotected_as_bytes())?;
let mut state = Blake2b::new(&blake2b_secret_key, BLAKE2B_TAG_SIZE)?;
state.update(data)?;
state.finalize()
}
#[must_use = "SECURITY WARNING: Ignoring a Result can have real security implications."]
/// Authenticate and verify a message using BLAKE2b-256 in keyed mode.
pub fn authenticate_verify(
expected: &Tag,
secret_key: &SecretKey,
data: &[u8],
) -> Result<(), UnknownCryptoError> {
if secret_key.len() < BLAKE2B_MIN_KEY_SIZE || expected.len() != BLAKE2B_TAG_SIZE {
return Err(UnknownCryptoError);
}
let key = blake2b::SecretKey::from_slice(secret_key.unprotected_as_bytes())?;
Blake2b::verify(expected, &key, BLAKE2B_TAG_SIZE, data)
}
// Testing public functions in the module.
#[cfg(test)]
mod public {
use super::*;
mod test_auth_and_verify {
use super::*;
#[test]
fn test_authenticate_verify_bad_key() {
let sec_key_correct = SecretKey::generate(64).unwrap();
let sec_key_false = SecretKey::default();
let msg = "what do ya want for nothing?".as_bytes().to_vec();
let mac_bob = authenticate(&sec_key_correct, &msg).unwrap();
assert!(authenticate_verify(&mac_bob, &sec_key_correct, &msg).is_ok());
assert!(authenticate_verify(&mac_bob, &sec_key_false, &msg).is_err());
}
#[test]
fn test_authenticate_verify_bad_msg() {
let sec_key = SecretKey::generate(64).unwrap();
let msg = "what do ya want for nothing?".as_bytes().to_vec();
let mac_bob = authenticate(&sec_key, &msg).unwrap();
assert!(authenticate_verify(&mac_bob, &sec_key, &msg).is_ok());
assert!(authenticate_verify(&mac_bob, &sec_key, b"bad msg").is_err());
}
#[test]
fn test_authenticate_key_too_small() {
let sec_key = SecretKey::generate(31).unwrap();
let msg = "what do ya want for nothing?".as_bytes().to_vec();
assert!(authenticate(&sec_key, &msg).is_err());
}
#[test]
fn test_authenticate_verify_key_too_small() {
let sec_key = SecretKey::generate(31).unwrap();
let msg = "what do ya want for nothing?".as_bytes().to_vec();
let mac = Tag::from_slice(&[0u8; 32][..]).unwrap();
assert!(authenticate_verify(&mac, &sec_key, &msg).is_err());
}
}
#[quickcheck]
#[cfg(feature = "safe_api")]
/// Authentication and verifying that tag with the same parameters
/// should always be true.
fn prop_authenticate_verify(input: Vec<u8>) -> bool {
let sk = SecretKey::default();
let tag = authenticate(&sk, &input[..]).unwrap();
authenticate_verify(&tag, &sk, &input[..]).is_ok()
}
#[quickcheck]
#[cfg(feature = "safe_api")]
/// Authentication and verifying that tag with a different key should
/// never be true.
fn prop_verify_fail_diff_key(input: Vec<u8>) -> bool {
let sk = SecretKey::default();
let sk2 = SecretKey::default();
let tag = authenticate(&sk, &input[..]).unwrap();
authenticate_verify(&tag, &sk2, &input[..]).is_err()
}
#[quickcheck]
#[cfg(feature = "safe_api")]
/// Authentication and verifying that tag with different input should
/// never be true.
fn prop_verify_fail_diff_input(input: Vec<u8>) -> bool {
let sk = SecretKey::default();
let tag = authenticate(&sk, &input[..]).unwrap();
authenticate_verify(&tag, &sk, b"Completely wrong input").is_err()
}
use crate::hazardous::hash::blake2::blake2b_core::BLAKE2B_KEYSIZE;
#[quickcheck]
#[cfg(feature = "safe_api")]
/// Verify the bounds of 32..=64 (inclusive) for the `SecretKey` used
/// in `authenticate/authenticate_verify`.
fn prop_authenticate_key_size(input: Vec<u8>) -> bool {
let sec_key_res = SecretKey::from_slice(&input);
if input.is_empty() || input.len() >= u32::MAX as usize {
return sec_key_res.is_err();
}
let sec_key = sec_key_res.unwrap();
let msg = "what do ya want for nothing?".as_bytes().to_vec();
let auth_res = authenticate(&sec_key, &msg);
if input.len() >= BLAKE2B_MIN_KEY_SIZE && input.len() <= BLAKE2B_KEYSIZE {
auth_res.is_ok()
} else {
auth_res.is_err()
}
}
}
|
