Struct bc_envelope::base::envelope::Envelope

pub struct Envelope(/* private fields */);

A flexible container for structured data.

Envelopes are immutable. You create “mutations” by creating new envelopes from old envelopes.

Implementations

impl Envelope

Support for adding assertions.

pub fn add_assertion( &self, predicate: impl EnvelopeEncodable, object: impl EnvelopeEncodable ) -> Self

Returns the result of adding the given assertion to the envelope.

pub fn add_assertion_envelope( &self, assertion_envelope: Self ) -> Result<Self, EnvelopeError>

Returns the result of adding the given assertion to the envelope.

The assertion envelope must be a valid assertion envelope, or an obscured variant (elided, encrypted, compressed) of one.

pub fn add_assertion_envelopes( &self, assertions: &[Self] ) -> Result<Self, EnvelopeError>

Returns the result of adding the given array of assertions to the envelope.

Each assertion envelope must be a valid assertion envelope, or an obscured variant (elided, encrypted, compressed) of one.

pub fn add_optional_assertion_envelope( &self, assertion: Option<Self> ) -> Result<Self, EnvelopeError>

If the optional assertion is present, returns the result of adding it to the envelope. Otherwise, returns the envelope unchanged.

The assertion envelope must be a valid assertion envelope, or an obscured variant (elided, encrypted, compressed) of one.

pub fn add_optional_assertion( &self, predicate: impl EnvelopeEncodable, object: Option<impl EnvelopeEncodable> ) -> Self

If the optional object is present, returns the result of adding the assertion to the envelope. Otherwise, returns the envelope unchanged.

pub fn add_assertions(&self, envelopes: &[Self]) -> Self

Returns a new Envelope with the given array of assertions added.

• Parameter assertions: The assertions to add.

impl Envelope

Support for adding conditional assertions.

pub fn add_assertion_if( &self, condition: bool, predicate: impl EnvelopeEncodable, object: impl EnvelopeEncodable ) -> Self

If the condition is true, returns the result of adding the given assertion to the envelope. Otherwise, returns the envelope unchanged.

pub fn add_assertion_envelope_if( &self, condition: bool, assertion_envelope: Self ) -> Result<Self, EnvelopeError>

If the condition is true, returns the result of adding the given assertion to the envelope. Otherwise, returns the envelope unchanged.

impl Envelope

Support for adding assertions with salt.

pub fn add_assertion_salted<P, O>( &self, predicate: P, object: O, salted: bool ) -> Self

where P: EnvelopeEncodable, O: EnvelopeEncodable,

Returns the result of adding the given assertion to the envelope, optionally salting it.

pub fn add_assertion_envelope_salted( &self, assertion_envelope: Self, salted: bool ) -> Result<Self, EnvelopeError>

Returns the result of adding the given assertion to the envelope, optionally salting it.

The assertion envelope must be a valid assertion envelope, or an obscured variant (elided, encrypted, compressed) of one.

pub fn add_optional_assertion_envelope_salted( &self, assertion: Option<Self>, salted: bool ) -> Result<Self, EnvelopeError>

If the optional assertion is present, returns the result of adding it to the envelope, optionally salting it. Otherwise, returns the envelope unchanged.

The assertion envelope must be a valid assertion envelope, or an obscured variant (elided, encrypted, compressed) of one.

pub fn add_assertions_salted(&self, assertions: &[Self], salted: bool) -> Self

impl Envelope

Support for removing or replacing assertions.

pub fn remove_assertion(&self, target: Self) -> Self

Returns a new envelope with the given assertion removed. If the assertion does not exist, returns the same envelope.

pub fn replace_assertion( &self, assertion: Self, new_assertion: Self ) -> Result<Self, EnvelopeError>

Returns a new envelope with the given assertion replaced by the provided one. If the targeted assertion does not exist, returns the same envelope.

pub fn replace_subject(&self, subject: Self) -> Self

Returns a new envelope with its subject replaced by the provided one.

impl Envelope

Support for working with the digest tree of an Envelope.

pub fn digests(&self, level_limit: usize) -> HashSet<Digest>

Returns the set of digests contained in the envelope’s elements, down to the specified level.

The digest of the envelope is included as well as the digest of the envelope’s subject (if it is different).

If no levelLimit is provided, all digests in the envelope will be returned.

A levelLimit of zero will return no digests.

Arguments

• levelLimit - Return digests at levels below this value.

Returns

• A set of digests down to levelLimit.

pub fn deep_digests(&self) -> HashSet<Digest>

Returns the set of all digests in the envelope.

pub fn shallow_digests(&self) -> HashSet<Digest>

Returns the set of all digests in the envelope, down to its second level.

pub fn structural_digest(&self) -> Digest

Produce a value that will necessarily be different if two envelopes differ structurally, even if they are semantically equivalent.

Comparing the digest field of two envelopes (or calling isEquivalent(to:)) tests whether two envelopes are semantically equivalent. This is accomplished by simply comparing the top level digests of the envelopes for equality, and has a complexity of O(1).

This means that two envelopes are considered equivalent if they contain identical information in their completely unencrypted and unelided form.

Some applications need to determine whether two envelopes are not only semantically equivalent, but also structurally identical. Two envelopes that are not semantically equivalent cannot be structurally identical, but two envelopes that are semantically equivalent may or may not be structurally identical.

The structural_digest attribute is used to produce a value that will necessarily be different if two envelopes differ structurally, even if they are semantically equivalent. It has a complexity of O(m + n) where m and n are the number of elements in each of the two envelopes when they are semantically equivalent. It is recommended that envelopes be compared for structural equality by calling isIdentical(to:) as this short-circuits to false in cases where the compared envelopes are not semantically equivalent.

pub fn is_equivalent_to(&self, other: Self) -> bool

Tests two envelopes for semantic equivalence.

Calling e1.is_equivalent_to(e2) has a complexity of O(1) and simply compares the two envelope’s digests. The means that two envelopes with certain structural differences (e.g., one envelope is partially elided and the other is not) will still test as equivalent.

pub fn is_identical_to(&self, other: Self) -> bool

Tests two envelopes for structural equality.

Calling e1.is_identical_to(e2) has a complexity of O(1) if the envelopes are not semantically equivalent (that is, their top-level digests are different, and thus they must have different structures) and a complexity of O(m + n) where m and n are the number of elements in each of the two envelopes when they are semantically equivalent.

impl Envelope

pub fn case(&self) -> &EnvelopeCase

impl Envelope

pub fn false() -> Self

pub fn true() -> Self

pub fn null() -> Self

pub fn is_false(&self) -> bool

pub fn is_true(&self) -> bool

pub fn is_null(&self) -> bool

impl Envelope

Support for basic envelope creation.

pub fn new<E>(subject: E) -> Self

where E: EnvelopeEncodable,

Creates an envelope with a subject, which can be any instance that implements IntoEnvelope.

pub fn new_assertion<P, O>(predicate: P, object: O) -> Self

where P: EnvelopeEncodable, O: EnvelopeEncodable,

Creates an assertion envelope with a predicate and object, each of which can be any instance that implements IntoEnvelope.

impl Envelope

Support for eliding elements from envelopes.

This includes eliding, encrypting and compressing (obscuring) elements.

pub fn elide(&self) -> Self

Returns the elided variant of this envelope.

Returns the same envelope if it is already elided.

pub fn elide_removing_set_with_action( &self, target: &HashSet<Digest>, action: &ObscureAction ) -> Self

Returns a version of this envelope with elements in the target set elided.

• Parameters:

  • target: The target set of digests.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_removing_set(&self, target: &HashSet<Digest>) -> Self

Returns a version of this envelope with elements in the target set elided.

• Parameters:

  • target: The target set of digests.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_removing_array_with_action( &self, target: &[&dyn DigestProvider], action: &ObscureAction ) -> Self

Returns a version of this envelope with elements in the target set elided.

• Parameters:

  • target: An array of DigestProviders.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_removing_array(&self, target: &[&dyn DigestProvider]) -> Self

Returns a version of this envelope with elements in the target set elided.

• Parameters:

  • target: An array of DigestProviders.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_removing_target_with_action( &self, target: &dyn DigestProvider, action: &ObscureAction ) -> Self

Returns a version of this envelope with the target element elided.

• Parameters:

  • target: A DigestProvider.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_removing_target(&self, target: &dyn DigestProvider) -> Self

Returns a version of this envelope with the target element elided.

• Parameters:

  • target: A DigestProvider.

• Returns: The elided envelope.

pub fn elide_revealing_set_with_action( &self, target: &HashSet<Digest>, action: &ObscureAction ) -> Self

Returns a version of this envelope with elements not in the target set elided.

• Parameters:

  • target: The target set of digests.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_revealing_set(&self, target: &HashSet<Digest>) -> Self

Returns a version of this envelope with elements not in the target set elided.

• Parameters:

  • target: The target set of digests.

• Returns: The elided envelope.

pub fn elide_revealing_array_with_action( &self, target: &[&dyn DigestProvider], action: &ObscureAction ) -> Self

Returns a version of this envelope with elements not in the target set elided.

• Parameters:

  • target: An array of DigestProviders.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_revealing_array(&self, target: &[&dyn DigestProvider]) -> Self

Returns a version of this envelope with elements not in the target set elided.

• Parameters:

  • target: An array of DigestProviders.

• Returns: The elided envelope.

pub fn elide_revealing_target_with_action( &self, target: &dyn DigestProvider, action: &ObscureAction ) -> Self

Returns a version of this envelope with all elements except the target element elided.

• Parameters:

  • target: A DigestProvider.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_revealing_target(&self, target: &dyn DigestProvider) -> Self

Returns a version of this envelope with all elements except the target element elided.

• Parameters:

  • target: A DigestProvider.

• Returns: The elided envelope.

pub fn elide_set_with_action( &self, target: &HashSet<Digest>, is_revealing: bool, action: &ObscureAction ) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: The target set of digests.
  • isRevealing: If true, the target set contains the digests of the elements to leave revealed. If it is false, the target set contains the digests of the elements to elide.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_set(&self, target: &HashSet<Digest>, is_revealing: bool) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: The target set of digests.
  • isRevealing: If true, the target set contains the digests of the elements to leave revealed. If it is false, the target set contains the digests of the elements to elide.

• Returns: The elided envelope.

pub fn elide_array_with_action( &self, target: &[&dyn DigestProvider], is_revealing: bool, action: &ObscureAction ) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: An array of DigestProviders.
  • isRevealing: If true, the target set contains the digests of the elements to leave revealed. If it is false, the target set contains the digests of the elements to elide.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_array( &self, target: &[&dyn DigestProvider], is_revealing: bool ) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: An array of DigestProviders.
  • isRevealing: If true, the target set contains the digests of the elements to leave revealed. If it is false, the target set contains the digests of the elements to elide.

• Returns: The elided envelope.

pub fn elide_target_with_action( &self, target: &dyn DigestProvider, is_revealing: bool, action: &ObscureAction ) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: A DigestProvider.
  • isRevealing: If true, the target is the element to leave revealed, eliding all others. If it is false, the target is the element to elide, leaving all others revealed.
  • action: Perform the specified action (elision, encryption or compression).

• Returns: The elided envelope.

pub fn elide_target( &self, target: &dyn DigestProvider, is_revealing: bool ) -> Self

Returns an elided version of this envelope.

• Parameters:

  • target: A DigestProvider.
  • isRevealing: If true, the target is the element to leave revealed, eliding all others. If it is false, the target is the element to elide, leaving all others revealed.

• Returns: The elided envelope.

pub fn unelide(&self, envelope: Self) -> Result<Self, EnvelopeError>

Returns the unelided variant of this envelope.

Returns the same envelope if it is already unelided.

impl Envelope

Support for various queries on envelopes.

pub fn subject(&self) -> Self

The envelope’s subject.

For an envelope with no assertions, returns the same envelope.

pub fn assertions(&self) -> Vec<Self>

The envelope’s assertions.

pub fn has_assertions(&self) -> bool

true if the envelope has at least one assertion, false otherwise.

pub fn assertion(&self) -> Option<Self>

If the envelope’s subject is an assertion return it, else return None.

pub fn expect_assertion(&self) -> Result<Self, EnvelopeError>

If the envelope’s subject is an assertion return it, else return an error.

pub fn predicate(&self) -> Option<Self>

The envelope’s predicate, or None if the envelope is not an assertion.

pub fn expect_predicate(&self) -> Result<Self, EnvelopeError>

The envelope’s predicate, or an error if the envelope is not an assertion.

pub fn object(&self) -> Option<Self>

The envelope’s object, or None if the envelope is not an assertion.

pub fn expect_object(&self) -> Result<Self, EnvelopeError>

The envelope’s object, or an error if the envelope is not an assertion.

pub fn leaf(&self) -> Option<&CBOR>

The envelope’s leaf CBOR object, or None if the envelope is not a leaf.

pub fn expect_leaf(&self) -> Result<&CBOR, EnvelopeError>

The envelope’s leaf CBOR object, or an error if the envelope is not a leaf.

pub fn known_value(&self) -> Option<&KnownValue>

The envelope’s KnownValue, or None if the envelope is not case ::KnownValue.

pub fn expect_known_value(&self) -> Result<&KnownValue, EnvelopeError>

The envelope’s KnownValue, or an error if the envelope is not case ::KnownValue.

pub fn is_leaf(&self) -> bool

true if the envelope is case ::Leaf, false otherwise.

pub fn is_node(&self) -> bool

true if the envelope is case ::Node, false otherwise.

pub fn is_wrapped(&self) -> bool

true if the envelope is case ::Wrapped, false otherwise.

pub fn is_known_value(&self) -> bool

true if the envelope is case ::KnownValue, false otherwise.

pub fn is_assertion(&self) -> bool

true if the envelope is case ::Assertion, false otherwise.

pub fn is_encrypted(&self) -> bool

true if the envelope is case ::Encrypted, false otherwise.

pub fn is_compressed(&self) -> bool

true if the envelope is case ::Compressed, false otherwise.

pub fn is_elided(&self) -> bool

true if the envelope is case ::Elided, false otherwise.

pub fn is_subject_assertion(&self) -> bool

true if the subject of the envelope is an assertion, false otherwise.

pub fn is_subject_encrypted(&self) -> bool

true if the subject of the envelope has been encrypted, false otherwise.

pub fn is_subject_compressed(&self) -> bool

true if the subject of the envelope has been compressed, false otherwise.

pub fn is_subject_elided(&self) -> bool

true if the subject of the envelope has been elided, false otherwise.

pub fn is_subject_obscured(&self) -> bool

true if the subject of the envelope has been encrypted, elided, or compressed, false otherwise.

Obscured assertion envelopes may exist in the list of an envelope’s assertions.

pub fn is_internal(&self) -> bool

true if the envelope is internal, that is, it has child elements, or false if it is a leaf node.

Internal elements include .node, .wrapped, and .assertion.

pub fn is_obscured(&self) -> bool

true if the envelope is encrypted, elided, or compressed; false otherwise.

pub fn extract_subject<T>(&self) -> Result<T>

where T: Any + CBORDecodable,

Returns the envelope’s subject, decoded as the given type.

If the encoded type doesn’t match the given type, returns Error::InvalidFormat.

pub fn assertions_with_predicate( &self, predicate: impl EnvelopeEncodable ) -> Vec<Self>

Returns all assertions with the given predicate. Match by comparing digests.

pub fn assertion_with_predicate( &self, predicate: impl EnvelopeEncodable ) -> Result<Self, EnvelopeError>

Returns the assertion with the given predicate.

Returns an error if there is no matching predicate or multiple matching predicates.

pub fn object_for_predicate( &self, predicate: impl EnvelopeEncodable ) -> Result<Self, EnvelopeError>

Returns the object of the assertion with the given predicate.

Returns an error if there is no matching predicate or multiple matching predicates.

pub fn extract_object_for_predicate<T: CBORDecodable + 'static>( &self, predicate: impl EnvelopeEncodable ) -> Result<T>

Returns the object of the assertion with the given predicate, decoded as the given type.

Returns an error if there is no matching predicate or multiple matching predicates. Returns an error if the encoded type doesn’t match the given type.

pub fn extract_optional_object_for_predicate<T: CBORDecodable + 'static>( &self, predicate: impl EnvelopeEncodable ) -> Result<Option<T>>

Returns the object of the assertion with the given predicate, or None if there is no matching predicate.

pub fn objects_for_predicate( &self, predicate: impl EnvelopeEncodable ) -> Vec<Self>

Returns the objects of all assertions with the matching predicate.

pub fn extract_objects_for_predicate<T: CBORDecodable>( &self, predicate: impl EnvelopeEncodable ) -> Result<Vec<T>>

Returns the objects of all assertions with the matching predicate, decoded as the given type.

Returns an error if the encoded type doesn’t match the given type.

pub fn elements_count(&self) -> usize

Returns the number of structural elements in the envelope, including itself.

impl Envelope

Support for the various text output formats for Envelope.

pub fn format_opt(&self, context: Option<&FormatContext>) -> String

Returns the envelope notation for this envelope.

pub fn format(&self) -> String

Returns the envelope notation for this envelope.

Uses the current format context.

pub fn diagnostic_opt( &self, annotate: bool, context: Option<&FormatContext> ) -> String

Returns the CBOR diagnostic notation for this envelope.

See RFC-8949 §8 for information on CBOR diagnostic notation.

pub fn diagnostic(&self) -> String

Returns the CBOR diagnostic notation for this envelope.

Uses the current format context.

See RFC-8949 §8 for information on CBOR diagnostic notation.

pub fn hex_opt(&self, annotate: bool, context: Option<&FormatContext>) -> String

Returns the CBOR hex dump of this envelope.

See RFC-8949 for information on the CBOR binary format.

pub fn hex(&self) -> String

Returns the CBOR hex dump of this envelope.

Uses the current format context.

See RFC-8949 for information on the CBOR binary format.

impl Envelope

Support for tree-formatting envelopes.

pub fn tree_format_opt( &self, hide_nodes: bool, context: Option<&FormatContext> ) -> String

pub fn tree_format(&self, hide_nodes: bool) -> String

pub fn tree_format_with_target_opt( &self, hide_nodes: bool, highlighting_target: &HashSet<Digest>, context: Option<&FormatContext> ) -> String

pub fn tree_format_with_target( &self, hide_nodes: bool, highlighting_target: &HashSet<Digest> ) -> String

impl Envelope

Functions for walking an envelope.

pub fn walk<Parent: Clone>(&self, hide_nodes: bool, visit: &Visitor<'_, Parent>)

Walk the envelope, calling the visitor function for each element.

If hide_nodes is true, then the visitor function will not be called for nodes, but only for the children of nodes.

impl Envelope

Support for wrapping and unwrapping envelopes.

pub fn wrap_envelope(&self) -> Self

Return a new envelope which wraps the current envelope.

pub fn unwrap_envelope(&self) -> Result<Self, EnvelopeError>

Unwraps and returns the inner envelope.

Returns an error if this is not a wrapped envelope.

impl Envelope

pub fn new_attachment<A>( payload: A, vendor: &str, conforms_to: Option<&str> ) -> Self

where A: EnvelopeEncodable,

Returns a new attachment envelope.

The payload envelope has a 'vendor': String assertion and an optional 'conformsTo': String assertion.

pub fn add_attachment<A>( &self, payload: A, vendor: &str, conforms_to: Option<&str> ) -> Self

where A: EnvelopeEncodable,

Returns a new envelope with an added 'attachment': Envelope assertion.

The payload envelope has a 'vendor': String assertion and an optional 'conformsTo': String assertion.

impl Envelope

pub fn attachment_payload(&self) -> Result<Self, EnvelopeError>

Returns the payload of the given attachment envelope.

pub fn attachment_vendor(&self) -> Result<String>

Returns the vendor of the given attachment envelope.

pub fn attachment_conforms_to(&self) -> Result<Option<String>>

Returns the conformsTo of the given attachment envelope.

pub fn attachments_with_vendor_and_conforms_to( &self, vendor: Option<&str>, conforms_to: Option<&str> ) -> Result<Vec<Self>>

Searches the envelope’s attachments for any that match the given vendor and conformsTo.

If vendor is None, matches any vendor. If conformsTo is None, matches any conformsTo. If both are None, matches any attachment. On success, returns a vector of matching attachments. Returns an error if any of the attachments are invalid.

pub fn attachments(&self) -> Result<Vec<Self>>

pub fn validate_attachment(&self) -> Result<()>

Validates the given attachment envelope.

Ensures:

• The attachment envelope is a valid assertion envelope.
• The attachment envelope’s predicate is known_values::ATTACHMENT.
• The attachment envelope’s object is an envelope.
• The attachment envelope’s object has a 'vendor': String assertion.
• The attachment envelope’s object has an optional 'conformsTo': String assertion.

pub fn attachment_with_vendor_and_conforms_to( &self, vendor: Option<&str>, conforms_to: Option<&str> ) -> Result<Self>

Searches the envelope’s attachments for any that match the given vendor and conformsTo.

If vendor is None, matches any vendor. If conformsTo is None, matches any conformsTo. If both are None, matches any attachment. On success, returns the first matching attachment. Returns an error if more than one attachment matches, or if any of the attachments are invalid.

impl Envelope

Support for compressing and uncompressing envelopes.

pub fn compress(&self) -> Result<Self, EnvelopeError>

Returns the compressed variant of this envelope.

Returns the same envelope if it is already compressed.

pub fn uncompress(&self) -> Result<Self>

Returns the uncompressed variant of this envelope.

Returns the same envelope if it is already uncompressed.

pub fn compress_subject(&self) -> Result<Self, EnvelopeError>

Returns this envelope with its subject compressed.

Returns the same envelope if its subject is already compressed.

pub fn uncompress_subject(&self) -> Result<Self>

Returns this envelope with its subject uncompressed.

Returns the same envelope if its subject is already uncompressed.

impl Envelope

Support for encrypting and decrypting envelopes.

pub fn encrypt_subject(&self, key: &SymmetricKey) -> Result<Self, EnvelopeError>

Returns a new envelope with its subject encrypted.

Assertions are not encrypted. To encrypt an entire envelope including its assertions it must first be wrapped using the wrap() method.

• Parameters:

  • key: The SymmetricKey to be used to encrypt the subject.

• Returns: The encrypted envelope.

• Throws: If the envelope is already encrypted.

pub fn decrypt_subject(&self, key: &SymmetricKey) -> Result<Self>

Returns a new envelope with its subject decrypted.

impl Envelope

pub fn function(&self) -> Result<Function>

pub fn check_function(&self, function: &Function) -> Result<()>

impl Envelope

Envelope Expressions: Function Construction

pub fn new_function(function: impl Into<Function>) -> Self

Creates an envelope with a «function» subject.

impl Envelope

Envelope Expressions: Parameter Construction

pub fn new_parameter( param: impl Into<Parameter>, value: impl EnvelopeEncodable ) -> Self

Creates a new envelope containing a ❰parameter❱: value assertion.

• Parameters:

  • param: A Parameter. This will be encoded as either an unsigned integer or a string.
  • value: The argument value.

• Returns: The new assertion envelope. If value is None, returns None.

pub fn new_optional_parameter( param: impl Into<Parameter>, value: Option<impl EnvelopeEncodable> ) -> Option<Self>

Optionally adds a ❰parameter❱: value assertion to the envelope.

pub fn add_parameter( &self, param: impl Into<Parameter>, value: impl EnvelopeEncodable ) -> Self

Adds a ❰parameter❱: value assertion to the envelope.

• Parameters:

  • param: A Parameter. This will be encoded as either an unsigned integer or a string.
  • value: The argument value.

• Returns: The new envelope.

pub fn add_optional_parameter( &self, param: impl Into<Parameter>, value: Option<impl EnvelopeEncodable> ) -> Self

Optionally adds a ❰parameter❱: value assertion to the envelope.

• Parameters:

  • param: A Parameter. This will be encoded as either an unsigned integer or a string.
  • value: The optional argument value.

• Returns: The new envelope. If value is None, returns the original envelope.

impl Envelope

Envelope Expressions: Request Construction

pub fn new_request_with_metadata( id: impl AsRef<ARID>, body: impl EnvelopeEncodable, note: impl Into<String>, date: Option<Date> ) -> Self

Creates an envelope with an ARID subject and a body: «function» assertion.

Also adds a 'note' assertion if note is not empty, and a 'date' assertion if date is not nil.

pub fn new_request(id: impl AsRef<ARID>, body: impl EnvelopeEncodable) -> Self

Creates an envelope with an ARID subject and a body: «function» assertion.

impl Envelope

Envelope Expression: Request Parsing

pub fn request_id(&self) -> Result<ARID>

pub fn request_body(&self) -> Result<Self, EnvelopeError>

pub fn request_note(&self) -> Result<String>

pub fn request_date(&self) -> Result<Option<Date>>

impl Envelope

Envelope Expressions: Response Construction

pub fn new_response( response_id: impl AsRef<ARID>, result: impl EnvelopeEncodable ) -> Self

Creates an envelope with an ARID subject and a result: value assertion.

pub fn new_response_with_result( response_id: impl AsRef<ARID>, results: &[impl EnvelopeEncodable + Clone] ) -> Self

Creates an envelope with an ARID subject and a result: value assertion for each provided result.

pub fn new_error_response( response_id: Option<&ARID>, error: Option<impl EnvelopeEncodable> ) -> Self

Creates an error response envelope.

If response_id is None, the subject will be unknown. Used for an immediate response to a request without a proper ID, for example when a encrypted request envelope is received and the decryption fails, making it impossible to extract the request ID.

If error is None, no assertion will be added.

impl Envelope

Envelope Expressions: Parameter Decoding

pub fn object_for_parameter( &self, param: impl Into<Parameter> ) -> Result<Envelope>

pub fn objects_for_parameter( &self, param: impl Into<Parameter> ) -> Vec<Envelope>

pub fn extract_object_for_parameter<T>( &self, param: impl Into<Parameter> ) -> Result<T>

where T: CBORDecodable + 'static,

Returns the argument for the given parameter, decoded as the given type.

• Throws: Throws an exception if there is not exactly one matching parameter, or if the parameter value is not the correct type.

pub fn extract_optional_object_for_parameter<T: CBORDecodable + 'static>( &self, param: impl Into<Parameter> ) -> Result<Option<T>>

Returns the argument for the given parameter, or None if there is no matching parameter.

pub fn extract_objects_for_parameter<T>( &self, param: impl Into<Parameter> ) -> Result<Vec<T>>

where T: CBORDecodable + 'static,

Returns an array of arguments for the given parameter, decoded as the given type.

• Throws: Throws an exception if any of the parameter values are not the correct type.

impl Envelope

Envelope Expressions: Result Decoding

pub fn response_id(&self) -> Result<ARID>

pub fn result(&self) -> Result<Self, EnvelopeError>

Returns the object of the result predicate.

• Throws: Throws an exception if there is no result predicate.

pub fn results(&self) -> Vec<Self>

Returns the objects of every result predicate.

pub fn extract_result<T>(&self) -> Result<T>

where T: CBORDecodable + 'static,

Returns the object of the result predicate, decoded as the given type.

• Throws: Throws an exception if there is no result predicate, or if its object cannot be decoded to the specified type.

pub fn extract_results<T>(&self) -> Result<Vec<T>>

where T: CBORDecodable + 'static,

Returns the objects of every result predicate, decoded as the given type.

• Throws: Throws an if not all object cannot be decoded to the specified type.

pub fn is_result_ok(&self) -> Result<bool>

Returns whether the result predicate has the KnownValue .ok.

• Throws: Throws an exception if there is no result predicate.

pub fn error<T>(&self) -> Result<T>

where T: CBORDecodable + 'static,

Returns the error value, decoded as the given type.

• Throws: Throws an exception if there is no error predicate.

pub fn is_error(&self) -> bool

Returns whether the envelope is an error response.

impl Envelope

Support for inclusions proofs.

pub fn proof_contains_set( &self, target: &HashSet<Digest, RandomState> ) -> Option<Envelope>

Returns a proof that this envelope includes every element in the target set.

Parameters

• target: The elements if this envelope that the proof must include.

Returns

The proof, of None if it cannot be proven that the envelope contains every element in the target set.

pub fn proof_contains_target( &self, target: &dyn DigestProvider ) -> Option<Envelope>

Returns a proof that this envelope includes the target element.

Parameters

• target: The element of this envelope that the proof must include.

Returns

The proof, of None if it cannot be proven that the envelope contains the targeted element.

pub fn confirm_contains_set( &self, target: &HashSet<Digest, RandomState>, proof: &Envelope ) -> bool

Confirms whether or not this envelope contains the target set using the given inclusion proof.

Parameters

• target: The target elements that need to be proven exist somewhere in this envelope, even if they were elided or encrypted.
• proof: The inclusion proof to use.

Returns

true if every element of target is in this envelope as shown by proof, false otherwise.

pub fn confirm_contains_target( &self, target: &dyn DigestProvider, proof: &Envelope ) -> bool

Confirms whether or not this envelope contains the target element using the given inclusion proof.

Parameters

• target: The target element that needs to be proven to exist somewhere in this envelope, even if it was elided or encrypted.
• proof: The inclusion proof to use.

Returns

true if target is in this envelope as shown by proof, false otherwise.

impl Envelope

Support for public key encryption.

pub fn add_recipient( &self, recipient: &PublicKeyBase, content_key: &SymmetricKey ) -> Self

Returns a new envelope with an added hasRecipient: SealedMessage assertion.

The SealedMessage contains the contentKey encrypted to the recipient’s PublicKeyBase.

• Parameters:

  • recipient: The PublicKeyBase of the recipient.
  • contentKey: The SymmetricKey that was used to encrypt the subject.

• Returns: The new envelope.

pub fn recipients(&self) -> Result<Vec<SealedMessage>>

Returns an array of SealedMessages from all of the envelope’s hasRecipient assertions.

• Throws: Throws an exception if any hasRecipient assertions do not have a SealedMessage as their object.

pub fn encrypt_subject_to_recipients<T>( &self, recipients: &[T] ) -> Result<Self, EnvelopeError>

where T: AsRef<PublicKeyBase>,

Returns an new envelope with its subject encrypted and a hasRecipient assertion added for each of the recipients.

Generates an ephemeral symmetric key which is used to encrypt the subject and which is then encrypted to each recipient’s public key.

• Parameter recipients: An array of PublicKeyBase, one for each potential recipient.

• Returns: The encrypted envelope.

• Throws: If the envelope is already encrypted.

pub fn encrypt_subject_to_recipient( &self, recipient: &PublicKeyBase ) -> Result<Self, EnvelopeError>

Returns a new envelope with its subject encrypted and a hasRecipient assertion added for the recipient.

Generates an ephemeral symmetric key which is used to encrypt the subject and which is then encrypted to the recipient’s public key.

• Parameter recipient: The recipient’s PublicKeyBase.

• Returns: The encrypted envelope.

pub fn decrypt_to_recipient(&self, recipient: &PrivateKeyBase) -> Result<Self>

Returns a new envelope with its subject decrypted using the recipient’s PrivateKeyBase.

• Parameter recipient: The recipient’s PrivateKeyBase

• Returns: The decryptedEnvelope.

• Throws: If a SealedMessage for recipient is not found among the hasRecipient assertions on the envelope.

impl Envelope

Support for signing envelopes and verifying signatures.

pub fn sign_with(&self, private_keys: &PrivateKeyBase) -> Self

Creates a signature for the envelope’s subject and returns a new envelope with a verifiedBy: Signature assertion.

• Parameters:

  • privateKeys: The signer’s PrivateKeyBase

• Returns: The signed envelope.

pub fn sign_with_opt<D>( &self, private_keys: &PrivateKeyBase, note: Option<&str>, tag: D ) -> Self

where D: AsRef<[u8]>,

Creates a signature for the envelope’s subject and returns a new envelope with a verifiedBy: Signature assertion.

• Parameters:

  • privateKeys: The signer’s PrivateKeyBase
  • note: Optional text note to add to the Signature

• Returns: The signed envelope.

pub fn sign_with_keys<T>(&self, private_keys_array: &[T]) -> Self

where T: AsRef<PrivateKeyBase>,

pub fn sign_with_keys_opt<D, T>(&self, private_keys_array: &[T], tag: D) -> Self

where D: AsRef<[u8]> + Clone, T: AsRef<PrivateKeyBase>,

Creates several signatures for the envelope’s subject and returns a new envelope with additional verifiedBy: Signature assertions.

• Parameters:

  • privateKeys: An array of signers’ PrivateKeyBases.

• Returns: The signed envelope.

pub fn sign_with_uncovered_assertions<D>( &self, private_keys: &PrivateKeyBase, uncovered_assertions: &[Self], tag: D ) -> Self

where D: AsRef<[u8]>,

Creates a signature for the envelope’s subject and returns a new envelope with a verifiedBy: Signature assertion.

• Parameters:

  • privateKeys: The signer’s PrivateKeyBase
  • uncoveredAssertions: Assertions to add to the Signature.

• Returns: The signed envelope.

pub fn make_verified_by_signature( &self, signature: &Signature, note: Option<&str> ) -> Self

Convenience constructor for a verifiedBy: Signature assertion envelope.

• Parameters:

  • signature: The Signature for the object.
  • note: An optional note to be added to the Signature.

• Returns: The new assertion envelope.

pub fn signatures(&self) -> Result<Vec<Signature>>

Returns an array of Signatures from all of the envelope’s verifiedBy predicates.

• Throws: Throws an exception if any verifiedBy assertion doesn’t contain a valid Signature as its object.

pub fn is_verified_signature( &self, signature: &Signature, public_keys: &PublicKeyBase ) -> bool

Returns whether the given signature is valid.

• Parameters:

  • signature: The Signature to be checked.
  • publicKeys: The potential signer’s PublicKeyBase.

• Returns: true if the signature is valid for this envelope’s subject, false otherwise.

pub fn verify_signature( &self, signature: &Signature, public_keys: &PublicKeyBase ) -> Result<Self, EnvelopeError>

Checks whether the given signature is valid for the given public key.

Used for chaining a series of operations that include validating signatures.

• Parameters:

  • signature: The Signature to be checked.
  • publicKeys: The potential signer’s PublicKeyBase.

• Returns: This envelope.

• Throws: Throws EnvelopeError.unverifiedSignature if the signature is not valid. valid.

pub fn has_signature_from(&self, public_keys: &PublicKeyBase) -> Result<bool>

Returns whether the envelope’s subject has a valid signature from the given public key.

• Parameters:

  • publicKeys: The potential signer’s PublicKeyBase.

• Returns: true if the signature is valid for this envelope’s subject, false otherwise.

• Throws: Throws an exception if any verifiedBy assertion doesn’t contain a valid Signature as its object.

pub fn verify_signature_from(&self, public_keys: &PublicKeyBase) -> Result<Self>

Returns whether the envelope’s subject has a valid signature from the given public key.

Used for chaining a series of operations that include validating signatures.

• Parameters:

  • publicKeys: The potential signer’s PublicKeyBase.

• Returns: This envelope.

• Throws: Throws EnvelopeError.unverifiedSignature if the signature is not valid. valid.

pub fn has_signatures_from<T>(&self, public_keys_array: &[T]) -> Result<bool>

where T: AsRef<PublicKeyBase>,

Checks whether the envelope’s subject has a set of signatures.

pub fn has_signatures_from_threshold<T>( &self, public_keys_array: &[T], threshold: Option<usize> ) -> Result<bool>

where T: AsRef<PublicKeyBase>,

Returns whether the envelope’s subject has some threshold of signatures.

If threshold is nil, then all signers in publicKeysArray must have signed. If threshold is 1, then at least one signer must have signed.

• Parameters:

  • publicKeysArray: An array of potential signers’ PublicKeyBases.
  • threshold: Optional minimum number of signers.

• Returns: true if the threshold of valid signatures is met, false otherwise.

• Throws: Throws an exception if any verifiedBy assertion doesn’t contain a valid Signature as its object.

pub fn verify_signatures_from<T>(&self, public_keys_array: &[T]) -> Result<Self>

where T: AsRef<PublicKeyBase>,

Checks whether the envelope’s subject has a set of signatures.

pub fn verify_signatures_from_threshold<T>( &self, public_keys_array: &[T], threshold: Option<usize> ) -> Result<Self>

where T: AsRef<PublicKeyBase>,

Checks whether the envelope’s subject has some threshold of signatures.

If threshold is nil, then all signers in publicKeysArray must have signed. If threshold is 1, then at least one signer must have signed.

Used for chaining a series of operations that include validating signatures.

• Parameters:

  • publicKeysArray: An array of potential signers’ PublicKeyBases.
  • threshold: Optional minimum number of signers.

• Returns: This envelope.

• Throws: Throws an exception if the threshold of valid signatures is not met.

impl Envelope

Support for decorrelation of envelopes using salt.

pub fn add_salt(&self) -> Self

Add a number of bytes of salt generally proportionate to the size of the object being salted.

pub fn add_salt_instance(&self, salt: Salt) -> Self

Add the given Salt as an assertion

pub fn add_salt_with_len(&self, count: usize) -> Result<Self>

Add a specified number of bytes of salt.

Returns an error if the number of bytes is less than 8.

pub fn add_salt_in_range(&self, range: RangeInclusive<usize>) -> Result<Self>

Add a number of bytes of salt chosen randomly from the given range.

Returns an error if the minimum number of bytes is less than 8.

impl Envelope

Support for splitting and combining envelopes using SSKR (Shamir’s Secret Sharing).

pub fn sskr_split( &self, spec: &SSKRSpec, content_key: &SymmetricKey ) -> Result<Vec<Vec<Envelope>>, SSKRError>

Splits the envelope into a set of SSKR shares.

The envelope subject should already be encrypted by a specific SymmetricKey known as the contentKey.

Each returned envelope will have an sskrShare: SSKRShare assertion added to it.

• Parameters:

  • spec: The SSKR split specification.
  • contentKey: The SymmetricKey used to encrypt the envelope’s subject.

• Returns: An array of arrays. Each element of the outer array represents an SSKR group, and the elements of each inner array are the envelope with a unique sskrShare: SSKRShare assertion added to each.

pub fn sskr_join(envelopes: &[Envelope]) -> Result<Envelope>

Creates a new envelope resulting from the joining a set of envelopes split by SSKR.

Given a set of envelopes that are ostensibly all part of the same SSKR split, this method attempts to reconstruct the original envelope subject. It will try all present sskrShare: SSKRShare assertions, grouped by split ID, to achieve a threshold of shares. If it can do so successfully the initializer succeeds.

• Parameter envelopes: The envelopes to be joined.

• Throws: Throws an exception if no quorum of shares can be found to reconstruct the original envelope.

impl Envelope

pub fn add_type<O>(&self, object: O) -> Self

where O: EnvelopeEncodable,

Returns the result of adding the given 'IsA' type assertion to the envelope.

pub fn types(&self) -> Vec<Self>

Returns all of the envelope’s 'IsA' type assertions.

pub fn get_type(&self) -> Result<Self, EnvelopeError>

Gets a single 'IsA' type assertion from the envelope.

If there is more than one 'IsA' type assertion, returns an error.

pub fn has_type_envelope(&self, t: impl EnvelopeEncodable) -> bool

Returns true if the envelope has an 'IsA' type assertion with the given envelope t’s digest.

pub fn has_type(&self, t: &KnownValue) -> bool

Returns true if the envelope has an 'IsA' type assertion with the given known value t.

pub fn check_type(&self, t: &KnownValue) -> Result<(), EnvelopeError>

Succeeds if the envelope has an 'IsA' type assertion with the given known value t.

Fails with EnvelopeError::InvalidType otherwise.

pub fn check_type_envelope( &self, t: impl EnvelopeEncodable ) -> Result<(), EnvelopeError>

Succeeds if the envelope has an 'IsA' type assertion with the given envelope t’s digest.

Fails with EnvelopeError::InvalidType otherwise.

impl Envelope

pub fn sign_and_encrypt( &self, sender: &PrivateKeyBase, recipient: &PublicKeyBase ) -> Result<Envelope>

pub fn verify_and_decrypt( &self, sender: &PublicKeyBase, recipient: &PrivateKeyBase ) -> Result<Envelope>

Trait Implementations

impl CBORDecodable for Envelope

fn from_cbor(cbor: &CBOR) -> Result<Self>

Creates an instance of this type from CBOR symbolic representation.

fn from_cbor_data(cbor_data: &[u8]) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type from encoded CBOR binary data.

impl CBOREncodable for Envelope

fn cbor(&self) -> CBOR

Returns the value in CBOR symbolic representation.

fn cbor_data(&self) -> Vec<u8>

Returns the value in CBOR binary representation.

impl CBORTagged for Envelope

Support for CBOR encoding and decoding of Envelope. All envelopes are tagged with the envelope tag. Within that tag, each of the seven cases has a unique CBOR signature:

• .node contains a CBOR array, the first element of which is the subject, followed by one or more assertions.
• .leaf is tagged #6.24, which is the IANA tag for embedded CBOR.
• .wrapped is tagged with the envelope tag.
• .assertion is a single-element map {predicate: object}.
• .knownValue is a 64-bit signed numeric value.
• .encrypted is tagged with the crypto-msg tag.
• .elided is a byte string of length 32.

const CBOR_TAG: Tag = tags::ENVELOPE

The CBOR tag assocated with this type.

impl CBORTaggedDecodable for Envelope

fn from_untagged_cbor(cbor: &CBOR) -> Result<Self>

Creates an instance of this type by decoding it from untagged CBOR.

fn from_tagged_cbor(cbor: &CBOR) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: &[u8]) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: &[u8]) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for Envelope

fn untagged_cbor(&self) -> CBOR

Returns the untagged CBOR encoding of this instance.

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for Envelope

fn clone(&self) -> Envelope

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Envelope

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

Formats the value using the given formatter.

impl DigestProvider for Envelope

Support for calculating the digests associated with Envelope.

fn digest(&self) -> Cow<'_, Digest>

The envelope’s digest.

This digest can be used to compare two envelopes for semantic equivalence, that is, the two envelopes would contain the same information in their unencrypted and unelided forms. See doc:Diffing for more information.

impl Display for Envelope

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

Formats the value using the given formatter.

impl EnvelopeEncodable for Envelope

fn envelope(self) -> Envelope

impl EnvelopeFormat for Envelope

fn format_item(&self, context: &FormatContext) -> EnvelopeFormatItem

impl From<&[u8]> for Envelope

fn from(bytes: &[u8]) -> Self

Converts to this type from the input type.

impl<T> From<&T> for Envelope

where T: EnvelopeEncodable + Clone,

fn from(value: &T) -> Self

Converts to this type from the input type.

impl From<&str> for Envelope

fn from(string: &str) -> Self

Converts to this type from the input type.

impl<const N: usize> From<[u8; N]> for Envelope

fn from(bytes: [u8; N]) -> Self

Converts to this type from the input type.

impl From<ARID> for Envelope

fn from(value: ARID) -> Self

Converts to this type from the input type.

impl From<Assertion> for Envelope

fn from(assertion: Assertion) -> Self

Converts to this type from the input type.

impl From<Box<CBOR>> for Envelope

fn from(cbor: Box<CBOR>) -> Self

Converts to this type from the input type.

impl From<Bytes> for Envelope

fn from(value: Bytes) -> Self

Converts to this type from the input type.

impl From<CBOR> for Envelope

fn from(cbor: CBOR) -> Self

Converts to this type from the input type.

impl From<Compressed> for Envelope

fn from(compressed: Compressed) -> Self

Converts to this type from the input type.

impl From<Date> for Envelope

fn from(value: Date) -> Self

Converts to this type from the input type.

impl From<Digest> for Envelope

fn from(value: Digest) -> Self

Converts to this type from the input type.

impl From<EncryptedMessage> for Envelope

fn from(encrypted: EncryptedMessage) -> Self

Converts to this type from the input type.

impl From<Envelope> for CBOR

fn from(value: Envelope) -> Self

Converts to this type from the input type.

impl From<EnvelopeCase> for Envelope

fn from(case: EnvelopeCase) -> Self

Converts to this type from the input type.

impl From<Function> for Envelope

fn from(value: Function) -> Self

Converts to this type from the input type.

impl From<KnownValue> for Envelope

fn from(known_value: KnownValue) -> Self

Converts to this type from the input type.

impl From<Parameter> for Envelope

fn from(value: Parameter) -> Self

Converts to this type from the input type.

impl From<PrivateKeyBase> for Envelope

fn from(value: PrivateKeyBase) -> Self

Converts to this type from the input type.

impl From<PublicKeyBase> for Envelope

fn from(value: PublicKeyBase) -> Self

Converts to this type from the input type.

impl From<SSKRShare> for Envelope

fn from(value: SSKRShare) -> Self

Converts to this type from the input type.

impl From<Salt> for Envelope

fn from(value: Salt) -> Self

Converts to this type from the input type.

impl From<SealedMessage> for Envelope

fn from(value: SealedMessage) -> Self

Converts to this type from the input type.

impl From<Signature> for Envelope

fn from(value: Signature) -> Self

Converts to this type from the input type.

impl From<Simple> for Envelope

fn from(simple: Simple) -> Self

Converts to this type from the input type.

impl From<String> for Envelope

fn from(string: String) -> Self

Converts to this type from the input type.

impl From<URI> for Envelope

fn from(value: URI) -> Self

Converts to this type from the input type.

impl From<UUID> for Envelope

fn from(value: UUID) -> Self

Converts to this type from the input type.

impl From<bool> for Envelope

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<f32> for Envelope

fn from(value: f32) -> Self

Converts to this type from the input type.

impl From<f64> for Envelope

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i16> for Envelope

fn from(value: i16) -> Self

Converts to this type from the input type.

impl From<i32> for Envelope

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Envelope

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i8> for Envelope

fn from(value: i8) -> Self

Converts to this type from the input type.

impl From<u16> for Envelope

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Envelope

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Envelope

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Envelope

fn from(value: u8) -> Self

Converts to this type from the input type.

impl From<usize> for Envelope

fn from(value: usize) -> Self

Converts to this type from the input type.

impl TryFrom<Envelope> for Bytes

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Envelope) -> Result<Self>

Performs the conversion.

impl URDecodable for Envelope

fn from_ur(ur: &UR) -> Result<Self, Error>

where Self: Sized,

fn from_ur_string<T>(ur_string: T) -> Result<Self, Error>

where T: Into<String>, Self: Sized,

impl UREncodable for Envelope

fn ur(&self) -> UR

Returns the UR representation of the object.

fn ur_string(&self) -> String

Returns the UR string representation of the object.

impl CBORCodable for Envelope

impl CBORTaggedCodable for Envelope

impl URCodable for Envelope