didbot_key/

secp256r1.rs

//! P-256 verification, and deliberately no P-256 signing.
//!
//! atproto accepts two signing curves. This server mints secp256k1 keys and
//! only secp256k1 keys, for the reason the crate documentation gives: `k256`
//! normalizes `s` on the way out and refuses a high `s` on the way in, and
//! `p256` does neither, so a P-256 *signer* here would emit a malleable
//! signature about half the time and a relay would refuse it.
//!
//! Verifying is the other direction and the argument does not apply to it. A
//! key that arrives from somewhere else is not ours to normalize; it is ours
//! to judge, and the judgement is the same three questions asked of a
//! secp256k1 signature — a 64-byte compact pair, a low `s`, and a
//! verification that succeeds. The low-`s` check that `k256` performs
//! internally is written out by hand here, because `p256` will happily verify
//! a high-`s` signature that atproto refuses.
//!
//! Half of the network's accounts sign with this curve, so a server that can
//! read another server's commit needs it. Nothing in this crate can produce
//! one.
//!
//! ```
//! use didbot_key::secp256r1;
//!
//! // A key from the W3C did:key vectors, which mint nothing here.
//! let key = secp256r1::VerifyingKey::from_did_key(
//!     "did:key:zDnaeTiq1PdzvZXUaMdezchcMJQpBdH2VN4pgrrEhMCCbmwSb",
//! )?;
//! assert!(key.to_did_key().starts_with("did:key:zDn"));
//! # Ok::<(), didbot_key::KeyError>(())
//! ```

use core::fmt;

use jacquard_common::types::crypto::{multikey, KeyCodec, PublicKey};
use p256::ecdsa::signature::Verifier;
use p256::elliptic_curve::scalar::IsHigh;

use crate::{KeyError, COMPRESSED_LEN, DID_KEY_PREFIX};

/// The multicodec for a P-256 public key.
const P256_CODEC: u64 = 0x1200;

/// A P-256 ECDSA signature over SHA-256, in 64-byte compact `r || s` form.
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct Signature(p256::ecdsa::Signature);

impl Signature {
    /// Parses a 64-byte compact `r || s` signature.
    ///
    /// A high-`s` signature parses. Refusing malleability is
    /// [`VerifyingKey::verify`]'s job, so that a signature from elsewhere can
    /// be read and then honestly reported as one atproto does not accept.
    pub fn from_bytes(bytes: &[u8; 64]) -> Result<Self, KeyError> {
        p256::ecdsa::Signature::from_slice(bytes)
            .map(Self)
            .map_err(|_| KeyError::InvalidSignature)
    }

    /// The 64-byte compact `r || s` encoding.
    pub fn to_bytes(&self) -> [u8; 64] {
        self.0.to_bytes().into()
    }

    /// Whether `s` is in the lower half of the curve order, as atproto
    /// requires.
    pub fn is_low_s(&self) -> bool {
        !bool::from(self.0.s().is_high())
    }
}

impl fmt::Debug for Signature {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("secp256r1::Signature(")?;
        for byte in self.to_bytes() {
            write!(f, "{byte:02x}")?;
        }
        f.write_str(")")
    }
}

/// A P-256 public key that arrived from somewhere else.
///
/// There is no private counterpart in this crate by design.
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct VerifyingKey(p256::ecdsa::VerifyingKey);

impl VerifyingKey {
    /// The `publicKeyMultibase` form: base58btc over the `0x1200` multicodec
    /// and the 33-byte SEC1 compressed point.
    pub fn to_multibase(&self) -> String {
        multikey(P256_CODEC, self.0.to_encoded_point(true).as_bytes())
    }

    /// The `did:key` URI form.
    pub fn to_did_key(&self) -> String {
        format!("{DID_KEY_PREFIX}{}", self.to_multibase())
    }

    /// Parses a `did:key:z...` URI naming a P-256 key.
    pub fn from_did_key(did: &str) -> Result<Self, KeyError> {
        let multibase = did
            .strip_prefix(DID_KEY_PREFIX)
            .ok_or(KeyError::NotDidKey)?;
        Self::from_multibase(multibase)
    }

    /// Parses a bare `publicKeyMultibase` string naming a P-256 key.
    ///
    /// Refuses any other curve and any encoding but the 33-byte compressed
    /// point, exactly as the secp256k1 reader does: a key that round-trips
    /// through this crate is one atproto will accept.
    pub fn from_multibase(multibase: &str) -> Result<Self, KeyError> {
        if !multibase.starts_with('z') {
            return Err(KeyError::NotBase58Btc);
        }
        let public = PublicKey::decode_owned(multibase)?;
        if public.codec != KeyCodec::P256 {
            return Err(KeyError::WrongCurve {
                codec: public.codec,
            });
        }
        if public.bytes.len() != COMPRESSED_LEN {
            return Err(KeyError::NotCompressed {
                got: public.bytes.len(),
            });
        }
        // Decoded here rather than through `jacquard-common`'s `to_p256`,
        // which sits behind a feature this workspace does not turn on. The
        // bytes are a SEC1 point either way and the check above has already
        // established the codec and the length.
        let point = p256::PublicKey::from_sec1_bytes(public.bytes.as_ref())
            .map_err(|_| KeyError::InvalidPublicKey)?;
        Ok(Self(point.into()))
    }

    /// Verifies a signature over `message`, refusing a high `s`.
    ///
    /// The low-`s` check is written out rather than inherited. `p256` accepts
    /// a high-`s` signature and atproto does not, so a verifier that leaned on
    /// the library the way the secp256k1 one does would accept exactly the
    /// signatures the protocol exists to rule out.
    pub fn verify(&self, message: &[u8], sig: &Signature) -> Result<(), KeyError> {
        if !sig.is_low_s() {
            return Err(KeyError::VerificationFailed);
        }
        self.0
            .verify(message, &sig.0)
            .map_err(|_| KeyError::VerificationFailed)
    }
}

impl fmt::Debug for VerifyingKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("secp256r1::VerifyingKey")
            .field(&self.to_did_key())
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The one vector the W3C file carries, so the module has a check that
    /// does not depend on the conformance target being run.
    const W3C_DID: &str = "did:key:zDnaeTiq1PdzvZXUaMdezchcMJQpBdH2VN4pgrrEhMCCbmwSb";

    #[test]
    fn a_p256_did_key_round_trips() {
        let key = VerifyingKey::from_did_key(W3C_DID).expect("the vector's key decodes");
        assert_eq!(key.to_did_key(), W3C_DID);
    }

    #[test]
    fn a_secp256k1_key_is_refused_by_curve() {
        let ours = crate::SigningKey::generate().verifying_key().to_did_key();
        assert!(matches!(
            VerifyingKey::from_did_key(&ours),
            Err(KeyError::WrongCurve { .. })
        ));
    }

    #[test]
    fn a_uri_that_is_not_a_did_key_is_refused() {
        assert!(matches!(
            VerifyingKey::from_did_key("did:web:example.com"),
            Err(KeyError::NotDidKey)
        ));
    }
}