Skip to main content

SignedEnvelope

Struct SignedEnvelope 

Source
pub struct SignedEnvelope {
    pub envelope: RequestEnvelope,
    pub sig: [u8; 64],
    pub cnf: [u8; 32],
    pub encrypted_envelope: Option<Vec<u8>>,
    pub client_ephemeral_public: Option<[u8; 32]>,
    pub cose: Vec<u8>,
    pub policy: CryptoPolicy,
    pub pq_kem_ciphertext: Option<Vec<u8>>,
}
Expand description

Signed envelope wrapping a RequestEnvelope with Ed25519 signature.

The signature covers the serialized bytes of the inner RequestEnvelope, making the signing scope structurally explicit.

§Security

  • Signature survives message forwarding (unlike transport-layer auth)
  • Nonce + timestamp prevent replay attacks
  • Signer pubkey included for verification without key lookup

§Example

ⓘ
use hyprstream_rpc::envelope::{RequestEnvelope, SignedEnvelope};
use hyprstream_rpc::crypto::SigningKey;

// Create and sign
let envelope = RequestEnvelope::anonymous(payload);
let signed = SignedEnvelope::new_signed(envelope, &signing_key);

// Verify
signed.verify(&expected_pubkey, &nonce_cache)?;

Fields§

§envelope: RequestEnvelope

The unsigned envelope (cleartext path, or decrypted from encrypted_envelope)

§sig: [u8; 64]

Ed25519 signature (64 bytes)

§cnf: [u8; 32]

Ed25519 public key of the signer (32 bytes)

§encrypted_envelope: Option<Vec<u8>>

AES-256-GCM-SIV ciphertext of serialized RequestEnvelope (None = cleartext mode)

§client_ephemeral_public: Option<[u8; 32]>

X25519 ephemeral public key for DH key agreement (present when encrypted)

§cose: Vec<u8>

M3 (#152): CBOR-encoded COSE_Sign composite signature (detached).

Authoritative authentication mechanism. Production envelopes carry the pinned EdDSA + ML-DSA-65 composite over the canonical signing-data. EdDSA-only encoding remains available only to test fixtures. The ML-DSA-65 verifying key is NOT embedded; it is resolved by kid from a trust store (kid-anchored), which fixes the prior self-certification weakness.

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

§policy: CryptoPolicy

Signature suite marker. Production construction always uses Hybrid.

§pq_kem_ciphertext: Option<Vec<u8>>

ML-KEM-768 ciphertext (1088 bytes, present when hybrid encryption is used)

Implementations§

Source§

impl SignedEnvelope

Source

pub fn new_signed_hybrid( envelope: RequestEnvelope, signing_key: &SigningKey, pq_signing_key: &MlDsaSigningKey, ) -> Self

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

Source

pub fn new_signed_with_policy( envelope: RequestEnvelope, signing_key: &SigningKey, pq_signing_key: Option<&MlDsaSigningKey>, policy: CryptoPolicy, ) -> Result<Self>

Create and sign a new envelope under an explicit [CryptoPolicy].

  • Hybrid: emits an EdDSA + ML-DSA-65 COSE composite. pq_signing_key MUST be Some; absence is a fail-closed construction error.

sig/cnf are always populated with the raw EdDSA signature + signer public key for the cnf key-binding path.

Source

pub fn new_signed_encrypted_mesh_kem( envelope: RequestEnvelope, signing_key: &SigningKey, pq_signing_key: &MlDsaSigningKey, server_kem_public: &RecipientPublic, ) -> EnvelopeResult<Self>

Create, hybrid-encrypt (HyKEM #mesh-kem → COSE_Encrypt0), and dual-sign (EdDSA + ML-DSA-65) a new envelope — the fail-closed hybrid-PQ path (#555 / S4).

The serialized RequestEnvelope is sealed with crate::crypto::cose_encrypt::seal_to_recipient to the server’s anchored #mesh-kem crate::crypto::hybrid_kem::RecipientPublic (resolved out-of-band via a crate::crypto::hybrid_kem::KemTrustStore, NEVER self-asserted). The KEM material rides inside the COSE_Encrypt0 (ek header), so the COSE composite signature simply covers the COSE_Encrypt0 bytes.

This replaces the retired envelope_crypto X25519-static scheme, which reused the Ed25519 signing key as a static X25519 KEX key (key-reuse + no forward secrecy + fixed-zero-nonce AEAD). Forward secrecy now comes from the ephemeral X25519 leg of HyKEM and from rotated #mesh-kem prekeys (S1 KemPrekey).

Source

pub fn is_encrypted(&self) -> bool

Returns true if this envelope uses the encrypted path.

Source

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

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

  • pq_store: when Some, resolves the trust-anchored ML-DSA-65 key for the envelope’s EdDSA signer (cnf). The COSE ML-DSA-65 entry must verify against this key and its kid must match (kid-anchoring) — fixing the self-certification weakness.
  • verify_policy: production pins Hybrid, which requires an anchored ML-DSA-65 key and enforces the outer layer. Missing anchors, stripped outers, forged keys, and self-asserted PQ keys all fail closed.
Source

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

Verify signature only under an explicit policy + PQ trust store.

Source

pub fn verify_any_signer_with( &self, nonce_cache: &dyn NonceCache, pq_store: Option<&dyn PqTrustStore>, verify_policy: CryptoPolicy, ) -> EnvelopeResult<()>

verify_any_signer with an explicit kid-anchored PQ trust store + policy.

Source

pub fn decrypt_in_place_mesh_kem( &mut self, node_kem_keypair: &RecipientKeypair, ) -> EnvelopeResult<()>

Decrypt a #mesh-kem-encrypted envelope in-place, replacing envelope.

Opens the COSE_Encrypt0 in encrypted_envelope with the node’s #mesh-kem crate::crypto::hybrid_kem::RecipientKeypair (deterministically derived from the node Ed25519 key — see crate::node_identity::derive_mesh_kem_recipient). The encrypted bytes remain for signature verification.

Source

pub fn request_id(&self) -> u64

Get the request ID from the inner envelope.

Source

pub fn payload(&self) -> &[u8] ⓘ

Get the payload from the inner envelope.

Source

pub fn authorization(&self) -> &Authorization

Get the authorization context.

Trait Implementations§

Source§

impl Clone for SignedEnvelope

Source§

fn clone(&self) -> SignedEnvelope

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 SignedEnvelope

Source§

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

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

impl FromCapnp for SignedEnvelope

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 SignedEnvelope

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,