HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulelibsodium-bindings-0.0.1.1Haskell2010

LibSodium.Bindings.CryptoBox

  • 17 values

Introduction

0 declarations

Using public-key authenticated encryption, Alice can encrypt a confidential message specifically for Bob, using Bob's public key.

Based on Bob's public key, Alice can compute a shared secret key. Using Alice's public key and his secret key, Bob can compute the same shared secret key. That shared secret key can be used to verify that the encrypted message was not tampered with before decryption.

To send messages to Bob, Alice only needs Bob's public key. Bob should never share his secret key, even with Alice.

For verification and decryption, Bob only needs Alice's public key, the nonce, and the ciphertext. Alice should never share her secret key either, even with Bob.

Bob can reply to Alice using the same system without needing to generate a distinct key pair.

The nonce doesn't have to be confidential, but it should be used with just one invocation of cryptoBoxEasy for a particular pair of public and secret keys.

One easy way to generate a nonce is to use randombytesBuf. Considering the size of the nonce, the risk of a random collision is negligible.

For some applications, if you wish to use nonces to detect missing messages or to ignore replayed messages, it is also acceptable to use a simple incrementing counter as a nonce. However, you must ensure that the same value is never reused. Be careful as you may have multiple threads or even hosts generating messages using the same key pairs. A better alternative is to use the LibSodium.Bindings.SecretStream API.

As stated above, senders can decrypt their own messages and compute a valid authentication tag for any messages encrypted with a given shared secret key. This is generally not an issue for online protocols. If this is not acceptable, then check out the Sealed Boxes and Key Exchange sections of the documentation.

Usage

0 declarations

There are three families of APIs exposed:

  1. Combined Mode: It is the most commonly used entry point to this module.

  2. Detached Mode: If you need to store the authentication tag and encrypted message at different locations

  3. Precalculation Interface: Applications that send several messages to the same recipient or receive several messages from the same sender can improve performance by calculating the shared key only once and reusing it in subsequent operations.

Functions

0 declarations

Key Pair Generation

Combined Mode

valuecryptoBoxEasy
  1. :: Ptr CUChar

    Buffer that will hold the encrypted message, of size cryptoBoxMACBytes + messageLength.

  2. -> Ptr CUChar

    Buffer that holds the message to be encrypted

  3. -> CULLong

    Length of the message in bytes (messageLength)

  4. -> Ptr CUChar

    Nonce, that should be of size cryptoBoxNonceBytes

  5. -> Ptr CUChar

    Buffer that holds the public key, of size cryptoBoxPublicKeyBytes

  6. -> Ptr CUChar

    Buffer that holds the secret key, of size cryptoBoxSecretKeyBytes

  7. -> IO CInt

    The function returns 0 on success and -1 if something fails.

#

Encrypt a message using the public key of the recipient, the secret key of the sender and a cryptographic nonce.

The pointers to the buffers containing the message to encrypt and the combination of authentication tag and encrypted message can overlap, making in-place encryption possible. However do not forget that cryptoBoxMACBytes extra bytes are required to prepend the tag.

See: crypto_box_easy()

valuecryptoBoxOpenEasy
  1. :: Ptr CUChar

    Buffer that will hold the decrypted message

  2. -> Ptr CUChar

    Buffer that holds the authentication tag and encrypted message combination produced by cryptoBoxEasy.

  3. -> CULLong

    Length of the authentication tag and encrypted message combination, which is cryptoBoxMACBytes + length of the message

  4. -> Ptr CUChar

    Nonce, that should be at least of size cryptoBoxNonceBytes. It must match the nonce used by cryptoBoxEasy.

  5. -> Ptr CUChar

    Buffer that holds the recipient's public key, of size cryptoBoxPublicKeyBytes

  6. -> Ptr CUChar

    Buffer that holds the sender's secret key, of size cryptoBoxSecretKeyBytes

  7. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Verify and decrypt a cyphertext produced by cryptoBoxEasy. The first argument is a pointer to a combination of authentication tag and message as produced by cryptoBoxEasy.

The pointers to the buffers containing the plaintext message and the combination of authentication tag and encrypted message can overlap, making in-place decryption possible.

See: crypto_box_open_easy()

Detached Mode

valuecryptoBoxDetached
  1. :: Ptr CUChar

    Buffer that will hold the encrypted message.

  2. -> Ptr CUChar

    Buffer that will hold the authentication tag, of size cryptoBoxMACBytes

  3. -> Ptr CUChar

    Buffer that holds the message to be encrypted.

  4. -> CULLong

    Length of the message to be encrypted.

  5. -> Ptr CUChar

    Nonce, that should be of size cryptoBoxNonceBytes. It must match the nonce used by cryptoBoxEasy.

  6. -> Ptr CUChar

    Buffer that holds the public key, of size cryptoBoxPublicKeyBytes

  7. -> Ptr CUChar

    Buffer that holds the secret key, of size cryptoBoxSecretKeyBytes

  8. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Encrypt a message in the same way as cryptoBoxEasy with the the authentication tag and the encrypted message held in separate buffers.

See: crypto_box_detached()

valuecryptoBoxOpenDetached
  1. :: Ptr CUChar

    Buffer that will hold the plaintext message

  2. -> Ptr CUChar

    Buffer that holds the encrypted message

  3. -> Ptr CUChar

    Buffer that will hold the authentication tag, of size cryptoBoxMACBytes

  4. -> CULLong

    Length of the plaintext message

  5. -> Ptr CUChar

    Nonce, that should be at least of size cryptoBoxNonceBytes.

  6. -> Ptr CUChar

    Buffer that holds the public key, of size cryptoBoxPublicKeyBytes

  7. -> Ptr CUChar

    Buffer that holds the secret key, of size cryptoBoxSecretKeyBytes

  8. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Decrypt a message in the same way as cryptoBoxEasy with the the authentication tag and the encrypted message held in separate buffers.

See: crypto_box_open_detached()

Precalculation Interface

valuecryptoBoxEasyAfterNM
  1. :: Ptr CUChar

    Buffer that will holds the encrypted message.

  2. -> Ptr CUChar

    Buffer that holds the plaintext message.

  3. -> CULLong

    Length of the plaintext message

  4. -> Ptr CUChar

    Nonce, that should of size cryptoBoxNonceBytes.

  5. -> Ptr CUChar

    Precalculated shared secret key (created by cryptoBoxBeforeNM).

  6. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Encrypt a message using the public key of the recipient, a cryptographic nonce and a shared secret key.

See: crypto_box_easy_afternm()

valuecryptoBoxOpenEasyAfterNM
  1. :: Ptr CUChar

    Buffer that will hold the decrypted plaintext message.

  2. -> Ptr CUChar

    Buffer that holds the encrypted message.

  3. -> CULLong

    Length of the plaintext message

  4. -> Ptr CUChar

    Nonce, that should be at least of size cryptoBoxNonceBytes.

  5. -> Ptr CUChar

    Precalculated shared secret key (created by cryptoBoxBeforeNM).

  6. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Decrypt a message using the public key of the recipient, a cryptographic nonce and a shared secret key.

See: crypto_box_open_easy_afternm()

valuecryptoBoxDetachedAfterNM
  1. :: Ptr CUChar

    Buffer that will hold the encrypted message.

  2. -> Ptr CUChar

    Buffer that will hold the authentication tag, of size cryptoBoxMACBytes

  3. -> Ptr CUChar

    Buffer that holds the plaintext message.

  4. -> CULLong

    Length of the plaintext message

  5. -> Ptr CUChar

    Nonce, that should be at least of size cryptoBoxNonceBytes.

  6. -> Ptr CUChar

    Precalculated shared secret key (created by cryptoBoxBeforeNM).

  7. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Encrypt a message in the same way as cryptoBoxDetached with the the authentication tag and the encrypted message held in separate buffers, with the difference that a precalculated, shared secret key is used instead of a public/secret key pair.

See: crypto_box_detached_afternm()

valuecryptoBoxOpenDetachedAfterNM
  1. :: Ptr CUChar

    Buffer that will hold the decrypted plaintext message.

  2. -> Ptr CUChar

    Buffer that holds the encrypted message.

  3. -> Ptr CUChar

    Buffer that holds the authentication tag, of size cryptoBoxMACBytes

  4. -> CULLong

    Length of the plaintext message

  5. -> Ptr CUChar

    Nonce, that should be at least of size cryptoBoxNonceBytes.

  6. -> Ptr CUChar

    Precalculated shared secret key (created by cryptoBoxBeforeNM).

  7. -> IO CInt

    The function returns -1 if the verification fails and 0 on success

#

Decrypt a message using the public key of the recipient, a cryptographic nonce and a shared secret key.

See: crypto_box_open_detached_afternm()

Constants

6 declarations