Crate crypto_box

source ·
Expand description

RustCrypto: crypto_box

crate Docs Apache2/MIT licensed Rust Version Project Chat Build Status

Pure Rust implementation of NaCl’s crypto_box primitive, providing public-key authenticated encryption which combines the X25519 Diffie-Hellman function and the XSalsa20Poly1305 authenticated encryption cipher into an Elliptic Curve Integrated Encryption Scheme (ECIES).

Documentation

About

Imagine Alice wants something valuable shipped to her. Because it’s valuable, she wants to make sure it arrives securely (i.e. hasn’t been opened or tampered with) and that it’s not a forgery (i.e. it’s actually from the sender she’s expecting it to be from and nobody’s pulling the old switcheroo).

One way she can do this is by providing the sender (let’s call him Bob) with a high-security box of her choosing. She provides Bob with this box, and something else: a padlock, but a padlock without a key. Alice is keeping that key all to herself. Bob can put items in the box then put the padlock onto it, but once the padlock snaps shut, the box cannot be opened by anyone who doesn’t have Alice’s private key.

Here’s the twist though, Bob also puts a padlock onto the box. This padlock uses a key Bob has published to the world, such that if you have one of Bob’s keys, you know a box came from him because Bob’s keys will open Bob’s padlocks (let’s imagine a world where padlocks cannot be forged even if you know the key). Bob then sends the box to Alice.

In order for Alice to open the box, she needs two keys: her private key that opens her own padlock, and Bob’s well-known key. If Bob’s key doesn’t open the second padlock then Alice knows that this is not the box she was expecting from Bob, it’s a forgery.

Security Notes

This crate has received one security audit by Cure53 (version 0.7.1), with no significant findings. We would like to thank Threema for funding the audit.

License

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

use crypto_box::{
    aead::{Aead, AeadCore, OsRng},
    SalsaBox, PublicKey, SecretKey
};

//
// Encryption
//

// Generate a random secret key.
// NOTE: The secret key bytes can be accessed by calling `secret_key.as_bytes()`
let alice_secret_key = SecretKey::generate(&mut OsRng);

// Get the public key for the secret key we just generated
let alice_public_key_bytes = alice_secret_key.public_key().as_bytes().clone();

// Obtain your recipient's public key.
let bob_public_key = PublicKey::from([
   0xe8, 0x98, 0xc, 0x86, 0xe0, 0x32, 0xf1, 0xeb,
   0x29, 0x75, 0x5, 0x2e, 0x8d, 0x65, 0xbd, 0xdd,
   0x15, 0xc3, 0xb5, 0x96, 0x41, 0x17, 0x4e, 0xc9,
   0x67, 0x8a, 0x53, 0x78, 0x9d, 0x92, 0xc7, 0x54,
]);

// Create a `SalsaBox` by performing Diffie-Hellman key agreement between
// the two keys.
let alice_box = SalsaBox::new(&bob_public_key, &alice_secret_key);

// Get a random nonce to encrypt the message under
let nonce = SalsaBox::generate_nonce(&mut OsRng);

// Message to encrypt
let plaintext = b"Top secret message we're encrypting";

// Encrypt the message using the box
let ciphertext = alice_box.encrypt(&nonce, &plaintext[..])?;

//
// Decryption
//

// Either side can encrypt or decrypt messages under the Diffie-Hellman key
// they agree upon. The example below shows Bob's side.
let bob_secret_key = SecretKey::from([
    0xb5, 0x81, 0xfb, 0x5a, 0xe1, 0x82, 0xa1, 0x6f,
    0x60, 0x3f, 0x39, 0x27, 0xd, 0x4e, 0x3b, 0x95,
    0xbc, 0x0, 0x83, 0x10, 0xb7, 0x27, 0xa1, 0x1d,
    0xd4, 0xe7, 0x84, 0xa0, 0x4, 0x4d, 0x46, 0x1b
]);

// Deserialize Alice's public key from bytes
let alice_public_key = PublicKey::from(alice_public_key_bytes);

// Bob can compute the same `SalsaBox` as Alice by performing the
// key agreement operation.
let bob_box = SalsaBox::new(&alice_public_key, &bob_secret_key);

// Decrypt the message, using the same randomly generated nonce
let decrypted_plaintext = bob_box.decrypt(&nonce, &ciphertext[..])?;

assert_eq!(&plaintext[..], &decrypted_plaintext[..]);

Choosing ChaChaBox vs SalsaBox

The crypto_box construction was originally specified using SalsaBox.

However, the newer ChaChaBox construction is also available, which provides better security and performance.

To use it, enable the chacha20 feature.

use crypto_box::{
    aead::{Aead, AeadCore, Payload, OsRng},
    ChaChaBox, PublicKey, SecretKey
};

let alice_secret_key = SecretKey::generate(&mut OsRng);
let alice_public_key_bytes = alice_secret_key.public_key().as_bytes().clone();
let bob_public_key = PublicKey::from([
   0xe8, 0x98, 0xc, 0x86, 0xe0, 0x32, 0xf1, 0xeb,
   0x29, 0x75, 0x5, 0x2e, 0x8d, 0x65, 0xbd, 0xdd,
   0x15, 0xc3, 0xb5, 0x96, 0x41, 0x17, 0x4e, 0xc9,
   0x67, 0x8a, 0x53, 0x78, 0x9d, 0x92, 0xc7, 0x54,
]);
let alice_box = ChaChaBox::new(&bob_public_key, &alice_secret_key);
let nonce = ChaChaBox::generate_nonce(&mut OsRng);

// Message to encrypt
let plaintext = b"Top secret message we're encrypting".as_ref();

// Encrypt the message using the box
let ciphertext = alice_box.encrypt(&nonce, plaintext).unwrap();

//
// Decryption
//

let bob_secret_key = SecretKey::from([
    0xb5, 0x81, 0xfb, 0x5a, 0xe1, 0x82, 0xa1, 0x6f,
    0x60, 0x3f, 0x39, 0x27, 0xd, 0x4e, 0x3b, 0x95,
    0xbc, 0x0, 0x83, 0x10, 0xb7, 0x27, 0xa1, 0x1d,
    0xd4, 0xe7, 0x84, 0xa0, 0x4, 0x4d, 0x46, 0x1b
]);
let alice_public_key = PublicKey::from(alice_public_key_bytes);
let bob_box = ChaChaBox::new(&alice_public_key, &bob_secret_key);

// Decrypt the message, using the same randomly generated nonce
let decrypted_plaintext = bob_box.decrypt(&nonce, ciphertext.as_slice()).unwrap();

assert_eq!(&plaintext[..], &decrypted_plaintext[..]);

In-place Usage (eliminates alloc requirement)

This crate has an optional alloc feature which can be disabled in e.g. microcontroller environments that don’t have a heap.

The AeadInPlace::encrypt_in_place and AeadInPlace::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Note that if you enable the heapless feature of this crate, you will receive an impl of aead::Buffer for heapless::Vec (re-exported from the aead crate as aead::heapless::Vec), which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods.

A heapless usage example can be found in the documentation for the xsalsa20poly1305 crate:

https://docs.rs/xsalsa20poly1305/latest/xsalsa20poly1305/#in-place-usage-eliminates-alloc-requirement

Re-exports

Structs

Constants

  • KEY_SIZE
    Size of a crypto_box public or secret key in bytes.
  • SEALBYTESseal
    Extra bytes for the ciphertext of a crypto_box_seal compared to the plaintext

Type Definitions