crypto-sodium-0.0.3.1: Easy-and-safe-to-use high-level cryptography based on Sodium
Safe HaskellNone
LanguageHaskell2010

Crypto.Encrypt.Box

Description

Public-key authenticated encryption.

It is best to import this module qualified:

import qualified Crypto.Encrypt.Box as Box

encrypted = Box.create pk sk nonce message
decrypted = Box.open 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.

Synopsis

Keys

type PublicKey = SizedByteArray CRYPTO_BOX_PUBLICKEYBYTES ByteString #

Public key that can be used for Box.

toPublicKey :: ByteString -> Maybe PublicKey #

Convert bytes to a public key.

type SecretKey = SizedByteArray CRYPTO_BOX_SECRETKEYBYTES ScrubbedBytes #

Secret key that can be used for Box.

toSecretKey :: ScrubbedBytes -> Maybe SecretKey #

Convert bytes to a secret key.

keypair :: IO (PublicKey, SecretKey) #

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.

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

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 is required for security. See Crypto.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, open will refuse to decrypt it.

open #

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.