all: type alias fingerprint to support embedding and encoding

Author: karalabe

examples/demo.rs

@@ -32,7 +32,7 @@ fn main() {
     let root_public = root_secret.public_key();
     println!(
         "   Root fingerprint: {}",
-        hex::encode(&root_public.fingerprint())
+        hex::encode(root_public.fingerprint().to_bytes())
     );
 
     // =========================================================================
@@ -56,7 +56,7 @@ fn main() {
         .unwrap();
     println!(
         "   Alice xDSA fingerprint: {}",
-        hex::encode(&alice_xdsa_public.fingerprint())
+        hex::encode(alice_xdsa_public.fingerprint().to_bytes())
     );
 
     // =========================================================================
@@ -80,7 +80,7 @@ fn main() {
         .unwrap();
     println!(
         "   Bob xDSA fingerprint: {}",
-        hex::encode(&bob_xdsa_public.fingerprint())
+        hex::encode(bob_xdsa_public.fingerprint().to_bytes())
     );
 
     // =========================================================================
@@ -104,7 +104,7 @@ fn main() {
         .unwrap();
     println!(
         "   Alice xHPKE fingerprint: {}",
-        hex::encode(&alice_xhpke_public.fingerprint())
+        hex::encode(alice_xhpke_public.fingerprint().to_bytes())
     );
 
     // =========================================================================
@@ -128,7 +128,7 @@ fn main() {
         .unwrap();
     println!(
         "   Bob xHPKE fingerprint: {}",
-        hex::encode(&bob_xhpke_public.fingerprint())
+        hex::encode(bob_xhpke_public.fingerprint().to_bytes())
     );
 
     // =========================================================================

src/cose/mod.rs

@@ -125,7 +125,7 @@ pub fn sign_at(
 ) -> Vec<u8> {
     let protected = cbor::encode(&SigProtectedHeader {
         algorithm: ALGORITHM_ID_XDSA,
-        kid: signer.fingerprint(),
+        kid: signer.fingerprint().to_bytes(),
         timestamp,
     });
 
@@ -335,7 +335,7 @@ pub fn seal_at(
     // Build protected header with recipient's fingerprint
     let protected = cbor::encode(&EncProtectedHeader {
         algorithm: ALGORITHM_ID_XHPKE,
-        kid: recipient.fingerprint(),
+        kid: recipient.fingerprint().to_bytes(),
     });
 
     // Build and seal Enc_structure
@@ -455,8 +455,11 @@ fn verify_sig_protected_header(
     if header.algorithm != exp_algo {
         return Err(Error::UnexpectedAlgorithm(header.algorithm, exp_algo));
     }
-    if header.kid != verifier.fingerprint() {
-        return Err(Error::UnexpectedKey(header.kid, verifier.fingerprint()));
+    if header.kid != verifier.fingerprint().to_bytes() {
+        return Err(Error::UnexpectedKey(
+            header.kid,
+            verifier.fingerprint().to_bytes(),
+        ));
     }
     Ok(header)
 }
@@ -472,8 +475,11 @@ fn verify_enc_protected_header(
     if header.algorithm != exp_algo {
         return Err(Error::UnexpectedAlgorithm(header.algorithm, exp_algo));
     }
-    if header.kid != recipient.fingerprint() {
-        return Err(Error::UnexpectedKey(header.kid, recipient.fingerprint()));
+    if header.kid != recipient.fingerprint().to_bytes() {
+        return Err(Error::UnexpectedKey(
+            header.kid,
+            recipient.fingerprint().to_bytes(),
+        ));
     }
     Ok(header)
 }

src/eddsa/mod.rs

@@ -32,6 +32,9 @@ pub const PUBLIC_KEY_SIZE: usize = 32;
 /// Size of a signature in bytes.
 pub const SIGNATURE_SIZE: usize = 64;
 
+/// Size of a fingerprint in bytes.
+pub const FINGERPRINT_SIZE: usize = 32;
+
 /// SecretKey contains an Ed25519 private key usable for signing.
 #[derive(Clone)]
 pub struct SecretKey {
@@ -110,7 +113,7 @@ impl SecretKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For HPKE,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         self.public_key().fingerprint()
     }
 
@@ -165,10 +168,10 @@ impl PublicKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For Ed25519,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         let mut hasher = sha2::Sha256::new();
         hasher.update(self.to_bytes());
-        hasher.finalize().into()
+        Fingerprint(hasher.finalize().into())
     }
 
     /// verify verifies a digital signature.
@@ -194,6 +197,22 @@ impl Signature {
     }
 }
 
+/// Fingerprint contains an Ed25519 key fingerprint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Fingerprint([u8; FINGERPRINT_SIZE]);
+
+impl Fingerprint {
+    /// from_bytes converts a 32-byte array into a fingerprint.
+    pub fn from_bytes(bytes: &[u8; FINGERPRINT_SIZE]) -> Self {
+        Self(*bytes)
+    }
+
+    /// to_bytes converts a fingerprint into a 32-byte array.
+    pub fn to_bytes(&self) -> [u8; FINGERPRINT_SIZE] {
+        self.0
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/mldsa/mod.rs

@@ -34,6 +34,9 @@ pub const PUBLIC_KEY_SIZE: usize = 1952;
 /// Size of a signature in bytes.
 pub const SIGNATURE_SIZE: usize = 3309;
 
+/// Size of a fingerprint in bytes.
+pub const FINGERPRINT_SIZE: usize = 32;
+
 /// ML-DSA-65 private key inner structure.
 #[derive(Clone, Debug, Eq, PartialEq, Sequence)]
 struct MlDsa65PrivateKeyInner {
@@ -159,7 +162,7 @@ impl SecretKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For ML-DSA,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         self.public_key().fingerprint()
     }
 
@@ -244,10 +247,10 @@ impl PublicKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For ML-DSA,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         let mut hasher = sha2::Sha256::new();
         hasher.update(self.inner.encode().as_slice());
-        hasher.finalize().into()
+        Fingerprint(hasher.finalize().into())
     }
 
     /// verify verifies a digital signature with an optional context string.
@@ -282,6 +285,22 @@ impl Signature {
     }
 }
 
+/// Fingerprint contains a 32-byte unique identifier for an ML-DSA-65 key.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Fingerprint([u8; FINGERPRINT_SIZE]);
+
+impl Fingerprint {
+    /// from_bytes converts a 32-byte array into a fingerprint.
+    pub fn from_bytes(bytes: &[u8; FINGERPRINT_SIZE]) -> Self {
+        Self(*bytes)
+    }
+
+    /// to_bytes converts a fingerprint into a 32-byte array.
+    pub fn to_bytes(&self) -> [u8; FINGERPRINT_SIZE] {
+        self.0
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/rsa/mod.rs

@@ -28,6 +28,9 @@ pub const PUBLIC_KEY_SIZE: usize = 264;
 /// Size of an RSA-2048 signature.
 pub const SIGNATURE_SIZE: usize = 256;
 
+/// Size of an RSA key fingerprint (SHA256 hash).
+pub const FINGERPRINT_SIZE: usize = 32;
+
 /// SecretKey contains a 2048-bit RSA private key usable for signing, with SHA256
 /// as the underlying hash algorithm. Whilst RSA could also be used for encryption,
 /// that is not exposed on the API as it's not required by the project.
@@ -155,7 +158,7 @@ impl SecretKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For RSA, that
     /// is the SHA256 hash of the raw (le modulus || le exponent) public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         self.public_key().fingerprint()
     }
 
@@ -259,7 +262,7 @@ impl PublicKey {
 
     /// fingerprint returns a 256bit unique identified for this key. For RSA, that
     /// is the SHA256 hash of the raw (le modulus || le exponent) public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         let pubkey: RsaPublicKey = self.inner.as_ref().clone();
 
         let mut mod_le = pubkey.n().to_bytes_le();
@@ -270,7 +273,7 @@ impl PublicKey {
         let mut hasher = Sha256::new();
         hasher.update(&mod_le);
         hasher.update(&exp_le);
-        hasher.finalize().into()
+        Fingerprint(hasher.finalize().into())
     }
 
     /// verify verifies a digital signature.
@@ -310,6 +313,22 @@ impl Signature {
     }
 }
 
+/// Fingerprint contains an RSA key fingerprint (SHA256 hash).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fingerprint([u8; FINGERPRINT_SIZE]);
+
+impl Fingerprint {
+    /// from_bytes converts a 32-byte array into a fingerprint.
+    pub fn from_bytes(bytes: &[u8; FINGERPRINT_SIZE]) -> Self {
+        Self(*bytes)
+    }
+
+    /// to_bytes converts a fingerprint into a 32-byte array.
+    pub fn to_bytes(&self) -> [u8; FINGERPRINT_SIZE] {
+        self.0
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -557,7 +576,7 @@ fQIDAQAB
 -----END PUBLIC KEY-----",
         )
         .unwrap();
-        assert_eq!(hex::encode(key.fingerprint()), input);
+        assert_eq!(hex::encode(key.fingerprint().to_bytes()), input);
     }
 
     // Tests signing and verifying messages. Note, this test is not meant to test

src/xdsa/mod.rs

@@ -40,6 +40,9 @@ pub const PUBLIC_KEY_SIZE: usize = 1984;
 /// Format: ML-DSA (3309 bytes) || Ed25519 (64 bytes)
 pub const SIGNATURE_SIZE: usize = 3373;
 
+/// Size of a key fingerprint in bytes.
+pub const FINGERPRINT_SIZE: usize = 32;
+
 /// SecretKey is an ML-DSA-65 private key paired with an Ed25519 private key for
 /// creating and verifying quantum resistant digital signatures.    
 #[derive(Clone)]
@@ -150,7 +153,7 @@ impl SecretKey {
     }
 
     /// fingerprint returns a 256bit unique identifier for this key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         self.public_key().fingerprint()
     }
 
@@ -273,11 +276,11 @@ impl PublicKey {
     }
 
     /// fingerprint returns a 256bit unique identifier for this key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         let mut hasher = sha2::Sha256::new();
         hasher.update(self.ml_key.to_bytes());
         hasher.update(self.ed_key.to_bytes());
-        hasher.finalize().into()
+        Fingerprint(hasher.finalize().into())
     }
 
     /// verify verifies a digital signature.
@@ -345,6 +348,22 @@ impl Signature {
     }
 }
 
+/// Fingerprint contains a 256-bit unique identifier for a composite ML-DSA-65-Ed25519-SHA512 key.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Fingerprint([u8; FINGERPRINT_SIZE]);
+
+impl Fingerprint {
+    /// from_bytes creates a fingerprint from a 32-byte array.
+    pub fn from_bytes(bytes: &[u8; FINGERPRINT_SIZE]) -> Self {
+        Self(*bytes)
+    }
+
+    /// to_bytes converts a fingerprint into a 32-byte array.
+    pub fn to_bytes(&self) -> [u8; FINGERPRINT_SIZE] {
+        self.0
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/xhpke/mod.rs

@@ -54,6 +54,9 @@ pub const PUBLIC_KEY_SIZE: usize = 1216;
 /// Size of the encapsulated key in bytes.
 pub const ENCAP_KEY_SIZE: usize = 1120;
 
+/// Size of the fingerprint in bytes.
+pub const FINGERPRINT_SIZE: usize = 32;
+
 /// SecretKey contains a private key of the type bound to the configured crypto.
 #[derive(Clone, PartialEq, Eq)]
 pub struct SecretKey {
@@ -136,7 +139,7 @@ impl SecretKey {
 
     /// fingerprint returns a 256bit unique identifier for this key. For HPKE,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         self.public_key().fingerprint()
     }
 
@@ -251,10 +254,10 @@ impl PublicKey {
 
     /// fingerprint returns a 256bit unique identifier for this key. For HPKE,
     /// that is the SHA256 hash of the raw public key.
-    pub fn fingerprint(&self) -> [u8; 32] {
+    pub fn fingerprint(&self) -> Fingerprint {
         let mut hasher = sha2::Sha256::new();
         hasher.update(self.to_bytes());
-        hasher.finalize().into()
+        Fingerprint(hasher.finalize().into())
     }
 
     /// seal creates a standalone cryptographic construct encrypted to this public
@@ -298,6 +301,22 @@ impl PublicKey {
     }
 }
 
+/// Fingerprint contains a 256-bit unique identifier for an HPKE key.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Fingerprint([u8; FINGERPRINT_SIZE]);
+
+impl Fingerprint {
+    /// from_bytes converts a 32-byte array into a fingerprint.
+    pub fn from_bytes(bytes: &[u8; FINGERPRINT_SIZE]) -> Self {
+        Self(*bytes)
+    }
+
+    /// to_bytes converts a fingerprint into a 32-byte array.
+    pub fn to_bytes(&self) -> [u8; FINGERPRINT_SIZE] {
+        self.0
+    }
+}
+
 /// Validates an ML-KEM-768 encapsulation key by checking that all polynomial
 /// coefficients are in the valid range [0, 3329).
 ///