Module onionsalt::crypto [−] [src]

A rust translation of the TweetNaCl library. It is mostly a direct translation, but in places I tried to make the API more rustic. It has three major features, of which you are likely to use only one.

Authenticated symmetric-key encryption This is not so very often useful, but on the off chance you have a shared secret you could use it.
SHA512 hasing This again could be handy, but is not necesarily what you want most of the time. And to be honest, you probably don't want my crude translation to rust of the pure C TweetNaCl implementation.
Public-key encryption with authentication This is what you want. It allows you to send messages to a remote party, and ensure they aren't modified in transit. The remote party can verify that you sent the message (or someone else did who had access to either your private key or their private key), but they can't prove that you sent the message. It's a nice set of functionality, implemented in the functions box_up (which encrypts) and box_open (which decrypts and authenticates).

Examples

Here is a simple example of encrypting a message and decrypting it. The one thing that it doesn't demonstrate is that the ciphertext is padded with 16 zero bytes, which you probably don't want to bother sending over the network.

// of course, in practice, don't use unwrap:  handle the error!
let mykey = crypto::box_keypair();
let thykey = crypto::box_keypair();

let plaintext = b"Friendly message.";

let mut padded_plaintext: vec::Vec<u8> = vec::Vec::with_capacity(32+plaintext.len());
for _ in 0..32 { padded_plaintext.push(0); }
for i in 0..plaintext.len() { padded_plaintext.push(plaintext[i]); }

let mut ciphertext: vec::Vec<u8> = vec::Vec::with_capacity(padded_plaintext.len());
for _ in 0..padded_plaintext.len() { ciphertext.push(0); }

let nonce = crypto::random_nonce();

// Here we encreypt the message.  Keep in mind when sending it
// that you should strip the 16 zeros off the beginning!

crypto::box_up(&mut ciphertext, &padded_plaintext,
               &nonce, &thykey.public, &mykey.secret);

let mut decrypted: vec::Vec<u8> = vec::Vec::with_capacity(padded_plaintext.len());
for _ in 0..ciphertext.len() { decrypted.push(0); }

// Use box_open to decrypt the message.  You REALLY don't want
// to unwrap (or ignore) the output of box_open, since this is
// how you know that the message was authenticated.

crypto::box_open(&mut decrypted, &ciphertext,
                 &nonce, &mykey.public, &thykey.secret).unwrap();

// Note that decrypted (like padded_plaintext) has 32 bytes of
// zeros padded at the beginning.
for i in 0..plaintext.len() {
    assert!(plaintext[i] == decrypted[i+32]);
}

Structs

KeyPair	A pair with public and secret keys.
Nonce	A nonce. You should never reuse a nonce for two different messages between the same set of keys.
PublicKey	A public key.
SecretKey	A secret key.

Enums

NaClError

The error return type. You can get errors for only one of three reasons:

Functions

box_afternm	Encrypt a message after creating a secret key using `box_beforenm`. The two functions together come out to the same thing as `box_up`.
box_beforenm	Prepare to either open or encrypt some public-key messages. This is useful if you want to handle many messages between the same two recipients, since it allows you to do the public-key business just once.
box_keypair	Generate a random public/secret key pair. This is the only way you should generate keys. Although of course you can store keys to disk and then read them back again. But they always start with `box_keypair`.
box_open	Open a message encrypted with `crypto::box_up`.
box_open_afternm	Decrypt a message using a key that was precomputed using `box_beforenm`. The two functions together are the same as the easier-to-use `box_open`.
box_up	An implementation of the NaCl function `crypto_box`, renamed to `crypto::box_up` because `box` is a keyword in rust.
funnybox_open	Decrypt a message encrypted with `funnybox`, only authenticating the first `nauth` bytes.
hash	Compute the SHA512 hash of some data.
random_24	Securely creates 32 random bytes.
random_32	Securely creates 32 random bytes.
random_byte	Securely creates a byte.
random_nonce	Securely creates a random nonce. This function isn't in the NaCl, but I feel like it could be very handy, and a random nonce from a secure source is often what you want.
random_u32	Securely creates a u32.
random_u64	Securely creates a u64.
secretbox	Use symmetric encryption to encrypt a message.
secretbox_open	Decrypt a message encrypted with `secretbox`.
sillybox	An implementation of public-key encryption similar to the NaCl function `crypto_box` (renamed `crypto::sillybox_up` in this package), but with the feature that it only authenticates the first `nauth` bytes. This is not useful for most purposes (thus its silly name), but is helpful for enabling round-trip onion routing in which all the routing information is authenticated (to information leaks triggered by maliciously modified packets), but information may be added to the communication en-route.
sillybox_afternm	Encrypt a message after creating a secret key using `sillybox_beforenm`. The two functions together come out to the same thing as `sillybox`, which you should read to find out how it differs from the standard NaCl `box` encryption.
sillybox_beforenm	Prepare to either open or encrypt some public-key messages. This is useful if you want to handle many messages between the same two recipients, since it allows you to do the public-key business just once.
sillybox_open	Open a message encrypted with `crypto::sillybox_up`, only authenticating the first `nauth` bytes. It is your business to separately verify (or distrust) the remaining bytes. An obvious approach would be to nest in the remaining bytes an encrypted and authenticated message.
sillybox_open_afternm	Decrypt a message using a key that was precomputed using `sillybox_beforenm`. The two functions together are the same as the easier-to-use `sillybox_open`.