Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
- 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
Keys
type PublicKey = SizedByteArray CRYPTO_BOX_PUBLICKEYBYTES ByteString #
Public key that can be used for Box.
toPublicKey :: ByteString -> Maybe PublicKey #
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
:: (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.
:: (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 ofcreate
.
This function will return Nothing
if the encrypted message was tampered
with after it was encrypted.