Struct ExternalSigner 

pub struct ExternalSigner { /* private fields */ }

A signer that hands the bytes to a callback: a key in the Android Keystore or the iOS Secure Enclave, a KMS, a hardware token.

The key is never exported; the callback is asked to sign the complete Sig_structure and nothing else. On wasm32 neither the callback nor its future needs to be Send (see CoseSigner).

An Ed25519 key behind a callback, with the platform’s own primitive standing in for the key store (here, Ed25519Signer):

use cratestack_cose::{CoseAlg, CoseSigner, Ed25519Signer, ExternalSigner};

let key = Ed25519Signer::from_seed(&[7; 32]);
let public = key.verify_key().ed25519_bytes().unwrap();
let signer = ExternalSigner::ed25519(&public, move |tbs| {
    let key = key.clone();
    async move { key.sign(&tbs).await }
})
.unwrap();
assert_eq!(signer.alg(), CoseAlg::Ed25519);
assert_eq!(signer.kid().len(), 8);

A P-256 key:

use cratestack_cose::{CoseAlg, CoseSigner, ExternalSigner, P256Signer};

// A stand-in for a platform keystore.
let key = P256Signer::from_scalar(&[7; 32]).unwrap();
let public = key.verify_key().p256_sec1_uncompressed().unwrap();
let signer = ExternalSigner::esp256(&public, move |tbs| {
    let key = key.clone();
    async move { key.sign(&tbs).await }
})
.unwrap();
assert_eq!(signer.alg(), CoseAlg::Esp256);
assert_eq!(signer.kid().len(), 8);

Implementations

impl ExternalSigner

pub fn esp256<F, Fut>( public_key_sec1: &[u8], sign: F, ) -> Result<ExternalSigner, CratestackError>

where F: Fn(Vec<u8>) -> Fut + MaybeSendSync + 'static, Fut: Future<Output = Result<Vec<u8>, CratestackError>> + MaybeSend + 'static,

An ESP256 (-9) signer for the P-256 key whose public half is public_key_sec1 (compressed or uncompressed SEC1). The kid is the key’s RFC 9679 thumbprint prefix, computed here so the caller cannot get it wrong.

sign receives the full to-be-signed bytes and must sign them with ECDSA over SHA-256 (SHA256withECDSA on Android, ecdsaSignatureMessageX962SHA256 on iOS: both hash for you, so pass the bytes as given, never a digest). It may return the signature DER encoded, which is what both platform keystores produce, or as the raw 64-byte r ‖ s. A DER signature is converted; the envelope then normalises to low-s. A signature that does not verify under public_key_sec1 is refused here, on every call, instead of failing at the peer as the coarse 401.

Fails with CratestackError::Validation if public_key_sec1 is not a point on the curve.

pub fn ed25519<F, Fut>( public_key: &[u8; 32], sign: F, ) -> Result<ExternalSigner, CratestackError>

where F: Fn(Vec<u8>) -> Fut + MaybeSendSync + 'static, Fut: Future<Output = Result<Vec<u8>, CratestackError>> + MaybeSend + 'static,

An Ed25519 (-19) signer for the key whose public half is public_key. The kid is the key’s RFC 9679 thumbprint prefix, computed here so the caller cannot get it wrong.

sign receives the full to-be-signed bytes and must return the 64-byte Ed25519 signature over exactly those bytes (pure Ed25519, as RFC 8032 defines it, never a pre-hash of them), which is what a Node crypto.sign(null, tbs, key) or a KMS ED25519 key produces. Any other length is refused as the signer’s failure, and so is a signature that does not verify under public_key, which is checked here on every call instead of failing at the peer as the coarse 401.

Fails with CratestackError::Validation if public_key is not a point encoding.

Trait Implementations

impl Clone for ExternalSigner

fn clone(&self) -> ExternalSigner

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CoseSigner for ExternalSigner

fn alg(&self) -> CoseAlg

The algorithm every signature from this signer uses.

fn kid(&self) -> &[u8]

The key’s kid: the first 8 bytes of its RFC 9679 thumbprint (§3).

fn sign<'life0, 'life1, 'async_trait>( &'life0 self, to_be_signed: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, CratestackError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, ExternalSigner: 'async_trait,

Sign (or MAC) to_be_signed. For HMAC 256/64 this returns the truncated 8-byte tag. An error is a backend failure (a 500).

fn sign_chunks( &self, to_be_signed: &[&[u8]], ) -> Option<Result<Vec<u8>, CratestackError>>

Sign the concatenation of to_be_signed without it ever being built in one buffer, or None to have the envelope build it and call sign instead (the default).

impl Debug for ExternalSigner

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.