mockforge_platform_signing/
signer.rs

1//! [`PlatformSigner`] — backend-agnostic trait for the platform signing
2//! root.
3//!
4//! Backends keep the private key behind an HSM boundary (AWS KMS today,
5//! GCP KMS or a `YubiHSM` tomorrow) and only expose a `sign(...)`
6//! round-trip. All test fixtures use [`MockSigner`], which holds a
7//! software keypair in memory and is **not safe for production**.
8
9use async_trait::async_trait;
10use thiserror::Error;
11
12/// What signature algorithm a [`PlatformSigner`] produces.
13///
14/// AWS KMS does not support Ed25519, so the platform root uses ECDSA over
15/// NIST P-256 or P-384. P-256 is the default (smaller signatures, faster
16/// verify on the host fleet) — P-384 is available for higher-assurance
17/// deployments.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
19#[serde(rename_all = "kebab-case")]
20pub enum SigningAlgorithm {
21    /// ECDSA over NIST P-256 with SHA-256. Default.
22    EcdsaSha256P256,
23    /// ECDSA over NIST P-384 with SHA-384. Higher-assurance opt-in.
24    EcdsaSha384P384,
25}
26
27impl SigningAlgorithm {
28    /// Stable wire-form for use inside [`crate::rotation::RotationEventPayload`].
29    pub fn as_str(self) -> &'static str {
30        match self {
31            Self::EcdsaSha256P256 => "ecdsa-sha256-p256",
32            Self::EcdsaSha384P384 => "ecdsa-sha384-p384",
33        }
34    }
35}
36
37/// The platform signer abstraction. One instance corresponds to one HSM-
38/// hosted key.
39///
40/// Implementations MUST guarantee that the private key bytes never leave
41/// the HSM. Only [`PlatformSigner::sign`] crosses the boundary, and only
42/// the resulting signature comes back.
43#[async_trait]
44pub trait PlatformSigner: Send + Sync {
45    /// Opaque identifier the operator uses to refer to this key (e.g. a
46    /// KMS key ARN). Stable across signer instances.
47    fn key_id(&self) -> &str;
48
49    /// Signature algorithm this key produces.
50    fn algorithm(&self) -> SigningAlgorithm;
51
52    /// `SubjectPublicKeyInfo` (DER) for the key. Plugin-hosts use this
53    /// to verify signatures the signer produces.
54    async fn public_key_der(&self) -> Result<Vec<u8>, SignerError>;
55
56    /// Sign the given message. The returned bytes are the DER-encoded
57    /// ECDSA signature (matches what AWS KMS `Sign` returns when called
58    /// with `MessageType=RAW`).
59    async fn sign(&self, message: &[u8]) -> Result<Vec<u8>, SignerError>;
60}
61
62/// Errors a signer backend can produce.
63#[derive(Debug, Error)]
64pub enum SignerError {
65    /// The backend rejected the call (e.g. `AccessDenied`, `KeyDisabled`).
66    /// The string is the backend's own error message, surfaced as-is.
67    #[error("signer backend error: {0}")]
68    Backend(String),
69
70    /// The configured key id was empty or malformed.
71    #[error("invalid key id: {0}")]
72    InvalidKeyId(String),
73
74    /// Required environment variable missing.
75    #[error("missing environment variable: {0}")]
76    MissingEnv(&'static str),
77
78    /// The backend returned a public key in an unexpected encoding.
79    #[error("unexpected public-key encoding from backend: {0}")]
80    UnexpectedPublicKey(String),
81}
82
83/// Forward [`PlatformSigner`] through a boxed trait object so a
84/// `RotationStateMachine<Box<dyn PlatformSigner>>` is a valid concrete
85/// instantiation. This is the type that `mockforge-registry-server`
86/// stores in `AppState`: the binary's startup code may build either an
87/// `AwsKmsSigner` (production) or a `MockSigner` (tests / OSS smoke
88/// runs), and erasing to `Box<dyn _>` keeps the rest of the call sites
89/// free of cargo features.
90#[async_trait]
91impl PlatformSigner for Box<dyn PlatformSigner> {
92    fn key_id(&self) -> &str {
93        (**self).key_id()
94    }
95
96    fn algorithm(&self) -> SigningAlgorithm {
97        (**self).algorithm()
98    }
99
100    async fn public_key_der(&self) -> Result<Vec<u8>, SignerError> {
101        (**self).public_key_der().await
102    }
103
104    async fn sign(&self, message: &[u8]) -> Result<Vec<u8>, SignerError> {
105        (**self).sign(message).await
106    }
107}
108
109/// Software-keypair signer for tests. **Never use in production** — the
110/// private bytes live in process memory, which defeats the entire point
111/// of this crate.
112///
113/// Uses ring's ECDSA implementation over NIST P-256 with SHA-256.
114pub struct MockSigner {
115    key_id: String,
116    keypair: ring::signature::EcdsaKeyPair,
117    public_key_der: Vec<u8>,
118    algorithm: SigningAlgorithm,
119}
120
121impl std::fmt::Debug for MockSigner {
122    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
123        f.debug_struct("MockSigner")
124            .field("key_id", &self.key_id)
125            .field("algorithm", &self.algorithm)
126            .finish_non_exhaustive()
127    }
128}
129
130impl MockSigner {
131    /// Generate a fresh P-256 keypair labelled with `key_id`.
132    pub fn generate(key_id: impl Into<String>) -> Result<Self, SignerError> {
133        let rng = ring::rand::SystemRandom::new();
134        let pkcs8 = ring::signature::EcdsaKeyPair::generate_pkcs8(
135            &ring::signature::ECDSA_P256_SHA256_ASN1_SIGNING,
136            &rng,
137        )
138        .map_err(|e| SignerError::Backend(format!("ring pkcs8 generate failed: {e}")))?;
139        let keypair = ring::signature::EcdsaKeyPair::from_pkcs8(
140            &ring::signature::ECDSA_P256_SHA256_ASN1_SIGNING,
141            pkcs8.as_ref(),
142            &rng,
143        )
144        .map_err(|e| SignerError::Backend(format!("ring keypair load failed: {e}")))?;
145        // ring returns the raw subject-public-key (uncompressed point);
146        // wrap it in a SubjectPublicKeyInfo so the verifier can use the
147        // same DER shape as the AWS KMS path.
148        let raw_pub = ring::signature::KeyPair::public_key(&keypair).as_ref().to_vec();
149        let public_key_der = wrap_p256_spki(&raw_pub);
150        Ok(Self {
151            key_id: key_id.into(),
152            keypair,
153            public_key_der,
154            algorithm: SigningAlgorithm::EcdsaSha256P256,
155        })
156    }
157}
158
159#[async_trait]
160impl PlatformSigner for MockSigner {
161    fn key_id(&self) -> &str {
162        &self.key_id
163    }
164
165    fn algorithm(&self) -> SigningAlgorithm {
166        self.algorithm
167    }
168
169    async fn public_key_der(&self) -> Result<Vec<u8>, SignerError> {
170        Ok(self.public_key_der.clone())
171    }
172
173    async fn sign(&self, message: &[u8]) -> Result<Vec<u8>, SignerError> {
174        let rng = ring::rand::SystemRandom::new();
175        let sig = self
176            .keypair
177            .sign(&rng, message)
178            .map_err(|e| SignerError::Backend(format!("ring sign failed: {e}")))?;
179        Ok(sig.as_ref().to_vec())
180    }
181}
182
183/// Wrap a raw P-256 uncompressed public-key point (65 bytes, leading 0x04)
184/// in a minimal `SubjectPublicKeyInfo` so the verifier sees the same DER
185/// shape the AWS KMS backend returns.
186fn wrap_p256_spki(raw_uncompressed_point: &[u8]) -> Vec<u8> {
187    // Hand-rolled DER builder — this is fixed-shape ASN.1 (RFC 5480
188    // §2.1.1) so a bespoke encoding is simpler than pulling in a full
189    // DER library just for one record.
190    //
191    // SEQUENCE {
192    //   SEQUENCE {            // AlgorithmIdentifier
193    //     OID 1.2.840.10045.2.1     // id-ecPublicKey
194    //     OID 1.2.840.10045.3.1.7   // secp256r1
195    //   }
196    //   BIT STRING { <unused = 0> || raw_uncompressed_point }
197    // }
198    const ALG_PREFIX: &[u8] = &[
199        0x30, 0x13, // SEQUENCE (AlgorithmIdentifier), len 19
200        0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01, // OID id-ecPublicKey
201        0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07, // OID secp256r1
202    ];
203    let bitstring_len = 1 + raw_uncompressed_point.len(); // 1 = "unused bits" byte
204    let mut bitstring = Vec::with_capacity(2 + bitstring_len);
205    bitstring.push(0x03); // BIT STRING tag
206    bitstring.push(bitstring_len as u8);
207    bitstring.push(0x00); // 0 unused bits
208    bitstring.extend_from_slice(raw_uncompressed_point);
209    let body_len = ALG_PREFIX.len() + bitstring.len();
210    let mut out = Vec::with_capacity(2 + body_len);
211    out.push(0x30); // outer SEQUENCE
212    out.push(body_len as u8);
213    out.extend_from_slice(ALG_PREFIX);
214    out.extend_from_slice(&bitstring);
215    out
216}
217
218#[cfg(test)]
219mod tests {
220    use super::*;
221
222    #[tokio::test]
223    async fn mock_signer_round_trips() {
224        let signer = MockSigner::generate("test-key-1").unwrap();
225        assert_eq!(signer.key_id(), "test-key-1");
226        assert_eq!(signer.algorithm(), SigningAlgorithm::EcdsaSha256P256);
227
228        let msg = b"hello mockforge";
229        let sig = signer.sign(msg).await.unwrap();
230        let pub_der = signer.public_key_der().await.unwrap();
231
232        // Verify with ring directly against the wrapped SPKI — the
233        // verifier module does the same thing for the rotation event.
234        // Strip the SPKI wrapping to get back the raw point ring expects.
235        let raw_point = extract_p256_point_from_spki(&pub_der).expect("valid spki");
236        let pubkey = ring::signature::UnparsedPublicKey::new(
237            &ring::signature::ECDSA_P256_SHA256_ASN1,
238            &raw_point,
239        );
240        pubkey.verify(msg, &sig).expect("signature should verify");
241    }
242
243    #[tokio::test]
244    async fn mock_signer_rejects_tampered_message() {
245        let signer = MockSigner::generate("test-key-2").unwrap();
246        let sig = signer.sign(b"original").await.unwrap();
247        let pub_der = signer.public_key_der().await.unwrap();
248        let raw_point = extract_p256_point_from_spki(&pub_der).unwrap();
249        let pubkey = ring::signature::UnparsedPublicKey::new(
250            &ring::signature::ECDSA_P256_SHA256_ASN1,
251            &raw_point,
252        );
253        assert!(pubkey.verify(b"tampered", &sig).is_err());
254    }
255
256    #[test]
257    fn signing_algorithm_wire_form_is_stable() {
258        // These strings ship over the wire inside RotationEventPayload;
259        // any change is a backwards-incompatible break of every
260        // plugin-host that's persisted a rotation event.
261        assert_eq!(SigningAlgorithm::EcdsaSha256P256.as_str(), "ecdsa-sha256-p256");
262        assert_eq!(SigningAlgorithm::EcdsaSha384P384.as_str(), "ecdsa-sha384-p384");
263    }
264
265    /// Pull the 65-byte uncompressed point back out of a minimal P-256
266    /// `SubjectPublicKeyInfo` so ring can verify against it.
267    fn extract_p256_point_from_spki(spki: &[u8]) -> Option<Vec<u8>> {
268        // The wrap_p256_spki layout is fixed; the raw point starts at
269        // a known offset. This is test-only — production verifier in
270        // `verifier.rs` does the same thing more carefully.
271        const HEADER_LEN: usize = 26; // outer SEQ(2) + AlgorithmIdentifier(21) + BIT STRING tag+len(2) + unused-bits(1)
272        if spki.len() <= HEADER_LEN {
273            return None;
274        }
275        Some(spki[HEADER_LEN..].to_vec())
276    }
277}
mockforge_platform_signing/signer.rs

mockforge_platform_signing/
signer.rs
