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)(rawr || 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
-
- Object
- CoseSigner
- ExternalSigner
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