Crypto.TripleSec

TripleSec is a simple, triple-paranoid, symmetric encryption library.

https://keybase.io/triplesec/

A tutorial for how to use this library can be found in Crypto.TripleSec.Tutorial

Cipher Type

data TripleSec ba

TripleSec cipher used for encryption and decryption.

Dealing with this type is only necessary if you wish to use the somewhat lower-level API consisting of encryptWithCipher and decryptWithCipher.

You can create a TripleSec cipher with newCipher or newCipherWithSalt.

Standard API

class (CanTripleSecDecrypt m, MonadRandom m) => CanTripleSec m where

Represents the action of encrypting and decrypting with the TripleSec protocol.

Fully implemented with default functions. Any instances must provide a source of randomness and be an instance of CanTripleSecDecrypt.

Minimal complete definition

Nothing

Methods

encrypt

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Plaintext

-> m ba

Ciphertext

Encrypt a plaintext with a passphrase.

 encrypt passphrase plaintext

encryptWithCipher

Arguments

:: ByteArray ba

=> TripleSec ba

-> ba

Plaintext

-> m ba

Encrypt a plaintext with a TripleSec cipher.

This function allows encrypting multiple plaintexts without continually paying for the expensive key-derivation process. Please consider your use case and any risks that come from repeated usage of the same salt for encrypting different pieces of information.

For a simpler alternative, please see encrypt.

newCipher

Arguments

:: ByteArray ba

=> ba

Passphrase

-> m (TripleSec ba)

Create a new TripleSec cipher.

Instances

Monad m => CanTripleSec (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

encrypt :: ByteArray ba => ba -> ba -> TripleSecT m ba

encryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecT m ba

newCipher :: ByteArray ba => ba -> TripleSecT m (TripleSec ba)

MonadIO m => CanTripleSec (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

encrypt :: ByteArray ba => ba -> ba -> TripleSecIOT m ba

encryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecIOT m ba

newCipher :: ByteArray ba => ba -> TripleSecIOT m (TripleSec ba)

class MonadError TripleSecException m => CanTripleSecDecrypt m where

Represents the action of decrypting with the TripleSec protocol.

Fully implemented with default functions. Any instances must provide a way to represent failure with a TripleSecException.

Minimal complete definition

Nothing

Methods

decrypt

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Ciphertext

-> m ba

Plaintext

Decrypt a ciphertext with a passphrase.

 decrypt passphrase ciphertext

decryptWithCipher

Arguments

:: ByteArray ba

=> TripleSec ba

-> ba

Ciphertext

-> m ba

Decrypt a ciphertext with a TripleSec cipher.

This function allows decrypting multiple ciphertexts without continually paying for the expensive key-derivation process. This function will only work if the given cipher's salt matches that of the ciphertext, otherwise it throws a MisMatchedCipherSalt.

For a simpler alternative, please see decrypt.

newCipherWithSalt

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Salt

-> m (TripleSec ba)

Create a new TripleSec cipher with a provided salt.

Creating a cipher with a specific salt is useful if you know you have several ciphertexts to decrypt, all of which were encrypted with the same cipher (salt + passphrase). Creating the cipher once up front allows you to save time, cpu, and memory by avoiding the expensive key-derivation on subsequent decryptions.

 newCipherWithSalt passphrase salt

Instances

Monad m => CanTripleSecDecrypt (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecDecryptT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecDecryptT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecDecryptT m (TripleSec ba)

Monad m => CanTripleSecDecrypt (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecT m (TripleSec ba)

Monad m => CanTripleSecDecrypt (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecIOT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecIOT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecIOT m (TripleSec ba)

Exception Types

data TripleSecException

Exceptions thrown by this library.

Constructors

CipherInitException CipherInitFailure

EncryptionException EncryptionFailure

DecryptionException DecryptionFailure

Instances

Eq TripleSecException

Defined in Crypto.TripleSec.Types

Methods

(==) :: TripleSecException -> TripleSecException -> Bool

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

Show TripleSecException

Defined in Crypto.TripleSec.Types

Methods

showsPrec :: Int -> TripleSecException -> ShowS

show :: TripleSecException -> String

showList :: [TripleSecException] -> ShowS

Exception TripleSecException

Defined in Crypto.TripleSec.Types

Methods

toException :: TripleSecException -> SomeException

fromException :: SomeException -> Maybe TripleSecException

displayException :: TripleSecException -> String

Monad m => MonadError TripleSecException (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

throwError :: TripleSecException -> TripleSecDecryptT m a

catchError :: TripleSecDecryptT m a -> (TripleSecException -> TripleSecDecryptT m a) -> TripleSecDecryptT m a

Monad m => MonadError TripleSecException (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

throwError :: TripleSecException -> TripleSecT m a

catchError :: TripleSecT m a -> (TripleSecException -> TripleSecT m a) -> TripleSecT m a

Monad m => MonadError TripleSecException (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

throwError :: TripleSecException -> TripleSecIOT m a

catchError :: TripleSecIOT m a -> (TripleSecException -> TripleSecIOT m a) -> TripleSecIOT m a

data CipherInitFailure

Possible cipher initialization failures

Constructors

ZeroLengthPassword

InvalidSaltLength

Instances

Eq CipherInitFailure

Defined in Crypto.TripleSec.Types

Methods

(==) :: CipherInitFailure -> CipherInitFailure -> Bool

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

Show CipherInitFailure

Defined in Crypto.TripleSec.Types

Methods

showsPrec :: Int -> CipherInitFailure -> ShowS

show :: CipherInitFailure -> String

showList :: [CipherInitFailure] -> ShowS

data EncryptionFailure

Possible encryption failures

Constructors

ZeroLengthPlaintext

Instances

Eq EncryptionFailure

Defined in Crypto.TripleSec.Types

Methods

(==) :: EncryptionFailure -> EncryptionFailure -> Bool

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

Show EncryptionFailure

Defined in Crypto.TripleSec.Types

Methods

showsPrec :: Int -> EncryptionFailure -> ShowS

show :: EncryptionFailure -> String

showList :: [EncryptionFailure] -> ShowS

data DecryptionFailure

Possible decryption Failures

Constructors

InvalidCipherTextLength

InvalidMagicBytes

InvalidVersion

InvalidSha512Hmac

InvalidKeccakHmac

MisMatchedCipherSalt

Instances

Eq DecryptionFailure

Defined in Crypto.TripleSec.Types

Methods

(==) :: DecryptionFailure -> DecryptionFailure -> Bool

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

Show DecryptionFailure

Defined in Crypto.TripleSec.Types

Methods

showsPrec :: Int -> DecryptionFailure -> ShowS

show :: DecryptionFailure -> String

showList :: [DecryptionFailure] -> ShowS

Specialized IO API

encryptIO

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Plaintext

-> IO ba

encrypt specialized to IO. Throws instead of returning a TripleSecException.

decryptIO

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Ciphertext

-> IO ba

decrypt specialized to IO. Throws instead of returning a TripleSecException.

newCipherIO

Arguments

:: ByteArray ba

=> ba

Passphrase

-> IO (TripleSec ba)

newCipher specialized to IO. Throws instead of returning a TripleSecException.

newCipherWithSaltIO

Arguments

:: ByteArray ba

=> ba

Passphrase

-> ba

Salt

-> IO (TripleSec ba)

newCipherWithSalt specialized to IO. Throws instead of returning a TripleSecException.

encryptWithCipherIO

Arguments

:: ByteArray ba

=> TripleSec ba

-> ba

Ciphertext

-> IO ba

encryptWithCipher specialized to IO. Throws instead of returning a TripleSecException.

decryptWithCipherIO

Arguments

:: ByteArray ba

=> TripleSec ba

-> ba

Ciphertext

-> IO ba

decryptWithCipher specialized to IO. Throws instead of returning a TripleSecException.

IO Based Monad API

type TripleSecIOM = TripleSecIOT IO

Monad that works "out of the box" for encrypting/decrypting.

Does not throw exceptions (returns Either TripleSecException ba). Use with runTripleSecIO.

data TripleSecIOT m a

Monad transformer for use with any IO based monad stack.

Does not throw exceptions (returns Either TripleSecException a). Use with runTripleSecIO.

Instances

MonadTrans TripleSecIOT

Defined in Crypto.TripleSec.IO

Methods

lift :: Monad m => m a -> TripleSecIOT m a

Monad m => MonadError TripleSecException (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

throwError :: TripleSecException -> TripleSecIOT m a

catchError :: TripleSecIOT m a -> (TripleSecException -> TripleSecIOT m a) -> TripleSecIOT m a

Monad m => Monad (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

(>>=) :: TripleSecIOT m a -> (a -> TripleSecIOT m b) -> TripleSecIOT m b

(>>) :: TripleSecIOT m a -> TripleSecIOT m b -> TripleSecIOT m b

return :: a -> TripleSecIOT m a

fail :: String -> TripleSecIOT m a

Functor m => Functor (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

fmap :: (a -> b) -> TripleSecIOT m a -> TripleSecIOT m b

(<$) :: a -> TripleSecIOT m b -> TripleSecIOT m a

MonadFail m => MonadFail (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

fail :: String -> TripleSecIOT m a

Monad m => Applicative (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

pure :: a -> TripleSecIOT m a

(<*>) :: TripleSecIOT m (a -> b) -> TripleSecIOT m a -> TripleSecIOT m b

liftA2 :: (a -> b -> c) -> TripleSecIOT m a -> TripleSecIOT m b -> TripleSecIOT m c

(*>) :: TripleSecIOT m a -> TripleSecIOT m b -> TripleSecIOT m b

(<*) :: TripleSecIOT m a -> TripleSecIOT m b -> TripleSecIOT m a

MonadIO m => MonadIO (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

liftIO :: IO a -> TripleSecIOT m a

MonadIO m => MonadRandom (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

getRandomBytes :: ByteArray byteArray => Int -> TripleSecIOT m byteArray

MonadIO m => CanTripleSec (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

encrypt :: ByteArray ba => ba -> ba -> TripleSecIOT m ba

encryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecIOT m ba

newCipher :: ByteArray ba => ba -> TripleSecIOT m (TripleSec ba)

Monad m => CanTripleSecDecrypt (TripleSecIOT m)

Defined in Crypto.TripleSec.IO

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecIOT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecIOT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecIOT m (TripleSec ba)

runTripleSecIO :: TripleSecIOT m a -> m (Either TripleSecException a)

Evaluate a TripleSecIOT computation.

Pure Monad API

type TripleSecM = TripleSecT Identity

Monad that works "out of the box" for pure encrypting/decrypting.

Use with runTripleSecM or evalTripleSecM. SystemDRG can be obtained with getSystemDRG.

data TripleSecT m a

Monad transformer for use with any non-IO based monad stack (See TripleSecIOT for IO based stacks).

Use with runTripleSecT or evalTripleSecT. SystemDRG can be obtained with getSystemDRG.

Instances

MonadTrans TripleSecT

Defined in Crypto.TripleSec.Pure

Methods

lift :: Monad m => m a -> TripleSecT m a

Monad m => MonadError TripleSecException (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

throwError :: TripleSecException -> TripleSecT m a

catchError :: TripleSecT m a -> (TripleSecException -> TripleSecT m a) -> TripleSecT m a

Monad m => Monad (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

(>>=) :: TripleSecT m a -> (a -> TripleSecT m b) -> TripleSecT m b

(>>) :: TripleSecT m a -> TripleSecT m b -> TripleSecT m b

return :: a -> TripleSecT m a

fail :: String -> TripleSecT m a

Functor m => Functor (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

fmap :: (a -> b) -> TripleSecT m a -> TripleSecT m b

(<$) :: a -> TripleSecT m b -> TripleSecT m a

MonadFail m => MonadFail (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

fail :: String -> TripleSecT m a

Monad m => Applicative (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

pure :: a -> TripleSecT m a

(<*>) :: TripleSecT m (a -> b) -> TripleSecT m a -> TripleSecT m b

liftA2 :: (a -> b -> c) -> TripleSecT m a -> TripleSecT m b -> TripleSecT m c

(*>) :: TripleSecT m a -> TripleSecT m b -> TripleSecT m b

(<*) :: TripleSecT m a -> TripleSecT m b -> TripleSecT m a

Monad m => MonadRandom (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

getRandomBytes :: ByteArray byteArray => Int -> TripleSecT m byteArray

Monad m => CanTripleSec (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

encrypt :: ByteArray ba => ba -> ba -> TripleSecT m ba

encryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecT m ba

newCipher :: ByteArray ba => ba -> TripleSecT m (TripleSec ba)

Monad m => CanTripleSecDecrypt (TripleSecT m)

Defined in Crypto.TripleSec.Pure

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecT m (TripleSec ba)

data SystemDRG

A referentially transparent System representation of the random evaluated out of the system.

Holding onto a specific DRG means that all the already evaluated bytes will be consistently replayed.

There's no need to reseed this DRG, as only pure entropy is represented here.

Instances

DRG SystemDRG

Defined in Crypto.Random.SystemDRG

Methods

randomBytesGenerate :: ByteArray byteArray => Int -> SystemDRG -> (byteArray, SystemDRG)

getSystemDRG :: IO SystemDRG

Grab one instance of the System DRG

runTripleSecM :: TripleSecM a -> SystemDRG -> (Either TripleSecException a, SystemDRG)

Evaluate a TripleSecM computation.

If you have no use for the output SystemDRG. See evalTripleSecM.

evalTripleSecM :: TripleSecM a -> SystemDRG -> Either TripleSecException a

Evaluate a TripleSecM computation.

Do NOT re-use the input SystemDRG (very bad!). See runTripleSecM for an output SystemDRG that's safe to use elsewhere.

runTripleSecT :: TripleSecT m a -> SystemDRG -> m (Either TripleSecException a, SystemDRG)

Evaluate a TripleSecT computation.

If you have no use for the output SystemDRG. See evalTripleSecT.

evalTripleSecT :: Functor m => TripleSecT m a -> SystemDRG -> m (Either TripleSecException a)

Evaluate a TripleSecT computation.

Do NOT re-use the input SystemDRG (very bad!). See runTripleSecT for an output SystemDRG that's safe to use elsewhere.

Pure Decryption Only Monad API

type TripleSecDecryptM = TripleSecDecryptT Identity

Monad that works "out of the box" for pure decrypting only.

Use with runTripleSecDecryptM. Useful as it does not require a source of randomness.

data TripleSecDecryptT m a

Monad transformer for decryption only with any non-IO based monad stack (See TripleSecIOT for IO based stacks as it's more powerful and just as easy to use).

Use with runTripleSecDecryptT. Useful as it does not require a source of randomness.

Instances

MonadTrans TripleSecDecryptT

Defined in Crypto.TripleSec.Pure

Methods

lift :: Monad m => m a -> TripleSecDecryptT m a

Monad m => MonadError TripleSecException (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

throwError :: TripleSecException -> TripleSecDecryptT m a

catchError :: TripleSecDecryptT m a -> (TripleSecException -> TripleSecDecryptT m a) -> TripleSecDecryptT m a

Monad m => Monad (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

(>>=) :: TripleSecDecryptT m a -> (a -> TripleSecDecryptT m b) -> TripleSecDecryptT m b

(>>) :: TripleSecDecryptT m a -> TripleSecDecryptT m b -> TripleSecDecryptT m b

return :: a -> TripleSecDecryptT m a

fail :: String -> TripleSecDecryptT m a

Functor m => Functor (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

fmap :: (a -> b) -> TripleSecDecryptT m a -> TripleSecDecryptT m b

(<$) :: a -> TripleSecDecryptT m b -> TripleSecDecryptT m a

Monad m => Applicative (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

pure :: a -> TripleSecDecryptT m a

(<*>) :: TripleSecDecryptT m (a -> b) -> TripleSecDecryptT m a -> TripleSecDecryptT m b

liftA2 :: (a -> b -> c) -> TripleSecDecryptT m a -> TripleSecDecryptT m b -> TripleSecDecryptT m c

(*>) :: TripleSecDecryptT m a -> TripleSecDecryptT m b -> TripleSecDecryptT m b

(<*) :: TripleSecDecryptT m a -> TripleSecDecryptT m b -> TripleSecDecryptT m a

Monad m => CanTripleSecDecrypt (TripleSecDecryptT m)

Defined in Crypto.TripleSec.Pure

Methods

decrypt :: ByteArray ba => ba -> ba -> TripleSecDecryptT m ba

decryptWithCipher :: ByteArray ba => TripleSec ba -> ba -> TripleSecDecryptT m ba

newCipherWithSalt :: ByteArray ba => ba -> ba -> TripleSecDecryptT m (TripleSec ba)

runTripleSecDecryptM :: TripleSecDecryptM a -> Either TripleSecException a

Evaluate a TripleSecDecryptM computation.

runTripleSecDecryptT :: TripleSecDecryptT m a -> m (Either TripleSecException a)

Evaluate a TripleSecDecryptT computation.

Low Level Utils

checkPrefix

Arguments

:: (ByteArray ba, MonadError TripleSecException m)

=> ba

Ciphertext

-> m (ba, ba, ba)

(TripleSec prefix, Salt, encrypted payload)

Utility function to check that ciphertext is structurally valid and encrypted with a supported TripleSec version.

This function can be used for extracting the salt from a ciphertext to build a cipher with newCipherWithSalt. If you know you've encrypted many things with the same cipher this lets you decrypt them all without continually paying for the expensive key-derivation.

The only potentially useful output as a consumer of this library is the salt.

checkSalt

Arguments

:: (ByteArray ba, MonadError TripleSecException m)

=> ba

Salt

-> m ()

Utility function to check salt length.

checkCipher

Arguments

:: (ByteArray ba, MonadError TripleSecException m)

=> TripleSec ba

-> ba

Salt

-> m ()

Utility function to check that the provided TripleSec was built with the provided salt.

This function does not confirm anything about the passphrase provided when the TripleSec cipher was created or the passphrase used to encrypt a ciphertext where the salt came from.