Crate bc_envelope 

Gordian Envelope: A Flexible Container for Structured Data

Introduction

The Gordian Envelope protocol specifies a structured format for hierarchical binary data focused on the ability to transmit it in a privacy-focused way. Envelopes are designed to facilitate “smart documents” and have a number of unique features including: easy representation of a variety of semantic structures, a built-in Merkle-like digest tree, deterministic representation using CBOR, and the ability for the holder of a document to selectively encrypt or elide specific parts of a document without invalidating the document structure including the digest tree, or any cryptographic signatures that rely on it.

Getting Started

[dependencies]
bc-envelope = "0.35.1"

Specification

Gordian Envelope is currently specified in this IETF Internet Draft.

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

Basic Envelope Creation

• Envelope::new Creates an envelope with a subject.
• Envelope::new_assertion Creates an assertion envelope with a predicate and object.

Adding Assertions

Adding Assertions with a Predicate and Object

• Envelope::add_assertion Adds an assertion to an envelope.
• Envelope::add_assertion_salted Adds an optionally salted assertion to an envelope.
• Envelope::add_optional_assertion Optionally adds an assertion to an envelope.

Adding Assertions with an Assertion Envelope

• Envelope::add_assertion_envelope Adds an assertion envelope to an envelope.
• Envelope::add_assertion_envelope_salted Adds an optionally salted assertion envelope to an envelope.
• Envelope::add_assertion_envelopes Adds a vector of assertion envelopes to an envelope.
• Envelope::add_optional_assertion_envelope_salted Optionally adds an assertion envelope to an envelope.

Removing and Replacing Assertions

• Envelope::remove_assertion Removes an assertion from an envelope.
• Envelope::replace_assertion Replaces an assertion in an envelope.
• Envelope::replace_subject Replaces the subject of an envelope.

Queries

Getting the basic parts of an envelope

• Envelope::subject Returns the subject of an envelope.
• Envelope::as_predicate If the envelope’s subject is an assertion return its predicate, else return None.
• Envelope::as_object If the envelope’s subject is an assertion return its object, else return None.

Getting assertions on an envelope

• Envelope::assertions Returns the assertions of an envelope.
• Envelope::has_assertions Returns whether an envelope has assertions.
• Envelope::as_assertion If the envelope’s subject is an assertion return it, else return None.

Getting the specific types of an envelope

• Envelope::as_leaf The envelope’s leaf CBOR object, or None if the envelope is not a leaf.
• Envelope::as_known_value The envelope’s known value, or None if the envelope is not a known value.

Determining the type of an envelope

• Envelope::is_leaf Returns whether an envelope is a leaf.
• Envelope::is_node Returns whether an envelope is a node (whether it has at least one assertion).
• Envelope::is_wrapped Returns whether an envelope is wrapped.
• Envelope::is_known_value Returns whether an envelope is a known value.
• Envelope::is_assertion Returns whether an envelope is an assertion.
• Envelope::is_encrypted Returns whether an envelope is encrypted.
• Envelope::is_compressed Returns whether an envelope is compressed.
• Envelope::is_elided Returns whether an envelope is elided.

Determining the type of an envelope’s subject

• Envelope::is_subject_assertion Returns whether an envelope’s subject is an assertion.
• Envelope::is_subject_encrypted Returns whether an envelope’s subject is encrypted.
• Envelope::is_subject_compressed Returns whether an envelope’s subject is compressed.
• Envelope::is_subject_elided Returns whether an envelope’s subject is elided.
• Envelope::is_subject_obscured Returns whether an envelope’s subject is obscured.

Getting assertions and parts of assertions

• Envelope::assertion_with_predicate Returns the assertion with the given predicate.
• Envelope::assertions_with_predicate Returns all assertions with the given predicate.
• Envelope::object_for_predicate Returns the object of the assertion with the given predicate.
• Envelope::objects_for_predicate Returns the objects of all assertions with the matching predicate.
• Envelope::elements_count Returns the number of elements in the envelope.

Extracting parts of envelopes as specific types

• Envelope::extract_subject Returns the envelope’s subject, decoded as the given type.
• Envelope::extract_object_for_predicate Returns the object of the assertion with the given predicate, decoded as the given type.
• Envelope::extract_objects_for_predicate Returns the objects of all assertions with the matching predicate, decoded as the given type.

Other queries

• Envelope::is_internal Returns whether an envelope is internal, that is, if it has child elements.
• Envelope::is_obscured Returns whether an envelope is obscured (elided, encrypted, or compressed).

Wrapping and Unwrapping Envelopes

• Envelope::wrap Wraps an envelope in a new envelope.
• Envelope::try_unwrap Unwraps an envelope.

Formatting Envelopes

Envelope notation

• Envelope::format Formats an envelope in envelope notation.
• Envelope::format_opt Formats an envelope in envelope notation, with optional annotations.

Tree notation

• Envelope::tree_format Formats an envelope in envelope tree notation.
• [Envelope::tree_format_with_target] Formats an envelope in envelope tree notation, highlighting a target set of elements.

CBOR diagnostic notation

• Envelope::diagnostic Formats an envelope in CBOR diagnostic notation.
• Envelope::diagnostic Formats an envelope in CBOR diagnostic notation, with optional annotations.

CBOR hexadecimal notation

• Envelope::hex Formats an envelope in CBOR hexadecimal notation.
• Envelope::hex_opt Formats an envelope in CBOR hexadecimal notation, with optional annotations.

Working with the Digest Tree

Semantic equivalence

• bc_components::DigestProvider::digest Returns the digest of an envelope.
• Envelope::digests Returns the set of digests contained in the envelope’s elements, down to the specified level.
• Envelope::deep_digests Returns the set of all digests in the envelope.
• Envelope::shallow_digests Returns the set of all digests in the envelope, down to its second level.
• Envelope::is_equivalent_to Tests two envelopes for semantic equivalence.

Structural identicality

• Envelope::structural_digest Produce a value that will necessarily be different if two envelopes differ structurally, even if they are semantically equivalent.
• Envelope::is_identical_to Tests two envelopes for structural equality.

Signing and Verifying Signatures

Signing

• Envelope::add_signature Creates a signature for the envelope’s subject and returns a new envelope with a 'signed': Signature assertion.
• Envelope::add_signature_opt Creates a signature for the envelope’s subject and returns a new envelope with a 'signed': Signature assertion.
• Envelope::add_signatures Creates several signatures for the envelope’s subject and returns a new envelope with additional 'signed': Signature assertions.
• Envelope::add_signatures_opt Creates several signatures for the envelope’s subject and returns a new envelope with additional 'signed': Signature assertions.
• Envelope::add_signature Creates a signature for the envelope’s subject and returns a new envelope with a 'signed': Signature assertion.

Verifying by returning a boolean

• Envelope::is_verified_signature Returns whether the given signature is valid.
• Envelope::has_signature_from Returns whether the envelope’s subject has a valid signature from the given public key.
• Envelope::has_signatures_from Returns whether the envelope’s subject has a set of signatures.
• Envelope::has_signatures_from_threshold Returns whether the envelope’s subject has some threshold of signatures.

Verifying by returning a result

• Envelope::verify_signature Checks whether the given signature is valid for the given public key.
• Envelope::verify_signature_from Checks whether the envelope’s subject has a valid signature from the given public key.
• Envelope::verify_signatures_from Checks whether the envelope’s subject has a set of signatures.
• Envelope::verify_signatures_from_threshold Checks whether the envelope’s subject has some threshold of signatures.

Helpers

• Envelope::verify_signature Returns an array of Signatures from all of the envelope’s signed predicates.
• Envelope::make_signed_assertion Convenience constructor for a signed: Signature assertion envelope.

Splitting Envelopes with SSKR

• Envelope::sskr_split Splits the envelope into a set of SSKR shares.
• Envelope::sskr_join Creates a new envelope resulting from the joining a set of envelopes split by SSKR.

Encryption

• Envelope::encrypt_subject Returns a new envelope with its subject encrypted.
• Envelope::decrypt_subject Returns a new envelope with its subject decrypted.

Public Key Encryption

• Envelope::add_recipient Returns a new envelope with an added hasRecipient: SealedMessage assertion.
• Envelope::recipients Returns an array of SealedMessages from all of the envelope’s hasRecipient assertions.
• Envelope::encrypt_subject_to_recipients Returns an new envelope with its subject encrypted and a hasRecipient
• Envelope::encrypt_subject_to_recipient Returns a new envelope with its subject encrypted and a hasRecipient assertion added for the recipient.
• Envelope::decrypt_to_recipient Returns a new envelope with its subject decrypted using the recipient’s PrivateKeyBase.

Compression

• Envelope::compress Returns the compressed variant of this envelope.
• Envelope::decompress Returns the decompressed variant of this envelope.
• Envelope::compress_subject Returns this envelope with its subject compressed.
• Envelope::decompress_subject Returns this envelope with its subject decompressed.

Eliding, Encrypting, or Compressing Parts of an Envelope

• Envelope::elide Returns the elided variant of this envelope.

• Returns a version of this envelope with the given element(s) elided:

  • Envelope::elide_removing_set
  • Envelope::elide_removing_array
  • Envelope::elide_removing_target

• Returns a version with all elements except the given element(s) elided:

  • Envelope::elide_revealing_set
  • Envelope::elide_revealing_array
  • Envelope::elide_revealing_target

• As above, but takes a boolean to determine whether to remove or reveal:

  • Envelope::elide_set
  • Envelope::elide_array
  • Envelope::elide_target

• Returns a version with the given element(s) elided, encrypted, or compressed:

  • Envelope::elide_removing_set_with_action
  • Envelope::elide_removing_array_with_action
  • Envelope::elide_removing_target_with_action

• Returns a version with all elements except the given element(s) elided, encrypted, or compressed:

  • Envelope::elide_revealing_set_with_action
  • Envelope::elide_revealing_array_with_action
  • Envelope::elide_revealing_target_with_action

• As above, but takes a boolean to determine whether to remove or reveal:

  • Envelope::elide_set_with_action
  • Envelope::elide_array_with_action
  • Envelope::elide_target_with_action

• Envelope::unelide Returns the unelided variant of this envelope, given the envelope that was elided.

Decorrelating Envelopes using Salt

• Envelope::add_salt Add a number of bytes of salt generally proportionate to the size of the object being salted.
• Envelope::add_salt_with_len Add a specified number of bytes of salt.
• Envelope::add_salt_in_range Add a number of bytes of salt chosen randomly from the given range.

Walking an Envelope’s Hierarchy

• Envelope::walk Walk the envelope, calling the visitor function for each element.

Envelope Expressions

Constructing Expressions, Requests, and Responses

• Expression::new Creates an envelope with a «function» subject.
• Parameter::new_named Creates a new envelope containing a ❰parameter❱: value assertion.
• Parameter::new_known Optionally adds a ❰parameter❱: value assertion to the envelope.
• ExpressionBehavior::with_parameter Adds a ❰parameter❱: value assertion to the envelope.
• ExpressionBehavior::with_optional_parameter Optionally adds a ❰parameter❱: value assertion to the envelope.
• Request::new Creates an envelope with an ARID subject and a body: «function» assertion.
• Response::new_success Creates an envelope with an ARID subject and a result: value assertion.
• Response::new_success Creates an envelope with an ARID subject and a result: value assertion for each provided result.
• Response::new_failure Creates an envelope with an ARID subject and a error: value assertion.
• Response::new_early_failure Creates an envelope with an unknown subject and a error: value assertion.

Decoding Parameters and Results

• ExpressionBehavior::extract_object_for_parameter Returns the argument for the given parameter, decoded as the given type.
• ExpressionBehavior::extract_objects_for_parameter Returns an array of arguments for the given parameter, decoded as the given type.
• ResponseBehavior::result Returns the object of the result predicate.
• ResponseBehavior::result Returns the objects of every result predicate.
• ResponseBehavior::extract_result Returns the object of the result predicate, decoded as the given type.
• ResponseBehavior::extract_result Returns the objects of every result predicate, decoded as the given type.
• ResponseBehavior::extract_result Returns whether the result predicate has the KnownValue .ok.
• ResponseBehavior::extract_error Returns the error value, decoded as the given type.

Re-exports

pub use base::Assertion;

pub use base::Envelope;

pub use base::EnvelopeCase;

pub use base::EnvelopeEncodable;

pub use base::Error;

pub use base::Result;

pub use base::elide;

pub use base::elide::ObscureAction;

pub use base::walk;

pub use base::walk::EdgeType;

pub use format::DigestDisplayFormat;

pub use format::EnvelopeSummary;

pub use format::FormatContext;

pub use format::FormatContextOpt;

pub use format::GLOBAL_FORMAT_CONTEXT;

pub use format::MermaidFormatOpts;

pub use format::MermaidOrientation;

pub use format::MermaidTheme;

pub use format::TreeFormatOpts;

pub use format::register_tags;

pub use format::register_tags_in;

pub use extension::SignatureMetadata;

pub use extension::attachment::Attachable;

pub use extension::attachment::Attachments;

pub use extension::expressions::Event;

pub use extension::expressions::EventBehavior;

pub use extension::expressions::Expression;

pub use extension::expressions::ExpressionBehavior;

pub use extension::expressions::Function;

pub use extension::expressions::IntoExpression;

pub use extension::expressions::Parameter;

pub use extension::expressions::Request;

pub use extension::expressions::RequestBehavior;

pub use extension::expressions::Response;

pub use extension::expressions::ResponseBehavior;

pub use extension::expressions::functions;

pub use extension::expressions::parameters;

pub use known_values;

Modules

base

extension

format

prelude

seal

Envelope Sealing and Unsealing

Macros

function_constant

A macro that declares a function at compile time.

impl_attachable

A macro for easily implementing the Attachable trait for types with an attachments field.

impl_envelope_decodable

parameter_constant

A macro that declares a parameter at compile time.

with_format_context

A macro to access the global format context for read-only operations.

with_format_context_mut

A macro to access the global format context for read-write operations.

Structs

KnownValue

A value in a namespace of unsigned integers that represents a stand-alone ontological concept.

KnownValuesStore

A store that maps between Known Values and their assigned names.

PrivateKeyBase

A secure foundation for deriving multiple cryptographic keys.

PublicKeys

A container for an entity’s public cryptographic keys.

Enums

EncapsulationPrivateKey

A private key used for key encapsulation mechanisms (KEM).

SigningOptions

Options for configuring signature creation.

Statics

KNOWN_VALUES

The global registry of Known Values.

Traits

Encrypter

A trait for types that can encapsulate shared secrets for public key encryption.

Signer

A trait for types capable of creating digital signatures.

Verifier

A trait for types capable of verifying digital signatures.