feat(rust/signed-doc): add type for Key ID

* update example
+ tidy up metadata module

Author: saibatizoku

rust/signed_doc/examples/mk_signed_doc.rs

@@ -6,6 +6,7 @@ use std::{
     fs::{read_to_string, File},
     io::{Read, Write},
     path::PathBuf,
+    str::FromStr,
 };
 
 use clap::Parser;
@@ -14,7 +15,7 @@ use ed25519_dalek::{
     ed25519::signature::Signer,
     pkcs8::{DecodePrivateKey, DecodePublicKey},
 };
-use signed_doc::{DocumentRef, Metadata, UuidV7};
+use signed_doc::{DocumentRef, Kid, Metadata, UuidV7};
 
 fn main() {
     if let Err(err) = Cli::parse().exec() {
@@ -132,9 +133,13 @@ impl Cli {
                 store_cose_file(cose, &doc)?;
             },
             Self::Verify { pk, doc, schema } => {
-                let pk = load_public_key_from_file(&pk)?;
-                let schema = load_schema_from_file(&schema)?;
-                let cose = load_cose_from_file(&doc)?;
+                let pk = load_public_key_from_file(&pk)
+                    .map_err(|e| anyhow::anyhow!("Failed to load public key from file: {e}"))?;
+                let schema = load_schema_from_file(&schema).map_err(|e| {
+                    anyhow::anyhow!("Failed to load document schema from file: {e}")
+                })?;
+                let cose = load_cose_from_file(&doc)
+                    .map_err(|e| anyhow::anyhow!("Failed to load COSE SIGN from file: {e}"))?;
                 validate_cose(&cose, &pk, &schema)?;
                 println!("Document is valid.");
             },
@@ -294,11 +299,15 @@ fn validate_cose(
     validate_json(&json_doc, schema)?;
 
     for sign in &cose.signatures {
+        let key_id = sign.protected.header.key_id.clone();
         anyhow::ensure!(
-            !sign.protected.header.key_id.is_empty(),
+            !key_id.is_empty(),
             "COSE missing signature protected header `kid` field "
         );
 
+        let kid_str = String::from_utf8_lossy(&key_id);
+        let kid = Kid::from_str(&kid_str)?;
+        println!("Signature Key ID: {kid}");
         let data_to_sign = cose.tbs_data(&[], sign);
         let signature_bytes = sign.signature.as_slice().try_into().map_err(|_| {
             anyhow::anyhow!(
@@ -307,6 +316,11 @@ fn validate_cose(
                 sign.signature.len()
             )
         })?;
+        println!(
+            "Verifying Key Len({}): 0x{}",
+            pk.as_bytes().len(),
+            hex::encode(pk.as_bytes())
+        );
         let signature = ed25519_dalek::Signature::from_bytes(signature_bytes);
         pk.verify_strict(&data_to_sign, &signature)?;
     }

rust/signed_doc/src/lib.rs

@@ -9,8 +9,10 @@ use std::{
 use coset::{CborSerializable, TaggedCborSerializable};
 
 mod metadata;
+mod signature;
 
 pub use metadata::{DocumentRef, Metadata, UuidV7};
+pub use signature::Kid;
 
 /// Catalyst Signed Document Content Encoding Key.
 const CONTENT_ENCODING_KEY: &str = "Content-Encoding";
@@ -30,9 +32,14 @@ impl Display for CatalystSignedDocument {
     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
         writeln!(f, "{}", self.inner.metadata)?;
         writeln!(f, "JSON Payload {:#}\n", self.inner.payload)?;
-        writeln!(f, "Signatures [")?;
+        writeln!(f, "Signature Information [")?;
         for signature in &self.inner.signatures {
-            writeln!(f, "  0x{:#}", hex::encode(signature.signature.as_slice()))?;
+            writeln!(
+                f,
+                "  {} 0x{:#}",
+                String::from_utf8_lossy(&signature.protected.header.key_id),
+                hex::encode(signature.signature.as_slice())
+            )?;
         }
         writeln!(f, "]\n")?;
         writeln!(f, "Content Errors [")?;
@@ -52,7 +59,7 @@ struct InnerCatalystSignedDocument {
     payload: serde_json::Value,
     /// Signatures
     signatures: Vec<coset::CoseSignature>,
-    /// Raw COSE Sign bytes
+    /// Raw COSE Sign data
     cose_sign: coset::CoseSign,
     /// Content Errors found when parsing the Document
     content_errors: Vec<String>,

rust/signed_doc/src/metadata/mod.rs

@@ -84,6 +84,7 @@ impl Metadata {
         &self.content_errors
     }
 }
+
 impl Display for Metadata {
     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
         writeln!(f, "Metadata {{")?;

rust/signed_doc/src/signature/kid/authority.rs

@@ -0,0 +1,37 @@
+//! COSE Signature Protected Header `kid` URI Authority.
+
+use std::{
+    fmt::{Display, Formatter},
+    str::FromStr,
+};
+
+/// URI Authority
+#[derive(Debug, Clone)]
+pub enum Authority {
+    /// Cardano Blockchain
+    Cardano,
+    /// Midnight Blockchain
+    Midnight,
+}
+
+impl FromStr for Authority {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "cardano" => Ok(Authority::Cardano),
+            "midnight" => Ok(Authority::Midnight),
+            _ => Err(anyhow::anyhow!("Unknown Authority: {s}")),
+        }
+    }
+}
+
+impl Display for Authority {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        let authority = match self {
+            Self::Cardano => "cardano",
+            Self::Midnight => "midnight",
+        };
+        write!(f, "{authority}")
+    }
+}

rust/signed_doc/src/signature/kid/key_version.rs

@@ -0,0 +1,19 @@
+//! COSE Signature Protected Header `kid` Role0 Key Version.
+
+use std::fmt::{Display, Formatter};
+
+/// Version of the Role0 Key.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KeyVersion(u16);
+
+impl From<u16> for KeyVersion {
+    fn from(value: u16) -> Self {
+        Self(value)
+    }
+}
+
+impl Display for KeyVersion {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(f, "{}", self.0)
+    }
+}

rust/signed_doc/src/signature/kid/mod.rs

@@ -0,0 +1,114 @@
+//! COSE Signature Protected Header `kid`.
+mod authority;
+mod key_version;
+mod role;
+mod role0_pk;
+
+use std::{
+    fmt::{Display, Formatter},
+    str::FromStr,
+};
+
+use authority::Authority;
+use key_version::KeyVersion;
+use role::Role;
+use role0_pk::Role0PublicKey;
+
+/// Catalyst Signed Document Key ID
+///
+/// Key ID associated with a `COSE` Signature that is structured as a Universal Resource
+/// Identifier (`URI`).
+#[derive(Debug, Clone)]
+pub struct Kid {
+    /// URI Authority
+    authority: Authority,
+    /// Role0 Public Key.
+    role0_public_key: Role0PublicKey,
+    /// User Role specified for the current document.
+    role: Role,
+    /// Role0 Public Key Version
+    key_version: KeyVersion,
+}
+
+impl Kid {
+    /// URI scheme for Catalyst
+    const URI_SCHEME_PREFIX: &str = "catalyst_kid://";
+}
+
+impl FromStr for Kid {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> anyhow::Result<Self> {
+        let Some(uri) = s.strip_prefix(Self::URI_SCHEME_PREFIX) else {
+            anyhow::bail!("Key ID scheme must be '{}': {s}", Self::URI_SCHEME_PREFIX);
+        };
+
+        let Some((authority_str, key_role_version)) = uri.split_once('/') else {
+            anyhow::bail!("Key ID must have an authority: {uri}");
+        };
+
+        let authority = Authority::from_str(authority_str)
+            .map_err(|e| anyhow::anyhow!("Invalid Authority: {authority_str}. {e}"))?;
+
+        let Some((role0_key_str, role_version)) = key_role_version.split_once('/') else {
+            anyhow::bail!("Expected Key ID have an Role0 Key set: {key_role_version}");
+        };
+
+        let role0_public_key = Role0PublicKey::from_str(role0_key_str)
+            .map_err(|e| anyhow::anyhow!("Invalid Role0 Public Key: {role0_key_str}. {e}"))?;
+
+        let Some((role_str, key_version_str)) = role_version.split_once('/') else {
+            anyhow::bail!("Expected Key ID have a role set");
+        };
+
+        let role = Role::from_str(role_str)
+            .map_err(|e| anyhow::anyhow!("Invalid Role: {role_str}. {e}"))?;
+
+        let key_version: KeyVersion = u16::from_str(key_version_str)
+            .map_err(|e| anyhow::anyhow!("Invalid Key Version: {key_version_str}. {e}"))?
+            .into();
+
+        Ok(Kid {
+            authority,
+            role0_public_key,
+            role,
+            key_version,
+        })
+    }
+}
+
+impl Display for Kid {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(
+            f,
+            "{}{}/{}/{}/{}",
+            Self::URI_SCHEME_PREFIX,
+            self.authority,
+            self.role0_public_key,
+            self.role,
+            self.key_version,
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::str::FromStr;
+
+    use super::Kid;
+
+    const KID_STR: &str = "catalyst_kid://cardano/0x0063ce08eccfdd5c93dd5cc9ca959fe669fd762fa816d70438efa90c0a75288c/3/0";
+
+    #[test]
+    fn test_kid_uri_from_str() {
+        let kid_str = KID_STR;
+        assert!(Kid::from_str(kid_str).is_ok());
+    }
+
+    #[test]
+    fn test_kid_uri_from_str_and_back() {
+        let kid_str = KID_STR;
+        let kid = Kid::from_str(kid_str).unwrap();
+        assert_eq!(KID_STR, format!("{kid}"));
+    }
+}

rust/signed_doc/src/signature/kid/role.rs

@@ -0,0 +1,42 @@
+//! COSE Signature Protected Header `kid` URI Catalyst User Role.
+
+use std::{
+    fmt::{Display, Formatter},
+    str::FromStr,
+};
+
+/// Project Catalyst User Role associated with the signature.
+///
+/// <https://github.com/input-output-hk/catalyst-CIPs/blob/x509-catalyst-role-definitions/CIP-XXXX/README.md>
+#[repr(u16)]
+#[derive(Debug, Copy, Clone)]
+pub enum Role {
+    /// Voter = 0
+    Zero,
+    /// Delegated Representative = 1
+    One,
+    /// Voter Delegation = 2
+    Two,
+    /// Proposer = 3
+    Three,
+}
+
+impl FromStr for Role {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "0" => Ok(Role::Zero),
+            "1" => Ok(Role::One),
+            "2" => Ok(Role::Two),
+            "3" => Ok(Role::Three),
+            _ => Err(anyhow::anyhow!("Unknown Role: {}", s)),
+        }
+    }
+}
+
+impl Display for Role {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(f, "{}", *self as u16)
+    }
+}

rust/signed_doc/src/signature/kid/role0_pk.rs

@@ -0,0 +1,40 @@
+//! COSE Signature Protected Header `kid` URI Role0 Public Key.
+
+use std::{
+    fmt::{Display, Formatter},
+    str::FromStr,
+};
+
+/// Role0 Public Key.
+#[derive(Debug, Clone)]
+pub struct Role0PublicKey([u8; 32]);
+
+impl FromStr for Role0PublicKey {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let Some(role0_hex) = s.strip_prefix("0x") else {
+            anyhow::bail!("Role0 Public Key hex string must start with '0x': {}", s);
+        };
+        let role0_key = hex::decode(role0_hex)
+            .map_err(|e| anyhow::anyhow!("Role0 Public Key is not a valid hex string: {}", e))?;
+        if role0_key.len() != 32 {
+            anyhow::bail!(
+                "Role0 Public Key must have 32 bytes: {role0_hex}, len: {}",
+                role0_key.len()
+            );
+        }
+        let role0 = role0_key.try_into().map_err(|e| {
+            anyhow::anyhow!(
+                "Unable to read Role0 Public Key, this should never happen. Eror: {e:?}"
+            )
+        })?;
+        Ok(Role0PublicKey(role0))
+    }
+}
+
+impl Display for Role0PublicKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(f, "0x{}", hex::encode(self.0))
+    }
+}

rust/signed_doc/src/signature/mod.rs

@@ -0,0 +1,4 @@
+//! Catalyst Signed Document COSE Signature information.
+mod kid;
+
+pub use kid::Kid;