The repository consists of the following main components: - Basic DIDComm v2 support in Rust. - Wasm - based DIDComm JavaScript/TypeScript, see wasm. - uniffi-rs - based wrappers - uniffi - callback-based Rust wrapper with uniffi-rs support - wrappers/swift - Swift wrapper generated via uniffi-rs
The docs below are provided for the main DIDComm Rust.
See wasm/README.md for DIDComm JavaScript/TypeScript docs.
See wrappers/swift/README.md for DIDComm Swift docs.
To use didcomm, add this to your Cargo.toml:
toml
[dependencies]
didcomm = "0.4"
Use cargo run --example {example-name} for example cargo run --example basic.
SecretsResolver and DIDResolver traits must be implemented on the application level.
Implementation of that traits is out of DIDComm library scope, but we provide 2 simple implementation ExampleDIDResolver
and ExampleSecretsResolver that allows resolve locally known DID docs and secrets for tests/demo purposes.
SecretsResolver must match the corresponding key IDs from DID Doc verification methods.did#key-id.fromPrior field) is supported.See examples for details.
A general usage of the API is the following:
- Sender Side:
- Build a Message (plaintext, payload).
- Convert a message to a DIDComm Message for further transporting by calling one of the following:
- Message::pack_encrypted to build an Encrypted DIDComm message
- Message::pack_signed to build a Signed DIDComm message
- Message::pack_plaintext to build a Plaintext DIDComm message
- Receiver side:
- Call Message::unpack on receiver side that will decrypt the message, verify signature if needed
and return a Message for further processing on the application level.
This is the most common DIDComm message to be used in most of the applications.
A DIDComm encrypted message is an encrypted JWM (JSON Web Messages) that - hides its content from all but authorized recipients - (optionally) discloses and proves the sender to only those recipients - provides message integrity guarantees
It is important in privacy-preserving routing. It is what normally moves over network transports in DIDComm applications, and is the safest format for storing DIDComm data at rest.
See Message::pack_encrypted documentation for more details.
Authentication encryption example (most common case):
```rust // --- Build message from ALICE to BOB --- let msg = Message::build( "example-1".toowned(), "example/v1".toowned(), json!("example-body"), ) .to(ALICEDID.toowned()) .from(BOBDID.toowned()) .finalize();
// --- Pack encrypted and authenticated message --- let didresolver = ExampleDIDResolver::new(vec![ALICEDIDDOC.clone(), BOBDIDDOC.clone()]); let secretsresolver = ExampleSecretsResolver::new(ALICE_SECRETS.clone());
let (msg, metadata) = msg .packencrypted( BOBDID, Some(ALICEDID), None, &didresolver, &secretsresolver, &PackEncryptedOptions::default(), ) .await .expect("Unable packencrypted");
println!("Encryption metadata is\n{:?}\n", metadata);
// --- Send message --- println!("Sending message \n{}\n", msg);
// --- Unpacking message --- let didresolver = ExampleDIDResolver::new(vec![ALICEDIDDOC.clone(), BOBDIDDOC.clone()]); let secretsresolver = ExampleSecretsResolver::new(BOB_SECRETS.clone());
let (msg, metadata) = Message::unpack( &msg, &didresolver, &secretsresolver, &UnpackOptions::default(), ) .await .expect("Unable unpack");
println!("Receved message is \n{:?}\n", msg); println!("Receved message unpack metadata is \n{:?}\n", metadata); ```
Anonymous encryption example:
rust
let (msg, metadata) = msg
.pack_encrypted(
BOB_DID,
None, // Keep sender as None here
None,
&did_resolver,
&secrets_resolver,
&PackEncryptedOptions::default(),
)
.await
.expect("Unable pack_encrypted");
Encryption with non-repudiation example:
rust
let (msg, metadata) = msg
.pack_encrypted(
BOB_DID,
Some(ALICE_DID),
Some(ALICE_DID), // Provide information about signer here
&did_resolver,
&secrets_resolver,
&PackEncryptedOptions::default(),
)
.await
.expect("Unable pack_encrypted");
Signed messages are only necessary when - the origin of plaintext must be provable to third parties - or the sender can’t be proven to the recipient by authenticated encryption because the recipient is not known in advance (e.g., in a broadcast scenario).
Adding a signature when one is not needed can degrade rather than enhance security because it relinquishes the sender’s ability to speak off the record.
See Message::pack_signed documentation for more details.
```rust // ALICE let msg = Message::build( "example-1".toowned(), "example/v1".toowned(), json!("example-body"), ) .to(ALICEDID.toowned()) .from(BOBDID.toowned()) .finalize();
let (msg, metadata) = msg .packsigned(ALICEDID, &didresolver, &secretsresolver) .await .expect("Unable pack_signed");
// BOB let (msg, metadata) = Message::unpack( &msg, &didresolver, &secretsresolver, &UnpackOptions::default(), ) .await .expect("Unable unpack"); ```
A DIDComm message in its plaintext form that - is not packaged into any protective envelope - lacks confidentiality and integrity guarantees - repudiable
They are therefore not normally transported across security boundaries.
```rust // ALICE let msg = Message::build( "example-1".toowned(), "example/v1".toowned(), json!("example-body"), ) .to(ALICEDID.toowned()) .from(BOBDID.toowned()) .finalize();
let msg = msg .packplaintext(&didresolver) .expect("Unable pack_plaintext");
// BOB let (msg, metadata) = Message::unpack( &msg, &didresolver, &secretsresolver, &UnpackOptions::default(), ) .await .expect("Unable unpack"); ```
PRs are welcome!
The following CI checks are run against every PR:
- No warnings from cargo check --all-targets
- All tests must pass with cargo tests
- Code must be formatted by cargo fmt --all