saltine-0.1.0.0: Cryptography that's easy to digest (NaCl/libsodium bindings).

Copyright(c) Joseph Abrahamson 2013
LicenseMIT
Maintainerme@jspha.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Crypto.Saltine.Core.Box

Description

Public-key cryptography abstraction: Crypto.Saltine.Core.Box

This module consists of functions dealing with two public-key cryptography concepts in libsodium.

The first one is an authenticated encryption scheme. In this scheme, 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 set of box functions 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 second concept is sealed boxes, which provide encryption and preservation of integrity, but not authentication. Technically, the sender of a message generates a keypair, uses the regular box mechanism, attaches the public key to the message and then immediately destroys the private key. This is useful, e.g. when the receiver cannot know the sender's public key in advance and hence cannot use the regular box functions, or when you want to send messages anonymously.

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.

Synopsis

Documentation

type Keypair = (SecretKey, PublicKey) Source #

A convenience type for keypairs

data Nonce Source #

An opaque box nonce.

newKeypair :: IO Keypair Source #

Randomly generates a secret key and a corresponding public key.

beforeNM :: SecretKey -> PublicKey -> CombinedKey Source #

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

newNonce :: IO Nonce Source #

Randomly generates a nonce for usage with box and boxOpen.

box Source #

Arguments

:: PublicKey 
-> SecretKey 
-> Nonce 
-> ByteString

Message

-> ByteString

Ciphertext (incl. authentication tag)

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 Source #

Arguments

:: PublicKey 
-> SecretKey 
-> Nonce 
-> ByteString

Ciphertext (incl. authentication tag)

-> Maybe ByteString

Message

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

boxAfterNM Source #

Arguments

:: CombinedKey 
-> Nonce 
-> ByteString

Message

-> ByteString

Ciphertext (incl. authentication tag)

box using a CombinedKey and thus faster.

boxOpenAfterNM Source #

Arguments

:: CombinedKey 
-> Nonce 
-> ByteString

Ciphertext (incl. authentication tag)

-> Maybe ByteString

Message

boxOpen using a CombinedKey and is thus faster.

boxSeal :: PublicKey -> ByteString -> IO ByteString Source #

Encrypts a message for sending to the owner of the public key. The message is unauthenticated, but permits integrity checking.

boxSealOpen Source #

Arguments

:: PublicKey 
-> SecretKey 
-> ByteString

Ciphertext

-> Maybe ByteString

Message

Decrypts a sealed box message. The message must have been encrypted using the receiver's public key. Returns Nothing if keys and message do not match or integrity is violated.