43 releases (24 breaking)
0.25.1 | Apr 3, 2025 |
---|---|
0.25.0 | Mar 28, 2025 |
0.24.0 | Mar 5, 2025 |
0.21.0 | Dec 25, 2024 |
0.1.0 | Jun 18, 2023 |
#14 in #binary-format
1,882 downloads per month
Used in 7 crates
495KB
5K
SLoC
Blockchain Commons Gordian Envelope for Rust
by Wolf McNally and Blockchain Commons
Introduction
Gordian Envelope is a structured format for hierarchical binary data focused on privacy. The Rust implementation provides a feature-rich, production-ready reference implementation.
Envelopes are designed to facilitate "smart documents" with a number of unique features:
- Hierarchical structure: Easy representation of a variety of semantic structures, from simple key-value pairs to complex property graphs
- Merkle-like digest tree: Built-in integrity verification at any level of the structure
- Deterministic representation: Uses CBOR with deterministic encoding rules for consistent serialization
- Privacy-focused: The holder of a document can selectively encrypt or elide specific parts without invalidating the structure, signatures, or digest tree
- Progressive trust: Holders can reveal information incrementally to build trust with verifiers
Getting Started
[dependencies]
bc-envelope = "0.25.1"
Basic usage examples:
use bc_envelope::prelude::*;
// Create a simple envelope with a string subject
let envelope = Envelope::new("Hello, world!");
// Add assertions to an envelope
let envelope = envelope
.add_assertion("created", "2025-04-03")
.add_assertion("author", "Alice");
// Selectively elide information
let elided = envelope.elide(|e| !e.extract_object_for_predicate::<String>("author").unwrap().eq("Alice"));
// Sign an envelope
let signed = envelope.add_signature(&private_key);
// Verify a signature
let verified = signed.verify_signature_from(&public_key)?;
Features and Components
Gordian Envelope includes several powerful features, all configurable through Cargo features:
Feature | Description |
---|---|
base |
Core envelope functionality and digest tree |
encrypt |
Symmetric encryption of envelope parts |
signature |
Digital signatures for authenticity and integrity |
compress |
Compression for efficient storage/transmission |
known_value |
Registry of well-known semantic values |
expression |
Support for representing function calls and requests |
recipient |
Public key encryption to multiple recipients |
salt |
Decorrelation of structurally similar envelopes |
sskr |
Sharded Secret Key Reconstruction for social recovery |
attachment |
Vendor-specific extensions mechanism |
By default, all features are enabled. You can select a subset for your specific needs.
Specification
Gordian Envelope is formally specified in the IETF Internet Draft, which is currently in the community review stage.
Extensions to the base specification are documented in the Blockchain Commons Research repository:
- BCR-2023-003: Envelope Known Value
- BCR-2023-004: Envelope Symmetric Encryption
- BCR-2023-005: Envelope Compression
- BCR-2023-006: Envelope Attachment
- BCR-2023-012: Envelope Expression
- BCR-2023-013: Envelope Crypto
- BCR-2024-003: Envelope (Full Specification)
- BCR-2024-006: Envelope Graph
- BCR-2024-007: Envelope Decorrelation
Gordian Principles
Gordian Envelope implements the Gordian Principles:
- Independence: Holders control their own data and can selectively disclose information without relying on third parties
- Privacy: Built-in support for elision, encryption, and decorrelation allows precise information control
- Resilience: Support for social recovery (SSKR), signatures, and encryption provides robust security
- Openness: Fully open-source, well-documented, with open standards and test vectors
Status - Community Review
Gordian Envelope is currently in community review. We appreciate your testing and feedback on:
- API usability
- Integration with your use cases
- Performance
- Bug reports
Comments can be posted to the Gordian Developer Community.
Because this library is still in community review, it should not be used for production tasks until it has received further testing and auditing.
See Blockchain Commons' Development Phases.
Dependencies
- dcbor: Deterministic CBOR for consistent serialization
- bc-crypto: Cryptographic primitives
- bc-components: Common cryptographic components
- bc-ur: Uniform Resources for encoding and decoding
Other Implementations
Gordian Envelope is also available in:
Contributing
We encourage public contributions through issues and pull requests! Please review CONTRIBUTING.md for details on our development process. All contributions to this repository require a GPG signed Contributor License Agreement.
Financial Support
Gordian Envelope is a project of Blockchain Commons, a "not-for-profit" social benefit corporation committed to open source & open development. Our work is funded entirely by donations and collaborative partnerships with people like you. Every contribution will be spent on building open tools, technologies, and techniques that sustain and advance blockchain and internet security infrastructure and promote an open web.
To financially support further development of Gordian Envelope and other projects, please consider becoming a Patron of Blockchain Commons through ongoing monthly patronage as a GitHub Sponsor. You can also support Blockchain Commons with bitcoins at our BTCPay Server.
Discussions
The best place to talk about Blockchain Commons and its projects is in our GitHub Discussions areas:
- Gordian Developer Community: For developers working with Gordian specifications
- Blockchain Commons Discussions: For general Blockchain Commons topics
Credits
The following people directly contributed to this repository:
Name | Role | Github | GPG Fingerprint | |
---|---|---|---|---|
Christopher Allen | Principal Architect | @ChristopherA | ChristopherA@LifeWithAlacrity.com | FDFE 14A5 4ECB 30FC 5D22 74EF F8D3 6C91 3574 05ED |
Wolf McNally | Contributor | @WolfMcNally | Wolf@WolfMcNally.com | 9436 52EE 3844 1760 C3DC 3536 4B6C 2FCF 8947 80AE |
Responsible Disclosure
We want to keep all our software safe for everyone. If you have discovered a security vulnerability, we appreciate your help in disclosing it to us in a responsible manner. Please see our security policy for details.
License
Gordian Envelope is licensed under the BSD-2-Clause-Patent license. See LICENSE for details.
Dependencies
~69MB
~1.5M SLoC