[−][src]Crate crypto_box
Pure Rust implementation of the crypto_box
publickey authenticated
encryption scheme from NaClfamily libraries (e.g. libsodium, TweetNaCl)
which combines the X25519 DiffieHellman function and the
XSalsa20Poly1305 authenticated encryption cipher into an Elliptic Curve
Integrated Encryption Scheme (ECIES).
Introduction
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 highsecurity 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 wellknown 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.
Usage
use crypto_box::{Box, PublicKey, SecretKey, aead::Aead}; // // Encryption // // Generate a random secret key. // NOTE: It can be serialized as bytes by calling `secret_key.to_bytes()` let mut rng = rand::thread_rng(); let alice_secret_key = SecretKey::generate(&mut rng); // 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 `Box` by performing DiffieHellman key agreement between // the two keys. let alice_box = Box::new(&bob_public_key, &alice_secret_key); // Get a random nonce to encrypt the message under let nonce = crypto_box::generate_nonce(&mut rng); // 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[..]).unwrap(); // // Decryption // // Either side can encrypt or decrypt messages under the DiffieHellman 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 Box as Alice by performing the reciprocal // key exchange operation. let bob_box = Box::new(&alice_public_key, &bob_secret_key); // Decrypt the message, using the same randomly generated nonce let decrypted_plaintext = bob_box.decrypt(&nonce, &ciphertext[..]).unwrap(); assert_eq!(&plaintext[..], &decrypted_plaintext[..]);
Inplace 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 [Aead::encrypt_in_place
] and [Aead::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
(reexported from the aead
crate as aead::heapless::Vec
),
which can then be passed as the buffer
parameter to the inplace encrypt
and decrypt methods.
A heapless
usage example can be found in the documentation for the
xsalsa20poly1305
crate:
Reexports
pub use xsalsa20poly1305::aead; 
Structs
PublicKey  A 
SalsaBox  Publickey encryption scheme based on the X25519 Elliptic Curve DiffieHellman function and the XSalsa20Poly1305 authenticated encryption cipher. 
SecretKey 

Constants
KEY_SIZE  Size of a 
Functions
generate_nonce  Generate a random nonce: every message MUST have a unique nonce! 
Type Definitions
Box  Alias for 