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


-- | Reversable and secure encoding of object ids as a bytestring
--   
--   Reversable and secure encoding of object ids as a bytestring
@package cryptoids
@version 0.1.0.1


-- | Given a strict <a>ByteString</a> we compute a cryptographic hash of
--   the associated namespace (carried as a phantom type of kind
--   <a>Symbol</a>). The payload is then encrypted using the symmetric
--   cipher in CBC mode using the hashed namespace as an initialization
--   vector (IV).
--   
--   The probability of detecting a namespace mismatch is thus the density
--   of valid payloads within all <a>ByteString</a>s of the correct length.
module Data.CryptoID.Poly
newtype CryptoID (namespace :: Symbol) a :: Symbol -> * -> *
CryptoID :: a -> CryptoID a
[ciphertext] :: CryptoID a -> a

-- | This newtype ensures only keys of the correct length can be created
--   
--   Use <a>genKey</a> to securely generate keys.
--   
--   Use the <a>Binary</a> instance to save and restore values of
--   <a>CryptoIDKey</a> across executions.
data CryptoIDKey

-- | Securely generate a new key using system entropy
--   
--   When <a>CryptoCipher</a> accepts keys of varying lengths this function
--   generates a key of the largest accepted size.
genKey :: MonadIO m => m CryptoIDKey

-- | Try to read a <a>CryptoIDKey</a> from a file. If the file does not
--   exist, securely generate a key (using <a>genKey</a>) and save it to
--   the file.
readKeyFile :: MonadIO m => FilePath -> m CryptoIDKey

-- | Encrypt a serialized value
encrypt :: forall m namespace. (KnownSymbol namespace, MonadThrow m) => CryptoIDKey -> ByteString -> m (CryptoID namespace ByteString)

-- | Decrypt a serialized value
decrypt :: forall m namespace. (KnownSymbol namespace, MonadThrow m) => CryptoIDKey -> CryptoID namespace ByteString -> m ByteString

-- | Error cases that can be encountered during <a>encrypt</a> and
--   <a>decrypt</a>
data CryptoIDError

-- | One of the underlying cryptographic algorithms (<a>CryptoHash</a> or
--   <a>CryptoCipher</a>) failed.
AlgorithmError :: CryptoError -> CryptoIDError

-- | The length of the digest produced by <a>CryptoHash</a> does not match
--   the block size of <a>CryptoCipher</a>.
--   
--   The offending digest is included.
--   
--   This error should not occur and is included primarily for sake of
--   totality.
NamespaceHashIsWrongLength :: ByteString -> CryptoIDError

-- | The produced <a>ByteString</a> is the wrong length for conversion into
--   a ciphertext.
CiphertextConversionFailed :: CryptoIDError

-- | The plaintext obtained by decrypting a ciphertext with the given
--   <a>CryptoIDKey</a> in the context of the <tt>namespace</tt> could not
--   be deserialized into a value of the expected <tt>payload</tt>-type.
--   
--   This is expected behaviour if the <tt>namespace</tt> or
--   <tt>payload</tt>-type does not match the ones used during
--   <a>encrypt</a>ion or if the <a>ciphertext</a> was tempered with.
DeserializationError :: (ByteString, ByteOffset, String) -> CryptoIDError

-- | We have determined that, allthough deserializion succeded, the
--   ciphertext was likely modified during transit or created using a
--   different namespace.
InvalidNamespaceDetected :: CryptoIDError

-- | The symmetric cipher <a>BlockCipher</a> this module uses
type CryptoCipher = Blowfish

-- | The cryptographic <tt>HashAlgorithm</tt> this module uses
--   
--   We expect the block size of <a>CryptoCipher</a> to be exactly the size
--   of the <a>Digest</a> generated by <a>CryptoHash</a> (since a
--   <a>Digest</a> is used as an <a>IV</a>).
--   
--   Violation of this expectation causes runtime errors.
type CryptoHash = SHAKE128 64
instance GHC.Classes.Eq Data.CryptoID.Poly.CryptoIDError
instance GHC.Show.Show Data.CryptoID.Poly.CryptoIDError
instance Data.ByteArray.Types.ByteArrayAccess Data.CryptoID.Poly.CryptoIDKey
instance GHC.Show.Show Data.CryptoID.Poly.CryptoIDKey
instance Data.Binary.Class.Binary Data.CryptoID.Poly.CryptoIDKey
instance GHC.Exception.Exception Data.CryptoID.Poly.CryptoIDError