feat: implement primary key binding signing; cleanup fn names

hko-s · hko-s · commit 976a03ce45fd · 2025-05-26T14:17:12.000+02:00
Also:
- Unroll subkey/primary key binding signature verification
- Drop non-functioning primary key binding signer from packet::PublicKey
diff --git a/src/composed/key/builder.rs b/src/composed/key/builder.rs
@@ -1371,7 +1371,7 @@ mod tests {
 
         embedded
             .unwrap()
-            .verify_backwards_key_binding(
+            .verify_primary_key_binding(
                 &subkey.key.public_key(),
                 &signed_secret_key.primary_key.public_key(),
             )
diff --git a/src/composed/key/public.rs b/src/composed/key/public.rs
@@ -92,11 +92,12 @@ impl PublicSubkey {
         PublicSubkey { key, keyflags }
     }
 
+    /// Produce a Subkey Binding Signature (Type ID 0x18), to bind this subkey to a primary key
     pub fn sign<R, K, P>(
         self,
         mut rng: R,
-        sec_key: &K,
-        pub_key: &P,
+        primary_sec_key: &K,
+        primary_pub_key: &P,
         key_pw: &Password,
     ) -> Result<SignedPublicSubKey>
     where
@@ -110,20 +111,22 @@ impl PublicSubkey {
                 chrono::Utc::now().trunc_subsecs(0),
             ))?,
             Subpacket::regular(SubpacketData::KeyFlags(self.keyflags))?,
-            Subpacket::regular(SubpacketData::IssuerFingerprint(sec_key.fingerprint()))?,
+            Subpacket::regular(SubpacketData::IssuerFingerprint(
+                primary_sec_key.fingerprint(),
+            ))?,
         ];
 
-        let mut config = match sec_key.version() {
+        let mut config = match primary_sec_key.version() {
             KeyVersion::V4 => SignatureConfig::v4(
                 SignatureType::SubkeyBinding,
-                sec_key.algorithm(),
-                sec_key.hash_alg(),
+                primary_sec_key.algorithm(),
+                primary_sec_key.hash_alg(),
             ),
             KeyVersion::V6 => SignatureConfig::v6(
                 &mut rng,
                 SignatureType::SubkeyBinding,
-                sec_key.algorithm(),
-                sec_key.hash_alg(),
+                primary_sec_key.algorithm(),
+                primary_sec_key.hash_alg(),
             )?,
             v => unsupported_err!("unsupported key version: {:?}", v),
         };
@@ -132,12 +135,14 @@ impl PublicSubkey {
 
         // If the version of the issuer is greater than 4, this subpacket MUST NOT be included in
         // the signature.
-        if sec_key.version() <= KeyVersion::V4 {
-            config.unhashed_subpackets =
-                vec![Subpacket::regular(SubpacketData::Issuer(sec_key.key_id()))?];
+        if primary_sec_key.version() <= KeyVersion::V4 {
+            config.unhashed_subpackets = vec![Subpacket::regular(SubpacketData::Issuer(
+                primary_sec_key.key_id(),
+            ))?];
         }
 
-        let signatures = vec![config.sign_key_binding(sec_key, pub_key, key_pw, &key)?];
+        let signatures =
+            vec![config.sign_subkey_binding(primary_sec_key, primary_pub_key, key_pw, &key)?];
 
         Ok(SignedPublicSubKey { key, signatures })
     }
diff --git a/src/composed/key/secret.rs b/src/composed/key/secret.rs
@@ -75,11 +75,12 @@ impl SecretSubkey {
         SecretSubkey { key, keyflags }
     }
 
+    /// Produce a Subkey Binding Signature (Type ID 0x18), to bind this subkey to a primary key
     pub fn sign<R, K, P>(
         self,
         mut rng: R,
-        sec_key: &K,
-        pub_key: &P,
+        primary_sec_key: &K,
+        primary_pub_key: &P,
         key_pw: &Password,
     ) -> Result<SignedSecretSubKey>
     where
@@ -89,17 +90,17 @@ impl SecretSubkey {
     {
         let key = self.key;
 
-        let mut config = match sec_key.version() {
+        let mut config = match primary_sec_key.version() {
             KeyVersion::V4 => SignatureConfig::v4(
                 SignatureType::SubkeyBinding,
-                sec_key.algorithm(),
-                sec_key.hash_alg(),
+                primary_sec_key.algorithm(),
+                primary_sec_key.hash_alg(),
             ),
             KeyVersion::V6 => SignatureConfig::v6(
                 &mut rng,
                 SignatureType::SubkeyBinding,
-                sec_key.algorithm(),
-                sec_key.hash_alg(),
+                primary_sec_key.algorithm(),
+                primary_sec_key.hash_alg(),
             )?,
             v => unsupported_err!("unsupported key version: {:?}", v),
         };
@@ -109,18 +110,25 @@ impl SecretSubkey {
                 chrono::Utc::now().trunc_subsecs(0),
             ))?,
             Subpacket::regular(SubpacketData::KeyFlags(self.keyflags))?,
-            Subpacket::regular(SubpacketData::IssuerFingerprint(sec_key.fingerprint()))?,
+            Subpacket::regular(SubpacketData::IssuerFingerprint(
+                primary_sec_key.fingerprint(),
+            ))?,
         ];
 
         // If the version of the issuer is greater than 4, this subpacket MUST NOT be included in
         // the signature.
-        if sec_key.version() <= KeyVersion::V4 {
-            config.unhashed_subpackets =
-                vec![Subpacket::regular(SubpacketData::Issuer(sec_key.key_id()))?];
+        if primary_sec_key.version() <= KeyVersion::V4 {
+            config.unhashed_subpackets = vec![Subpacket::regular(SubpacketData::Issuer(
+                primary_sec_key.key_id(),
+            ))?];
         }
 
-        let signatures =
-            vec![config.sign_key_binding(sec_key, pub_key, key_pw, key.public_key())?];
+        let signatures = vec![config.sign_subkey_binding(
+            primary_sec_key,
+            primary_pub_key,
+            key_pw,
+            key.public_key(),
+        )?];
 
         Ok(SignedSecretSubKey { key, signatures })
     }
diff --git a/src/composed/signed_key/public.rs b/src/composed/signed_key/public.rs
@@ -282,14 +282,14 @@ impl SignedPublicSubKey {
 
         // TODO: It's sufficient if the latest binding signature is valid
         for sig in &self.signatures {
-            sig.verify_key_binding(key, &self.key)?;
+            sig.verify_subkey_binding(key, &self.key)?;
 
             // If the subkey is signing capable, check the embedded backward signature
             if sig.key_flags().sign() {
                 let Some(backsig) = sig.embedded_signature() else {
                     bail!("missing embedded signature for signing capable subkey");
                 };
-                backsig.verify_backwards_key_binding(&self.key, key)?;
+                backsig.verify_primary_key_binding(&self.key, key)?;
             }
         }
 
diff --git a/src/composed/signed_key/secret.rs b/src/composed/signed_key/secret.rs
@@ -296,7 +296,7 @@ impl SignedSecretSubKey {
         ensure!(!self.signatures.is_empty(), "missing subkey bindings");
 
         for sig in &self.signatures {
-            sig.verify_key_binding(key, self.key.public_key())?;
+            sig.verify_subkey_binding(key, self.key.public_key())?;
         }
 
         Ok(())
diff --git a/src/packet/key/secret.rs b/src/packet/key/secret.rs
@@ -1,5 +1,6 @@
 use std::io::BufRead;
 
+use chrono::SubsecRound;
 use generic_array::GenericArray;
 use log::debug;
 use rand::{CryptoRng, Rng};
@@ -181,6 +182,49 @@ impl SecretSubkey {
         sign(rng, key, key_pw, SignatureType::SubkeyBinding, pub_key)
     }
 
+    /// Produce a Primary Key Binding Signature over the primary `pub_key`.
+    ///
+    /// This signature is used in an embedded signature subpacket to show that the subkey is
+    /// willing to be associated with the primary.
+    pub fn sign_primary_key_binding<R: CryptoRng + Rng, P>(
+        &self,
+        mut rng: R,
+        pub_key: &P,
+        key_pw: &Password,
+    ) -> Result<Signature>
+    where
+        P: PublicKeyTrait + Serialize,
+    {
+        let mut config = match self.version() {
+            KeyVersion::V4 => {
+                SignatureConfig::v4(SignatureType::KeyBinding, self.algorithm(), self.hash_alg())
+            }
+            KeyVersion::V6 => SignatureConfig::v6(
+                &mut rng,
+                SignatureType::KeyBinding,
+                self.algorithm(),
+                self.hash_alg(),
+            )?,
+            v => unsupported_err!("unsupported key version: {:?}", v),
+        };
+
+        config.hashed_subpackets = vec![
+            Subpacket::regular(SubpacketData::SignatureCreationTime(
+                chrono::Utc::now().trunc_subsecs(0),
+            ))?,
+            Subpacket::regular(SubpacketData::IssuerFingerprint(self.fingerprint()))?,
+        ];
+
+        // If the version of the issuer is greater than 4, this subpacket MUST NOT be included in
+        // the signature.
+        if self.version() <= KeyVersion::V4 {
+            config.unhashed_subpackets =
+                vec![Subpacket::regular(SubpacketData::Issuer(self.key_id()))?];
+        }
+
+        config.sign_primary_key_binding(self, &self.public_key(), key_pw, &pub_key)
+    }
+
     pub fn unlock<G, T>(&self, pw: &Password, work: G) -> Result<Result<T>>
     where
         G: FnOnce(&PublicParams, &PlainSecretParams) -> Result<T>,
diff --git a/src/packet/signature/config.rs b/src/packet/signature/config.rs
@@ -295,30 +295,33 @@ impl SignatureConfig {
         Signature::from_config(self, signed_hash_value, signature)
     }
 
-    /// Sign a key binding.
-    pub fn sign_key_binding<K, P, L>(
+    /// Sign a subkey binding that associates a subkey with a primary key.
+    ///
+    /// The primary key is expected as `signer`, the subkey as `signee`.
+    ///
+    /// Produces a "Subkey Binding Signature (type ID 0x18)"
+    pub fn sign_subkey_binding<K, P, L>(
         self,
-        signing_key: &K,
-        signing_pub_key: &P,
-        key_pw: &Password,
-        key: &L,
+        signer: &K,
+        signer_pub: &P,
+        signer_pw: &Password,
+        signee: &L,
     ) -> Result<Signature>
     where
         K: SecretKeyTrait,
         P: PublicKeyTrait + Serialize,
         L: PublicKeyTrait + Serialize,
     {
         ensure!(
-            (self.version() == SignatureVersion::V4 && signing_key.version() == KeyVersion::V4)
-                || (self.version() == SignatureVersion::V6
-                    && signing_key.version() == KeyVersion::V6),
+            (self.version() == SignatureVersion::V4 && signer.version() == KeyVersion::V4)
+                || (self.version() == SignatureVersion::V6 && signer.version() == KeyVersion::V6),
             "signature version {:?} not allowed for signer key version {:?}",
             self.version(),
-            signing_key.version()
+            signer.version()
         );
         debug!(
-            "signing key binding: {:#?} - {:#?} - {:#?}",
-            self, signing_key, key
+            "signing subkey binding: {:#?} - {:#?} - {:#?}",
+            self, signer, signee
         );
 
         let mut hasher = self.hash_alg.new_hasher()?;
@@ -327,18 +330,64 @@ impl SignatureConfig {
             hasher.update(salt.as_ref())
         }
 
-        // Signing Key
-        serialize_for_hashing(signing_pub_key, &mut hasher)?;
+        serialize_for_hashing(signer_pub, &mut hasher)?; // primary
+        serialize_for_hashing(signee, &mut hasher)?; // subkey
 
-        // Key being bound
-        serialize_for_hashing(key, &mut hasher)?;
+        let len = self.hash_signature_data(&mut hasher)?;
+        hasher.update(&self.trailer(len)?);
+
+        let hash = &hasher.finalize()[..];
+        let signed_hash_value = [hash[0], hash[1]];
+        let signature = signer.create_signature(signer_pw, self.hash_alg, hash)?;
+
+        Signature::from_config(self, signed_hash_value, signature)
+    }
+
+    /// Sign a primary key binding, or "back signature"
+    /// (with this signature, the subkey signals that it wants to be associated with the primary).
+    ///
+    /// The subkey is expected as `signer`, the primary key as `signee`.
+    ///
+    /// Produces a "Primary Key Binding Signature (type ID 0x19)"
+    pub fn sign_primary_key_binding<K, P, L>(
+        self,
+        signer: &K,
+        signer_pub: &P,
+        signer_pw: &Password,
+        signee: &L,
+    ) -> Result<Signature>
+    where
+        K: SecretKeyTrait,
+        P: PublicKeyTrait + Serialize,
+        L: PublicKeyTrait + Serialize,
+    {
+        ensure!(
+            (self.version() == SignatureVersion::V4 && signer.version() == KeyVersion::V4)
+                || (self.version() == SignatureVersion::V6 && signer.version() == KeyVersion::V6),
+            "signature version {:?} not allowed for signer key version {:?}",
+            self.version(),
+            signer.version()
+        );
+        debug!(
+            "signing primary key binding: {:#?} - {:#?} - {:#?}",
+            self, signer, signee
+        );
+
+        let mut hasher = self.hash_alg.new_hasher()?;
+
+        if let SignatureVersionSpecific::V6 { salt } = &self.version_specific {
+            hasher.update(salt.as_ref())
+        }
+
+        serialize_for_hashing(signee, &mut hasher)?; // primary
+        serialize_for_hashing(signer_pub, &mut hasher)?; // subkey
 
         let len = self.hash_signature_data(&mut hasher)?;
         hasher.update(&self.trailer(len)?);
 
         let hash = &hasher.finalize()[..];
         let signed_hash_value = [hash[0], hash[1]];
-        let signature = signing_key.create_signature(key_pw, self.hash_alg, hash)?;
+        let signature = signer.create_signature(signer_pw, self.hash_alg, hash)?;
 
         Signature::from_config(self, signed_hash_value, signature)
     }
diff --git a/src/packet/signature/types.rs b/src/packet/signature/types.rs

Original file line number	Diff line number	Diff line change
`@@ -1371,7 +1371,7 @@ mod tests {`
`1371`	`1371`
`1372`	`1372`	`embedded`
`1373`	`1373`	`.unwrap()`
`1374`		`- .verify_backwards_key_binding(`
	`1374`	`+ .verify_primary_key_binding(`
`1375`	`1375`	`&subkey.key.public_key(),`
`1376`	`1376`	`&signed_secret_key.primary_key.public_key(),`
`1377`	`1377`	`)`
Original file line number	Diff line number	Diff line change
`@@ -282,14 +282,14 @@ impl SignedPublicSubKey {`
`282`	`282`
`283`	`283`	`// TODO: It's sufficient if the latest binding signature is valid`
`284`	`284`	`for sig in &self.signatures {`
`285`		`- sig.verify_key_binding(key, &self.key)?;`
	`285`	`+ sig.verify_subkey_binding(key, &self.key)?;`
`286`	`286`
`287`	`287`	`// If the subkey is signing capable, check the embedded backward signature`
`288`	`288`	`if sig.key_flags().sign() {`
`289`	`289`	`let Some(backsig) = sig.embedded_signature() else {`
`290`	`290`	`bail!("missing embedded signature for signing capable subkey");`
`291`	`291`	`};`
`292`		`- backsig.verify_backwards_key_binding(&self.key, key)?;`
	`292`	`+ backsig.verify_primary_key_binding(&self.key, key)?;`
`293`	`293`	`}`
`294`	`294`	`}`
`295`	`295`
Original file line number	Diff line number	Diff line change
`@@ -296,7 +296,7 @@ impl SignedSecretSubKey {`
`296`	`296`	`ensure!(!self.signatures.is_empty(), "missing subkey bindings");`
`297`	`297`
`298`	`298`	`for sig in &self.signatures {`
`299`		`- sig.verify_key_binding(key, self.key.public_key())?;`
	`299`	`+ sig.verify_subkey_binding(key, self.key.public_key())?;`
`300`	`300`	`}`
`301`	`301`
`302`	`302`	`Ok(())`