Skip to main content

ResponseEnvelope

Struct ResponseEnvelope 

Source
pub struct ResponseEnvelope {
    pub request_id: u64,
    pub payload: Vec<u8>,
    pub encrypted_response: Option<Vec<u8>>,
    pub sig: [u8; 64],
    pub cnf: [u8; 32],
    pub cose: Vec<u8>,
    pub policy: CryptoPolicy,
    pub server_challenge: Option<Vec<u8>>,
}
Expand description

Signed response envelope for E2E authenticated responses.

All RPC responses are signed to prevent MITM attacks on response data (e.g., server’s DH public key in StreamInfo).

§Security (#275 — Hybrid parity with SignedEnvelope)

The signing-data is request_id || payload, binding the response to a specific request and ensuring the payload hasn’t been tampered with. The authoritative authentication mechanism is the COSE composite cose — the pinned EdDSA + ML-DSA-65 composite over that signing-data, bound to RESPONSE_ENVELOPE_TYPE_ID via the COSE external_aad so it can NEVER verify as a request signature.

sig/cnf remain populated with the raw EdDSA signature + signer public key for backward compatibility and signer-pubkey advertisement, but the COSE composite is what verify* enforces.

Fields§

§request_id: u64

Request ID this response corresponds to

§payload: Vec<u8>

Serialized inner response

§encrypted_response: Option<Vec<u8>>

HyKEM COSE_Encrypt0 carrying a ResponsePlaintext. When present the outer payload is empty and the hybrid signature covers these bytes.

§sig: [u8; 64]

Ed25519 signature (64 bytes) over request_id || payload

§cnf: [u8; 32]

Ed25519 public key of the signer (32 bytes)

§cose: Vec<u8>

#275: CBOR-encoded nested COSE composite signature (detached).

Authoritative authentication mechanism, mirroring SignedEnvelope::cose. Production carries the pinned EdDSA + ML-DSA-65 composite over the response signing-data (request_id || payload), bound to the distinct RESPONSE_ENVELOPE_TYPE_ID domain. The ML-DSA-65 verifying key is resolved by kid from a PqTrustStore (kid-anchored), not embedded.

§policy: CryptoPolicy

Signature suite marker. Production construction always uses Hybrid.

§server_challenge: Option<Vec<u8>>

v16 §4.7: the server’s current unattributed-proof challenge, carried uniformly on every pre-handler denial.

Bound into the signing transcript when present (see ResponseEnvelope::bind_server_challenge), so it can neither be stripped nor substituted in flight. Absent on ordinary responses, where the transcript is unchanged.

Implementations§

Source§

impl ResponseEnvelope

Source

pub fn new_signed_hybrid( request_id: u64, payload: Vec<u8>, signing_key: &SigningKey, pq_signing_key: &MlDsaSigningKey, ) -> Self

Create and dual-sign a response with Ed25519 + ML-DSA-65 (Hybrid).

Source

pub fn new_signed_with_policy( request_id: u64, payload: Vec<u8>, signing_key: &SigningKey, pq_signing_key: Option<&MlDsaSigningKey>, policy: CryptoPolicy, ) -> Result<Self>

Create and sign a response under an explicit [CryptoPolicy].

Mirrors SignedEnvelope::new_signed_with_policy:

  • Hybrid: EdDSA + ML-DSA-65 nested composite; pq_signing_key MUST be Some; absence is a fail-closed construction error returned as Err.

sig/cnf are always populated with the raw EdDSA signature + signer public key. The COSE build is fail-closed: a missing mandatory PQ key or a COSE encoding error is propagated as Err rather than silently emitting an empty (fail-open) composite, matching the request side.

Source

pub fn new_signed_with_challenge( request_id: u64, payload: Vec<u8>, server_challenge: Option<Vec<u8>>, signing_key: &SigningKey, pq_signing_key: Option<&MlDsaSigningKey>, policy: CryptoPolicy, ) -> Result<Self>

Create and sign a response that also advertises the server’s current challenge in the fixed response slot (§4.7).

The challenge is part of the signed transcript, so a denial’s challenge is as authentic as its payload.

Source

pub fn new_signed_encrypted( request_id: u64, payload: Vec<u8>, signing_key: &SigningKey, pq_signing_key: &MlDsaSigningKey, recipient: &RecipientPublic, request_iat: i64, request_nonce: &[u8; 16], service_domain: &str, ) -> EnvelopeResult<Self>

Seal a unary response to the request’s one-shot recipient, then hybrid-sign the ciphertext in the response signature domain.

Source

pub fn new_signed_encrypted_with_challenge( request_id: u64, payload: Vec<u8>, server_challenge: Option<Vec<u8>>, signing_key: &SigningKey, pq_signing_key: &MlDsaSigningKey, recipient: &RecipientPublic, request_iat: i64, request_nonce: &[u8; 16], service_domain: &str, ) -> EnvelopeResult<Self>

Seal a unary response that also advertises the server’s current challenge, so a denial on a confidential carrier carries one too.

The challenge is a public server value and rides in the cleartext slot — a client that cannot yet form an admissible proof must be able to read it — but it is bound into the sealed response’s signature transcript, so it can be neither stripped nor substituted.

Source

pub fn verify_with( &self, expected_pubkey: Option<&VerifyingKey>, pq_store: Option<&dyn PqTrustStore>, verify_policy: CryptoPolicy, ) -> Result<()>

Verify with an explicit kid-anchored PQ trust store and verify policy.

Mirrors SignedEnvelope::verify_with’s mandatory-hybrid semantics:

  • pq_store: when Some, resolves the trust-anchored ML-DSA-65 key for the response’s EdDSA signer (cnf); the outer COSE entry must verify against it and its kid must match (kid-anchoring).
  • verify_policy = Hybrid requires an anchored ML-DSA-65 key and the intact outer signature. Unanchored and classical-only responses fail.
Source

pub fn cnf_key(&self) -> Result<VerifyingKey>

Get the signer’s public key.

Trait Implementations§

Source§

impl Clone for ResponseEnvelope

Source§

fn clone(&self) -> ResponseEnvelope

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for ResponseEnvelope

Source§

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

Formats the value using the given formatter. Read more
Source§

impl FromCapnp for ResponseEnvelope

Source§

type Reader<'a> = Reader<'a>

The Cap’n Proto reader type for this struct.
Source§

fn read_from(reader: Self::Reader<'_>) -> Result<Self>

Read this struct’s fields from the reader.
Source§

impl ToCapnp for ResponseEnvelope

Source§

type Builder<'a> = Builder<'a>

The Cap’n Proto builder type for this struct.
Source§

fn write_to(&self, builder: &mut Self::Builder<'_>)

Write this struct’s fields to the builder.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,

Source§

impl<T> TerminalState for T
where T: Clone + Send + Sync,