Safe Haskell	None
Language	Haskell2010

Crypto.Box

Description

Public-key authenticated encryption.

It is best to import this module qualified:

import qualified Crypto.Box as Box

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

This is crypto_box_* from NaCl.

Synopsis

type PublicKey = SizedByteArray CRYPTO_BOX_PUBLICKEYBYTES ByteString
toPublicKey :: ByteString -> Maybe PublicKey
type SecretKey = SizedByteArray CRYPTO_BOX_SECRETKEYBYTES ScrubbedBytes
toSecretKey :: ScrubbedBytes -> Maybe SecretKey
keypair :: IO (PublicKey, SecretKey)
type Nonce a = SizedByteArray CRYPTO_BOX_NONCEBYTES a
toNonce :: ByteArrayAccess ba => ba -> Maybe (Nonce ba)
create :: (ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes) => PublicKey -> SecretKey -> Nonce nonceBytes -> ptBytes -> ctBytes
open :: (ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes) => SecretKey -> PublicKey -> Nonce nonceBytes -> ctBytes -> Maybe ptBytes

Documentation

type PublicKey = SizedByteArray CRYPTO_BOX_PUBLICKEYBYTES ByteString Source #

Public key that can be used for Box.

toPublicKey :: ByteString -> Maybe PublicKey Source #

type SecretKey = SizedByteArray CRYPTO_BOX_SECRETKEYBYTES ScrubbedBytes Source #

Secret key that can be used for Box.

toSecretKey :: ScrubbedBytes -> Maybe SecretKey Source #

Convert bytes to a secret key.

keypair :: IO (PublicKey, SecretKey) Source #

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

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

create Source #

Arguments

:: (ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes)
=> PublicKey	Receiver’s public key
-> SecretKey	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 public 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.
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 nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes)
=> SecretKey	Receiver’s secret key
-> PublicKey	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.