Skip to main content

Crate basil_cose

Crate basil_cose 

Source
Expand description

§basil-cose

A strict, deterministic COSE (RFC 9052/9053) profile for basil’s sealed invocations: broker-free and publishable, shared by the basil broker, the basil client, and some basil clients.

Three constructions:

Algorithms: EdDSA (-8) or ES256 (-7, ECDSA P-256 + SHA-256) signatures, ECDH-ES + HKDF-256 (-25) key agreement with X25519, and A256GCM (3) or ChaCha20-Poly1305 (24) content encryption. Key material stays behind the Signer, Verifier, and Recipient traits; nonces and ephemerals are always generated by the library. ES256 signing is deterministic (RFC 6979), so both signature algorithms re-sign byte-identically.

§Strictness

Every decode entry point enforces the profile: tagged top-level structures only, definite lengths, RFC 8949 §4.2 deterministic encodings (checked by re-encoding the parsed message and comparing bytes, on every decode, release builds included), closed algorithm/label allow-sets with no Unknown arms, crit coverage of every profile label, claims only in protected headers, and exactly one recipient.

§Claims

Claims ride in the protected header as a CWT map (header 15) plus basil private labels (-70001..=-70005, see label). ValidationParams parameterizes skew/TTL/audience bounds; now is injected, never sampled.

The crate is no_std + alloc and obtains production randomness through getrandom.

Modules§

label
The basil private label registry and canonical label ordering.

Structs§

Claims
The claim set carried in a protected header (CWT map, header 15, plus the basil private labels).
ContentType
Content type (COSE header 3, tstr media type of type/subtype form).
CoseBytes
Complete tagged COSE bytes: the output of every build entry point.
Ed25519Signer
A local Ed25519 signer: a SigningKey (ZeroizeOnDrop) plus its key id.
Ed25519Verifier
A local Ed25519 verifier over one or more pinned public keys, looked up by key id.
EncryptParams
Parameters for build_encrypted.
EncryptedMessage
A strictly decoded (not yet opened) seal-only message.
Es256Signer
A local ES256 signer: a P-256 SigningKey plus its key id.
ExternalAad
Caller-supplied external_aad for exactly one COSE layer. Empty is the explicit default, not an implicit one.
KdfParties
PartyU = message sender, PartyV = recipient, per RFC 9053 §5.1.
KeyId
COSE kid (bstr, 1..=128 bytes). Basil catalog names are UTF-8; other consumers may use raw byte ids.
KeyLengthError
A private key slice was not exactly 32 bytes.
MessageId
CWT cti (bstr, 1..=64 bytes, sender-unique inside the replay window).
OpenRequest
Everything an opener needs, already strictly validated by the decode entry points, plus the raw encrypt bytes so a remote (broker-backed) recipient can forward them verbatim without re-encoding.
Opened
An opened (decrypted) message.
P256Verifier
A local ES256 verifier over one or more pinned P-256 public keys, looked up by key id.
PartyIdentity
One party’s identity slot in the COSE_KDF_Context (RFC 9053 §5.2).
ProtectedHeaders
Additional protected header values carried outside the CWT claim map.
RequestHash
A SHA3-256 digest of the complete tagged request bytes.
ResponseSubject
The -70005 response subject (tstr, non-empty).
SealParams
Parameters for build_sealed.
SealedAad
Per-layer AAD for the sealed (two-layer) construction.
SignParams
Parameters for build_signed.
Signature
A raw signature over Sig_structure bytes.
Subject
CWT iss/aud subject (tstr, non-empty).
UnixTime
Seconds since the Unix epoch (CWT iat/exp).
ValidationParams
Parameterized validation bounds. The broker feeds its [invocation] config. now is injected, never sampled internally: a broker-free crate does not own time policy.
VerifiedSealed
A verified (signature-checked, claims-validated) sealed message, not yet opened.
VerifiedSigned
A verified bare signed message.
VerifySealedParams
Parameters for verify_sealed.
VerifySignedParams
Parameters for verify_signed.
X25519Recipient
A local X25519 recipient: the materialized static private key (Zeroizing) plus its key id.
X25519RecipientPublic
A recipient’s static X25519 public key: the seal target.
Zeroizing
Zeroizing is a wrapper for any Z: Zeroize type which implements a Drop handler which zeroizes dropped values.

Enums§

BuildError
Why building a message failed.
ClaimsError
Claim-set validation failures (temporal, audience, and role shape).
ContentAlgorithm
Content-encryption algorithms in the profile allow-set.
DecodeError
Strict-decode rejection reasons.
KeyAgreementAlgorithm
Key-agreement algorithms in the profile allow-set.
KeyError
Why constructing a local key failed.
MessageRole
Which claim shape a validator demands.
OpenError
Why opening (decrypting) a message failed.
ProfileError
An identifier newtype was constructed from out-of-range input.
SignError
Why producing a signature failed.
SignatureAlgorithm
Signature algorithms in the profile allow-set.
VerifyError
Why verification failed.

Traits§

Recipient
Opens one COSE_Encrypt addressed to key_id(): ECDH-ES decapsulation + HKDF-256 (COSE_KDF_Context) + content AEAD, returning zeroizing plaintext.
Signer
Produces the signature over Sig_structure bytes.
Verifier
Resolves a kid and verifies a signature.

Functions§

build_encrypted
Seal plaintext to one X25519 recipient as a bare tagged COSE_Encrypt.
build_sealed
Build a sealed message: encrypt plaintext to the recipient, then sign the embedded tagged COSE_Encrypt with signer.
build_signed
Build a bare signed message.
build_signed_with_headers
Build a bare signed message with additional critical protected headers.
decode_encrypted
Strict-decode a seal-only tagged COSE_Encrypt (no opening, no claims).
request_hash
SHA3-256 over the complete tagged request COSE_Sign1 bytes.
verify_sealed
Verify a sealed message.
verify_signed
Verify a bare signed message.