implement yubihsm auth

This is used to calculate session keys for Yubico HSM.

src/apdu.rs

@@ -198,6 +198,15 @@ pub enum Ins {
     /// Get slot metadata
     GetMetadata,
 
+    /// YubiHSM Auth // Calculate session keys
+    Calculate,
+
+    /// YubiHSM Auth // Get challenge
+    GetHostChallenge,
+
+    /// YubiHSM Auth // List credentials
+    ListCredentials,
+
     /// Other/unrecognized instruction codes
     Other(u8),
 }
@@ -223,6 +232,10 @@ impl Ins {
             Ins::Attest => 0xf9,
             Ins::GetSerial => 0xf8,
             Ins::GetMetadata => 0xf7,
+            // Yubihsm auth
+            Ins::Calculate => 0x03,
+            Ins::GetHostChallenge => 0x04,
+            Ins::ListCredentials => 0x05,
             Ins::Other(code) => code,
         }
     }
@@ -231,6 +244,9 @@ impl Ins {
 impl From<u8> for Ins {
     fn from(code: u8) -> Self {
         match code {
+            0x03 => Ins::Calculate,
+            0x04 => Ins::GetHostChallenge,
+            0x05 => Ins::ListCredentials,
             0x20 => Ins::Verify,
             0x24 => Ins::ChangeReference,
             0x2c => Ins::ResetRetry,

src/consts.rs

@@ -18,3 +18,8 @@ pub(crate) const TAG_ADMIN_TIMESTAMP: u8 = 0x83;
 // Protected tags
 pub(crate) const TAG_PROTECTED_FLAGS_1: u8 = 0x81;
 pub(crate) const TAG_PROTECTED_MGM: u8 = 0x89;
+
+// YubiHSM Auth
+pub(crate) const TAG_LABEL: u8 = 0x71;
+pub(crate) const TAG_PW: u8 = 0x73;
+pub(crate) const TAG_CONTEXT: u8 = 0x77;

src/hsmauth.rs

@@ -0,0 +1,269 @@
+//! YubiHSM Auth protocol
+//!
+//! YubiHSM Auth is a YubiKey CCID application that stores the long-lived
+//! credentials used to establish secure sessions with a YubiHSM 2. The secure
+//! session protocol is based on Secure Channel Protocol 3 (SCP03).
+use crate::{
+    error::{Error, Result},
+    transaction::Transaction,
+    YubiKey,
+};
+use nom::{
+    bytes::complete::{tag, take},
+    combinator::eof,
+    error::{Error as NumError, ErrorKind},
+    multi::many0,
+    number::complete::u8,
+    IResult,
+};
+use std::{fmt, str::FromStr};
+use zeroize::Zeroizing;
+
+/// Yubikey HSM Auth Applet ID
+pub(crate) const APPLET_ID: &[u8] = &[0xa0, 0x00, 0x00, 0x05, 0x27, 0x21, 0x07, 0x01];
+/// Yubikey HSM Auth Applet Name
+pub(crate) const APPLET_NAME: &str = "YubiHSM";
+
+/// AES key size in bytes. SCP03 theoretically supports other key sizes, but
+/// the YubiHSM 2 does not. Since this crate is somewhat specialized to the `YubiHSM 2` (at least for now)
+/// we hardcode to 128-bit for simplicity.
+pub(crate) const KEY_SIZE: usize = 16;
+
+/// Password to authenticate to the Yubikey HSM Auth Applet has a max length of 16
+pub(crate) const PW_LEN: usize = 16;
+
+/// Label associated with a secret on the Yubikey.
+#[derive(Clone)]
+pub struct Label(pub(crate) Vec<u8>);
+
+impl FromStr for Label {
+    type Err = Error;
+
+    fn from_str(input: &str) -> Result<Self> {
+        let buf = input.as_bytes();
+
+        if (1..=64).contains(&buf.len()) {
+            Ok(Self(buf.to_vec()))
+        } else {
+            Err(Error::ParseError)
+        }
+    }
+}
+
+/// [`Context`] holds the various challenges used for the authentication.
+///
+/// This is used as part of the key derivation for the session keys.
+pub struct Context(pub(crate) [u8; 16]);
+
+impl Context {
+    /// Creates a [`Context`] from its components
+    pub fn new(host_challenge: &Challenge, hsm_challenge: &Challenge) -> Self {
+        let mut out = Self::zeroed();
+        out.0[..8].copy_from_slice(host_challenge.as_slice());
+        out.0[8..].copy_from_slice(hsm_challenge.as_slice());
+
+        out
+    }
+
+    fn zeroed() -> Self {
+        Self([0u8; 16])
+    }
+
+    /// Build `Context` from the provided buffer
+    pub fn from_buf(buf: [u8; 16]) -> Self {
+        Self(buf)
+    }
+}
+
+/// Exclusive access to the Hsmauth applet.
+pub struct HsmAuth {
+    client: YubiKey,
+}
+
+impl HsmAuth {
+    pub(crate) fn new(mut client: YubiKey) -> Result<Self> {
+        Transaction::new(&mut client.card)?.select_application(
+            APPLET_ID,
+            APPLET_NAME,
+            "failed selecting YkHSM auth application",
+        )?;
+
+        Ok(Self { client })
+    }
+
+    /// Calculate session key with the specified key.
+    pub fn calculate(
+        &mut self,
+        label: Label,
+        context: Context,
+        password: &[u8],
+    ) -> Result<SessionKeys> {
+        Transaction::new(&mut self.client.card)?.calculate(
+            self.client.version,
+            label,
+            context,
+            password,
+        )
+    }
+
+    /// Get YubiKey Challenge
+    pub fn get_challenge(&mut self, label: Label) -> Result<Challenge> {
+        Transaction::new(&mut self.client.card)?.get_host_challenge(self.client.version, label)
+    }
+
+    /// List credentials
+    pub fn list_credentials(&mut self) -> Result<Vec<Credential>> {
+        Transaction::new(&mut self.client.card)?.list_credentials(self.client.version)
+    }
+
+    /// Retun the inner `YubiKey`
+    pub fn into_inner(mut self) -> Result<YubiKey> {
+        Transaction::new(&mut self.client.card)?.select_piv_application()?;
+        Ok(self.client)
+    }
+}
+
+#[derive(Debug)]
+/// Algorithm for the credentials
+pub enum Algorithm {
+    /// AES 128 keys
+    Aes128,
+    /// EC P256
+    EcP256,
+}
+
+impl fmt::Display for Algorithm {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Algorithm::Aes128 => write!(f, "AES128"),
+            Algorithm::EcP256 => write!(f, "ECP256"),
+        }
+    }
+}
+
+impl Algorithm {
+    fn parse(input: &[u8]) -> IResult<&[u8], Self> {
+        let (input, value) = u8(input)?;
+        match value {
+            38 => Ok((input, Algorithm::Aes128)),
+            39 => Ok((input, Algorithm::EcP256)),
+            _ => Err(nom::Err::Error(NumError::new(input, ErrorKind::Tag))),
+        }
+    }
+}
+
+/// YubiHSM Auth credential store in the Application
+#[derive(Debug)]
+pub struct Credential {
+    /// Algorithm of the key
+    pub algorithm: Algorithm,
+    /// Is touch required when using this credential
+    pub touch: bool,
+    /// Remaining attempts to authenticate to this credential
+    pub remaining_attempts: u8,
+    /// Label for the credential
+    pub label: Vec<u8>,
+}
+
+impl Credential {
+    /// Parse a buffer holding a single credential
+    fn parse(input: &[u8]) -> IResult<&[u8], Self> {
+        let (input, _list) = tag(b"\x72")(input)?;
+
+        let (input, buf_len) = u8(input)?;
+        let buf_len = if buf_len < 3 {
+            return Err(nom::Err::Error(NumError::new(
+                input,
+                ErrorKind::LengthValue,
+            )));
+        } else {
+            (buf_len - 3) as usize
+        };
+
+        let (input, algorithm) = Algorithm::parse(input)?;
+
+        let (input, touch) = u8(input)?;
+        let touch = match touch {
+            0 => false,
+            1 => true,
+            _ => return Err(nom::Err::Error(NumError::new(input, ErrorKind::Tag))),
+        };
+
+        let (input, label) = take(buf_len)(input)?;
+
+        let (input, remaining_attempts) = u8(input)?;
+
+        Ok((
+            input,
+            Credential {
+                algorithm,
+                touch,
+                label: label.to_vec(),
+                remaining_attempts,
+            },
+        ))
+    }
+
+    /// Parse a buffer holding a list of `Credential`
+    pub fn parse_list(input: &[u8]) -> Result<Vec<Self>> {
+        let (input, credentials) =
+            many0(Credential::parse)(input).map_err(|_| Error::ParseError)?;
+        let (_input, _) = eof(input).map_err(|_: nom::Err<NumError<&[u8]>>| Error::ParseError)?;
+
+        Ok(credentials)
+    }
+}
+
+/// The sessions keys after negociation via SCP03.
+#[derive(Default, Debug)]
+pub struct SessionKeys {
+    /// Session encryption key (S-ENC)
+    pub enc_key: Zeroizing<[u8; KEY_SIZE]>,
+    /// Session Command MAC key (S-MAC)
+    pub mac_key: Zeroizing<[u8; KEY_SIZE]>,
+    /// Session Respose MAC key (S-RMAC)
+    pub rmac_key: Zeroizing<[u8; KEY_SIZE]>,
+}
+
+/// Host challenge used for session keys calculation
+#[derive(Debug, Clone)]
+pub struct Challenge {
+    buffer: Zeroizing<[u8; Self::SIZE]>,
+    length: usize,
+}
+
+impl Challenge {
+    /// Challenge used in SCP03 computation
+    /// Can be as long as a P256 PUBKEY (for SCP11 support).
+    pub(crate) const SIZE: usize = 65;
+
+    /// Returns a slice containing the entire array.
+    pub fn as_slice(&self) -> &[u8] {
+        &self.buffer.as_slice()[..self.length]
+    }
+
+    /// Returns true if the challenge has a length of 0.
+    pub fn is_empty(&self) -> bool {
+        self.length == 0
+    }
+
+    /// Copy data from provided slice
+    pub fn copy_from_slice(&mut self, data: &[u8]) -> Result<()> {
+        self.length = data.len();
+        if self.length > Self::SIZE {
+            Err(Error::SizeError)
+        } else {
+            self.buffer[..self.length].copy_from_slice(data);
+            Ok(())
+        }
+    }
+}
+
+impl Default for Challenge {
+    fn default() -> Self {
+        Self {
+            buffer: Zeroizing::new([0u8; Self::SIZE]),
+            length: 0,
+        }
+    }
+}

src/lib.rs

@@ -43,6 +43,7 @@ mod chuid;
 mod config;
 mod consts;
 mod error;
+pub mod hsmauth;
 mod metadata;
 mod mgm;
 #[cfg(feature = "untested")]