Struct Envelope

Source

pub struct Envelope {
    pub federation: FederationId,
    pub attempt: AttemptId,
    pub sender: EndpointIdentity,
    pub recipient: EndpointIdentity,
    pub body: Body,
    /* private fields */
}

Expand description

A verified or to-be-signed FCP envelope.

Both signatures authenticate the exact same canonical bytes, including the complete sender and recipient identities. No single-signature record is a valid FCP envelope.

Fields§

§federation: FederationId

Federation routing namespace.

§attempt: AttemptId

Connection attempt identifier.

§sender: EndpointIdentity

Complete identity of the envelope author.

§recipient: EndpointIdentity

Complete identity of the intended endpoint.

§body: Body

Kind-specific body.

Implementations§

Source §

impl Envelope

Source

pub fn sign<S: EndpointSigner>( signer: &S, federation: FederationId, attempt: AttemptId, recipient: EndpointIdentity, body: Body, ) -> Result<Self, Error>

Creates and signs a canonical FCP envelope with both required algorithms.

Examples found in repository ?

examples/wire_benchmark.rs (lines 32-38)

23fn signed_wire(body: Body) -> Vec<u8> {
24    let signer = SigningIdentity::new(
25        SigningKey::from_bytes(&[41; 32]),
26        MlDsaSigningKey::<MlDsa65>::from_seed(&B32::from([41; 32])),
27    );
28    let recipient = SigningIdentity::new(
29        SigningKey::from_bytes(&[42; 32]),
30        MlDsaSigningKey::<MlDsa65>::from_seed(&B32::from([42; 32])),
31    );
32    Envelope::sign(
33        &signer,
34        FederationId::from_bytes([1; 32]),
35        AttemptId::from_bytes([2; 16]),
36        recipient.endpoint(),
37        body,
38    )
39    .expect("bounded test envelope")
40    .encode()
41    .expect("canonical wire")
42}

Source

pub fn decode(wire: &[u8]) -> Result<Self, Error>

Parses one complete canonical envelope without trusting its sender.

Source

pub fn decode_verified(wire: &[u8]) -> Result<Self, Error>

Parses and verifies one canonical envelope before returning it.

Examples found in repository ?

examples/wire_benchmark.rs (line 49)

44fn measure(name: &str, wire: &[u8]) {
45    let samples = u32::try_from(SAMPLES).expect("fixed sample count fits u32");
46    let start = Instant::now();
47    let mut total = 0_u32;
48    for _ in 0..samples {
49        let envelope = Envelope::decode_verified(black_box(wire)).expect("verified fixture");
50        let encoded = envelope.encode().expect("canonical re-encode");
51        let bytes = u32::try_from(encoded.len()).expect("bounded envelope fits u32");
52        total = total
53            .checked_add(bytes)
54            .expect("fixed benchmark byte count fits u32");
55        black_box(envelope);
56    }
57    let seconds = start.elapsed().as_secs_f64();
58    let envelopes_per_second = f64::from(samples) / seconds;
59    let mebibytes_per_second = f64::from(total) / (1024.0 * 1024.0) / seconds;
60    println!(
61        "{name}\twire_bytes={}\tsamples={SAMPLES}\tenvelopes_per_second={envelopes_per_second:.0}\tMiB_per_second={mebibytes_per_second:.2}",
62        wire.len()
63    );
64}

Source

pub fn verify(&self) -> Result<(), Error>

Verifies both mandatory signatures under the embedded sender identity.

Source

pub fn kind(&self) -> Kind

Returns the kind carried by this envelope.

Source

pub fn id(&self) -> Result<EnvelopeId, Error>

Returns the stable envelope id.

Source

pub fn encode(&self) -> Result<Vec<u8>, Error>

Returns the full canonical signed envelope wire encoding.

Examples found in repository ?

examples/wire_benchmark.rs (line 40)

23fn signed_wire(body: Body) -> Vec<u8> {
24    let signer = SigningIdentity::new(
25        SigningKey::from_bytes(&[41; 32]),
26        MlDsaSigningKey::<MlDsa65>::from_seed(&B32::from([41; 32])),
27    );
28    let recipient = SigningIdentity::new(
29        SigningKey::from_bytes(&[42; 32]),
30        MlDsaSigningKey::<MlDsa65>::from_seed(&B32::from([42; 32])),
31    );
32    Envelope::sign(
33        &signer,
34        FederationId::from_bytes([1; 32]),
35        AttemptId::from_bytes([2; 16]),
36        recipient.endpoint(),
37        body,
38    )
39    .expect("bounded test envelope")
40    .encode()
41    .expect("canonical wire")
42}
43
44fn measure(name: &str, wire: &[u8]) {
45    let samples = u32::try_from(SAMPLES).expect("fixed sample count fits u32");
46    let start = Instant::now();
47    let mut total = 0_u32;
48    for _ in 0..samples {
49        let envelope = Envelope::decode_verified(black_box(wire)).expect("verified fixture");
50        let encoded = envelope.encode().expect("canonical re-encode");
51        let bytes = u32::try_from(encoded.len()).expect("bounded envelope fits u32");
52        total = total
53            .checked_add(bytes)
54            .expect("fixed benchmark byte count fits u32");
55        black_box(envelope);
56    }
57    let seconds = start.elapsed().as_secs_f64();
58    let envelopes_per_second = f64::from(samples) / seconds;
59    let mebibytes_per_second = f64::from(total) / (1024.0 * 1024.0) / seconds;
60    println!(
61        "{name}\twire_bytes={}\tsamples={SAMPLES}\tenvelopes_per_second={envelopes_per_second:.0}\tMiB_per_second={mebibytes_per_second:.2}",
62        wire.len()
63    );
64}