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.PublicKey.Cipher

Contents

Introduction
Usage
Key pair generation
Nonce
Cipher text
Encryption and Decryption
Errors

Description

Synopsis

newKeyPair :: IO (PublicKey, SecretKey)
newtype SecretKey = SecretKey (ForeignPtr CUChar)
unsafeSecretKeyToHexByteString :: SecretKey -> StrictByteString
newtype PublicKey = PublicKey (ForeignPtr CUChar)
publicKeyToHexByteString :: PublicKey -> StrictByteString
keyPairFromHexByteStrings :: StrictByteString -> StrictByteString -> Either Text (PublicKey, SecretKey)
newtype Nonce = Nonce (ForeignPtr CUChar)
nonceFromHexByteString :: StrictByteString -> Either Text Nonce
nonceToHexByteString :: Nonce -> StrictByteString
data CipherText = CipherText {
- messageLength :: CULLong
- cipherTextForeignPtr :: ForeignPtr CUChar
}
cipherTextFromHexByteString :: StrictByteString -> Either Text CipherText
cipherTextToHexText :: CipherText -> Text
cipherTextToHexByteString :: CipherText -> StrictByteString
cipherTextToBinary :: CipherText -> StrictByteString
encrypt :: StrictByteString -> PublicKey -> SecretKey -> IO (Nonce, CipherText)
decrypt :: CipherText -> PublicKey -> SecretKey -> Nonce -> Maybe StrictByteString
data KeyPairGenerationException = KeyPairGenerationException
data EncryptionError = EncryptionError

Introduction

Public-key authenticated encryption allows a sender to encrypt a confidential message specifically for the recipient, using the recipient's public key.

Usage

import qualified Sel.PublicKey.Cipher as Cipher

main = do
  -- We get the sender their pair of keys:
  (senderSecretKey, senderPublicKey) <- newKeyPair
  -- We get the nonce from the other party with the message, or with 'encrypt' and our own message.
  (nonce, encryptedMessage) <- Cipher.encrypt "hello hello" secretKey
  let result = Cipher.decrypt encryptedMessage secretKey nonce
  print result
  -- "Just \"hello hello\""

Key pair generation

newKeyPair :: IO (PublicKey, SecretKey) Source #

Generate a new random secret key.

May throw KeyPairGenerationException if the generation fails.

Since: 0.0.1.0

newtype SecretKey Source #

A secret key of size cryptoBoxSecretKeyBytes.

Since: 0.0.1.0

Constructors

SecretKey (ForeignPtr CUChar)

Instances

Instances details

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

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

newtype PublicKey Source #

A public key of size cryptoBoxPublicKeyBytes.

Since: 0.0.1.0

Constructors

PublicKey (ForeignPtr CUChar)

Instances

Instances details

Show PublicKey Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods showsPrec :: Int -> PublicKey -> ShowS # show :: PublicKey -> String # showList :: [PublicKey] -> ShowS #
Eq PublicKey Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods (==) :: PublicKey -> PublicKey -> Bool # (/=) :: PublicKey -> PublicKey -> Bool #
Ord PublicKey Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods compare :: PublicKey -> PublicKey -> Ordering # (<) :: PublicKey -> PublicKey -> Bool # (<=) :: PublicKey -> PublicKey -> Bool # (>) :: PublicKey -> PublicKey -> Bool # (>=) :: PublicKey -> PublicKey -> Bool # max :: PublicKey -> PublicKey -> PublicKey # min :: PublicKey -> PublicKey -> PublicKey #
Display PublicKey Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods displayBuilder :: PublicKey -> Builder # displayList :: [PublicKey] -> Builder # displayPrec :: Int -> PublicKey -> Builder #

publicKeyToHexByteString :: PublicKey -> StrictByteString Source #

Convert a PublicKey to a hexadecimal-encoded StrictByteString.

Since: 0.0.1.0

keyPairFromHexByteStrings Source #

Arguments

:: StrictByteString	Public key
-> StrictByteString	Secret key
-> Either Text (PublicKey, SecretKey)

Create a pair of SecretKey and PublicKey from hexadecimal-encoded StrictByteStrings that you have obtained on your own, usually from the network or disk.

The public and secret keys, once decoded from base16, must respectively be at least of length cryptoBoxPublicKeyBytes and 'cryptoBoxSecretKeyBytes.

Since: 0.0.1.0

Nonce

newtype Nonce Source #

Convert a SecretKey to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

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

Since: 0.0.1.0

Constructors

Nonce (ForeignPtr CUChar)

Instances

Instances details

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

nonceFromHexByteString :: StrictByteString -> Either Text Nonce Source #

Create a Nonce from a hexadecimal-encoded StrictByteString that you have obtained on your own, usually from the network or disk.

Since: 0.0.1.0

nonceToHexByteString :: Nonce -> StrictByteString Source #

Convert a Nonce to a hexadecimal-encoded StrictByteString.

Since: 0.0.1.0

Cipher text

data CipherText Source #

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

Since: 0.0.1.0

Constructors

CipherText
Fields messageLength :: CULLong cipherTextForeignPtr :: ForeignPtr CUChar

Instances

Instances details

Show CipherText Source #	⚠️ Be prudent as to what you do with it! Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods showsPrec :: Int -> CipherText -> ShowS # show :: CipherText -> String # showList :: [CipherText] -> ShowS #
Eq CipherText Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods (==) :: CipherText -> CipherText -> Bool # (/=) :: CipherText -> CipherText -> Bool #
Ord CipherText Source #	Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods compare :: CipherText -> CipherText -> Ordering # (<) :: CipherText -> CipherText -> Bool # (<=) :: CipherText -> CipherText -> Bool # (>) :: CipherText -> CipherText -> Bool # (>=) :: CipherText -> CipherText -> Bool # max :: CipherText -> CipherText -> CipherText # min :: CipherText -> CipherText -> CipherText #
Display CipherText Source #	⚠️ Be prudent as to what you do with it! Since: 0.0.1.0
Instance details Defined in Sel.PublicKey.Cipher Methods displayBuilder :: CipherText -> Builder # displayList :: [CipherText] -> Builder # displayPrec :: Int -> CipherText -> Builder #

cipherTextFromHexByteString :: StrictByteString -> Either Text CipherText Source #

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

The input cipher text, once decoded from base16, must be at least of length cryptoBoxMACBytes.

Since: 0.0.1.0

cipherTextToHexText :: CipherText -> Text Source #

Convert a CipherText to a hexadecimal-encoded Text.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

cipherTextToHexByteString :: CipherText -> StrictByteString Source #

Convert a CipherText to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

cipherTextToBinary :: CipherText -> StrictByteString Source #

Convert a CipherText to a binary StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

Encryption and Decryption

encrypt Source #

Arguments

:: StrictByteString	Message to encrypt.
-> PublicKey	Public key of the recipient
-> SecretKey	Secret key of the sender
-> IO (Nonce, CipherText)

Create an authenticated CipherText from a message, a SecretKey, 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

:: CipherText	Encrypted message you want to decrypt.
-> PublicKey	Public key of the sender.
-> SecretKey	Secret key of the recipient.
-> Nonce	Nonce used for encrypting the original message.
-> Maybe StrictByteString

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

Since: 0.0.1.0

Errors

data KeyPairGenerationException Source #

Exception thrown upon error during the generation of the key pair by newKeyPair.

Since: 0.0.1.0

Constructors

KeyPairGenerationException

Instances

Instances details

Exception KeyPairGenerationException Source #
Instance details Defined in Sel.PublicKey.Cipher Methods toException :: KeyPairGenerationException -> SomeException # fromException :: SomeException -> Maybe KeyPairGenerationException # displayException :: KeyPairGenerationException -> String #
Show KeyPairGenerationException Source #
Instance details Defined in Sel.PublicKey.Cipher Methods showsPrec :: Int -> KeyPairGenerationException -> ShowS # show :: KeyPairGenerationException -> String # showList :: [KeyPairGenerationException] -> ShowS #
Eq KeyPairGenerationException Source #
Instance details Defined in Sel.PublicKey.Cipher Methods (==) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool # (/=) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool #
Ord KeyPairGenerationException Source #
Instance details Defined in Sel.PublicKey.Cipher Methods compare :: KeyPairGenerationException -> KeyPairGenerationException -> Ordering # (<) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool # (<=) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool # (>) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool # (>=) :: KeyPairGenerationException -> KeyPairGenerationException -> Bool # max :: KeyPairGenerationException -> KeyPairGenerationException -> KeyPairGenerationException # min :: KeyPairGenerationException -> KeyPairGenerationException -> KeyPairGenerationException #

data EncryptionError Source #

Exception thrown upon error during the encryption of the message by encrypt.

Since: 0.0.1.0

Constructors

EncryptionError

Instances

Instances details

Exception EncryptionError Source #
Instance details Defined in Sel.PublicKey.Cipher Methods toException :: EncryptionError -> SomeException # fromException :: SomeException -> Maybe EncryptionError # displayException :: EncryptionError -> String #
Show EncryptionError Source #
Instance details Defined in Sel.PublicKey.Cipher Methods showsPrec :: Int -> EncryptionError -> ShowS # show :: EncryptionError -> String # showList :: [EncryptionError] -> ShowS #
Eq EncryptionError Source #
Instance details Defined in Sel.PublicKey.Cipher Methods (==) :: EncryptionError -> EncryptionError -> Bool # (/=) :: EncryptionError -> EncryptionError -> Bool #
Ord EncryptionError Source #
Instance details Defined in Sel.PublicKey.Cipher Methods compare :: EncryptionError -> EncryptionError -> Ordering # (<) :: EncryptionError -> EncryptionError -> Bool # (<=) :: EncryptionError -> EncryptionError -> Bool # (>) :: EncryptionError -> EncryptionError -> Bool # (>=) :: EncryptionError -> EncryptionError -> Bool # max :: EncryptionError -> EncryptionError -> EncryptionError # min :: EncryptionError -> EncryptionError -> EncryptionError #