NaCl.Box

Public-key authenticated encryption.

It is best to import this module qualified:

import qualified NaCl.Box as Box

encrypted = Box.create pk sk nonce message
decrypted = Box.open pk sk nonce encrypted

This is crypto_box_* from NaCl.

Documentation

type PublicKey a = SizedByteArray CRYPTO_BOX_PUBLICKEYBYTES a

Public key that can be used for Box.

This type is parametrised by the actual data type that contains bytes. This can be, for example, a ByteString.

toPublicKey :: ByteArrayAccess bytes => bytes -> Maybe (PublicKey bytes)

Convert bytes to a public key.

type SecretKey a = SizedByteArray CRYPTO_BOX_SECRETKEYBYTES a

Secret key that can be used for Box.

This type is parametrised by the actual data type that contains bytes. This can be, for example, a ByteString, but, since this is a secret key, it is better to use ScrubbedBytes.

toSecretKey :: ByteArrayAccess bytes => bytes -> Maybe (SecretKey bytes)

Convert bytes to a secret key.

keypair :: IO (PublicKey ByteString, SecretKey ScrubbedBytes)

Generate a new SecretKey together with its PublicKey.

Note: this function is not thread-safe (since the underlying C function is not thread-safe both in Sodium and in NaCl)! Either make sure there are no concurrent calls or see Crypto.Init in crypto-sodium to learn how to make this function thread-safe.

type Nonce a = SizedByteArray CRYPTO_BOX_NONCEBYTES a

Nonce that can be used for Box.

This type is parametrised by the actual data type that contains bytes. This can be, for example, a ByteString.

toNonce :: ByteArrayAccess ba => ba -> Maybe (Nonce ba)

Make a Nonce from an arbitrary byte array.

This function returns Just if and only if the byte array has the right length to be used as a nonce with a Box.

create

Arguments

:: (ByteArrayAccess pkBytes, ByteArrayAccess skBytes, ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes)

=> PublicKey pkBytes

Receiver’s public key

-> SecretKey skBytes

Sender’s secret key

-> Nonce nonceBytes

Nonce

-> ptBytes

Plaintext message

-> ctBytes

Encrypt a message.

encrypted = Box.create pk sk nonce message

• pk is the receiver’s public key, used for encryption. sk is the sender’s secret key, used for authentication.

  These are generated using keypair and are supposed to be exchanged in advance. Both parties need to know their own secret key and the other’s public key.

• nonce is an extra noise that ensures that if you encrypt the same message with the same key multiple times, you will get different ciphertexts, which is required for semantic security. There are two standard ways of getting it:

  1. Use a counter. In this case you keep a counter of encrypted messages, which means that the nonce will be new for each new message.
  2. Random. You generate a random nonce every time you encrypt a message. Since the nonce is large enough, the chances of you using the same nonce twice are negligible. For useful helpers, see Crypto.Random, in crypto-sodium.

  In either case, you need to be able to provide the same nonce when decrypting, so you should be able to recover it by computation (e.g. in the case of a counter) or you should store it alongside the encrypted data. The nonce is not secret, so it is perfectly ok to store it in plaintext.

• message is the data you are encrypting.

This function adds authentication data, so if anyone modifies the cyphertext, open will refuse to decrypt it.

open

Arguments

:: (ByteArrayAccess skBytes, ByteArrayAccess pkBytes, ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes)

=> SecretKey skBytes

Receiver’s secret key

-> PublicKey pkBytes

Sender’s public key

-> Nonce nonceBytes

Nonce

-> ctBytes

Encrypted message (cyphertext)

-> Maybe ptBytes

Decrypt a message.

decrypted = Box.open sk pk nonce encrypted

• sk is the receiver’s secret key, used for description.
• pk is the sender’s public key, used for authentication.
• nonce is the same that was used for encryption.
• encrypted is the output of create.

This function will return Nothing if the encrypted message was tampered with after it was encrypted.