Safe Haskell | None |
---|---|

Language | Haskell2010 |

## Synopsis

- type Key a = SizedByteArray CRYPTO_SECRETBOX_KEYBYTES a
- toKey :: ByteArrayAccess ba => ba -> Maybe (Key ba)
- type Nonce a = SizedByteArray CRYPTO_SECRETBOX_NONCEBYTES a
- toNonce :: ByteArrayAccess ba => ba -> Maybe (Nonce ba)
- create :: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes) => Key keyBytes -> Nonce nonceBytes -> ptBytes -> ctBytes
- open :: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes) => Key keyBytes -> Nonce nonceBytes -> ctBytes -> Maybe ptBytes

# Documentation

type Key a = SizedByteArray CRYPTO_SECRETBOX_KEYBYTES a Source #

Encryption key that can be used for Secretbox.

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`

.

toKey :: ByteArrayAccess ba => ba -> Maybe (Key ba) Source #

Make a `Key`

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 key with a Secretbox.

type Nonce a = SizedByteArray CRYPTO_SECRETBOX_NONCEBYTES a Source #

Nonce that can be used for Secretbox.

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 Secretbox.

:: (ByteArrayAccess keyBytes, ByteArrayAccess nonceBytes, ByteArrayAccess ptBytes, ByteArray ctBytes) | |

=> Key keyBytes | Secret key |

-> Nonce nonceBytes | Nonce |

-> ptBytes | Plaintext message |

-> ctBytes |

Encrypt a message.

encrypted = Secretbox.create key nonce message

`key`

is the secret key used for encryption. There are two typical ways of creating it:*Derive from a password*. If you want to protect a message with a password, you must use a key derivation function to turn this password into an encryption key.*Generate a random one*. This can be useful in certain situations when you want to have an intermediate key that you will encrypt and share later.

The

`Crypto.Sodium.Key`

module in crypto-sodium has functions to help in either case.`nonce`

is an extra noise that is required for security. There are two standard ways of getting it:*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.*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.Sodium.Random`

, in crypto-sodium.

In either case, you need to be able to provide the same nonce when decrypting, so you should be able to recover it by computation (e.g. in the case of a counter) or you should store it alongside the encrypted data. The nonce is not secret, so it is perfectly ok to store it in plaintext.

`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 keyBytes, ByteArrayAccess nonceBytes, ByteArray ptBytes, ByteArrayAccess ctBytes) | |

=> Key keyBytes | Secret key |

-> Nonce nonceBytes | Nonce |

-> ctBytes | Encrypted message (cyphertext) |

-> Maybe ptBytes |

Decrypt a message.

decrypted = Secretbox.open key nonce encrypted

`key`

and`nonce`

are the same that were 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.