Skip to main content

passkey_rp/
cose.rs

1use std::{collections::BTreeMap, fmt};
2
3use p256::ecdsa::signature::Verifier;
4use p256::ecdsa::{Signature, VerifyingKey};
5use serde::{Deserialize, Serialize};
6use serde_cbor_2::de::Deserializer as CborDeserializer;
7use serde_cbor_2::value::Value;
8
9use crate::PasskeyError;
10
11const MAX_COSE_KEY_BYTES: usize = 16 * 1024;
12
13/// COSE algorithms accepted for credential public keys.
14#[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize)]
15#[non_exhaustive]
16pub enum CoseAlgorithm {
17    /// ECDSA over P-256 with SHA-256.
18    Es256,
19}
20
21impl CoseAlgorithm {
22    /// Returns the algorithm identifier registered by COSE.
23    #[must_use]
24    pub fn id(self) -> i64 {
25        match self {
26            Self::Es256 => -7,
27        }
28    }
29}
30
31/// A validated `WebAuthn` credential public key.
32///
33/// Key material is intentionally opaque so callers cannot construct a value
34/// that bypasses algorithm, curve, coordinate-length, or curve-point
35/// validation. `Debug` output never includes key coordinates.
36///
37/// Serde deserialization repeats curve-point validation. For application
38/// persistence, prefer serializing the containing [`crate::StoredCredential`],
39/// whose wire representation is versioned.
40#[derive(Clone, Eq, PartialEq)]
41pub struct PublicKey {
42    material: PublicKeyMaterial,
43}
44
45#[derive(Clone, Eq, PartialEq)]
46enum PublicKeyMaterial {
47    Es256 { x: [u8; 32], y: [u8; 32] },
48}
49
50impl fmt::Debug for PublicKey {
51    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
52        formatter
53            .debug_struct("PublicKey")
54            .field("algorithm", &self.algorithm())
55            .field("material", &"[REDACTED]")
56            .finish()
57    }
58}
59
60impl PublicKey {
61    /// Parses and validates a complete CBOR-encoded COSE key.
62    ///
63    /// Only EC2 keys using P-256 and ES256 are accepted. The input must contain
64    /// exactly one key with no trailing CBOR value and may not exceed 16 KiB.
65    ///
66    /// # Errors
67    ///
68    /// Returns a [`PasskeyError`] when the CBOR is malformed, the key shape or
69    /// curve point is invalid, the key type or algorithm is unsupported, the
70    /// input has trailing data, or the size limit is exceeded.
71    pub fn from_cose_key(input: &[u8]) -> Result<Self, PasskeyError> {
72        if input.len() > MAX_COSE_KEY_BYTES {
73            return Err(PasskeyError::PayloadTooLarge);
74        }
75        let (key, consumed) = Self::parse_cose_key_prefix(input)?;
76        if consumed != input.len() {
77            return Err(PasskeyError::InvalidPublicKey);
78        }
79        Ok(key)
80    }
81
82    /// Returns the validated credential key algorithm.
83    #[must_use]
84    pub fn algorithm(&self) -> CoseAlgorithm {
85        match self.material {
86            PublicKeyMaterial::Es256 { .. } => CoseAlgorithm::Es256,
87        }
88    }
89
90    /// Encodes the validated key as a CBOR COSE key.
91    ///
92    /// # Errors
93    ///
94    /// Returns [`PasskeyError::InvalidCbor`] if serialization fails.
95    pub fn to_cose_key(&self) -> Result<Vec<u8>, PasskeyError> {
96        let mut map = BTreeMap::new();
97        match &self.material {
98            PublicKeyMaterial::Es256 { x, y } => {
99                map.insert(Value::Integer(1), Value::Integer(2));
100                map.insert(
101                    Value::Integer(3),
102                    Value::Integer(i128::from(CoseAlgorithm::Es256.id())),
103                );
104                map.insert(Value::Integer(-1), Value::Integer(1));
105                map.insert(Value::Integer(-2), Value::Bytes(x.to_vec()));
106                map.insert(Value::Integer(-3), Value::Bytes(y.to_vec()));
107            }
108        }
109        serde_cbor_2::to_vec(&Value::Map(map)).map_err(|_| PasskeyError::InvalidCbor)
110    }
111
112    pub(crate) fn parse_cose_key_prefix(input: &[u8]) -> Result<(Self, usize), PasskeyError> {
113        let mut deserializer = CborDeserializer::from_slice(input);
114        let value = Value::deserialize(&mut deserializer).map_err(|_| PasskeyError::InvalidCbor)?;
115        let consumed = deserializer.byte_offset();
116        if consumed > MAX_COSE_KEY_BYTES {
117            return Err(PasskeyError::PayloadTooLarge);
118        }
119        let map = as_map(&value)?;
120
121        let kty = expect_i64(map, 1)?;
122        if kty != 2 {
123            return Err(PasskeyError::UnsupportedCoseKey);
124        }
125
126        let alg = expect_i64(map, 3)?;
127        if alg != CoseAlgorithm::Es256.id() {
128            return Err(PasskeyError::UnsupportedCoseAlgorithm);
129        }
130
131        let crv = expect_i64(map, -1)?;
132        if crv != 1 {
133            return Err(PasskeyError::UnsupportedCoseKey);
134        }
135
136        let x = expect_bytes(map, -2)?;
137        let y = expect_bytes(map, -3)?;
138        if x.len() != 32 || y.len() != 32 {
139            return Err(PasskeyError::InvalidPublicKey);
140        }
141
142        Ok((Self::es256(x, y)?, consumed))
143    }
144
145    fn es256(x: &[u8], y: &[u8]) -> Result<Self, PasskeyError> {
146        validate_es256_coordinates(x, y)?;
147        let x = <[u8; 32]>::try_from(x).map_err(|_| PasskeyError::InvalidPublicKey)?;
148        let y = <[u8; 32]>::try_from(y).map_err(|_| PasskeyError::InvalidPublicKey)?;
149        Ok(Self {
150            material: PublicKeyMaterial::Es256 { x, y },
151        })
152    }
153
154    pub(crate) fn verify(&self, data: &[u8], der_signature: &[u8]) -> Result<(), PasskeyError> {
155        match &self.material {
156            PublicKeyMaterial::Es256 { x, y } => verify_es256(x, y, data, der_signature),
157        }
158    }
159}
160
161fn verify_es256(x: &[u8], y: &[u8], data: &[u8], der_signature: &[u8]) -> Result<(), PasskeyError> {
162    let key = es256_verifying_key(x, y)?;
163    let signature =
164        Signature::from_der(der_signature).map_err(|_| PasskeyError::InvalidSignature)?;
165    key.verify(data, &signature)
166        .map_err(|_| PasskeyError::InvalidSignature)
167}
168
169fn validate_es256_coordinates(x: &[u8], y: &[u8]) -> Result<(), PasskeyError> {
170    es256_verifying_key(x, y).map(|_| ())
171}
172
173fn es256_verifying_key(x: &[u8], y: &[u8]) -> Result<VerifyingKey, PasskeyError> {
174    if x.len() != 32 || y.len() != 32 {
175        return Err(PasskeyError::InvalidPublicKey);
176    }
177    let mut sec1 = Vec::with_capacity(65);
178    sec1.push(0x04);
179    sec1.extend_from_slice(x);
180    sec1.extend_from_slice(y);
181
182    VerifyingKey::from_sec1_bytes(&sec1).map_err(|_| PasskeyError::InvalidPublicKey)
183}
184
185impl<'de> Deserialize<'de> for PublicKey {
186    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
187    where
188        D: serde::Deserializer<'de>,
189    {
190        #[derive(Deserialize)]
191        #[serde(deny_unknown_fields)]
192        enum Wire {
193            Es256 { x: Vec<u8>, y: Vec<u8> },
194        }
195
196        match Wire::deserialize(deserializer)? {
197            Wire::Es256 { x, y } => Self::es256(&x, &y).map_err(serde::de::Error::custom),
198        }
199    }
200}
201
202impl Serialize for PublicKey {
203    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
204    where
205        S: serde::Serializer,
206    {
207        #[derive(Serialize)]
208        enum Wire<'a> {
209            Es256 { x: &'a [u8; 32], y: &'a [u8; 32] },
210        }
211
212        match &self.material {
213            PublicKeyMaterial::Es256 { x, y } => Wire::Es256 { x, y }.serialize(serializer),
214        }
215    }
216}
217
218fn as_map(value: &Value) -> Result<&BTreeMap<Value, Value>, PasskeyError> {
219    match value {
220        Value::Map(map) => Ok(map),
221        _ => Err(PasskeyError::InvalidPublicKey),
222    }
223}
224
225fn expect_i64(map: &BTreeMap<Value, Value>, key: i64) -> Result<i64, PasskeyError> {
226    let value = map
227        .get(&Value::Integer(i128::from(key)))
228        .ok_or(PasskeyError::InvalidPublicKey)?;
229    match value {
230        Value::Integer(value) => i64::try_from(*value).map_err(|_| PasskeyError::InvalidPublicKey),
231        _ => Err(PasskeyError::InvalidPublicKey),
232    }
233}
234
235fn expect_bytes(map: &BTreeMap<Value, Value>, key: i64) -> Result<&[u8], PasskeyError> {
236    let value = map
237        .get(&Value::Integer(i128::from(key)))
238        .ok_or(PasskeyError::InvalidPublicKey)?;
239    match value {
240        Value::Bytes(bytes) => Ok(bytes),
241        _ => Err(PasskeyError::InvalidPublicKey),
242    }
243}
244
245#[cfg(test)]
246mod tests {
247    use std::collections::BTreeMap;
248
249    use p256::ecdsa::signature::Signer;
250    use p256::ecdsa::{Signature, SigningKey};
251    use serde_cbor_2::value::Value;
252
253    use super::PublicKey;
254
255    pub(crate) fn test_signing_key() -> SigningKey {
256        SigningKey::from_slice(&[3; 32]).expect("test key should be valid")
257    }
258
259    pub(crate) fn cose_key_for(signing_key: &SigningKey) -> Vec<u8> {
260        serde_cbor_2::to_vec(&Value::Map(cose_key_map(signing_key)))
261            .expect("COSE key should encode")
262    }
263
264    fn cose_key_map(signing_key: &SigningKey) -> BTreeMap<Value, Value> {
265        let public = signing_key.verifying_key().to_encoded_point(false);
266        let x = public.x().expect("x should exist").to_vec();
267        let y = public.y().expect("y should exist").to_vec();
268        let mut map = BTreeMap::new();
269        map.insert(Value::Integer(1), Value::Integer(2));
270        map.insert(Value::Integer(3), Value::Integer(-7));
271        map.insert(Value::Integer(-1), Value::Integer(1));
272        map.insert(Value::Integer(-2), Value::Bytes(x));
273        map.insert(Value::Integer(-3), Value::Bytes(y));
274        map
275    }
276
277    #[test]
278    fn es256_cose_key_parses_and_verifies_der_signatures() {
279        let signing_key = test_signing_key();
280        let cose = cose_key_for(&signing_key);
281        let public_key = PublicKey::from_cose_key(&cose).expect("COSE should parse");
282        assert_eq!(public_key.to_cose_key().expect("COSE should encode"), cose);
283
284        let data = b"authenticator-data-and-client-data-hash";
285        let signature: Signature = signing_key.sign(data);
286        public_key
287            .verify(data, signature.to_der().as_bytes())
288            .expect("signature should verify");
289
290        assert!(matches!(
291            public_key.verify(b"tampered", signature.to_der().as_bytes()),
292            Err(crate::PasskeyError::InvalidSignature)
293        ));
294    }
295
296    #[test]
297    fn public_key_deserialization_rejects_invalid_curve_points() {
298        let value = serde_json::json!({
299            "Es256": { "x": vec![0; 32], "y": vec![0; 32] }
300        });
301        assert!(serde_json::from_value::<PublicKey>(value).is_err());
302    }
303
304    #[test]
305    fn public_key_persistence_shape_remains_tagged_and_validated() {
306        let public_key = PublicKey::from_cose_key(&cose_key_for(&test_signing_key()))
307            .expect("COSE should parse");
308        let value = serde_json::to_value(&public_key).expect("key should serialize");
309        assert!(value["Es256"]["x"].is_array());
310        assert!(value["Es256"]["y"].is_array());
311        assert_eq!(
312            serde_json::from_value::<PublicKey>(value).expect("key should deserialize"),
313            public_key
314        );
315    }
316
317    #[test]
318    fn public_key_parser_rejects_trailing_cbor_data() {
319        let mut cose = cose_key_for(&test_signing_key());
320        cose.push(0xf6);
321        assert!(matches!(
322            PublicKey::from_cose_key(&cose),
323            Err(crate::PasskeyError::InvalidPublicKey)
324        ));
325    }
326
327    #[test]
328    fn public_key_parser_rejects_oversized_input_before_decoding() {
329        let oversized = vec![0; super::MAX_COSE_KEY_BYTES + 1];
330        assert!(matches!(
331            PublicKey::from_cose_key(&oversized),
332            Err(crate::PasskeyError::PayloadTooLarge)
333        ));
334    }
335
336    #[test]
337    fn public_key_parser_rejects_invalid_cose_parameters() {
338        let signing_key = test_signing_key();
339
340        let mut map = cose_key_map(&signing_key);
341        map.insert(Value::Integer(1), Value::Integer(1));
342        assert!(matches!(
343            PublicKey::from_cose_key(
344                &serde_cbor_2::to_vec(&Value::Map(map)).expect("COSE should encode")
345            ),
346            Err(crate::PasskeyError::UnsupportedCoseKey)
347        ));
348
349        let mut map = cose_key_map(&signing_key);
350        map.insert(Value::Integer(3), Value::Integer(-257));
351        assert!(matches!(
352            PublicKey::from_cose_key(
353                &serde_cbor_2::to_vec(&Value::Map(map)).expect("COSE should encode")
354            ),
355            Err(crate::PasskeyError::UnsupportedCoseAlgorithm)
356        ));
357
358        let mut map = cose_key_map(&signing_key);
359        map.insert(Value::Integer(-1), Value::Integer(2));
360        assert!(matches!(
361            PublicKey::from_cose_key(
362                &serde_cbor_2::to_vec(&Value::Map(map)).expect("COSE should encode")
363            ),
364            Err(crate::PasskeyError::UnsupportedCoseKey)
365        ));
366    }
367
368    #[test]
369    fn public_key_parser_rejects_missing_or_invalid_coordinates() {
370        let signing_key = test_signing_key();
371
372        let mut missing = cose_key_map(&signing_key);
373        missing.remove(&Value::Integer(-3));
374        assert!(matches!(
375            PublicKey::from_cose_key(
376                &serde_cbor_2::to_vec(&Value::Map(missing)).expect("COSE should encode")
377            ),
378            Err(crate::PasskeyError::InvalidPublicKey)
379        ));
380
381        let mut short = cose_key_map(&signing_key);
382        short.insert(Value::Integer(-2), Value::Bytes(vec![0; 31]));
383        assert!(matches!(
384            PublicKey::from_cose_key(
385                &serde_cbor_2::to_vec(&Value::Map(short)).expect("COSE should encode")
386            ),
387            Err(crate::PasskeyError::InvalidPublicKey)
388        ));
389
390        let mut invalid_point = cose_key_map(&signing_key);
391        invalid_point.insert(Value::Integer(-2), Value::Bytes(vec![0; 32]));
392        invalid_point.insert(Value::Integer(-3), Value::Bytes(vec![0; 32]));
393        assert!(matches!(
394            PublicKey::from_cose_key(
395                &serde_cbor_2::to_vec(&Value::Map(invalid_point)).expect("COSE should encode")
396            ),
397            Err(crate::PasskeyError::InvalidPublicKey)
398        ));
399    }
400
401    #[test]
402    fn public_key_parser_distinguishes_malformed_cbor_and_wrong_shape() {
403        assert!(matches!(
404            PublicKey::from_cose_key(&[0xff]),
405            Err(crate::PasskeyError::InvalidCbor)
406        ));
407        assert!(matches!(
408            PublicKey::from_cose_key(&[0x80]),
409            Err(crate::PasskeyError::InvalidPublicKey)
410        ));
411    }
412}