Struct CoseEnvelope 

pub struct CoseEnvelope { /* private fields */ }

A COSE_Sign1 or COSE_Mac0 envelope (ADR 0006 §§1, 3-5).

Cheap to clone: the configuration sits behind one Arc. Build it with CoseEnvelope::server or CoseEnvelope::client.

Errors, for every method (§10): a failed verification is the coarse CratestackError::Unauthorized; a failing backend (key resolver, nonce store, signer) is CratestackError::Internal, a 500; and local misuse (a binding whose shape does not fit the call, an empty audience, a request opened without a nonce store, a clock or cti source returning nonsense, a signer returning a signature of the wrong length, a codec whose encode_into does not append) is also CratestackError::Internal. Misuse depends only on local state, never on the received bytes, so a 500 for it reveals nothing about a message. A codec error from a *_value method is returned as the codec reported it.

Implementations

impl CoseEnvelope

pub fn server( mode: CoseMode, signer: Arc<dyn CoseSigner>, resolver: Arc<dyn CoseVerifierResolver>, nonce_store: Arc<dyn NonceStore>, ) -> CoseEnvelopeBuilder

A server envelope: opens requests (verifying with keys from resolver, recording (kid, cti) in nonce_store) and seals responses with signer.

pub fn client( mode: CoseMode, signer: Arc<dyn CoseSigner>, resolver: Arc<dyn CoseVerifierResolver>, ) -> CoseEnvelopeBuilder

A client envelope: seals requests with signer and opens responses with keys from resolver (typically the server keys pinned at enrolment, §8).

impl CoseEnvelope

pub async fn open_request( &self, body: Bytes, bind: &Binding<'_>, ) -> Result<Opened, CratestackError>

Verify a request and run the replay checks, without a CratestackContext (the #1006 axum layer runs before one exists). Needs a nonce store; without one it is local misuse (a 500).

pub async fn open_request_any( &self, body: Bytes, binds: &[Binding<'_>], ) -> Result<(Opened, usize), CratestackError>

open_request against several candidate bindings (differing, for the axum layer, only in the op-contract digest): the message is parsed once and its key resolved once, and only the signature verification is repeated per candidate, in order. Returns the opened request and the index of the binding that verified. A failed candidate records no nonce; an empty list is the coarse 401.

pub async fn open_response( &self, body: Bytes, bind: &Binding<'_>, ) -> Result<Opened, CratestackError>

Verify a response against the request it answers.

impl CoseEnvelope

pub fn role(&self) -> CoseRole

The side this envelope is on.

pub fn mode(&self) -> CoseMode

The message structure this envelope emits and accepts. An envelope accepts only its own mode’s tag: a Sign1 envelope refuses a Mac0 message outright, whatever keys its resolver holds.

pub fn request_nonce(&self) -> Result<RequestNonce, CratestackError>

A fresh Cratestack-Nonce for an outgoing request, from the builder’s nonce source. Fails with CratestackError::Internal if that source fails.

pub async fn seal_request( &self, payload: &[u8], bind: &Binding<'_>, ) -> Result<Bytes, CratestackError>

Seal an encoded request payload for bind (a request binding: response is None), with iat from the clock and a fresh cti. The payload is copied into the message once; see seal_request_value to avoid that.

pub async fn seal_response( &self, payload: &[u8], bind: &Binding<'_>, ) -> Result<Bytes, CratestackError>

Seal an encoded response payload for bind (a response binding: response names the request answered, its kind and the status). Responses carry alg and kid only.

pub async fn seal_request_value<C, T>( &self, codec: &C, value: &T, bind: &Binding<'_>, ) -> Result<Bytes, CratestackError>

where C: CratestackCodec, T: Serialize + ?Sized,

seal_request for a value codec has not encoded yet: it is encoded straight into the message buffer. The bytes are identical to encoding first and sealing after. A codec error is returned as the codec reported it.

pub async fn seal_response_value<C, T>( &self, codec: &C, value: &T, bind: &Binding<'_>, ) -> Result<Bytes, CratestackError>

where C: CratestackCodec, T: Serialize + ?Sized,

seal_response for a value, encoded in place as seal_request_value does.

Trait Implementations

impl Clone for CoseEnvelope

fn clone(&self) -> CoseEnvelope

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CratestackEnvelope for CoseEnvelope

fn media_type(&self, shape: BodyShape) -> Option<&'static str>

Unary bodies are application/cose; cose-type="cose-sign1" or "cose-mac0". Streams are None: chain mode is P1 (cratestack#1008), and until then a stream keeps plain cbor-seq, as the trait’s contract requires when the stream methods return None.

fn seal<'a>( &'a self, payload: Bytes, bind: &'a Binding<'a>, ) -> impl Future<Output = Result<Bytes, CratestackError>> + Send + 'a

A server seals a response, a client seals a request (see CoseRole). The payload arrives encoded, so it is copied into the message once; seal_value avoids that copy.

fn seal_value<'a, C, T>( &'a self, codec: &'a C, value: &'a T, bind: &'a Binding<'a>, ) -> impl Future<Output = Result<Bytes, CratestackError>> + Send + 'a

where C: CratestackCodec, T: Serialize + Sync + ?Sized,

Overridden to encode in place (ADR 0006 §1): codec.encode_into writes the payload straight into the message buffer, after the room reserved for its bstr head, and the head is patched in once the length is known. The bytes equal codec.encode followed by seal.

fn open<'a>( &'a self, body: Bytes, bind: &'a Binding<'a>, ctx: &'a mut CratestackContext, ) -> impl Future<Output = Result<Bytes, CratestackError>> + Send + 'a

A server opens a request (replay checks included), a client opens a response. On success the context records a VerifiedSigner that names the key that verified: its thumbprint, its kid (the header’s, which the opener checked is the key’s own, copied so the context does not keep the body alive) and the algorithm. The payload returned is a slice of body.

fn stream_sealer( &self, _bind: Binding<'static>, ) -> Option<Box<dyn StreamSealer>>

A sealer for one outgoing stream, or None when this envelope does not sign streams (plain cbor-seq passes through). It takes Binding<'static> because the sealer outlives the request borrow: chain mode’s h₀ = SHA-256(external_aad) needs the binding (§6).

fn stream_opener( &self, _bind: Binding<'static>, ) -> Option<Box<dyn StreamOpener>>

An opener for one incoming stream, or None when this envelope does not verify streams. See stream_sealer.

impl Debug for CoseEnvelope

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

Formats the value using the given formatter.

impl ServerEnvelope for CoseEnvelope

fn media_type(&self) -> &'static str

application/cose; cose-type="cose-sign1" or "cose-mac0", by mode.

fn open_request<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, body: Bytes, bind: &'life1 Binding<'life2>, ) -> Pin<Box<dyn Future<Output = Result<OpenedRequest, CratestackError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, CoseEnvelope: 'async_trait,

The signer is the key that verified: its full RFC 9679 thumbprint (not the 8-byte kid, which can collide), a copy of its kid (so the signer does not keep the body alive) and its algorithm. The same fields the CratestackEnvelope::open path records. One framing, so no seal context.

fn open_request_any<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, body: Bytes, binds: &'life1 [Binding<'life2>], ) -> Pin<Box<dyn Future<Output = Result<(OpenedRequest, usize), CratestackError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, CoseEnvelope: 'async_trait,

Parse and key resolution happen once; only the signature check runs per candidate binding.

fn seal_response<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, payload: &'life1 [u8], bind: &'life2 Binding<'life3>, _context: &'life4 SealContext, ) -> Pin<Box<dyn Future<Output = Result<Sealed, CratestackError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, CoseEnvelope: 'async_trait,

One copy of the payload into the message (D1), sent as this envelope’s mode’s media type.

fn is_envelope_content_type(&self, content_type: &str) -> bool

Whether content_type (a request’s Content-Type, or one Accept entry, parameters included) names this envelope’s framing. Only needed for a framing other than application/cose, which the layer always recognises itself; the default recognises nothing more.