Skip to main content

bitwarden_crypto/signing/
verifying_key.rs

1//! A verifying key is the public part of a signature key pair. It is used to verify signatures.
2//!
3//! This implements the lowest layer of the signature module, verifying signatures on raw byte
4//! arrays.
5
6use ciborium::{Value, value::Integer};
7use coset::{
8    CborSerializable, MlDsaVariant, RegisteredLabel, RegisteredLabelWithPrivate,
9    iana::{
10        AkpKeyParameter, Algorithm, EllipticCurve, EnumI64, KeyOperation, KeyParameter, KeyType,
11        OkpKeyParameter,
12    },
13};
14use ml_dsa::{MlDsa44, signature::Verifier};
15
16use super::{SignatureAlgorithm, ed25519_verifying_key, key_id, mldsa44_verifying_key};
17use crate::{
18    CoseKeyBytes, CoseKeyThumbprint, CryptoError,
19    content_format::CoseKeyContentFormat,
20    cose::{CoseKeyThumbprintExt, CoseSerializable, thumbprint_from_required_params},
21    error::{EncodingError, SignatureError},
22    keys::KeyId,
23    slow_crypto_span::{SlowCryptoOp, SlowCryptoSpan},
24};
25
26/// A `VerifyingKey` without the key id. This enum contains a variant for each supported signature
27/// scheme.
28pub(super) enum RawVerifyingKey {
29    Ed25519(ed25519_dalek::VerifyingKey),
30    MlDsa44(Box<ml_dsa::VerifyingKey<MlDsa44>>),
31}
32
33/// A verifying key is a public key used for verifying signatures. It can be published to other
34/// users, who can use it to verify that messages were signed by the holder of the corresponding
35/// `SigningKey`.
36pub struct VerifyingKey {
37    pub(super) id: KeyId,
38    pub(super) inner: RawVerifyingKey,
39}
40
41impl std::fmt::Debug for VerifyingKey {
42    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
43        let key_suffix = match &self.inner {
44            RawVerifyingKey::Ed25519(_) => "Ed25519",
45            RawVerifyingKey::MlDsa44(_) => "MlDsa44",
46        };
47        let mut debug_struct = f.debug_struct(format!("VerifyingKey::{}", key_suffix).as_str());
48        debug_struct.field("id", &self.id);
49        debug_struct.finish()
50    }
51}
52
53impl VerifyingKey {
54    /// Returns the signature scheme used by the verifying key.
55    pub fn algorithm(&self) -> SignatureAlgorithm {
56        match &self.inner {
57            RawVerifyingKey::Ed25519(_) => SignatureAlgorithm::Ed25519,
58            RawVerifyingKey::MlDsa44(_) => SignatureAlgorithm::MlDsa44,
59        }
60    }
61
62    /// Verifies the signature of the given data, for the given namespace.
63    /// This should never be used directly, but only through the `verify` method, to enforce
64    /// strong domain separation of the signatures.
65    pub(super) fn verify_raw(&self, signature: &[u8], data: &[u8]) -> Result<(), CryptoError> {
66        match &self.inner {
67            RawVerifyingKey::Ed25519(key) => {
68                let sig = ed25519_dalek::Signature::from_bytes(
69                    signature
70                        .try_into()
71                        .map_err(|_| SignatureError::InvalidSignature)?,
72                );
73                key.verify_strict(data, &sig)
74                    .map_err(|_| SignatureError::InvalidSignature.into())
75            }
76            RawVerifyingKey::MlDsa44(key) => {
77                let _span = SlowCryptoSpan::start(SlowCryptoOp::MlDsaVerify);
78                let sig = ml_dsa::Signature::<MlDsa44>::try_from(signature)
79                    .map_err(|_| SignatureError::InvalidSignature)?;
80                key.verify(data, &sig)
81                    .map_err(|_| SignatureError::InvalidSignature.into())
82            }
83        }
84    }
85}
86
87impl CoseSerializable<CoseKeyContentFormat> for VerifyingKey {
88    fn to_cose(&self) -> CoseKeyBytes {
89        match &self.inner {
90            RawVerifyingKey::Ed25519(key) => coset::CoseKeyBuilder::new_okp_key()
91                .key_id((&self.id).into())
92                .algorithm(Algorithm::EdDSA)
93                .param(
94                    OkpKeyParameter::Crv.to_i64(), // Elliptic curve identifier
95                    Value::Integer(Integer::from(EllipticCurve::Ed25519.to_i64())),
96                )
97                // Note: X does not refer to the X coordinate of the public key curve point, but
98                // to the verifying key (signature public key), as represented by the curve spec. In
99                // the case of Ed25519, this is the compressed Y coordinate. This
100                // was ill-defined in earlier drafts of the standard. https://www.rfc-editor.org/rfc/rfc9053.html#name-octet-key-pair
101                .param(
102                    OkpKeyParameter::X.to_i64(), // Verifying key (digital signature public key)
103                    Value::Bytes(key.to_bytes().to_vec()),
104                )
105                .add_key_op(KeyOperation::Verify)
106                .build()
107                .to_vec()
108                .expect("Verifying key is always serializable")
109                .into(),
110            RawVerifyingKey::MlDsa44(key) => coset::CoseKeyBuilder::new_mldsa_pub_key(
111                MlDsaVariant::MlDsa44,
112                key.encode().to_vec(),
113            )
114            .key_id((&self.id).into())
115            .add_key_op(KeyOperation::Verify)
116            .build()
117            .to_vec()
118            .expect("Verifying key is always serializable")
119            .into(),
120        }
121    }
122
123    fn from_cose(bytes: &CoseKeyBytes) -> Result<Self, EncodingError>
124    where
125        Self: Sized,
126    {
127        let cose_key = coset::CoseKey::from_slice(bytes.as_ref())
128            .map_err(|_| EncodingError::InvalidCoseEncoding)?;
129
130        let algorithm = cose_key
131            .alg
132            .as_ref()
133            .ok_or(EncodingError::MissingValue("COSE key algorithm"))?;
134        match (&cose_key.kty, algorithm) {
135            (
136                RegisteredLabel::Assigned(KeyType::OKP),
137                RegisteredLabelWithPrivate::Assigned(Algorithm::EdDSA),
138            ) => Ok(VerifyingKey {
139                id: key_id(&cose_key)?,
140                inner: RawVerifyingKey::Ed25519(ed25519_verifying_key(&cose_key)?),
141            }),
142            (
143                RegisteredLabel::Assigned(KeyType::AKP),
144                RegisteredLabelWithPrivate::Assigned(Algorithm::ML_DSA_44),
145            ) => Ok(VerifyingKey {
146                id: key_id(&cose_key)?,
147                inner: RawVerifyingKey::MlDsa44(Box::new(mldsa44_verifying_key(&cose_key)?)),
148            }),
149            _ => Err(EncodingError::UnsupportedValue(
150                "COSE key type or algorithm",
151            )),
152        }
153    }
154}
155
156impl CoseKeyThumbprintExt for VerifyingKey {
157    fn thumbprint(&self) -> Result<CoseKeyThumbprint, CryptoError> {
158        let params = match &self.inner {
159            // https://datatracker.ietf.org/doc/rfc9679/
160            RawVerifyingKey::Ed25519(key) => vec![
161                (
162                    KeyParameter::Kty.to_i64(),
163                    Value::Integer(Integer::from(KeyType::OKP.to_i64())),
164                ),
165                (
166                    OkpKeyParameter::Crv.to_i64(),
167                    Value::Integer(Integer::from(EllipticCurve::Ed25519.to_i64())),
168                ),
169                // `x` is the compressed Ed25519 public key (see the note in `to_cose`).
170                (
171                    OkpKeyParameter::X.to_i64(),
172                    Value::Bytes(key.to_bytes().to_vec()),
173                ),
174            ],
175            // https://datatracker.ietf.org/doc/rfc9964/
176            RawVerifyingKey::MlDsa44(key) => vec![
177                (
178                    KeyParameter::Kty.to_i64(),
179                    Value::Integer(Integer::from(KeyType::AKP.to_i64())),
180                ),
181                (
182                    KeyParameter::Alg.to_i64(),
183                    Value::Integer(Integer::from(Algorithm::ML_DSA_44.to_i64())),
184                ),
185                (
186                    AkpKeyParameter::Pub.to_i64(),
187                    Value::Bytes(key.encode().to_vec()),
188                ),
189            ],
190        };
191        Ok(thumbprint_from_required_params(params))
192    }
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198
199    const VERIFYING_KEY: &[u8] = &[
200        166, 1, 1, 2, 80, 55, 131, 40, 191, 230, 137, 76, 182, 184, 139, 94, 152, 45, 63, 13, 71,
201        3, 39, 4, 129, 2, 32, 6, 33, 88, 32, 93, 213, 35, 177, 81, 219, 226, 241, 147, 140, 238,
202        32, 34, 183, 213, 107, 227, 92, 75, 84, 208, 47, 198, 80, 18, 188, 172, 145, 184, 154, 26,
203        170,
204    ];
205    const SIGNED_DATA_RAW: &[u8] = &[
206        247, 239, 74, 181, 75, 54, 137, 225, 2, 158, 14, 0, 61, 210, 254, 208, 255, 16, 8, 81, 173,
207        33, 59, 67, 204, 31, 45, 38, 147, 118, 228, 84, 235, 252, 104, 38, 194, 173, 62, 52, 9,
208        184, 1, 22, 113, 134, 154, 108, 24, 83, 78, 2, 23, 235, 80, 22, 57, 110, 100, 24, 151, 33,
209        186, 12,
210    ];
211    // Same key as `MLDSA44_VERIFYING_KEY` in `signing_key.rs`'s tests, kept in sync so both
212    // modules pin the same underlying key.
213    const MLDSA44_VERIFYING_KEY: &str = "a501070250e11a339366953128787c1b2c16b6945803382f048102205905205cc3620a551a0213972ad845e4930f4ecdfe1d10a81ffde8cdd1a0fffc38eefa3fd659028cad345c823074e870ffb9ed12e1d08a407db8f2431f2b75d3934e8a2662c033c8337aec1afdc1bb1babf185d709365a3057b41774dcf08e3877d4fdca2111b778ed53f6cf5b2d46d4a2427ee72c1c08a87e4e231794d8418513bae5e57d65428c41fa0b1031d6bc3b07a15f3349c4361a627c736d4e86fe3285e74277117f57df4bc53a98afcd55a77aee7e1b1465abb72e68ab2da897ceecfb8f7d4f0ced0dcf39506b31a46b795c8cee3ee6d789a1f8f7c35eb20eb17c6af5402954ec6eb41576eb2d65078b9755aca0e3af11f438df2a8abfb35d75b3fd151099735908f9b15a42f5211d4ea691014142adae9c9fdf0cf704bc4197d10f8f5f60be29abc805c6fa0f6192e4d12c8f7d50289e0ea796217f453730ca5af1ac3eb3c8ccc4bc161925806506160489a175a07bcf0f9323a4d05013117ba5f3c6d5bc6f6feadcfd093e40efbc19b8648cc8251d6d2faca5da7b506ec4b9e66b821c4176205b9ce0cd4c358b5e2a742c93b9ddb481feca10bb213925e1c661149c04e84a7809e440c190977cf015f12b6259581c368c70eec633985b78c1108f7ff42d1cb03d9ce957f705b871b57c3705ada6d6b386e647a3bacf846da4feb5c508bc4960c2d1f5378700b118fd2ea20db2790aafb7d39043bd2ab6f8902111a45fb181be8e83fa5a4c43e5d2d56797042f8d0c3e832857db0fccc61e7ea3616b70da0439eedf1a1a40196435c99b24e2ab07f8515272972faeafb2670ff66b237b00bf092da2de98a99ed4319498b4d8385aa68e36974b9c31d44b2dfebda78b3465b859296c63958cbcb587dd82e04c51986fdb9e0f3a2941ef1eac8d3b08c2fcd32ceb9dc434096c7f03e529c82132cd7e242a5668520baf00332a2de8a4f52420378350993bd35c573ba4f32e5ad89ddca1b7b3ddb0a21b0faa3674de2bdcb3519b86ed33a8939e6c7cbb9b9493279db28739b163916776bdcc40f7368000b5cefb3425b77dce84a957642319cb95226e30e119a4e455795b24e627b69881dc87084c3c1972fd170c87bcf4cc228beb4083a063e7a44c4fa8490f48457d12e4cf44b84ef41556e53599c5b4a030b4d07ee6594b6830ac0cb7823f908130fd6d2f3f9b5d65012f8e9abeeb74f4042a2a8c05fcb28f968f15f4230dfce034595141c770c200c1fd710e86d9b4d820ee0f015762526cb5a148e18874a385acef6f9efb77d43bc14936e8aa966dd53a1d2403a820f735fd60f5867570fa93ffae3214dc9ac93b2c191115a0045f71923249a10fdd8aa6ca35f6420fa1c80a867d7f54ef54b465f151de0b9a040c31d7373c81565d503cc1332dc6808533171ff2513a7139dad63b1848ba46f09255e81f7edab6208e62d17955aa43e27c74b5ed77b8d3c66ea50c478760e0db5c1b8970a22e74a29bd07bed0ba7e9c7a1866531889fa516ffd66c363d9558b2716d67809d85f16b4e18f456d5ec2343d08ea601da77676246c26432bfcd935c0d80a1e32fc41b380dff041a2629683540d5f2b9d9ef6101114242508c68987a44a0169bf8fbdabf1954bd54d745f1d66b7367848e43e0c94a6d88ccbdfd65333301d34d06d400e643e36c681c7f475b0026967d68e58af2fbf4800ca7aad6a43a3782b1d9452226ef881d50fcbb7b4df0c8c3b15ca80321cbb928fa8dce4048f01fc48121eaa1da0a954a6150c3d2e42add1b4f58910c2db0869a5481d469ef4bdccec3e7c0a21253fd19ce941b16808bf14fca6fec2b1ba7f771580235034e5ca95763721d6add9aa3914f476b37097ce67b000d5d";
214
215    #[test]
216    fn test_cose_roundtrip_encode_verifying() {
217        let verifying_key = VerifyingKey::from_cose(&CoseKeyBytes::from(VERIFYING_KEY)).unwrap();
218        let cose = verifying_key.to_cose();
219        let parsed_key = VerifyingKey::from_cose(&cose).unwrap();
220
221        assert_eq!(verifying_key.to_cose(), parsed_key.to_cose());
222    }
223
224    #[test]
225    fn test_testvector() {
226        let verifying_key = VerifyingKey::from_cose(&CoseKeyBytes::from(VERIFYING_KEY)).unwrap();
227        assert_eq!(verifying_key.algorithm(), SignatureAlgorithm::Ed25519);
228
229        verifying_key
230            .verify_raw(SIGNED_DATA_RAW, b"Test message")
231            .unwrap();
232    }
233
234    #[test]
235    fn test_invalid_testvector() {
236        let verifying_key = VerifyingKey::from_cose(&CoseKeyBytes::from(VERIFYING_KEY)).unwrap();
237        assert_eq!(verifying_key.algorithm(), SignatureAlgorithm::Ed25519);
238
239        // This should fail, as the signed object is not valid for the given verifying key.
240        assert!(
241            verifying_key
242                .verify_raw(SIGNED_DATA_RAW, b"Invalid message")
243                .is_err()
244        );
245    }
246
247    #[test]
248    fn test_thumbprint_ed25519_vector() {
249        let verifying_key = VerifyingKey::from_cose(&CoseKeyBytes::from(VERIFYING_KEY)).unwrap();
250        assert_eq!(
251            verifying_key.thumbprint().unwrap().to_hex(),
252            "ea38af8eb96812daa5217a342946814921f0ebc74edaa1e9832cbc4daf9ba803"
253        );
254    }
255
256    #[test]
257    fn test_thumbprint_mldsa44_vector() {
258        let verifying_key = VerifyingKey::from_cose(&CoseKeyBytes::from(
259            hex::decode(MLDSA44_VERIFYING_KEY).unwrap(),
260        ))
261        .unwrap();
262        assert_eq!(
263            verifying_key.thumbprint().unwrap().to_hex(),
264            "fb932d165a6ff31caf0537ecb3c267dcbdac69773de6b739211c00e68969e233"
265        );
266    }
267}