Crypto.Saltine.Core.Box

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.

Documentation

data SecretKey

An opaque box cryptographic secret key.

Instances

Eq SecretKey

Methods

(==) :: SecretKey -> SecretKey -> Bool

(/=) :: SecretKey -> SecretKey -> Bool

Ord SecretKey

Methods

compare :: SecretKey -> SecretKey -> Ordering

(<) :: SecretKey -> SecretKey -> Bool

(<=) :: SecretKey -> SecretKey -> Bool

(>) :: SecretKey -> SecretKey -> Bool

(>=) :: SecretKey -> SecretKey -> Bool

max :: SecretKey -> SecretKey -> SecretKey

min :: SecretKey -> SecretKey -> SecretKey

IsEncoding SecretKey

Methods

encode :: SecretKey -> ByteString

decode :: ByteString -> Maybe SecretKey

encoded :: (Choice p, Applicative f) => p SecretKey (f SecretKey) -> p ByteString (f ByteString)

data PublicKey

An opaque box cryptographic public key.

Instances

Eq PublicKey

Methods

(==) :: PublicKey -> PublicKey -> Bool

(/=) :: PublicKey -> PublicKey -> Bool

Ord PublicKey

Methods

compare :: PublicKey -> PublicKey -> Ordering

(<) :: PublicKey -> PublicKey -> Bool

(<=) :: PublicKey -> PublicKey -> Bool

(>) :: PublicKey -> PublicKey -> Bool

(>=) :: PublicKey -> PublicKey -> Bool

max :: PublicKey -> PublicKey -> PublicKey

min :: PublicKey -> PublicKey -> PublicKey

IsEncoding PublicKey

Methods

encode :: PublicKey -> ByteString

decode :: ByteString -> Maybe PublicKey

encoded :: (Choice p, Applicative f) => p PublicKey (f PublicKey) -> p ByteString (f ByteString)

type Keypair = (SecretKey, PublicKey)

A convenience type for keypairs

data CombinedKey

An opaque boxAfterNM cryptographic combined key.

Instances

Eq CombinedKey

Methods

(==) :: CombinedKey -> CombinedKey -> Bool

(/=) :: CombinedKey -> CombinedKey -> Bool

Ord CombinedKey

Methods

compare :: CombinedKey -> CombinedKey -> Ordering

(<) :: CombinedKey -> CombinedKey -> Bool

(<=) :: CombinedKey -> CombinedKey -> Bool

(>) :: CombinedKey -> CombinedKey -> Bool

(>=) :: CombinedKey -> CombinedKey -> Bool

max :: CombinedKey -> CombinedKey -> CombinedKey

min :: CombinedKey -> CombinedKey -> CombinedKey

IsEncoding CombinedKey

Methods

encode :: CombinedKey -> ByteString

decode :: ByteString -> Maybe CombinedKey

encoded :: (Choice p, Applicative f) => p CombinedKey (f CombinedKey) -> p ByteString (f ByteString)

data Nonce

An opaque box nonce.

Instances

Eq Nonce

Methods

(==) :: Nonce -> Nonce -> Bool

(/=) :: Nonce -> Nonce -> Bool

Ord Nonce

Methods

compare :: Nonce -> Nonce -> Ordering

(<) :: Nonce -> Nonce -> Bool

(<=) :: Nonce -> Nonce -> Bool

(>) :: Nonce -> Nonce -> Bool

(>=) :: Nonce -> Nonce -> Bool

max :: Nonce -> Nonce -> Nonce

min :: Nonce -> Nonce -> Nonce

IsNonce Nonce

Methods

zero :: Nonce

nudge :: Nonce -> Nonce

IsEncoding Nonce

Methods

encode :: Nonce -> ByteString

decode :: ByteString -> Maybe Nonce

encoded :: (Choice p, Applicative f) => p Nonce (f Nonce) -> p ByteString (f ByteString)

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 public 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.

boxSeal :: PublicKey -> ByteString -> IO ByteString

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

boxSealOpen

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.