Struct SignedEnvelope 

pub struct SignedEnvelope {
    pub pubkey: ByteBufB64,
    pub signature: ByteBufB64,
    pub digest: Option<ByteBufB64>,
    pub delegation: Option<Vec<SignedDelegationCompact>>,
}

The authentication envelope for Internet Computer authentication.

This structure encapsulates all the necessary components for authenticating a request to an Internet Computer service. It includes the public key of the sender, the signature, the content digest, and an optional delegation chain.

The envelope can be serialized to and from various formats, including bytes, base64 strings, and HTTP headers, making it versatile for different transport mechanisms.

Fields

pubkey: ByteBufB64

The public key of the self-authenticating principal this request is from. This is the head of the delegation chain (if any) and is used to derive the principal ID of the sender.

signature: ByteBufB64

A cryptographic signature authorizing the request. When delegations are involved, this is the signature from the tail of the delegation chain, not necessarily made by the owner of pubkey.

digest: Option<ByteBufB64>

The request content’s hash digest that was signed by the sender. This is typically a SHA-256 or SHA3-256 hash of the request content.

delegation: Option<Vec<SignedDelegationCompact>>

The chain of delegations connecting pubkey to signature, in order. Each delegation authorizes the next entity in the chain to sign on behalf of the previous entity, forming a chain of trust from the original identity to the actual signer.

Implementations

impl SignedEnvelope

pub fn sender(&self) -> Principal

Returns the sender’s principal ID derived from the public key.

This computes a self-authenticating principal ID based on the public key in the envelope, which uniquely identifies the sender.

Returns

• Principal - The principal ID of the sender

pub fn to_bytes(&self) -> Vec<u8>

Encodes the SignedEnvelope into a binary representation.

Returns

• Vec<u8> - The CBOR-encoded binary representation of the envelope

pub fn from_bytes(bytes: &[u8]) -> Result<SignedEnvelope, String>

Decodes a SignedEnvelope from its binary representation.

Arguments

• bytes - The CBOR-encoded binary representation of the envelope

Returns

• Result<Self, String> - The decoded envelope or an error message

pub fn to_base64(&self) -> String

Encodes the SignedEnvelope into a base64url string.

Returns

• String - The base64url-encoded representation of the envelope

pub fn from_base64(s: &str) -> Result<SignedEnvelope, String>

Decodes a SignedEnvelope from a base64url string.

Arguments

• s - The base64url-encoded string representation of the envelope

Returns

• Result<Self, String> - The decoded envelope or an error message

pub fn verify( &self, now_ms: u64, expect_target: Option<Principal>, expect_digest: Option<&[u8]>, ) -> Result<(), String>

Verifies the SignedEnvelope according to the Internet Computer authentication rules.

Verification rules:

• Delegation chain length must not exceed 5
• Delegations must not be expired (considering the permitted time drift)
• Each signature in the chain must verify against the corresponding public key
• If delegation targets are specified, the expected target must be included
• The content digest must match the expected digest (if provided)

Arguments

• now_ms - The current time in milliseconds since the Unix epoch
• expect_target - Optional canister ID that should be in the delegation targets
• expect_digest - Optional expected content digest to verify against

Returns

• Ok(()) if verification succeeds
• Err(String) with a detailed error message if verification fails

pub fn from_authorization(headers: &HeaderMap) -> Option<SignedEnvelope>

Extracts a SignedEnvelope from the Authorization header.

This looks for an “ICP” authentication scheme in the Authorization header and decodes the associated token as a SignedEnvelope.

Arguments

• headers - The HTTP headers to extract from

Returns

• Option<Self> - The extracted envelope, or None if not found or invalid

pub fn to_authorization(&self, headers: &mut HeaderMap) -> Result<(), String>

Adds the SignedEnvelope to the Authorization header.

This encodes the envelope as a base64url string and adds it to the Authorization header with the “ICP” authentication scheme.

Arguments

• headers - The HTTP headers to add to

Returns

• Result<(), String> - Success or an error message if adding fails

pub fn from_headers(headers: &HeaderMap) -> Option<SignedEnvelope>

Extracts a SignedEnvelope from the IC-Auth-* HTTP headers.

This looks for the individual components of the envelope in separate headers and reconstructs the envelope from them.

Arguments

• headers - The HTTP headers to extract from

Returns

• Option<Self> - The extracted envelope, or None if not found or invalid

pub fn to_headers(&self, headers: &mut HeaderMap) -> Result<(), String>

Adds the SignedEnvelope components to the IC-Auth-* HTTP headers.

This breaks down the envelope into its components and adds each one to a separate HTTP header.

Arguments

• headers - The HTTP headers to add to

Returns

• Result<(), String> - Success or an error message

Trait Implementations

impl CandidType for SignedEnvelope

fn _ty() -> Type

fn id() -> TypeId

fn idl_serialize<__S>( &self, __serializer: __S, ) -> Result<(), <__S as Serializer>::Error>

where __S: Serializer,

fn ty() -> Type

impl Clone for SignedEnvelope

fn clone(&self) -> SignedEnvelope

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SignedEnvelope

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SignedEnvelope

fn deserialize<__D>( __deserializer: __D, ) -> Result<SignedEnvelope, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<SignedEnvelopeFull> for SignedEnvelope

fn from(envelope: SignedEnvelopeFull) -> SignedEnvelope

Converts to this type from the input type.

impl Serialize for SignedEnvelope

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.