-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | TripleSec is a simple, triple-paranoid, symmetric encryption library
--   
--   Additional details about this protocol can be found at the official
--   website: <a>https://keybase.io/triplesec</a>
--   
--   A tutorial for how to use this library can be found in <tt>
--   Crypto.TripleSec.Tutorial </tt>
@package triplesec
@version 0.1.2.0


-- | TripleSec is a simple, triple-paranoid, symmetric encryption library.
--   
--   <a>https://keybase.io/triplesec/</a>
--   
--   A tutorial for how to use this library can be found in <tt>
--   Crypto.TripleSec.Tutorial </tt>
module Crypto.TripleSec

-- | 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 <tt>encryptWithCipher</tt> and
--   <tt>decryptWithCipher</tt>.
--   
--   You can create a <a>TripleSec</a> cipher with <tt>newCipher</tt> or
--   <tt>newCipherWithSalt</tt>.
data TripleSec ba

-- | 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 <a>CanTripleSecDecrypt</a>.
class (CanTripleSecDecrypt m, MonadRandom m) => CanTripleSec m

-- | Encrypt a plaintext with a passphrase.
--   
--   <pre>
--   encrypt passphrase plaintext
--   </pre>
encrypt :: (CanTripleSec m, (ByteArray ba)) => ba -> ba -> m ba

-- | Encrypt a plaintext with a <a>TripleSec</a> 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 <a>encrypt</a>.
encryptWithCipher :: (CanTripleSec m, (ByteArray ba)) => TripleSec ba -> ba -> m ba

-- | Create a new <a>TripleSec</a> cipher.
newCipher :: (CanTripleSec m, (ByteArray ba)) => ba -> m (TripleSec ba)

-- | 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 <a>TripleSecException</a>.
class (MonadError TripleSecException m) => CanTripleSecDecrypt m

-- | Decrypt a ciphertext with a passphrase.
--   
--   <pre>
--   decrypt passphrase ciphertext
--   </pre>
decrypt :: (CanTripleSecDecrypt m, (ByteArray ba)) => ba -> ba -> m ba

-- | Decrypt a ciphertext with a <a>TripleSec</a> 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 <a>MisMatchedCipherSalt</a>.
--   
--   For a simpler alternative, please see <a>decrypt</a>.
decryptWithCipher :: (CanTripleSecDecrypt m, (ByteArray ba)) => TripleSec ba -> ba -> m ba

-- | Create a new <a>TripleSec</a> 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.
--   
--   <pre>
--   newCipherWithSalt passphrase salt
--   </pre>
newCipherWithSalt :: (CanTripleSecDecrypt m, (ByteArray ba)) => ba -> ba -> m (TripleSec ba)

-- | Exceptions thrown by this library.
data TripleSecException
CipherInitException :: CipherInitFailure -> TripleSecException
EncryptionException :: EncryptionFailure -> TripleSecException
DecryptionException :: DecryptionFailure -> TripleSecException

-- | Possible cipher initialization failures
data CipherInitFailure
ZeroLengthPassword :: CipherInitFailure
InvalidSaltLength :: CipherInitFailure

-- | Possible encryption failures
data EncryptionFailure
ZeroLengthPlaintext :: EncryptionFailure

-- | Possible decryption Failures
data DecryptionFailure
InvalidCipherTextLength :: DecryptionFailure
InvalidMagicBytes :: DecryptionFailure
InvalidVersion :: DecryptionFailure
InvalidSha512Hmac :: DecryptionFailure
InvalidKeccakHmac :: DecryptionFailure
MisMatchedCipherSalt :: DecryptionFailure

-- | <a>encrypt</a> specialized to <a>IO</a>. Throws instead of returning a
--   <a>TripleSecException</a>.
encryptIO :: (ByteArray ba) => ba -> ba -> IO ba

-- | <a>decrypt</a> specialized to <a>IO</a>. Throws instead of returning a
--   <a>TripleSecException</a>.
decryptIO :: ByteArray ba => ba -> ba -> IO ba

-- | <a>newCipher</a> specialized to <a>IO</a>. Throws instead of returning
--   a <a>TripleSecException</a>.
newCipherIO :: ByteArray ba => ba -> IO (TripleSec ba)

-- | <a>newCipherWithSalt</a> specialized to <a>IO</a>. Throws instead of
--   returning a <a>TripleSecException</a>.
newCipherWithSaltIO :: ByteArray ba => ba -> ba -> IO (TripleSec ba)

-- | <a>encryptWithCipher</a> specialized to <a>IO</a>. Throws instead of
--   returning a <a>TripleSecException</a>.
encryptWithCipherIO :: ByteArray ba => TripleSec ba -> ba -> IO ba

-- | <a>decryptWithCipher</a> specialized to <a>IO</a>. Throws instead of
--   returning a <a>TripleSecException</a>.
decryptWithCipherIO :: ByteArray ba => TripleSec ba -> ba -> IO ba

-- | Monad that works "out of the box" for encrypting/decrypting.
--   
--   Does not throw exceptions (returns <tt>Either TripleSecException
--   ba</tt>). Use with <a>runTripleSecIO</a>.
type TripleSecIOM = TripleSecIOT IO

-- | Monad transformer for use with any IO based monad stack.
--   
--   Does not throw exceptions (returns <tt>Either TripleSecException
--   a</tt>). Use with <a>runTripleSecIO</a>.
data TripleSecIOT m a

-- | Evaluate a <a>TripleSecIOT</a> computation.
runTripleSecIO :: TripleSecIOT m a -> m (Either TripleSecException a)

-- | Monad that works "out of the box" for pure encrypting/decrypting.
--   
--   Use with <a>runTripleSecM</a> or <a>evalTripleSecM</a>.
--   <a>SystemDRG</a> can be obtained with <a>getSystemDRG</a>.
type TripleSecM = TripleSecT Identity

-- | Monad transformer for use with any non-IO based monad stack (See
--   <tt>TripleSecIOT</tt> for <a>IO</a> based stacks).
--   
--   Use with <a>runTripleSecT</a> or <a>evalTripleSecT</a>.
--   <a>SystemDRG</a> can be obtained with <a>getSystemDRG</a>.
data TripleSecT m a

-- | 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.
data SystemDRG :: *

-- | Grab one instance of the System DRG
getSystemDRG :: IO SystemDRG

-- | Evaluate a <a>TripleSecM</a> computation.
--   
--   If you have no use for the output <a>SystemDRG</a>. See
--   <a>evalTripleSecM</a>.
runTripleSecM :: TripleSecM a -> SystemDRG -> (Either TripleSecException a, SystemDRG)

-- | Evaluate a <a>TripleSecM</a> computation.
--   
--   Do NOT re-use the input <a>SystemDRG</a> (very bad!). See
--   <a>runTripleSecM</a> for an output <a>SystemDRG</a> that's safe to use
--   elsewhere.
evalTripleSecM :: TripleSecM a -> SystemDRG -> Either TripleSecException a

-- | Evaluate a <a>TripleSecT</a> computation.
--   
--   If you have no use for the output <a>SystemDRG</a>. See
--   <a>evalTripleSecT</a>.
runTripleSecT :: TripleSecT m a -> SystemDRG -> m (Either TripleSecException a, SystemDRG)

-- | Evaluate a <a>TripleSecT</a> computation.
--   
--   Do NOT re-use the input <a>SystemDRG</a> (very bad!). See
--   <a>runTripleSecT</a> for an output <a>SystemDRG</a> that's safe to use
--   elsewhere.
evalTripleSecT :: Functor m => TripleSecT m a -> SystemDRG -> m (Either TripleSecException a)

-- | Monad that works "out of the box" for pure decrypting only.
--   
--   Use with <a>runTripleSecDecryptM</a>. Useful as it does not require a
--   source of randomness.
type TripleSecDecryptM = TripleSecDecryptT Identity

-- | Monad transformer for decryption only with any non-IO based monad
--   stack (See <tt>TripleSecIOT</tt> for <a>IO</a> based stacks as it's
--   more powerful and just as easy to use).
--   
--   Use with <a>runTripleSecDecryptT</a>. Useful as it does not require a
--   source of randomness.
data TripleSecDecryptT m a

-- | Evaluate a <a>TripleSecDecryptM</a> computation.
runTripleSecDecryptM :: TripleSecDecryptM a -> Either TripleSecException a

-- | Evaluate a <a>TripleSecDecryptT</a> computation.
runTripleSecDecryptT :: TripleSecDecryptT m a -> m (Either TripleSecException a)

-- | 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 <tt>newCipherWithSalt</tt>. 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.
checkPrefix :: (ByteArray ba, MonadError TripleSecException m) => ba -> m (ba, ba, ba)

-- | Utility function to check salt length.
checkSalt :: (ByteArray ba, MonadError TripleSecException m) => ba -> m ()

-- | Utility function to check that the provided <a>TripleSec</a> was built
--   with the provided salt.
--   
--   This function does <i>not</i> confirm anything about the passphrase
--   provided when the <a>TripleSec</a> cipher was created or the
--   passphrase used to encrypt a ciphertext where the salt came from.
checkCipher :: (ByteArray ba, MonadError TripleSecException m) => TripleSec ba -> ba -> m ()

module Crypto.TripleSec.Tutorial
