Copyright	(C) Hécate Moonlight 2022
License	BSD-3-Clause
Maintainer	The Haskell Cryptography Group
Portability	GHC only
Safe Haskell	Safe-Inferred
Language	Haskell2010

Sel.SecretKey.Cipher

Contents

Introduction
Usage
Encryption and Decryption
Secret Key
Nonce
Hash

Description

Synopsis

encrypt :: StrictByteString -> SecretKey -> IO (Nonce, Hash)
decrypt :: Hash -> SecretKey -> Nonce -> Maybe StrictByteString
data SecretKey
newSecretKey :: IO SecretKey
secretKeyFromHexByteString :: StrictByteString -> Either Text SecretKey
unsafeSecretKeyToHexByteString :: SecretKey -> StrictByteString
data Nonce
nonceFromHexByteString :: StrictByteString -> Either Text Nonce
nonceToHexByteString :: Nonce -> StrictByteString
data Hash
hashFromHexByteString :: StrictByteString -> Either Text Hash
hashToBinary :: Hash -> StrictByteString
hashToHexByteString :: Hash -> StrictByteString
hashToHexText :: Hash -> Text

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

main = 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 Source #

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 Source #

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 Source #

A secret key of size cryptoSecretboxKeyBytes.

Since: 0.0.1.0

Instances

Instances details

Show SecretKey Source #	show secretKey == "[REDACTED]" Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods showsPrec :: Int -> SecretKey -> ShowS # show :: SecretKey -> String # showList :: [SecretKey] -> ShowS #
Eq SecretKey Source #	Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods (==) :: SecretKey -> SecretKey -> Bool # (/=) :: SecretKey -> SecretKey -> Bool #
Ord SecretKey Source #	Since: 0.0.1.0
Instance details 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 Source #	display secretKey == "[REDACTED]" Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods displayBuilder :: SecretKey -> Builder # displayList :: [SecretKey] -> Builder # displayPrec :: Int -> SecretKey -> Builder #

newSecretKey :: IO SecretKey Source #

Generate a new random secret key.

Since: 0.0.1.0

secretKeyFromHexByteString :: StrictByteString -> Either Text SecretKey Source #

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 Source #

Convert a SecretKey to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

Nonce

data Nonce Source #

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

Instances details

Show Nonce Source #	Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods showsPrec :: Int -> Nonce -> ShowS # show :: Nonce -> String # showList :: [Nonce] -> ShowS #
Eq Nonce Source #	Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods (==) :: Nonce -> Nonce -> Bool # (/=) :: Nonce -> Nonce -> Bool #
Ord Nonce Source #	Since: 0.0.1.0
Instance details 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 Source #	Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods displayBuilder :: Nonce -> Builder # displayList :: [Nonce] -> Builder # displayPrec :: Int -> Nonce -> Builder #

nonceFromHexByteString :: StrictByteString -> Either Text Nonce Source #

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 Source #

Convert a Nonce to a hexadecimal-encoded StrictByteString.

Since: 0.0.1.0

Hash

data Hash Source #

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

Since: 0.0.1.0

Instances

Instances details

Show Hash Source #	⚠️ Be prudent as to what you do with it! Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods showsPrec :: Int -> Hash -> ShowS # show :: Hash -> String # showList :: [Hash] -> ShowS #
Eq Hash Source #	Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods (==) :: Hash -> Hash -> Bool # (/=) :: Hash -> Hash -> Bool #
Ord Hash Source #	Since: 0.0.1.0
Instance details 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 Source #	⚠️ Be prudent as to what you do with it! Since: 0.0.1.0
Instance details Defined in Sel.SecretKey.Cipher Methods displayBuilder :: Hash -> Builder # displayList :: [Hash] -> Builder # displayPrec :: Int -> Hash -> Builder #

hashFromHexByteString :: StrictByteString -> Either Text Hash Source #

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 Source #

Convert a Hash to a binary StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

hashToHexByteString :: Hash -> StrictByteString Source #

Convert a Hash to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

hashToHexText :: Hash -> Text Source #

Convert a Hash to a hexadecimal-encoded Text.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0