Crypto.Sodium.Encrypt.Public

Public-key authenticated encryption.

It is best to import this module qualified:

import qualified Crypto.Sodium.Encrypt.Public as Public

encrypted = Public.encrypt pk sk nonce message
decrypted = Public.decrypt pk sk nonce encrypted

A box is an abstraction from NaCl. One way to think about it is to imagine that you are putting data into a box protected by the receiver’s public key and signed by your private key. The receive will then be able to “open” it using their private key and your public key.

Note that this means that you need to exchange your public keys in advance. It might seem strange at first that the receiver needs to know your public key too, but this is actually very important as otherwise the receiver would not be able to have any guarantees regarding the source or the integrity of the data.

Keys

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.

keypairFromSeed :: ByteArrayAccess seed => Seed seed -> IO (PublicKey ByteString, SecretKey ScrubbedBytes)

Generate a new SecretKey together with its PublicKey from a given seed.

unsafeKeypairFromSeed :: ByteArrayAccess seed => Seed seed -> (PublicKey ByteString, SecretKey ScrubbedBytes)

Generate a new SecretKey together with its PublicKey from a given seed, in a pure context.

Nonce

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.

Encryption/decryption

encrypt

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 = Public.encrypt 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 is required for security. See Crypto.Sodium.Nonce for how to work with it.
• message is the data you are encrypting.

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

decrypt

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 = Public.decrypt sk pk nonce encrypted

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

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