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: RequestEnvelopeThe 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: CryptoPolicySignature 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
impl SignedEnvelope
Sourcepub fn new_signed_hybrid(
envelope: RequestEnvelope,
signing_key: &SigningKey,
pq_signing_key: &MlDsaSigningKey,
) -> Self
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).
Sourcepub fn new_signed_with_policy(
envelope: RequestEnvelope,
signing_key: &SigningKey,
pq_signing_key: Option<&MlDsaSigningKey>,
policy: CryptoPolicy,
) -> Result<Self>
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_keyMUST beSome; 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.
Sourcepub fn new_signed_encrypted_mesh_kem(
envelope: RequestEnvelope,
signing_key: &SigningKey,
pq_signing_key: &MlDsaSigningKey,
server_kem_public: &RecipientPublic,
) -> EnvelopeResult<Self>
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).
Sourcepub fn is_encrypted(&self) -> bool
pub fn is_encrypted(&self) -> bool
Returns true if this envelope uses the encrypted path.
Sourcepub fn verify_with(
&self,
expected_pubkey: &VerifyingKey,
nonce_cache: &dyn NonceCache,
pq_store: Option<&dyn PqTrustStore>,
verify_policy: CryptoPolicy,
) -> EnvelopeResult<()>
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: whenSome, 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 pinsHybrid, 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.
Sourcepub fn verify_signature_only_with(
&self,
expected_pubkey: &VerifyingKey,
pq_store: Option<&dyn PqTrustStore>,
verify_policy: CryptoPolicy,
) -> EnvelopeResult<()>
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.
Sourcepub fn verify_any_signer_with(
&self,
nonce_cache: &dyn NonceCache,
pq_store: Option<&dyn PqTrustStore>,
verify_policy: CryptoPolicy,
) -> EnvelopeResult<()>
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.
Sourcepub fn decrypt_in_place_mesh_kem(
&mut self,
node_kem_keypair: &RecipientKeypair,
) -> EnvelopeResult<()>
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.
Sourcepub fn request_id(&self) -> u64
pub fn request_id(&self) -> u64
Get the request ID from the inner envelope.
Get the authorization context.
Trait Implementations§
Source§impl Clone for SignedEnvelope
impl Clone for SignedEnvelope
Source§fn clone(&self) -> SignedEnvelope
fn clone(&self) -> SignedEnvelope
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Debug for SignedEnvelope
impl Debug for SignedEnvelope
Source§impl FromCapnp for SignedEnvelope
impl FromCapnp for SignedEnvelope
Auto Trait Implementations§
impl Freeze for SignedEnvelope
impl RefUnwindSafe for SignedEnvelope
impl Send for SignedEnvelope
impl Sync for SignedEnvelope
impl Unpin for SignedEnvelope
impl UnsafeUnpin for SignedEnvelope
impl UnwindSafe for SignedEnvelope
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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