Sel.SecretKey.Cipher

Introduction

"Authenticated Encryption" uses a secret key along with a single-use number called a "nonce" to encrypt a message. The resulting hash is accompanied by an authentication tag.

Encryption is done with the XSalsa20 stream cipher and authentication is done with the Poly1305 MAC hash.

Usage

import qualified Sel.SecretKey.Cipher as Cipher
import Sel (secureMain)

main = secureMain $ do
  -- We get the secretKey from the other party or with 'newSecretKey'.
  -- We get the nonce from the other party with the message, or with 'encrypt' and our own message.
  -- Do not reuse a nonce with the same secret key!
  (nonce, encryptedMessage) <- Cipher.encrypt "hello hello" secretKey
  let result = Cipher.decrypt encryptedMessage secretKey nonce
  print result
  -- "Just \"hello hello\""

Encryption and Decryption

encrypt

Arguments

:: StrictByteString

Message to encrypt.

-> SecretKey

Secret key generated with newSecretKey.

-> IO (Nonce, Hash)

Create an authenticated hash from a message, a secret key, and a one-time cryptographic nonce that must never be re-used with the same secret key to encrypt another message.

Since: 0.0.1.0

decrypt

Arguments

:: Hash

Encrypted message you want to decrypt.

-> SecretKey

Secret key used for encrypting the original message.

-> Nonce

Nonce used for encrypting the original message.

-> Maybe StrictByteString

Decrypt a hashed and authenticated message with the shared secret key and the one-time cryptographic nonce.

Since: 0.0.1.0

Secret Key

data SecretKey

A secret key of size cryptoSecretboxKeyBytes.

Since: 0.0.1.0

Instances

Show SecretKey

show secretKey == "[REDACTED]"

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

showsPrec :: Int -> SecretKey -> ShowS

show :: SecretKey -> String

showList :: [SecretKey] -> ShowS

Eq SecretKey

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

(==) :: SecretKey -> SecretKey -> Bool

(/=) :: SecretKey -> SecretKey -> Bool

Ord SecretKey

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

compare :: SecretKey -> SecretKey -> Ordering

(<) :: SecretKey -> SecretKey -> Bool

(<=) :: SecretKey -> SecretKey -> Bool

(>) :: SecretKey -> SecretKey -> Bool

(>=) :: SecretKey -> SecretKey -> Bool

max :: SecretKey -> SecretKey -> SecretKey

min :: SecretKey -> SecretKey -> SecretKey

Display SecretKey

display secretKey == "[REDACTED]"

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

displayBuilder :: SecretKey -> Builder

displayList :: [SecretKey] -> Builder

displayPrec :: Int -> SecretKey -> Builder

newSecretKey :: IO SecretKey

Generate a new random secret key.

Since: 0.0.1.0

secretKeyFromHexByteString :: StrictByteString -> Either Text SecretKey

Create a SecretKey from a binary StrictByteString that you have obtained on your own, usually from the network or disk.

The input secret key, once decoded from base16, must be of length cryptoSecretboxKeyBytes.

Since: 0.0.1.0

unsafeSecretKeyToHexByteString :: SecretKey -> StrictByteString

Convert a SecretKey to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

Nonce

data Nonce

A random number that must only be used once per exchanged message. It does not have to be confidential. It is of size cryptoSecretboxNonceBytes.

Since: 0.0.1.0

Instances

Show Nonce

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

showsPrec :: Int -> Nonce -> ShowS

show :: Nonce -> String

showList :: [Nonce] -> ShowS

Eq Nonce

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

(==) :: Nonce -> Nonce -> Bool

(/=) :: Nonce -> Nonce -> Bool

Ord Nonce

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

compare :: Nonce -> Nonce -> Ordering

(<) :: Nonce -> Nonce -> Bool

(<=) :: Nonce -> Nonce -> Bool

(>) :: Nonce -> Nonce -> Bool

(>=) :: Nonce -> Nonce -> Bool

max :: Nonce -> Nonce -> Nonce

min :: Nonce -> Nonce -> Nonce

Display Nonce

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

displayBuilder :: Nonce -> Builder

displayList :: [Nonce] -> Builder

displayPrec :: Int -> Nonce -> Builder

nonceFromHexByteString :: StrictByteString -> Either Text Nonce

Create a Nonce from a binary StrictByteString that you have obtained on your own, usually from the network or disk. Once decoded from hexadecimal, it must be of length cryptoSecretboxNonceBytes.

Since: 0.0.1.0

nonceToHexByteString :: Nonce -> StrictByteString

Convert a Nonce to a hexadecimal-encoded StrictByteString.

Since: 0.0.1.0

Hash

data Hash

A ciphertext consisting of an encrypted message and an authentication tag.

Since: 0.0.1.0

Instances

Show Hash

⚠️ Be prudent as to what you do with it!

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

showsPrec :: Int -> Hash -> ShowS

show :: Hash -> String

showList :: [Hash] -> ShowS

Eq Hash

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

(==) :: Hash -> Hash -> Bool

(/=) :: Hash -> Hash -> Bool

Ord Hash

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

compare :: Hash -> Hash -> Ordering

(<) :: Hash -> Hash -> Bool

(<=) :: Hash -> Hash -> Bool

(>) :: Hash -> Hash -> Bool

(>=) :: Hash -> Hash -> Bool

max :: Hash -> Hash -> Hash

min :: Hash -> Hash -> Hash

Display Hash

⚠️ Be prudent as to what you do with it!

Since: 0.0.1.0

Defined in Sel.SecretKey.Cipher

Methods

displayBuilder :: Hash -> Builder

displayList :: [Hash] -> Builder

displayPrec :: Int -> Hash -> Builder

hashFromHexByteString :: StrictByteString -> Either Text Hash

Create a Hash from a binary StrictByteString that you have obtained on your own, usually from the network or disk. It must be a valid hash built from the concatenation of the encrypted message and the authentication tag.

The input hash must at least of length cryptoSecretboxMACBytes

Since: 0.0.1.0

hashToBinary :: Hash -> StrictByteString

Convert a Hash to a binary StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

hashToHexByteString :: Hash -> StrictByteString

Convert a Hash to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

hashToHexText :: Hash -> Text

Convert a Hash to a hexadecimal-encoded Text.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0