double-ratchet-rs

Signal所描述的Double Ratchet算法的纯Rust实现。

此实现遵循Signal提供的加密建议。AEAD算法使用一个常量Nonce。这可能会在未来改变。

double-ratchet-2的分支。

示例

标准用法

Alice加密一条消息，然后Bob解密。

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

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

assert_eq!(data, decrypted)

恢复丢失的消息

Alice为Bob加密了两条消息。必须首先解密最新的一条消息。

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

let data = b"Hello World".to_vec(); // Data to be encrypted
let ad = b"Associated Data";        // Associated data

let (header1, encrypted1, nonce1) = alice_ratchet.encrypt(&data, ad); // Lost message
let (header2, encrypted2, nonce2) = alice_ratchet.encrypt(&data, ad); // Successful message

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

assert_eq!(data, decrypted1);
assert_eq!(data, decrypted2);

在解密第一条消息之前加密

Bob在解密Alice的消息之前加密了一条消息。这会导致panic。

use double_ratchet_rs::Ratchet;

let sk = [1; 32];

let (mut bob_ratchet, _) = Ratchet::init_bob(sk);

let data = b"Hello World".to_vec();
let ad = b"Associated Data";

let (_, _, _) = bob_ratchet.encrypt(&data, ad);

在解密第一条消息之后加密

Bob也可以加密消息。但这只能在首先解密Alice的消息之后才能实现。

use double_ratchet_rs::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 (header1, encrypted1, nonce1) = alice_ratchet.encrypt(&data, ad);
let _decrypted1 = bob_ratchet.decrypt(&header1, &encrypted1, &nonce1, ad);

let (header2, encrypted2, nonce2) = bob_ratchet.encrypt(&data, ad);
let decrypted2 = alice_ratchet.decrypt(&header2, &encrypted2, &nonce2, ad);

assert_eq!(data, decrypted2);

构建和解构头信息

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);
let header_bytes: Vec<u8> = header.clone().into();
let header_const = Header::from(header_bytes);

assert_eq!(header, header_const);

加密头信息

use double_ratchet_rs::RatchetEncHeader;

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);

let data = b"Hello World".to_vec();
let ad = b"Associated Data";

let (header, encrypted, nonce) = alice_ratchet.encrypt(&data, ad);
let decrypted = bob_ratchet.decrypt(&header, &encrypted, &nonce, ad);

assert_eq!(data, decrypted)

使用加密头信息导出/导入Ratchet

这可以用于在文件中存储和使用ratchets。

use double_ratchet_rs::RatchetEncHeader;

let sk = [0; 32];
let shared_hka = [1; 32];
let shared_nhkb = [2; 32];

let (bob_ratchet, public_key) = RatchetEncHeader::init_bob(sk, shared_hka, shared_nhkb);
let ex_ratchet = bob_ratchet.export();
let im_ratchet = RatchetEncHeader::import(&ex_ratchet).unwrap();

assert_eq!(im_ratchet, bob_ratchet)

特性

• hashbrown：使用hashbrown进行HashMap。默认启用以支持no_std。
• std：使用std而不是alloc。可以与hashbrown一起使用，但不是必需的。

Minimum Supported Rust Version (MSRV)

当前的MSRV是不使用hashbrown的1.60.0，使用hashbrown的是1.64.0。

许可证

本项目采用MIT许可证。