2023-07-18 23:27:53 +00:00
[![Crate ](https://img.shields.io/crates/v/double-ratchet-rs )](https://crates.io/crates/double-ratchet-rs)
2023-07-18 23:33:31 +00:00
[![License ](https://img.shields.io/github/license/notsatvrn/double-ratchet-rs )](https://github.com/notsatvrn/double-ratchet-rs/blob/main/LICENSE)
[![Coverage Status ](https://coveralls.io/repos/github/notsatvrn/double-ratchet-rs/badge.svg?branch=main )](https://coveralls.io/github/notsatvrn/double-ratchet-rs?branch=main)
[![Workflow Status ](https://github.com/notsatvrn/double-ratchet-rs/actions/workflows/rust.yml/badge.svg )](https://github.com/notsatvrn/double-ratchet-rs/actions/workflows/rust.yml)
2021-06-18 10:16:01 +00:00
2023-07-18 23:27:53 +00:00
# double-ratchet-rs
2021-05-13 16:00:35 +00:00
2023-07-18 23:27:53 +00:00
A pure Rust implementation of the Double Ratchet Algorithm as specified by [Signal][1].
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
This implementation follows the cryptographic recommendations provided by [Signal][2].
2021-06-16 09:03:37 +00:00
The AEAD Algorithm uses a constant Nonce. This might be changed in the future.
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
Fork of [double-ratchet-2 ](https://github.com/Dione-Software/double-ratchet-2 ).
## Examples
### Standard Usage
Alice encrypts a message which is then decrypted by Bob.
2021-05-13 15:49:11 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::Ratchet;
let sk = [1; 32]; // Shared key created by a symmetric key agreement protocol
let (mut bob_ratchet, public_key) = Ratchet::init_bob(sk); // Creating Bob's Ratchet (returns Bob's PublicKey)
let mut alice_ratchet = Ratchet::init_alice(sk, public_key); // Creating Alice's Ratchet with Bob's PublicKey
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let data = b"Hello World".to_vec(); // Data to be encrypted
let ad = b"Associated Data"; // Associated data
let (header, encrypted, nonce) = alice_ratchet.encrypt(& data, ad); // Encrypting message with Alice's Ratchet (Alice always needs to send the first message)
let decrypted = bob_ratchet.decrypt(& header, & encrypted, & nonce, ad); // Decrypt message with Bob's Ratchet
2021-05-13 15:49:11 +00:00
assert_eq!(data, decrypted)
```
2023-07-18 23:27:53 +00:00
### Recovering a Lost Message
Alice encrypts 2 messages for Bob.
The latest message must be decrypted first.
2021-05-13 15:49:11 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::Ratchet;
let sk = [1; 32]; // Shared key created by a symmetric key agreement protocol
let (mut bob_ratchet, public_key) = Ratchet::init_bob(sk); // Creating Bob's Ratchet (returns Bob's PublicKey)
let mut alice_ratchet = Ratchet::init_alice(sk, public_key); // Creating Alice's Ratchet with Bob's PublicKey
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let data = b"Hello World".to_vec(); // Data to be encrypted
let ad = b"Associated Data"; // Associated data
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let (header1, encrypted1, nonce1) = alice_ratchet.encrypt(& data, ad); // Lost message
let (header2, encrypted2, nonce2) = alice_ratchet.encrypt(& data, ad); // Successful message
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let decrypted2 = bob_ratchet.decrypt(& header2, & encrypted2, & nonce2, ad); // Decrypting second message first
let decrypted1 = bob_ratchet.decrypt(& header1, & encrypted1, & nonce1, ad); // Decrypting latter message
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
assert_eq!(data, decrypted1);
assert_eq!(data, decrypted2);
2021-05-13 15:49:11 +00:00
```
2023-07-18 23:27:53 +00:00
### Encryption Before Decrypting First Message
Bob encrypts a message before decrypting one from Alice.
This will result in a panic.
2021-05-13 15:49:11 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::Ratchet;
2021-05-13 15:49:11 +00:00
let sk = [1; 32];
2023-07-18 23:27:53 +00:00
2021-05-13 15:49:11 +00:00
let (mut bob_ratchet, _) = Ratchet::init_bob(sk);
2023-07-18 23:27:53 +00:00
2021-05-13 15:49:11 +00:00
let data = b"Hello World".to_vec();
2023-07-18 23:27:53 +00:00
let ad = b"Associated Data";
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let (_, _, _ ) = bob_ratchet.encrypt(& data, ad);
2021-05-13 15:49:11 +00:00
```
2023-07-18 23:27:53 +00:00
### Encryption After Decrypting First Message
Bob *can* also encrypt messages.
This is only possible after decrypting one from Alice first though.
2021-05-13 15:49:11 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::Ratchet;
2021-05-13 15:49:11 +00:00
let sk = [1; 32];
let (mut bob_ratchet, public_key) = Ratchet::init_bob(sk);
let mut alice_ratchet = Ratchet::init_alice(sk, public_key);
let data = b"Hello World".to_vec();
2021-05-14 16:42:17 +00:00
let ad = b"Associated Data";
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let (header1, encrypted1, nonce1) = alice_ratchet.encrypt(& data, ad);
let _decrypted1 = bob_ratchet.decrypt(& header1, & encrypted1, & nonce1, ad);
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
let (header2, encrypted2, nonce2) = bob_ratchet.encrypt(& data, ad);
let decrypted2 = alice_ratchet.decrypt(& header2, & encrypted2, & nonce2, ad);
2021-05-13 15:49:11 +00:00
assert_eq!(data, decrypted2);
```
2023-07-18 23:27:53 +00:00
2021-05-13 15:49:11 +00:00
### Constructing and Deconstructing Headers
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::{Header, Ratchet};
let sk = [1; 32];
let (mut bob_ratchet, public_key) = Ratchet::init_bob(sk);
let mut alice_ratchet = Ratchet::init_alice(sk, public_key);
let data = b"hello World".to_vec();
let ad = b"Associated Data";
let (header, _, _ ) = alice_ratchet.encrypt(& data, ad);
2021-05-13 15:49:11 +00:00
let header_bytes: Vec< u8 > = header.clone().into();
let header_const = Header::from(header_bytes);
2023-07-18 23:27:53 +00:00
2021-05-13 15:49:11 +00:00
assert_eq!(header, header_const);
```
2023-07-18 23:27:53 +00:00
### Encrypted Headers
2021-05-14 16:22:18 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::RatchetEncHeader;
2021-05-14 16:22:18 +00:00
let sk = [0; 32];
let shared_hka = [1; 32];
let shared_nhkb = [2; 32];
let (mut bob_ratchet, public_key) = RatchetEncHeader::init_bob(sk, shared_hka, shared_nhkb);
let mut alice_ratchet = RatchetEncHeader::init_alice(sk, public_key, shared_hka, shared_nhkb);
2023-07-18 23:27:53 +00:00
2021-05-14 16:22:18 +00:00
let data = b"Hello World".to_vec();
2021-05-14 16:42:17 +00:00
let ad = b"Associated Data";
2021-05-14 16:22:18 +00:00
2023-07-18 23:27:53 +00:00
let (header, encrypted, nonce) = alice_ratchet.encrypt(& data, ad);
let decrypted = bob_ratchet.decrypt(& header, & encrypted, & nonce, ad);
2021-05-14 16:22:18 +00:00
assert_eq!(data, decrypted)
```
2023-07-18 23:27:53 +00:00
### Exporting / Importing Ratchet w/ Encrypted Headers
This can be used for storing and using ratchets in a file.
2021-08-23 12:05:05 +00:00
```rust
2023-07-18 23:27:53 +00:00
use double_ratchet_rs::RatchetEncHeader;
let sk = [0; 32];
let shared_hka = [1; 32];
let shared_nhkb = [2; 32];
2021-08-23 12:05:05 +00:00
let (bob_ratchet, public_key) = RatchetEncHeader::init_bob(sk, shared_hka, shared_nhkb);
let ex_ratchet = bob_ratchet.export();
2023-07-18 23:27:53 +00:00
let im_ratchet = RatchetEncHeader::import(&ex_ratchet).unwrap();
2021-08-23 12:05:05 +00:00
assert_eq!(im_ratchet, bob_ratchet)
```
2023-07-18 23:27:53 +00:00
## **M**inimum **S**upported **R**ust **V**ersion (MSRV)
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
The current MSRV is 1.61.0.
2021-05-13 15:49:11 +00:00
2023-07-18 23:27:53 +00:00
## License
2021-05-13 15:49:11 +00:00
2023-07-18 23:33:31 +00:00
This project is licensed under the [MIT license ](https://github.com/notsatvrn/double-ratchet-rs/blob/main/LICENSE ).
2021-05-13 15:49:11 +00:00
[1]: https://signal.org/docs/specifications/doubleratchet/
[2]: https://signal.org/docs/specifications/doubleratchet/#recommended-cryptographic-algorithms
[3]: https://signal.org/docs/specifications/doubleratchet/#double-ratchet-with-header-encryption
2021-05-13 18:23:43 +00:00