ExternalSigner class final

Signs a COSE_Sign1 (ESP256) with a P-256 key that never enters this process: one in the Android Keystore, the iOS Secure Enclave, WebCrypto, or any other store that can sign but not export (cratestack#1151).

Only the key's public half is given here. For each request the envelope hands sign the complete to-be-signed bytes and expects an ECDSA signature over SHA-256 of exactly those bytes; everything else (the CBOR, the binding, DER to raw r || s, low-s, and checking the signature verifies under publicKey before anything is sent) is cratestack-cose's, so sign does none of it. The kid is derived from publicKey (ClientEnvelope.kid), never supplied.

How to sign, passing the bytes as given and never a digest (the platform hashes for you):

  • Android: Signature.getInstance("SHA256withECDSA"), update(tbs), sign() (DER).
  • iOS: SecKeyCreateSignature(key, .ecdsaSignatureMessageX962SHA256, tbs) (DER).
  • Web: crypto.subtle.sign({name: 'ECDSA', hash: 'SHA-256'}, key, tbs) (raw r || s).

publicKey is a SEC1 point (uncompressed, 65 bytes 0x04 || x || y, or compressed, 33 bytes) or a P-256 SubjectPublicKeyInfo, which is what Android's PublicKey.getEncoded() returns. This is asymmetric with the server keys (CoseServerKey.p256Sec1), which are SEC1 only. A key that is neither, or not on the curve, is CoseMisuse when the envelope is created.

sign returns a SignOutcome and must not throw: report a dismissed prompt as SignOutcome.cancelled and a keystore failure as SignOutcome.failed. A throw is still caught and becomes CoseSignerFailed (without the exception's text). A signature that is not a valid ECDSA signature by publicKey is CoseMisuse, not a signer failure.

timeout bounds each call; there is no default, because a keystore prompt can wait on a person for as long as they like and only the app knows how long a request may. Exceeding it is CoseSignerTimedOut. It does not cancel the platform prompt: the callback keeps running and its late answer is discarded.

Inheritance

Constructors

ExternalSigner.esp256({required Uint8List publicKey, required SignCallback sign, required Duration timeout})
An ESP256 signer for the key whose public half is publicKey.

Properties

hashCode → int
The hash code for this object.
no setterinherited
publicKey → Uint8List
The public key (a copy): a SEC1 point (uncompressed or compressed) or a SubjectPublicKeyInfo.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sign → SignCallback
Signs the to-be-signed bytes it is given with the keystore.
final
timeout → Duration
How long one sign call may take.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited