Struct 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: impl EnvelopeEncodable, ) -> Result<Self>

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>

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>

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>

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>

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>

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>

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(subject: impl EnvelopeEncodable) -> Self

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

pub fn new_or_null(subject: Option<impl EnvelopeEncodable>) -> Self

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

If subject is None, returns a null envelope.

pub fn new_or_none(subject: Option<impl EnvelopeEncodable>) -> Option<Self>

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

If subject is None, returns None.

pub fn new_assertion( predicate: impl EnvelopeEncodable, object: impl EnvelopeEncodable, ) -> Self

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

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: impl Into<Envelope>) -> Result<Self>

Returns the unelided variant of this envelope.

Returns the same envelope if it is already unelided.

impl Envelope

pub fn try_from_cbor(cbor: CBOR) -> Result<Self>

pub fn try_from_cbor_data(data: Vec<u8>) -> Result<Self>

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 as_assertion(&self) -> Option<Self>

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

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

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

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

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

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

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

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

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

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

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

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

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

pub fn try_leaf(&self) -> Result<CBOR>

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

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

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

pub fn try_known_value(&self) -> Result<&KnownValue>

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 + TryFrom<CBOR, Error = Error>,

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>

Returns the assertion with the given predicate.

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

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

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

Returns an error if there are multiple matching predicates.

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

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 optional_object_for_predicate( &self, predicate: impl EnvelopeEncodable, ) -> Result<Option<Self>>

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

Returns an error if there are multiple matching predicates.

pub fn extract_object<T: TryFrom<CBOR, Error = Error> + 'static>( &self, ) -> Result<T>

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

Returns an error if the envelope is not an assertion. Returns an error if the encoded type doesn’t match the given type.

pub fn extract_predicate<T: TryFrom<CBOR, Error = Error> + 'static>( &self, ) -> Result<T>

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

Returns an error if the envelope is not an assertion. Returns an error if the encoded type doesn’t match the given type.

pub fn extract_object_for_predicate<T: TryFrom<CBOR, Error = Error> + '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: TryFrom<CBOR, Error = Error> + '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.

Returns an error if there are multiple matching predicates.

pub fn extract_object_for_predicate_with_default<T: TryFrom<CBOR, Error = Error> + 'static>( &self, predicate: impl EnvelopeEncodable, default: T, ) -> Result<T>

Returns the object of the assertion with the given predicate, or a default value 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: TryFrom<CBOR, Error = Error> + 'static>( &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 format_flat(&self) -> String

Returns the envelope notation for this envelope in flat format.

In flat format, the envelope is printed on a single line.

pub fn diagnostic_annotated(&self) -> String

Returns the CBOR diagnostic notation for this envelope, with annotations.

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

pub fn short_id(&self) -> String

pub fn summary(&self, max_length: usize, context: &FormatContext) -> 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>

Unwraps and returns the inner envelope.

Returns an error if this is not a wrapped envelope.

impl Envelope

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

Returns a new attachment envelope.

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

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

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>

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>

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>

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>

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 encrypt(&self, key: &SymmetricKey) -> Envelope

pub fn decrypt(&self, key: &SymmetricKey) -> Result<Envelope>

impl Envelope

pub fn unknown() -> Self

pub fn ok() -> Self

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: &dyn Encrypter, 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( &self, recipients: &[&dyn Encrypter], ) -> Result<Self>

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: &dyn Encrypter, ) -> Result<Self>

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_subject_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

pub fn encrypt_to_recipient(&self, recipient: &dyn Encrypter) -> Envelope

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

impl Envelope

Support for signing envelopes and verifying signatures.

pub fn add_signature(&self, private_key: &dyn Signer) -> Self

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

• Parameters:

  • private_key: The signer’s SigningPrivateKey

• Returns: The signed envelope.

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

Convenience constructor for a 'signed': 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 is_verified_signature( &self, signature: &Signature, public_key: &dyn Verifier, ) -> bool

Returns whether the given signature is valid.

• Parameters:

  • signature: The Signature to be checked.
  • public_key: The potential signer’s Verifier.

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

pub fn verify_signature( &self, signature: &Signature, public_key: &dyn Verifier, ) -> Result<Self>

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.
  • public_key: The potential signer’s Verifier.

• Returns: This envelope.

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

pub fn has_signature_from(&self, public_key: &dyn Verifier) -> Result<bool>

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

• Parameters:

  • public_key: The potential signer’s Verifier.

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

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

pub fn has_signature_from_returning_metadata( &self, public_key: &dyn Verifier, ) -> Result<Option<Envelope>>

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

• Parameters:

• public_key: The potential signer’s Verifier.

• Returns: The metadata envelope if the signature is valid, None otherwise.

pub fn verify_signature_from(&self, public_key: &dyn Verifier) -> 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:

  • public_key: The potential signer’s Verifier.

• Returns: This envelope.

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

pub fn verify_signature_from_returning_metadata( &self, public_key: &dyn Verifier, ) -> Result<Envelope>

pub fn has_signatures_from(&self, public_keys: &[&dyn Verifier]) -> Result<bool>

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

pub fn has_signatures_from_threshold( &self, public_keys: &[&dyn Verifier], threshold: Option<usize>, ) -> Result<bool>

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

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

• Parameters:

  • public_keys: An array of potential signers’ Verifiers.
  • threshold: Optional minimum number of signers.

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

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

pub fn verify_signatures_from_threshold( &self, public_keys: &[&dyn Verifier], threshold: Option<usize>, ) -> Result<Self>

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

If threshold is nil, then all signers in public_keys 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:

  • public_keys: An array of potential signers’ Verifiers.
  • threshold: Optional minimum number of signers.

• Returns: This envelope.

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

pub fn verify_signatures_from( &self, public_keys: &[&dyn Verifier], ) -> Result<Self>

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

impl Envelope

pub fn sign(&self, signer: &dyn Signer) -> Envelope

pub fn verify(&self, verifier: &dyn Verifier) -> Result<Envelope>

pub fn verify_returning_metadata( &self, verifier: &dyn Verifier, ) -> Result<(Envelope, Envelope)>

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>>>

Splits the envelope into a set of SSKR shares.

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

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

• Parameters:

  • spec: The SSKR split specification.
  • content_key: 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_split_flattened( &self, spec: &SSKRSpec, content_key: &SymmetricKey, ) -> Result<Vec<Envelope>>

Splits the envelope into a set of SSKR shares.

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

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

• Parameters:

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

• Returns: An array of shares. Each element of the array represents an SSKR share.

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(&self, object: impl EnvelopeEncodable) -> Self

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>

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<()>

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<()>

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 seal(&self, sender: &impl Signer, recipient: &PublicKeyBase) -> Envelope

pub fn unseal( &self, sender: &impl Verifier, recipient: &PrivateKeyBase, ) -> Result<Envelope>

Trait Implementations

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 an unsigned 64-bit integer.
• .encrypted is tagged with the crypto-msg tag.
• .elided is a byte string of length 32.

fn cbor_tags() -> Vec<Tag>

The CBOR tags assocated with this type. If more than one tag is present, they are considered equivalent for reading, but only the first one is used for writing.

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: impl AsRef<[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: impl AsRef<[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 EnvelopeFormat for Envelope

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

impl From<&Envelope> for Envelope

fn from(envelope: &Envelope) -> 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<T> From<Event<T>> for Envelope

where T: EnvelopeEncodable + TryFrom<Envelope> + Debug + Clone + PartialEq,

fn from(event: Event<T>) -> Self

Converts to this type from the input type.

impl From<Expression> for Envelope

Expression -> Envelope

fn from(expression: Expression) -> Self

Converts to this type from the input type.

impl From<Request> for Envelope

fn from(request: Request) -> Self

Converts to this type from the input type.

impl From<Response> for Envelope

fn from(value: Response) -> Self

Converts to this type from the input type.

impl PartialEq for Envelope

Implement PartialEq for Envelope to allow for structural comparison.

Note that we deliberately do not also implement Eq as this comparison for identicality is potentially expensive, and structures like HashMap require that Eq be implemented for its keys. This should be a fast/cheap operation.

If you want to use envelopes as keys in such structures, you can pre-compute an envelope’s structural_digest and use that as the key.

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<CBOR> for Envelope

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Compressed> for Envelope

type Error = Error

The type returned in the event of a conversion error.

fn try_from(compressed: Compressed) -> Result<Self>

Performs the conversion.

impl TryFrom<EncryptedMessage> for Envelope

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for ByteString

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<T> TryFrom<Envelope> for Event<T>

where T: EnvelopeEncodable + TryFrom<Envelope> + Debug + Clone + PartialEq,

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for Expression

Envelope -> Expression

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for Function

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for Request

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for Response

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Envelope> for String

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.