NaCl-0.0.4.0: Easy-and-safe-to-use high-level Haskell bindings to NaCl
Safe HaskellNone
LanguageHaskell2010

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

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