cose library
COSE signed transport for CrateStack Dart/Flutter clients (ADR 0006,
cratestack#1026): seal a request and open a response with
cratestack-cose, the one Rust implementation, reached through the same
backends as the CBOR codec: flutter_rust_bridge natively and the
cratestack-cbor-wasm build on the web. Nothing here implements COSE or
any crypto in Dart.
Import it next to the codec; a codec-only app imports nothing new:
import 'package:cratestack_cbor/cose.dart';
final envelope = await ClientEnvelope.create(
signer: Ed25519Signer.fromSeed(seed),
serverKeys: [CoseServerKey.ed25519(serverPublicKey)],
audience: 'payments',
);
Keystore keys. A key that must not enter the process (Android Keystore, Secure Enclave, WebCrypto) signs through a callback; see ExternalSigner:
final signer = ExternalSigner.esp256(
publicKey: publicKey, // SEC1 point (either form) or SubjectPublicKeyInfo
timeout: const Duration(seconds: 60),
sign: (tbs) async {
try {
return SignOutcome.signature(await keystore.sign(tbs));
} on UserDismissed {
return const SignOutcome.cancelled();
}
},
);
Errors. Everything the Rust side refuses is a CoseException (a sealed
class: CoseRejected, CoseMisuse, and the signer variants). Dart-side
argument checks that cannot be right are ArgumentError, thrown by the
constructors of the key and binding types before any bridge call, and
ClientEnvelope.contractHeaderValue before the backend has started is a
StateError.
This client is Required-only, like the Rust client: it seals every request and opens only responses to a sealed request.
Classes
- CallBinding
- The inputs a call's signature is bound to (ADR 0006 §4). The audience is the envelope's, not the call's.
- CancelledOutcome
- The prompt was dismissed; see SignOutcome.cancelled.
- ClientEnvelope
- Seals requests and opens responses for one service (ADR 0006).
- CoseServerKey
- A key the server's responses verify with, pinned at enrolment.
- CoseSigner
- Who signs a request. Sealed: HmacSigner and Ed25519Signer hold their key in memory (service credentials and tests); ExternalSigner never has the key, which stays in the Android Keystore, the Secure Enclave or WebCrypto, and only asks it to sign.
- Ed25519Signer
- Signs a COSE_Sign1 with the Ed25519 key of a 32-byte seed.
- ExternalSigner
- 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).
- FailedOutcome
- The keystore failed; see SignOutcome.failed.
- HmacSigner
- Signs a COSE_Mac0 with a shared secret of at least 32 random bytes.
- Opened
- A response that verified.
- SignedOutcome
- The keystore signed; see SignOutcome.signature.
- SignOutcome
- What a keystore signing call ended with.
- TimedOutOutcome
- The keystore was too slow; see SignOutcome.timedOut.
Enums
Typedefs
-
SignCallback
= Future<
SignOutcome> Function(Uint8List toBeSigned) -
Signs the complete to-be-signed bytes with a keystore key: ECDSA over
SHA-256 of exactly
toBeSigned, never of a digest of it. Returns a SignOutcome; see ExternalSigner.
Exceptions / Errors
- CoseException
- Why sealing a request or opening a response failed.
- CoseMisuse
- The caller or its configuration is wrong: a key of the wrong length, an empty audience, a binding of the wrong shape.
- CoseRejected
-
The message did not verify (the coarse
401): a tampered body, a wrong key, a response to another request, a stale or replayed message. Never says which. - CoseSignerCancelled
- The person dismissed the keystore's prompt: an ExternalSigner whose callback returned SignOutcome.cancelled.
- CoseSignerFailed
- The keystore failed: the callback of an ExternalSigner returned SignOutcome.failed (the message is the callback's), or threw (the message names only the exception's type). A signature that is not a valid one by the key is CoseMisuse instead, because the callback did not fail.
- CoseSignerTimedOut
- The keystore did not answer in time: the callback of an ExternalSigner returned SignOutcome.timedOut, or exceeded ExternalSigner.timeout.