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

//! `YubiHSM2` authentication keys (2 * AES-128 symmetric PSK) from which session keys are derived

use clear_on_drop::clear::Clear;
use error::Error;
#[cfg(feature = "hmac")]
use hmac::Hmac;
#[cfg(feature = "pbkdf2")]
use pbkdf2::pbkdf2;
use rand::{OsRng, RngCore};
#[cfg(feature = "sha2")]
use sha2::Sha256;
use std::fmt::{self, Debug};

/// Auth keys are 2 * AES-128 keys
pub const AUTH_KEY_SIZE: usize = 32;

/// Password from which the default auth key is derived
pub const DEFAULT_PASSWORD: &[u8] = b"password";

/// Salt value to use with PBKDF2 when deriving auth keys from a password.
/// This salt is designed to be compatible with the password functionality in
/// yubihsm-shell (otherwise using a static salt is not best practice).
pub const DEFAULT_PBKDF2_SALT: &[u8] = b"Yubico";

/// Number of PBKDF2 iterations to perform when deriving auth keys.
/// This number of iterations matches what is performed by yubihsm-shell.
pub const DEFAULT_PBKDF2_ITERATIONS: usize = 10_000;

/// `YubiHSM2` authentication keys (2 * AES-128 symmetric PSK) from which
/// session keys are derived.c
#[derive(Clone)]
pub struct AuthKey(pub(crate) [u8; AUTH_KEY_SIZE]);

impl AuthKey {
    /// Generate a random `AuthKey` using `OsRng`.
    pub fn random() -> Self {
        let mut rng = OsRng::new().expect("RNG failure!");
        let mut challenge = [0u8; AUTH_KEY_SIZE];
        rng.fill_bytes(&mut challenge);
        AuthKey(challenge)
    }

    /// Derive an auth key from a password (using PBKDF2 + static salt).
    /// This method is designed to be compatible with yubihsm-shell. Ensure
    /// you use a long, random password when using this method as the key
    /// derivation algorithm used does little to prevent brute force attacks.
    #[cfg(feature = "passwords")]
    pub fn derive_from_password(password: &[u8]) -> Self {
        let mut kdf_output = [0u8; AUTH_KEY_SIZE];
        pbkdf2::<Hmac<Sha256>>(
            password,
            DEFAULT_PBKDF2_SALT,
            DEFAULT_PBKDF2_ITERATIONS,
            &mut kdf_output,
        );
        Self::new(kdf_output)
    }

    /// Create an AuthKey from a 32-byte slice, returning an error if the key
    /// is the wrong length
    pub fn from_slice(key_slice: &[u8]) -> Result<Self, AuthKeyError> {
        ensure!(
            key_slice.len() == AUTH_KEY_SIZE,
            AuthKeyErrorKind::SizeInvalid,
            "expected {}-byte key, got {}",
            AUTH_KEY_SIZE,
            key_slice.len()
        );

        let mut key_bytes = [0u8; AUTH_KEY_SIZE];
        key_bytes.copy_from_slice(key_slice);

        Ok(AuthKey(key_bytes))
    }

    /// Create a new AuthKey from the given byte array
    pub fn new(key_bytes: [u8; AUTH_KEY_SIZE]) -> Self {
        AuthKey(key_bytes)
    }

    /// Borrow the secret authentication keys
    pub fn as_secret_slice(&self) -> &[u8] {
        &self.0
    }

    /// Obtain the encryption key portion of this auth key
    pub(crate) fn enc_key(&self) -> &[u8] {
        &self.0[..16]
    }

    /// Obtain the MAC key portion of this auth key
    pub(crate) fn mac_key(&self) -> &[u8] {
        &self.0[16..]
    }
}

impl Debug for AuthKey {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // Avoid leaking secrets in debug messages
        write!(f, "yubihsm::AuthKey(...)")
    }
}

/// Derive the default authentication key for all YubiHSM2s
#[cfg(feature = "passwords")]
impl Default for AuthKey {
    fn default() -> Self {
        AuthKey::derive_from_password(DEFAULT_PASSWORD)
    }
}

impl Drop for AuthKey {
    fn drop(&mut self) {
        self.0.clear();
    }
}

impl From<[u8; AUTH_KEY_SIZE]> for AuthKey {
    fn from(key_bytes: [u8; AUTH_KEY_SIZE]) -> AuthKey {
        AuthKey::new(key_bytes)
    }
}

impl_array_serializers!(AuthKey, AUTH_KEY_SIZE);

/// `AuthKey`-related errors
pub type AuthKeyError = Error<AuthKeyErrorKind>;

/// Kinds of `AuthKey`-related errors
#[derive(Copy, Clone, Eq, PartialEq, Debug, Fail)]
pub enum AuthKeyErrorKind {
    /// Size is invalid
    #[fail(display = "invalid size")]
    SizeInvalid,
}