fix(ffi): implement YubiKey-related cache items for WinSCard (#531)

Author: PavloMyroniuk-apriorit

Cargo.lock

@@ -24,7 +24,7 @@ pub type Bool = i32;
 ///   unsigned char  Data4[8];
 /// } GUID;
 /// ```
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Debug)]
 #[repr(C)]
 pub struct Guid {
     pub data1: u32,

crates/ffi-types/src/common.rs

@@ -25,6 +25,7 @@ cfg-if.workspace = true
 num-traits = { workspace = true, default-features = true }
 whoami.workspace = true
 sha1.workspace = true
+sha2.workspace = true
 ffi-types = { workspace = true, features = ["winscard"], optional = true }
 
 picky = { workspace = true, features = ["x509"], optional = true }

ffi/Cargo.toml

@@ -34,6 +34,53 @@ const CERTIFICATE_LABELS: &[(&[u8], [u8; 3])] = &[
     ),
 ];
 
+/// PIV certificate slot ID.
+///
+/// Read more in the NIST SP 800-73pt1-5 specification: Table 5. PIV Card Application key references.
+#[derive(Debug, Clone, Copy)]
+#[repr(u8)]
+pub enum SlotId {
+    /// PIV Authentication Key.
+    PivAuthentication = 0x9a,
+    /// Digital Signature Key.
+    DigitalSignature = 0x9c,
+    /// Key Management Key.
+    KeyManagement = 0x9d,
+    /// Card Authentication Key.
+    CardAuthentication = 0x9e,
+}
+
+impl SlotId {
+    /// Returns [u8] representation of the slot.
+    pub fn as_u8(&self) -> u8 {
+        *self as u8
+    }
+
+    /// Determines the slot id based on the slot certificate label.
+    pub fn from_certificate_label(certificate_label: &[u8]) -> Result<Self> {
+        for (label, slot_id) in CERTIFICATE_SLOT_IDS {
+            if *label == certificate_label {
+                return Ok(*slot_id);
+            }
+        }
+
+        Err(Error::new(ErrorKind::NoCredentials, "certificate label not recognized"))
+    }
+}
+
+/// Possible PIV slot IDs.
+///
+/// The PIV (Personal Identity Verification) standard specifies 25 slots. Each slot has a name and number.
+/// Each slot number is given as a hex value, and all slot numbers can be represented as a single byte.
+///
+/// More info: https://docs.yubico.com/yesdk/users-manual/application-piv/slots.html.
+const CERTIFICATE_SLOT_IDS: &[(&[u8], SlotId)] = &[
+    (b"X.509 Certificate for PIV Authentication", SlotId::PivAuthentication),
+    (b"X.509 Certificate for Digital Signature", SlotId::DigitalSignature),
+    (b"X.509 Certificate for Key Management", SlotId::KeyManagement),
+    (b"X.509 Certificate for Card Authentication", SlotId::CardAuthentication),
+];
+
 /// SELECT APDU command.
 ///
 /// The SELECT card command sets the currently selected application. More info:

ffi/src/winscard/piv.rs

@@ -1007,7 +1007,6 @@ unsafe fn write_cache(
 ) -> WinScardResult<()> {
     check_handle!(context, "scard context handle");
     check_null!(card_identifier, "card identified");
-    check_null!(data, "cache data buffer");
 
     // SAFETY: The `card_identifier` parameter is not null (checked above).
     let card_id = unsafe {
@@ -1021,8 +1020,14 @@ unsafe fn write_cache(
 
     // SAFETY: The `context` value is not zero (checked above).
     let context = unsafe { scard_context_to_winscard_context(context) }?;
-    // SAFETY: The `data` parameter is not null (checked above).
-    let data = unsafe { from_raw_parts(data, data_len.try_into()?) }.to_vec();
+    // The YubiKey Smart Card Minidriver can call `SCardWriteCacheW` with the `Data` pointer set to NULL and
+    // `DataLen` equal to 0.
+    let data = if data.is_null() || data_len == 0 {
+        Vec::new()
+    } else {
+        // SAFETY: The `data` parameter is not null (checked above).
+        unsafe { from_raw_parts(data, data_len.try_into()?) }.to_vec()
+    };
 
     context.write_cache(card_id, freshness_counter, lookup_name.to_owned(), data)
 }

ffi/src/winscard/scard_context.rs

@@ -85,12 +85,19 @@ impl SystemScardContext {
 
         #[cfg(not(target_os = "windows"))]
         if _with_cache {
-            let (container_name, auth_cert, auth_cert_der) = if let (Ok(auth_cert), Ok(container_name)) =
+            let scard_logon_params = if let (Ok(certificate), Ok(container_name)) =
                 (winscard::env::auth_cert_from_env(), winscard::env::container_name())
             {
-                let auth_cert_der = auth_cert.to_der()?;
+                use crate::winscard::piv::SlotId;
 
-                (container_name, auth_cert, auth_cert_der)
+                let certificate_der = certificate.to_der()?;
+
+                ScardLogonParams {
+                    container_name,
+                    certificate,
+                    certificate_der,
+                    slot: SlotId::PivAuthentication,
+                }
             } else {
                 use std::path::Path;
 
@@ -102,23 +109,29 @@ impl SystemScardContext {
                 try_extract_container_name_and_certificate(Path::new(&pkcs11_module_path))?
             };
 
-            scard_context.cache = init_scard_cache(&container_name, auth_cert, &auth_cert_der)?;
+            scard_context.cache = init_scard_cache(&scard_logon_params)?;
         }
 
         Ok(scard_context)
     }
 }
 
+#[cfg(not(target_os = "windows"))]
+struct ScardLogonParams {
+    container_name: String,
+    certificate: picky::x509::Cert,
+    certificate_der: Vec<u8>,
+    slot: crate::winscard::piv::SlotId,
+}
+
 #[cfg(not(target_os = "windows"))]
 #[instrument(err)]
-pub fn try_extract_container_name_and_certificate(
-    pkcs11_module: &std::path::Path,
-) -> Result<(String, picky::x509::Cert, Vec<u8>), Error> {
+fn try_extract_container_name_and_certificate(pkcs11_module: &std::path::Path) -> Result<ScardLogonParams, Error> {
     use cryptoki::context::{CInitializeArgs, Pkcs11};
     use cryptoki::object::{Attribute, AttributeType, CertificateType, ObjectClass};
     use picky::x509::Cert;
 
-    use crate::winscard::piv::try_get_piv_container_name;
+    use crate::winscard::piv::{try_get_piv_container_name, SlotId};
 
     macro_rules! try_execute {
         ($x:expr, $msg:literal) => {{
@@ -177,6 +190,7 @@ pub fn try_extract_container_name_and_certificate(
         };
 
         let mut container_name = None;
+        let mut slot = None;
         // We found a suitable certificate for smart card logon on the device.
         // Next, we check if the inserted device is a PIV smart card. If so, we will attempt
         // to extract the container name using raw APDU commands.
@@ -192,6 +206,10 @@ pub fn try_extract_container_name_and_certificate(
                 try_get_piv_container_name(reader_name, &label),
                 "failed to construct a container name"
             ));
+            slot = Some(try_execute!(
+                SlotId::from_certificate_label(&label),
+                "failed to determine a slot id"
+            ));
 
             if container_name.is_some() {
                 break;
@@ -202,12 +220,21 @@ pub fn try_extract_container_name_and_certificate(
             continue;
         };
 
+        let Some(slot) = slot else {
+            continue;
+        };
+
         let certificate = try_execute!(
             Cert::from_der(&certificate_der),
             "failed to parse smart card certificate"
         );
 
-        return Ok((container_name, certificate, certificate_der));
+        return Ok(ScardLogonParams {
+            container_name,
+            certificate,
+            certificate_der,
+            slot,
+        });
     }
 
     Err(Error::new(
@@ -253,11 +280,14 @@ fn validate_certificate(certificate: &[u8]) -> Result<(), Error> {
 }
 
 #[cfg(not(target_os = "windows"))]
-fn init_scard_cache(
-    container_name: &str,
-    auth_cert: picky::x509::Cert,
-    auth_cert_der: &[u8],
-) -> WinScardResult<BTreeMap<String, Vec<u8>>> {
+fn init_scard_cache(scard_logon_params: &ScardLogonParams) -> WinScardResult<BTreeMap<String, Vec<u8>>> {
+    let ScardLogonParams {
+        container_name,
+        certificate,
+        certificate_der,
+        slot,
+    } = scard_logon_params;
+
     use picky_asn1_x509::{PublicKey, SubjectPublicKeyInfo};
 
     // https://github.com/selfrender/Windows-Server-2003/blob/5c6fe3db626b63a384230a1aa6b92ac416b0765f/ds/security/csps/wfsccsp/inc/basecsp.h#L86-L93
@@ -388,7 +418,7 @@ fn init_scard_cache(
         value.extend_from_slice(b"RSA1"); // magic = RSA1
         value.extend_from_slice(&2048_u32.to_le_bytes()); // bitlen = 2048
 
-        let public_key = auth_cert.public_key();
+        let public_key = certificate.public_key();
         let public_key: &SubjectPublicKeyInfo = public_key.as_ref();
         let (modulus, public_exponent) = match &public_key.subject_public_key {
             PublicKey::Rsa(rsa) => (
@@ -423,9 +453,9 @@ fn init_scard_cache(
         // unkown flags
         value.extend_from_slice(&[0, 0, 0, 0, 0, 0]);
 
-        value.extend_from_slice(&(u16::try_from(auth_cert_der.len())?.to_le_bytes())); // uncompressed certificate data len
+        value.extend_from_slice(&(u16::try_from(certificate_der.len())?.to_le_bytes())); // uncompressed certificate data len
         value.extend_from_slice(&[0x00, 0x00]); // flags that specify that the certificate is not compressed
-        value.extend_from_slice(auth_cert_der);
+        value.extend_from_slice(certificate_der);
 
         value
     });
@@ -443,6 +473,93 @@ fn init_scard_cache(
         value
     });
 
+    //= YubiKey-related cache items =//
+
+    /// The KeySpec property identifies how a key that is generated or retrieved using the Microsoft CryptoAPI (CAPI)
+    /// from a Microsoft legacy Cryptographic Storage Provider (CSP) can be used.
+    ///
+    /// We need the [KeySpec] value to build scard cache items correctly.
+    #[repr(u8)]
+    enum KeySpec {
+        /// RSA key that can be used for signing and decryption.
+        AtKeyExchange = 1,
+        /// RSA signature only key.
+        AtSignature = 2,
+    }
+
+    cache.insert("ykmd_cardcf".to_owned(), CACHE_ITEM_HEADER.to_vec());
+
+    cache.insert("ykmd_lastupdate".to_owned(), {
+        use std::time::{SystemTime, UNIX_EPOCH};
+
+        let now = SystemTime::now();
+        let epoch_seconds = now.duration_since(UNIX_EPOCH).unwrap().as_secs();
+
+        epoch_seconds.to_le_bytes().to_vec()
+    });
+
+    cache.insert("ykmd_cmap".to_owned(), {
+        use ffi_types::WChar;
+        use sha2::Digest;
+
+        use crate::winscard::piv::SlotId;
+
+        // This cache item represents the `ykpiv_container` object:
+        //
+        // https://github.com/Yubico/yubico-piv-tool/blob/6444d40d73f4d4c029c9739938edf57ede23e6f1/lib/ykpiv.h#L268-L277
+        // ```C
+        //   typedef struct _ykpiv_container {
+        //     wchar_t name[40];
+        //     uint8_t slot;
+        //     uint8_t key_spec;
+        //     uint16_t key_size_bits;
+        //     uint8_t flags;
+        //     uint8_t pin_id;
+        //     uint8_t associated_echd_container;
+        //     uint8_t cert_fingerprint[20];
+        //   } ykpiv_container;
+        // ```
+
+        let mut container_name_encoded = container_name
+            .encode_utf16()
+            .chain(core::iter::once(0))
+            .flat_map(|v| v.to_le_bytes())
+            .collect::<Vec<_>>();
+        let container_name_bytes_len = size_of::<WChar>() * MAX_CONTAINER_NAME_LEN;
+        debug_assert_eq!(container_name_bytes_len, 80);
+
+        container_name_encoded.resize(container_name_bytes_len, 0);
+        debug!(?container_name_encoded);
+
+        let mut value = container_name_encoded;
+        value.push(slot.as_u8()); // Slot.
+
+        // The KeySpec value is not encoded inside certificate. We determine it by looking at the certificate slot id.
+        let key_spec = match slot {
+            SlotId::PivAuthentication => KeySpec::AtKeyExchange,
+            SlotId::DigitalSignature => KeySpec::AtSignature,
+            SlotId::KeyManagement => KeySpec::AtKeyExchange,
+            SlotId::CardAuthentication => KeySpec::AtKeyExchange,
+        };
+        value.push(key_spec as u8);
+
+        value.extend_from_slice(&[0x00, 0x08]); // KeySize.
+        value.push(0x03); // Flags.
+        value.push(0x01); // PIN id.
+        value.push(0xff); // Associated ECHD container (none).
+
+        // Discovered experimentally:
+        // The `cert_fingerprint` field contains the first 20 bytes of SHA256 cert hash (instead of SHA1 cert hash).
+        let cert_fingerprint = sha2::Sha256::digest(certificate_der);
+        value.extend_from_slice(&cert_fingerprint.as_slice()[0..20]);
+
+        // The value length must be the correct size. The YubiKey Smart Card Minidriver checks it.
+        // The `0x6b` was extracted from the `ykmd.dll` and is also equal to the `ykpiv_container` size.
+        debug_assert_eq!(value.len(), 0x6b);
+
+        value
+    });
+
     Ok(cache)
 }