didbot_key/

lib.rs

//! Custodial signing keys for agent accounts.
//!
//! This personal data server holds an agent's signing key the way any hosted
//! atproto PDS holds keys for its users. Agents never hold long-lived key
//! material; they ask the server to sign, and the server decides whether to.
//! [`SigningKey::to_bytes`] and [`SigningKey::from_bytes`] exist for that
//! custody, not for handing keys out.
//!
//! # Why secp256k1 and nothing else
//!
//! atproto accepts two signing curves, secp256k1 (`0xE7`) and P-256
//! (`0x1200`), but it requires every ECDSA signature to be *low-S*: of the two
//! mathematically valid `s` values for a signature, only the one below half
//! the curve order is accepted. This removes the trivial malleability where
//! `(r, n - s)` verifies just as well as `(r, s)` and would give the same
//! record two different valid signatures.
//!
//! The `k256` crate enforces that for us in both directions. Its
//! `SignPrimitive` normalizes `s` before returning a signature, and its
//! `VerifyPrimitive` rejects a signature whose `s` is high. The `p256` crate
//! does neither: it emits whichever `s` the math produced, so around half of
//! the signatures a P-256 implementation would produce here are malleable and
//! a relay would reject them. Getting P-256 right means normalizing by hand on
//! every sign and re-checking on every verify, with a silent, intermittent,
//! half-the-time failure as the cost of forgetting once.
//!
//! So this crate *signs* with secp256k1 only, and the low-S property is
//! covered by a test rather than by this paragraph. It can still **read** a
//! P-256 key and judge a P-256 signature, which is a different thing: see
//! [`secp256r1`], where the normalization this crate refuses to do on the way
//! out is done by hand on the way in. A server that will one day verify
//! another server's commit needs both curves; nothing here can mint the
//! second one.
//!
//! # Encoding
//!
//! Public keys leave this crate as `did:key:z...`, or as the bare multibase
//! string that goes in a DID document's `publicKeyMultibase`. atproto requires
//! the **33-byte SEC1 compressed** point encoding there. Nothing in the stack
//! compresses on your behalf — `k256` will happily hand back a 65-byte
//! uncompressed point, and `jacquard-common` accepts both on decode — so
//! [`VerifyingKey::to_multibase`] asks for compression explicitly and
//! [`VerifyingKey::from_multibase`] refuses anything else.
//!
//! ```
//! use didbot_key::{SigningKey, VerifyingKey};
//!
//! let key = SigningKey::generate();
//! let sig = key.sign(b"record");
//! assert_eq!(sig.to_bytes().len(), 64);
//!
//! let did = key.verifying_key().to_did_key();
//! assert!(did.starts_with("did:key:z"));
//! VerifyingKey::from_did_key(&did)?.verify(b"record", &sig)?;
//! # Ok::<(), didbot_key::KeyError>(())
//! ```

#![forbid(unsafe_code)]

pub mod secp256r1;

use core::fmt;

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

/// Multicodec code for a secp256k1 public key.
const SECP256K1_CODEC: u64 = 0xE7;

/// URI scheme prefix for the `did:key` method.
const DID_KEY_PREFIX: &str = "did:key:";

/// Length of a SEC1 compressed secp256k1 point.
const COMPRESSED_LEN: usize = 33;

/// Anything that can go wrong handling a key or a signature.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum KeyError {
    /// The 32 bytes are not a valid secp256k1 scalar: zero, or at or above the
    /// curve order.
    #[error("not a valid secp256k1 private key")]
    InvalidPrivateKey,

    /// The point bytes are not on the curve, or are otherwise malformed.
    #[error("not a valid secp256k1 public key")]
    InvalidPublicKey,

    /// The string did not start with `did:key:`.
    #[error("not a did:key URI")]
    NotDidKey,

    /// The multibase string was not base58btc, which atproto requires. Other
    /// multibase alphabets decode fine but are not interoperable here.
    #[error("multibase string is not base58btc (expected a leading 'z')")]
    NotBase58Btc,

    /// The multibase or multicodec framing did not decode.
    #[error("could not decode multikey: {0}")]
    Multikey(#[from] jacquard_common::types::crypto::CryptoError),

    /// The key decoded, but it is for a curve this crate does not sign with.
    /// See the module docs for why there is only one.
    #[error("expected a secp256k1 key, got {codec:?}")]
    WrongCurve {
        /// The codec that was actually present.
        codec: KeyCodec,
    },

    /// A secp256k1 key in the 65-byte uncompressed form, or some other length.
    #[error("expected a 33-byte compressed key, got {got} bytes")]
    NotCompressed {
        /// Length of the key bytes that were present.
        got: usize,
    },

    /// The 64 bytes are not a well-formed `r || s` pair.
    #[error("not a valid compact signature")]
    InvalidSignature,

    /// The signature is well-formed but does not match this key and message.
    /// A high-S signature lands here too: `k256` rejects those on verify.
    #[error("signature did not verify")]
    VerificationFailed,
}

/// A secp256k1 ECDSA signature over SHA-256, in 64-byte compact `r || s` form.
///
/// Every value of this type that this crate produces is low-S; see the module
/// docs.
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct Signature(k256::ecdsa::Signature);

impl Signature {
    /// The 64-byte compact `r || s` encoding, which is what atproto puts in a
    /// record's `sig` field.
    pub fn to_bytes(&self) -> [u8; 64] {
        self.0.to_bytes().into()
    }

    /// Parses a 64-byte compact `r || s` signature.
    ///
    /// This accepts a high-S signature — rejecting malleability is
    /// [`VerifyingKey::verify`]'s job, so that a signature from elsewhere can
    /// be parsed and then be honestly reported as failing to verify.
    pub fn from_bytes(bytes: &[u8; 64]) -> Result<Self, KeyError> {
        k256::ecdsa::Signature::from_slice(bytes)
            .map(Self)
            .map_err(|_| KeyError::InvalidSignature)
    }

    /// 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())
    }

    /// The underlying `k256` signature, for callers that need `r`, `s`, or DER.
    pub fn as_k256(&self) -> &k256::ecdsa::Signature {
        &self.0
    }
}

impl From<k256::ecdsa::Signature> for Signature {
    fn from(inner: k256::ecdsa::Signature) -> Self {
        Self(inner)
    }
}

impl fmt::Debug for Signature {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Signatures are public, but the default k256 rendering is a wall of
        // scalar internals. Hex of the wire form is what a log reader wants.
        f.write_str("Signature(")?;
        for byte in self.to_bytes() {
            write!(f, "{byte:02x}")?;
        }
        f.write_str(")")
    }
}

/// A secp256k1 private key held on behalf of an agent.
///
/// The inner `k256` key zeroizes on drop. That is a floor, not a guarantee:
/// anything that goes through [`SigningKey::to_bytes`] is an ordinary array
/// and is the caller's problem.
#[derive(Clone)]
pub struct SigningKey(k256::ecdsa::SigningKey);

impl SigningKey {
    /// Generates a new key from the operating system's CSPRNG.
    pub fn generate() -> Self {
        Self(k256::ecdsa::SigningKey::random(&mut rand_core::OsRng))
    }

    /// Loads a key from its 32-byte big-endian scalar, as written by
    /// [`SigningKey::to_bytes`].
    ///
    /// Fails for zero and for anything at or above the curve order, so a
    /// corrupted or truncated store surfaces here rather than as an unusable
    /// key later.
    pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self, KeyError> {
        k256::ecdsa::SigningKey::from_bytes(bytes.into())
            .map(Self)
            .map_err(|_| KeyError::InvalidPrivateKey)
    }

    /// The 32-byte big-endian scalar, for writing to custodial storage.
    ///
    /// This is the whole secret. Nothing else in this crate exposes it.
    pub fn to_bytes(&self) -> [u8; 32] {
        self.0.to_bytes().into()
    }

    /// Signs a message with ECDSA over SHA-256.
    ///
    /// The nonce is deterministic (RFC 6979), so the same key and message give
    /// the same signature, and a bad RNG at signing time cannot leak the key.
    pub fn sign(&self, message: &[u8]) -> Signature {
        Signature(self.0.sign(message))
    }

    /// The public half.
    pub fn verifying_key(&self) -> VerifyingKey {
        VerifyingKey(*self.0.verifying_key())
    }
}

impl fmt::Debug for SigningKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Written by hand so that no derive, now or after a future field is
        // added, can put the scalar into a log line or a panic message. The
        // public identifier is enough to tell two keys apart while debugging.
        f.debug_struct("SigningKey")
            .field("public", &self.verifying_key().to_did_key())
            .finish_non_exhaustive()
    }
}

/// The public half of a [`SigningKey`].
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct VerifyingKey(k256::ecdsa::VerifyingKey);

impl VerifyingKey {
    /// The `publicKeyMultibase` value for a DID document verification method:
    /// base58btc multibase over the multicodec prefix `0xE7` and the 33-byte
    /// SEC1 compressed point.
    ///
    /// Compression is requested explicitly here because `k256` can produce
    /// either form and an uncompressed key is not valid in atproto.
    pub fn to_multibase(&self) -> String {
        multikey(SECP256K1_CODEC, self.0.to_encoded_point(true).as_bytes())
    }

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

    /// Parses a `did:key:z...` URI.
    ///
    /// `jacquard-common` decodes bare multibase strings, not URIs, so the
    /// prefix is stripped here.
    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.
    ///
    /// Rejects any curve other than secp256k1 and any encoding other than the
    /// 33-byte compressed point, so that a key which 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::Secp256k1 {
            return Err(KeyError::WrongCurve {
                codec: public.codec,
            });
        }
        if public.bytes.len() != COMPRESSED_LEN {
            return Err(KeyError::NotCompressed {
                got: public.bytes.len(),
            });
        }
        let point = public.to_k256().map_err(|_| KeyError::InvalidPublicKey)?;
        Ok(Self(point.into()))
    }

    /// Verifies a signature over `message`.
    ///
    /// A high-S signature fails here, because `k256` rejects one internally.
    pub fn verify(&self, message: &[u8], sig: &Signature) -> Result<(), KeyError> {
        self.0
            .verify(message, &sig.0)
            .map_err(|_| KeyError::VerificationFailed)
    }

    /// The underlying `k256` key, for callers doing their own point work.
    pub fn as_k256(&self) -> &k256::ecdsa::VerifyingKey {
        &self.0
    }
}

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

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

    use jacquard_common::types::crypto::decode_uvarint;

    #[test]
    fn sign_and_verify_round_trip() {
        let key = SigningKey::generate();
        let message = b"quernstone attestation payload";
        let sig = key.sign(message);
        assert!(key.verifying_key().verify(message, &sig).is_ok());
    }

    #[test]
    fn signature_does_not_verify_against_another_message() {
        let key = SigningKey::generate();
        let sig = key.sign(b"first message");
        let err = key.verifying_key().verify(b"second message", &sig);
        assert!(matches!(err, Err(KeyError::VerificationFailed)));
    }

    #[test]
    fn signature_does_not_verify_against_another_key() {
        let message = b"shared message";
        let sig = SigningKey::generate().sign(message);
        let other = SigningKey::generate();
        assert!(matches!(
            other.verifying_key().verify(message, &sig),
            Err(KeyError::VerificationFailed)
        ));
    }

    #[test]
    fn did_key_round_trips() {
        let key = SigningKey::generate().verifying_key();
        let did = key.to_did_key();
        assert_eq!(VerifyingKey::from_did_key(&did).expect("parse"), key);
    }

    #[test]
    fn multibase_round_trips() {
        let key = SigningKey::generate().verifying_key();
        let mb = key.to_multibase();
        assert_eq!(VerifyingKey::from_multibase(&mb).expect("parse"), key);
    }

    /// The point of this crate is to hand keys to jacquard. If our encoding and
    /// its decoder ever disagree, everything downstream silently stops working,
    /// so agreement is asserted directly rather than assumed.
    #[test]
    fn did_key_decodes_through_jacquard() {
        let key = SigningKey::generate().verifying_key();
        let did = key.to_did_key();
        let multibase = did.strip_prefix(DID_KEY_PREFIX).expect("prefix");

        let decoded = PublicKey::decode_owned(multibase).expect("jacquard decode");
        assert_eq!(decoded.codec, KeyCodec::Secp256k1);
        assert_eq!(
            decoded.to_k256().expect("to k256"),
            k256::PublicKey::from(key.as_k256())
        );
    }

    #[test]
    fn multibase_is_base58btc_compressed_secp256k1() {
        let mb = SigningKey::generate().verifying_key().to_multibase();
        assert!(mb.starts_with('z'), "expected base58btc multibase: {mb}");

        let (_base, data) = multibase::decode(&mb).expect("multibase decode");
        let (code, offset) = decode_uvarint(&data).expect("varint");
        assert_eq!(code, SECP256K1_CODEC);
        assert_eq!(data.len() - offset, COMPRESSED_LEN);
        // 0x02/0x03 is the SEC1 compressed tag; 0x04 would mean 65 uncompressed
        // bytes, which atproto rejects.
        assert!(matches!(data[offset], 0x02 | 0x03));
    }

    /// The single property the curve choice rests on. Deterministic RFC 6979
    /// nonces mean a fixed set of messages would only ever prove itself, so the
    /// loop covers a fresh key and many distinct messages.
    #[test]
    fn every_signature_is_low_s() {
        for i in 0..256u32 {
            let key = SigningKey::generate();
            let message = format!("message {i}");
            let sig = key.sign(message.as_bytes());
            assert!(
                !bool::from(sig.as_k256().s().is_high()),
                "high-S signature for message {i}"
            );
            assert!(sig.is_low_s());
        }
    }

    #[test]
    fn private_key_bytes_round_trip() {
        let key = SigningKey::generate();
        let restored = SigningKey::from_bytes(&key.to_bytes()).expect("reload");
        assert_eq!(restored.verifying_key(), key.verifying_key());
    }

    #[test]
    fn from_bytes_rejects_invalid_scalars() {
        // Zero is not a valid scalar.
        assert!(matches!(
            SigningKey::from_bytes(&[0u8; 32]),
            Err(KeyError::InvalidPrivateKey)
        ));
        // All-ones is above the secp256k1 group order.
        assert!(matches!(
            SigningKey::from_bytes(&[0xFFu8; 32]),
            Err(KeyError::InvalidPrivateKey)
        ));
        // Exactly the group order n, the first value that is out of range.
        let order = [
            0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
            0xFF, 0xFE, 0xBA, 0xAE, 0xDC, 0xE6, 0xAF, 0x48, 0xA0, 0x3B, 0xBF, 0xD2, 0x5E, 0x8C,
            0xD0, 0x36, 0x41, 0x41,
        ];
        assert!(matches!(
            SigningKey::from_bytes(&order),
            Err(KeyError::InvalidPrivateKey)
        ));
        // n - 1 is the largest valid scalar, so the bound is not off by one.
        let mut max = order;
        max[31] = 0x40;
        assert!(SigningKey::from_bytes(&max).is_ok());
    }

    #[test]
    fn debug_never_prints_key_material() {
        let key = SigningKey::generate();
        let rendered = format!("{key:?}");

        // The whole rendering, not a search through it for things that look
        // like the scalar. A substring search over two arbitrary strings
        // decides by luck how often it is right — the decimal of a single
        // secret byte is one to three digits, and a base58 did:key is full of
        // digits, so that search failed about one run in ten while the code
        // under it was correct. Pinning the entire output instead is exact:
        // any leaked byte, any added field, any switch to a derived Debug
        // changes this string and fails here.
        let public = key.verifying_key().to_did_key();
        assert_eq!(rendered, format!("SigningKey {{ public: {public:?}, .. }}"));

        // Spelled out so the property being defended stays legible: the
        // renderings a derived Debug would have produced are the ones that
        // must never appear. Each is the full 32-byte scalar, so unlike a
        // fragment it cannot collide with the public identifier by chance.
        let secret = key.to_bytes();
        let lower: String = secret.iter().map(|b| format!("{b:02x}")).collect();
        let upper: String = secret.iter().map(|b| format!("{b:02X}")).collect();
        let derived = format!("{secret:?}");
        for leak in [&lower, &upper, &derived] {
            assert!(!rendered.contains(leak), "leaked {leak} in {rendered}");
        }
    }

    #[test]
    fn rejects_did_key_with_wrong_prefix() {
        let mb = SigningKey::generate().verifying_key().to_multibase();
        assert!(matches!(
            VerifyingKey::from_did_key(&mb),
            Err(KeyError::NotDidKey)
        ));
        assert!(matches!(
            VerifyingKey::from_did_key(&format!("did:plc:{mb}")),
            Err(KeyError::NotDidKey)
        ));
        assert!(matches!(
            VerifyingKey::from_did_key(""),
            Err(KeyError::NotDidKey)
        ));
    }

    #[test]
    fn rejects_other_curves() {
        // ed25519: multicodec 0xED over 32 bytes.
        let ed = format!("{DID_KEY_PREFIX}{}", multikey(0xED, &[7u8; 32]));
        assert!(matches!(
            VerifyingKey::from_did_key(&ed),
            Err(KeyError::WrongCurve {
                codec: KeyCodec::Ed25519
            })
        ));

        // P-256: multicodec 0x1200 over a compressed point. Rejected on codec
        // alone, before the point is ever looked at; see the module docs.
        let p256 = {
            let mut bytes = [0u8; COMPRESSED_LEN];
            bytes[0] = 0x02;
            format!("{DID_KEY_PREFIX}{}", multikey(0x1200, &bytes))
        };
        assert!(matches!(
            VerifyingKey::from_did_key(&p256),
            Err(KeyError::WrongCurve {
                codec: KeyCodec::P256
            })
        ));
    }

    #[test]
    fn rejects_unknown_multicodec() {
        let bogus = format!("{DID_KEY_PREFIX}{}", multikey(0x99, &[2u8; COMPRESSED_LEN]));
        assert!(matches!(
            VerifyingKey::from_did_key(&bogus),
            Err(KeyError::Multikey(_))
        ));
    }

    #[test]
    fn rejects_uncompressed_secp256k1() {
        let uncompressed = SigningKey::generate()
            .verifying_key()
            .as_k256()
            .to_encoded_point(false);
        assert_eq!(uncompressed.as_bytes().len(), 65);
        let did = format!(
            "{DID_KEY_PREFIX}{}",
            multikey(SECP256K1_CODEC, uncompressed.as_bytes())
        );
        assert!(matches!(
            VerifyingKey::from_did_key(&did),
            Err(KeyError::NotCompressed { got: 65 })
        ));
    }

    #[test]
    fn rejects_wrong_length() {
        let short = format!("{DID_KEY_PREFIX}{}", multikey(SECP256K1_CODEC, &[2u8; 20]));
        assert!(matches!(
            VerifyingKey::from_did_key(&short),
            // jacquard's own length check fires before ours for this one.
            Err(KeyError::Multikey(_)) | Err(KeyError::NotCompressed { .. })
        ));
    }

    #[test]
    fn rejects_bad_base58() {
        let mut mb = SigningKey::generate().verifying_key().to_multibase();
        // 0, O, I and l are not in the base58btc alphabet.
        mb.push('0');
        assert!(matches!(
            VerifyingKey::from_did_key(&format!("{DID_KEY_PREFIX}{mb}")),
            Err(KeyError::Multikey(_))
        ));
    }

    #[test]
    fn rejects_non_base58btc_multibase() {
        // A valid multibase string in base64url ('u'), which decodes fine but
        // is not what atproto specifies.
        let key = SigningKey::generate().verifying_key();
        let mut payload = jacquard_common::types::crypto::encode_uvarint(SECP256K1_CODEC);
        payload.extend_from_slice(key.as_k256().to_encoded_point(true).as_bytes());
        let b64 = multibase::encode(multibase::Base::Base64Url, &payload);
        assert!(matches!(
            VerifyingKey::from_multibase(&b64),
            Err(KeyError::NotBase58Btc)
        ));
    }

    #[test]
    fn signature_bytes_round_trip() {
        let key = SigningKey::generate();
        let message = b"wire form";
        let sig = key.sign(message);
        let bytes = sig.to_bytes();
        assert_eq!(bytes.len(), 64);
        let parsed = Signature::from_bytes(&bytes).expect("parse");
        assert_eq!(parsed, sig);
        assert!(key.verifying_key().verify(message, &parsed).is_ok());
    }

    #[test]
    fn all_zero_signature_is_rejected() {
        assert!(matches!(
            Signature::from_bytes(&[0u8; 64]),
            Err(KeyError::InvalidSignature)
        ));
    }

    /// Malleability in practice: flipping a valid signature to its high-S twin
    /// keeps it mathematically valid but must not verify here.
    #[test]
    fn high_s_signature_does_not_verify() {
        let key = SigningKey::generate();
        let message = b"malleable?";
        let sig = key.sign(message);

        let (r, s) = sig.as_k256().split_scalars();
        let flipped = k256::ecdsa::Signature::from_scalars(r.to_bytes(), (-*s).to_bytes())
            .expect("negated s is a valid scalar");
        assert!(bool::from(flipped.s().is_high()));

        let flipped = Signature::from(flipped);
        assert!(!flipped.is_low_s());
        assert!(matches!(
            key.verifying_key().verify(message, &flipped),
            Err(KeyError::VerificationFailed)
        ));
    }
}