didcomm-rs

Rust implementation of DIDComm v2 spec

License

Apache-2.0

Examples of usage

1. Prepare raw message for send and receive

GoTo: full test

``rust // Message construction let m = Message::new() // settingfromheader (sender) - Optional .from("did:xyz:ulapcuhsatnpuhza930hpu34n_") // settingtoheader (recipients) - Optional .to(&[ "did::xyz:34r3cu403hnth03r49g03", "did:xyz:30489jnutnjqhiu0uh540u8hunoe", ]) // populating body with some data -Vec` .body(TEST_DID);

// Serialize message into JWM json (SENDER action) let readytosend = m.clone().asrawjson().unwrap();

// ... transport is happening here ...

// On receival deserialize from json into Message (RECEIVER action) // Error handling recommended here

let received = Message::receive(&readytosend, None, None, None); ```

2. Prepare JWE message for direct send

GoTo: full test

```rust // sender key as bytes let ek = [130, 110, 93, 113, 105, 127, 4, 210, 65, 234, 112, 90, 150, 120, 189, 252, 212, 165, 30, 209, 194, 213, 81, 38, 250, 187, 216, 14, 246, 250, 166, 92];

// Message construction let message = Message::new() .from("did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp") .to(&[ "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp", "did:key:z6MkjchhfUsD6mmvni8mCdXHw216Xrm9bQe2mBH1P5RDjVJG", ]) // packing in some payload (can be anything really) .body(TESTDID) // decide which Algorithm is used (based on key) .asjwe( &CryptoAlgorithm::XC20P, Some(&bobspublic), ) // add some custom app/protocol related headers to didcomm header portion // these are not included into JOSE header .addheaderfield("mycustomkey".into(), "mycustomvalue".into()) .addheaderfield("anotherkey".into(), "another_value".into()) // set kid property .kid(r#"#z6LShs9GGnqk85isEBzzshkuVWrVKsRp24GnDuHk8QWkARMW"#);

// recipient public key is automatically resolved let readytosend = message.seal( &ek, Some(vec![Some(&bobspublic), Some(&carolpublic)]), ).unwrap();

//... transport is happening here ... ```

3. Prepare JWS message -> send -> receive

• Here Message is signed but not encrypted.
• In such scenarios explicit use of .sign(...) and Message::verify(...) required.

```rust // Message construction an JWS wrapping let message = Message::new() // creating message .from("did:xyz:ulapcuhsatnpuhza930hpu34n") // setting from .to(&["did::xyz:34r3cu403hnth03r49g03", "did:xyz:30489jnutnjqhiu0uh540u8hunoe"]) // setting to .body(TESTDID) // packing in some payload .asjws(&SignatureAlgorithm::EdDsa) .sign(SignatureAlgorithm::EdDsa.signer(), &signkeypair.to_bytes()).unwrap();

//... transport is happening here ...

// Receiving JWS let received = Message::verify(&message.asbytes(), &signkeypair.public.to_bytes()); ```

4. Prepare JWE message to be mediated -> mediate -> receive

• Message should be encrypted by destination key first in .routed_by() method call using key for the recipient.
• Next it should be encrypted by mediator key in .seal() method call - this can be done multiple times - once for each mediator in chain but should be strictly sequential to match mediators sequence in the chain.
• Method call .seal() MUST be preceded by .as_jwe(CryptoAlgorithm) as mediators may use different algorithms and key types than destination and this is not automatically predicted or populated.
• Keys used for encryption should be used in reverse order - final destination - last mediator - second to last mediator - etc. Onion style.

GoTo: full test

``rust let mediated = Message::new() // setting from .from("did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp") // setting to .to(&["did:key:z6MkjchhfUsD6mmvni8mCdXHw216Xrm9bQe2mBH1P5RDjVJG"]) // packing in some payload .body(r#"{"foo":"bar"}"#) // set JOSE header for XC20P algorithm .as_jwe(&CryptoAlgorithm::XC20P, Some(&bobs_public)) // custom header .add_header_field("my_custom_key".into(), "my_custom_value".into()) // another custom header .add_header_field("another_key".into(), "another_value".into()) // set kid header .kid(&"Ef1sFuyOozYm3CEY4iCdwqxiSyXZ5Br-eUDdQXk6jaQ") // here we use destination key to bob andtoheader of mediator - //**THIS MUST BE LAST IN THE CHAIN** - after this call you'll get new instance of envelopeMessage` destined to the mediator. .routedby( &aliceprivate, Some(vec![Some(&bobspublic)]), "did:key:z6MknGc3ocHs3zdPiJbnaaqDi58NGb4pk1Sp9WxWufuXSdxf", Some(&mediatorspublic), ); assert!(mediated.is_ok());

//... transport to mediator is happening here ...

// Received by mediator let mediatorreceived = Message::receive( &mediated.unwrap(), Some(&mediatorsprivate), Some(&alicepublic), None, ); assert!(mediatorreceived.is_ok());

// Get inner JWE as string from message let mediatorreceivedunwrapped = mediatorreceived.unwrap().getbody().unwrap(); let plstring = String::fromutf8lossy(mediatorreceivedunwrapped.asref()); let messagetoforward: Mediated = serdejson::fromstr(&plstring).unwrap(); let attachedjwe = serdejson::fromslice::(&messagetoforward.payload); assert!(attachedjwe.isok()); let strjwe = serdejson::tostring(&attachedjwe.unwrap()); assert!(strjwe.isok());

//... transport to destination is happening here ...

// Received by Bob let bobreceived = Message::receive( &String::fromutf8lossy(&messagetoforward.payload), Some(&bobsprivate), Some(&alicepublic), None, ); assert!(bobreceived.is_ok()); ```

5. Prepare JWS envelope wrapped into JWE -> sign -> pack -> receive

• JWS header is set automatically based on signing algorithm type.
• Message forming and encryption happens in same way as in other JWE examples.
• ED25519-dalek signature is used in this example with keypair for signing and public key for verification.

GoTo: full test

```rust let KeyPairSet { alicepublic, aliceprivate, bobsprivate, bobspublic, .. } = getkeypairset(); // Message construction let message = Message::new() // creating message .from("did:xyz:ulapcuhsatnpuhza930hpu34n") // setting from .to(&["did::xyz:34r3cu403hnth03r49g03"]) // setting to .body(TESTDID) // packing in some payload .asjwe(&CryptoAlgorithm::XC20P, Some(&bobspublic)) // set JOSE header for XC20P algorithm .addheaderfield("mycustomkey".into(), "mycustomvalue".into()) // custom header .addheaderfield("anotherkey".into(), "anothervalue".into()) // another custom header .kid(r#"Ef1sFuyOozYm3CEY4iCdwqxiSyXZ5Br-eUDdQXk6jaQ"#); // set kid header

// Send as signed and encrypted JWS wrapped into JWE let readytosend = message.sealsigned( &aliceprivate, Some(vec![Some(&bobspublic)]), SignatureAlgorithm::EdDsa, &signkeypair.to_bytes(), ).unwrap();

//... transport to destination is happening here ...

// Receive - same method to receive for JWE or JWS wrapped into JWE but with pub verifying key let received = Message::receive( &readytosend, Some(&bobsprivate), Some(&alicepublic), None, ); // and now we parse received ```

6. Multiple recipients static key wrap per recipient with shared secret

• ! Works with resolve feature only - requires resolution of public keys for each recipient for shared secret generation.
• Static key generated randomly in the background (to field has >1 recipient).

GoTo: full test

```rust // Creating message with multiple recipients. let m = Message::new() .from("did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp") .to(&[ "did:key:z6MkjchhfUsD6mmvni8mCdXHw216Xrm9bQe2mBH1P5RDjVJG", "did:key:z6MknGc3ocHs3zdPiJbnaaqDi58NGb4pk1Sp9WxWufuXSdxf", ]) .as_jwe(&CryptoAlgorithm::XC20P, None);

let jwe = m.seal(&aliceprivate, None); // Packing was ok? assert!(jwe.isok());

let jwe = jwe.unwrap();

// Each of the recipients receive it in same way as before (direct with single recipient) let receivedfirst = Message::receive(&jwe, Some(&bobsprivate), None, None); let receivedsecond = Message::receive(&jwe, Some(&carolprivate), None, None);

// All good without any extra inputs assert!(receivedfirst.isok()); assert!(receivedsecond.isok()); ```

7. Working with attachments

7.1 Adding Attachment

```rust use didcomm_rs::{Message, AttachmentBuilder, AttachmentDataBuilder};

let payload = b"some usefull data"; let mut m = Message:new(); m.appendattachment( AttachmentBuilder::new(true) .withid("best attachment") .withdata( AttachmentDataBuilder::new() .withraw_payload(payload) ) ); ```

or

```rust use didcomm_rs::{Message, AttachmentBuilder, AttachmentDataBuilder};

let attachments: Vec; // instantiate properly

let mut m = Message:new();

for attachment in attachments { m.append_attachment(attachment); } ```

7.2 Parsing Attachment's

``rust //misreceive()'d instance of aMessage`

let somethingimlookingfor = m.getattachments().filter(|single| single.id == "id I'm looking for"); assert!(somethingimlookingfor.next().issome());

for found in somethingimlooking_for { // process attachments }

```

8. Threading

By default all new messages are created with random UUID as thid header value and with empty pthid value.

To reply to a message in thread with both thid and pthid copied use reply_to method:

```rust

let m = Message::new() .reply_to(&received) // - other methods to form a message ; ```

To set parent thread id (or pthid header), use with_parent method:

```rust

let m = Message::new() .with_parent(&receievd) // - other methods to form a message ; ```

9. Other application-level headers and decorators

In order to satisfy any other header values universal method is present: Message::add_header_field' This method is backed up by aHashMap` of . If the key was present - it's value will be updated.

```rust

let m = Message::new() .addheaderfield("key", "value") .addheaderfield("~decorator", "value") // - other methods to form a message ; ```

To find if specific application level header is present and get it's value get_application_params method should be used.

```rust

let m: Message; // proprely instantiated received message

if let Some((mykey, myvalue)) = m.getapplicationparams().filter(|(key, )| key == "mykey").first(); ```

Plugable cryptography

In order to use your own implementation(s) of message crypto and/or signature algorithms implement these trait(s):

didcomm_rs::crypto::Cypher

didcomm_rs::crypto::Signer

Don't use default feature - might change in future.

When implemented - use them instead of CryptoAlgorithm and SignatureAlgorithm from examples above.

Strongly typed Message payload (body)

GoTo: full test

In most cases application implementation would prefer to have strongly typed body of the message instead of raw Vec<u8>. For this scenario Shape trait should be implemented for target type.

• First, let's define our target type. JSON in this example.

```rust

[derive(Serialize, Deserialize, PartialEq, Debug)]

struct DesiredShape { numfield: usize, stringfield: String, } ```

• Next, implement Shape trait for it

rust impl Shape for DesiredShape { type Err = Error; fn shape(m: &Message) -> Result<DesiredShape, Error> { serde_json::from_str(&m.get_body().unwrap()) .map_err(|e| Error::SerdeError(e)) } }

• Now we can call shape() on our Message and shape in in.
• In this example we expect JSON payload and use it's Deserializer to get our data, but your implementation can work with any serialization.

rust let body = r#"{"num_field":123,"string_field":"foobar"}"#.to_string(); let message = Message::new() // creating message .from("did:xyz:ulapcuhsatnpuhza930hpu34n_") // setting from .to(&["did::xyz:34r3cu403hnth03r49g03"]) // setting to .body(&body); // packing in some payload let received_typed_body = DesiredShape::shape(&message).unwrap(); // Where m = Message

Disclaimer

This is a sample implementation of the DIDComm V2 spec. The DIDComm V2 spec is still actively being developed by the DIDComm WG in the DIF and therefore subject to change.