Crypto.Saltine.Core.Box

Public-key authenticated encryption: Crypto.Saltine.Core.Box

The box function encrypts and authenticates a message ByteString using the sender's secret key, the receiver's public key, and a nonce. The boxOpen function verifies and decrypts a ciphertext ByteString using the receiver's secret key, the sender's public key, and a nonce. If the ciphertext fails verification, boxOpen returns Nothing.

The Crypto.Saltine.Core.Box module is designed to meet the standard notions of privacy and third-party unforgeability for a public-key authenticated-encryption scheme using nonces. For formal definitions see, e.g., Jee Hea An, "Authenticated encryption in the public-key setting: security notions and analyses," http://eprint.iacr.org/2001/079.

Distinct messages between the same {sender, receiver} set are required to have distinct nonces. For example, the lexicographically smaller public key can use nonce 1 for its first message to the other key, nonce 3 for its second message, nonce 5 for its third message, etc., while the lexicographically larger public key uses nonce 2 for its first message to the other key, nonce 4 for its second message, nonce 6 for its third message, etc. Nonces are long enough that randomly generated nonces have negligible risk of collision.

There is no harm in having the same nonce for different messages if the {sender, receiver} sets are different. This is true even if the sets overlap. For example, a sender can use the same nonce for two different messages if the messages are sent to two different public keys.

The Crypto.Saltine.Core.Box module is not meant to provide non-repudiation. On the contrary: the crypto_box function guarantees repudiability. A receiver can freely modify a boxed message, and therefore cannot convince third parties that this particular message came from the sender. The sender and receiver are nevertheless protected against forgeries by other parties. In the terminology of http://groups.google.com/group/sci.crypt/msg/ec5c18b23b11d82c, crypto_box uses "public-key authenticators" rather than "public-key signatures."

Users who want public verifiability (or receiver-assisted public verifiability) should instead use signatures (or signcryption). Signatures are documented in the Crypto.Saltine.Core.Sign module.

Crypto.Saltine.Core.Box is curve25519xsalsa20poly1305, a particular combination of Curve25519, Salsa20, and Poly1305 specified in "Cryptography in NaCl" (http://nacl.cr.yp.to/valid.html). This function is conjectured to meet the standard notions of privacy and third-party unforgeability.

This is version 2010.08.30 of the box.html web page.

Documentation

data SecretKey

An opaque box cryptographic secret key.

Instances

Eq SecretKey

Ord SecretKey

IsEncoding SecretKey

data PublicKey

An opaque box cryptographic public key.

Instances

Eq PublicKey

Ord PublicKey

IsEncoding PublicKey

type Keypair = (SecretKey, PublicKey)

A convenience type for keypairs

data CombinedKey

An opaque boxAfterNM cryptographic combined key.

Instances

Eq CombinedKey

Ord CombinedKey

IsEncoding CombinedKey

data Nonce

An opaque box nonce.

Instances

Eq Nonce

Ord Nonce

IsNonce Nonce

IsEncoding Nonce

newKeypair :: IO Keypair

Randomly generates a secret key and a corresponding public key.

beforeNM :: SecretKey -> PublicKey -> CombinedKey

Build a CombinedKey for sending from SecretKey to PublicKey. This is a precomputation step which can accelerate later encryption calls.

newNonce :: IO Nonce

Randomly generates a nonce for usage with box and boxOpen.

box

Arguments

:: PublicKey

-> SecretKey

-> Nonce

-> ByteString

Message

-> ByteString

Ciphertext

Encrypts a message for sending to the owner of the public key. They must have your public key in order to decrypt the message. It is infeasible for an attacker to decrypt the message so long as the Nonce is not repeated.

boxOpen

Arguments

:: PublicKey

-> SecretKey

-> Nonce

-> ByteString

Ciphertext

-> Maybe ByteString

Message

Decrypts a message sent from the owner of the public key. They must have encrypted it using your secret key. Returns Nothing if the keys and message do not match.

boxAfterNM

Arguments

:: CombinedKey

-> Nonce

-> ByteString

Message

-> ByteString

Ciphertext

box using a CombinedKey and is thus faster.

boxOpenAfterNM

Arguments

:: CombinedKey

-> Nonce

-> ByteString

Ciphertext

-> Maybe ByteString

Message

boxOpen using a CombinedKey and is thus faster.