Safe Haskell	None
Language	Haskell2010

NaCl.Secretbox

Description

Symmetric authenticated encryption.

It is best to import this module qualified:

import qualified NaCl.Secretbox as Secretbox

encrypted = Secretbox.create key nonce message
decrypted = Secretbox.open key nonce encrypted

This is crypto_secretbox_* from NaCl.

Synopsis

type Key a = SizedByteArray CRYPTO_SECRETBOX_KEYBYTES a
toKey :: ByteArrayAccess ba => ba -> Maybe (Key ba)
type Nonce a = SizedByteArray CRYPTO_SECRETBOX_NONCEBYTES a
toNonce :: ByteArrayAccess ba => ba -> Maybe (Nonce ba)
create :: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes) => Key keyBytes -> Nonce nonceBytes -> ptBytes -> ctBytes
open :: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes) => Key keyBytes -> Nonce nonceBytes -> ctBytes -> Maybe ptBytes

Documentation

type Key a = SizedByteArray CRYPTO_SECRETBOX_KEYBYTES a Source #

Encryption key that can be used for Secretbox.

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.

toKey :: ByteArrayAccess ba => ba -> Maybe (Key ba) Source #

Make a Key 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 key with a Secretbox.

type Nonce a = SizedByteArray CRYPTO_SECRETBOX_NONCEBYTES a Source #

Nonce that can be used for Secretbox.

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

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

create Source #

Arguments

:: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes)
=> Key keyBytes	Secret key
-> Nonce nonceBytes	Nonce
-> ptBytes	Plaintext message
-> ctBytes

Encrypt a message.

encrypted = Secretbox.create key nonce message

key is the secret key used for encryption. There are two typical ways of creating it:
1. Derive from a password. If you want to protect a message with a password, you must use a key derivation function to turn this password into an encryption key.
2. Generate a random one. This can be useful in certain situations when you want to have an intermediate key that you will encrypt and share later.
The Crypto.Sodium.Key module in crypto-sodium has functions to help in either case.
nonce is an extra noise that is required for 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.Sodium.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 Source #

Arguments

:: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes)
=> Key keyBytes	Secret key
-> Nonce nonceBytes	Nonce
-> ctBytes	Encrypted message (cyphertext)
-> Maybe ptBytes

Decrypt a message.

decrypted = Secretbox.open key nonce encrypted

key and nonce are the same that were 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.