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


-- | FFI Bindings to OpenSSL's EVP Digest Interface
--   
--   Foreign-function bindings to the <a>OpenSSL library</a>. Currently
--   provides access to the messages digests MD5, DSS, DSS1, RIPEMD160, and
--   various SHA variants through the EVP digest interface.
@package hopenssl
@version 2.2.4


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest.Error

-- | Most OpenSSL functions return an approximation of <tt>Bool</tt> to
--   signify failure. This wrapper makes it easier to move the error
--   handling to the exception layer where appropriate.
throwIfZero :: String -> IO CInt -> IO ()

-- | A custom exception type which is thrown by <tt>digestByName</tt> in
--   case the requested digest algorithm is not available in the OpenSSL
--   system library.
newtype UnknownAlgorithm
UnknownAlgorithm :: String -> UnknownAlgorithm
instance GHC.Show.Show OpenSSL.EVP.Digest.Error.UnknownAlgorithm
instance GHC.Exception.Type.Exception OpenSSL.EVP.Digest.Error.UnknownAlgorithm


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest.Context

-- | A context for digest computations. Use <a>newContext</a> and
--   <a>freeContext</a> to allocate/deallocate this type.
newtype Context
Context :: Ptr () -> Context

-- | Allocate and initialize an <a>Context</a> for use in a digest
--   computation on the heap. Release its underlying memory after use with
--   <a>freeContext</a>.
newContext :: IO Context
_newContext :: IO Context

-- | Release all resources associated with a digest computation.
freeContext :: Context -> IO ()

-- | Free all resources associated with this <a>Context</a>, but don't
--   destroy the context itself so that it can be re-used for a new digest
--   computation.
resetDigest :: Context -> IO ()
_resetContext :: Context -> IO CInt
instance GHC.Classes.Eq OpenSSL.EVP.Digest.Context.Context
instance GHC.Show.Show OpenSSL.EVP.Digest.Context.Context


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest.Initialization

-- | Initialize the OpenSSL EVP engine and register all known digest types
--   in the internal data structures. This function must be called before
--   any of the message digest functions can succeed. This is generally
--   handled transparently by the Haskell implementation and users do not
--   need to worry about this.
initializeEVPDigests :: IO ()


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest.Algorithm

-- | An opaque handle into OpenSSL's collection of message digest
--   algorithms. Use <a>digestByName</a> to look up any of the available
--   algorithms by name. For the sake of convenience, <a>Algorithm</a> is
--   an instance of <a>IsString</a> so that the compiler can transparently
--   map <a>String</a> literals to algorithms via <a>fromString</a> if the
--   <tt>XOverloadedStrings</tt> extension is enabled.
--   
--   <pre>
--   &gt;&gt;&gt; fromString "sha256" == digestByName "sha256"
--   True
--   </pre>
newtype Algorithm
Algorithm :: Ptr () -> Algorithm

-- | Look up a digest algorithm engine by name. Algorithms usually offered
--   by OpenSSL are "md2", "md5", "sha1", "mdc2", "ripemd160",
--   "blake2b512", "blake2s256", "sha224", "sha256", "sha384", and
--   "sha512", but the exact set may vary between platforms. Throws
--   <a>UnknownAlgorithm</a> if the requested algorithm is not known.
digestByName :: String -> Algorithm

-- | Variant of <a>digestByName</a> that signals failure by evaluating to
--   <a>Nothing</a> rather than failing.
--   
--   <pre>
--   &gt;&gt;&gt; digestByName' "sha256" == Just (digestByName "sha256")
--   True
--   
--   &gt;&gt;&gt; digestByName' "Guess what?" :: Maybe Algorithm
--   Nothing
--   </pre>
digestByName' :: String -> Maybe Algorithm

-- | Return the size of the digest in bytes that the given algorithm will
--   produce.
--   
--   <pre>
--   &gt;&gt;&gt; digestSize (digestByName "sha256")
--   32
--   </pre>
digestSize :: Algorithm -> Int

-- | The largest possible digest size of any of the algorithms supported by
--   this library will generate. So if you want to store a digest without
--   bothering to retrieve the appropriate size with <a>digestSize</a>
--   first, allocate a buffer of that size.
maxDigestSize :: Int

-- | Return the block size the the given algorithm operates with.
--   
--   <pre>
--   &gt;&gt;&gt; digestBlockSize (digestByName "sha256")
--   64
--   </pre>
digestBlockSize :: Algorithm -> Int
_digestByName :: CString -> Algorithm
_digestSize :: Algorithm -> CInt
_digestBlockSize :: Algorithm -> CInt
instance GHC.Classes.Eq OpenSSL.EVP.Digest.Algorithm.Algorithm
instance GHC.Show.Show OpenSSL.EVP.Digest.Algorithm.Algorithm
instance Data.String.IsString OpenSSL.EVP.Digest.Algorithm.Algorithm


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest.Digest

-- | Configure the given digest context to use the given message digest
--   algorithm. Throws an exception to signal failure, i.e. because the
--   system is out of memory.
initDigest :: Algorithm -> Context -> IO ()

-- | Hash the given block of memory and update the digest state
--   accordingly. This function can be called many times. Then use
--   <a>finalizeDigest</a> to retrieve the actual hash value.
updateDigest :: Context -> Ptr a -> CSize -> IO ()

-- | Finalize the digest calculation and return the result in the
--   <a>Word8</a> array passed as an argument. Naturally, that array is
--   expected to be large enough to contain the digest. <a>digestSize</a>
--   or <a>maxDigestSize</a> are your friends. This function does
--   <i>not</i> clean up the digest context; this has to be done with an
--   explicit call to <a>freeContext</a> (or <tt>resetContext</tt>, if you
--   want to re-use it). However, it does invalidate the digest state so
--   that no further calls of <tt>digestUpdate</tt> can be made without
--   re-initializing the context first.
finalizeDigest :: Context -> Ptr Word8 -> IO ()

-- | We don't support choosing a custom engine to implement the given
--   algorithm. This type is just a place holder, and we always pass
--   <a>nullPtr</a> wherever it is required to let OpenSSL choose whatever
--   engine it thinks is best.
data OpaqueEngine
_initDigest :: Context -> Algorithm -> Ptr OpaqueEngine -> IO CInt
_updateDigest :: Context -> Ptr a -> CSize -> IO CInt
_finalizeDigest :: Context -> Ptr Word8 -> Ptr CUInt -> IO CInt


-- | Low-level bindings to OpenSSL's EVP interface. Most users do not need
--   this code. Check out <a>OpenSSL.Digest</a> for a more comfortable
--   interface.
module OpenSSL.EVP.Digest

-- | An opaque handle into OpenSSL's collection of message digest
--   algorithms. Use <a>digestByName</a> to look up any of the available
--   algorithms by name. For the sake of convenience, <a>Algorithm</a> is
--   an instance of <a>IsString</a> so that the compiler can transparently
--   map <a>String</a> literals to algorithms via <a>fromString</a> if the
--   <tt>XOverloadedStrings</tt> extension is enabled.
--   
--   <pre>
--   &gt;&gt;&gt; fromString "sha256" == digestByName "sha256"
--   True
--   </pre>
data Algorithm

-- | Look up a digest algorithm engine by name. Algorithms usually offered
--   by OpenSSL are "md2", "md5", "sha1", "mdc2", "ripemd160",
--   "blake2b512", "blake2s256", "sha224", "sha256", "sha384", and
--   "sha512", but the exact set may vary between platforms. Throws
--   <a>UnknownAlgorithm</a> if the requested algorithm is not known.
digestByName :: String -> Algorithm

-- | Variant of <a>digestByName</a> that signals failure by evaluating to
--   <a>Nothing</a> rather than failing.
--   
--   <pre>
--   &gt;&gt;&gt; digestByName' "sha256" == Just (digestByName "sha256")
--   True
--   
--   &gt;&gt;&gt; digestByName' "Guess what?" :: Maybe Algorithm
--   Nothing
--   </pre>
digestByName' :: String -> Maybe Algorithm

-- | Return the size of the digest in bytes that the given algorithm will
--   produce.
--   
--   <pre>
--   &gt;&gt;&gt; digestSize (digestByName "sha256")
--   32
--   </pre>
digestSize :: Algorithm -> Int

-- | The largest possible digest size of any of the algorithms supported by
--   this library will generate. So if you want to store a digest without
--   bothering to retrieve the appropriate size with <a>digestSize</a>
--   first, allocate a buffer of that size.
maxDigestSize :: Int

-- | Return the block size the the given algorithm operates with.
--   
--   <pre>
--   &gt;&gt;&gt; digestBlockSize (digestByName "sha256")
--   64
--   </pre>
digestBlockSize :: Algorithm -> Int

-- | A custom exception type which is thrown by <tt>digestByName</tt> in
--   case the requested digest algorithm is not available in the OpenSSL
--   system library.
data UnknownAlgorithm

-- | A context for digest computations. Use <a>newContext</a> and
--   <a>freeContext</a> to allocate/deallocate this type.
data Context

-- | Allocate and initialize an <a>Context</a> for use in a digest
--   computation on the heap. Release its underlying memory after use with
--   <a>freeContext</a>.
newContext :: IO Context

-- | Release all resources associated with a digest computation.
freeContext :: Context -> IO ()

-- | Free all resources associated with this <a>Context</a>, but don't
--   destroy the context itself so that it can be re-used for a new digest
--   computation.
resetDigest :: Context -> IO ()

-- | Configure the given digest context to use the given message digest
--   algorithm. Throws an exception to signal failure, i.e. because the
--   system is out of memory.
initDigest :: Algorithm -> Context -> IO ()

-- | Hash the given block of memory and update the digest state
--   accordingly. This function can be called many times. Then use
--   <a>finalizeDigest</a> to retrieve the actual hash value.
updateDigest :: Context -> Ptr a -> CSize -> IO ()

-- | Finalize the digest calculation and return the result in the
--   <a>Word8</a> array passed as an argument. Naturally, that array is
--   expected to be large enough to contain the digest. <a>digestSize</a>
--   or <a>maxDigestSize</a> are your friends. This function does
--   <i>not</i> clean up the digest context; this has to be done with an
--   explicit call to <a>freeContext</a> (or <tt>resetContext</tt>, if you
--   want to re-use it). However, it does invalidate the digest state so
--   that no further calls of <tt>digestUpdate</tt> can be made without
--   re-initializing the context first.
finalizeDigest :: Context -> Ptr Word8 -> IO ()


-- | Random collection of utility functions that may be useful, but which
--   aren't useful enough to be included in the main API modules.
module OpenSSL.Util

-- | Neat helper to pretty-print digests into the common hexadecimal
--   notation:
--   
--   <pre>
--   &gt;&gt;&gt; [0..15] &gt;&gt;= toHex
--   "000102030405060708090a0b0c0d0e0f"
--   </pre>
toHex :: Word8 -> String


-- | This module provides a generic high-level API to the message digest
--   algorithms found in OpenSSL's <tt>crypto</tt> library. There are two
--   functions of particular interest: <a>digestByName</a> and
--   <a>digest</a>. The former can be used to retrieve an <a>Algorithm</a>,
--   i.e. an OpenSSL object that implements a particular algorithm. That
--   type can then be used to compute actual message digests with the
--   latter function:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.ByteString.Char8 ( pack )
--   
--   &gt;&gt;&gt; digest (digestByName "md5") (pack "Hello, world.")
--   "\b\n\239\131\155\149\250\207s\236Y\147u\233-G"
--   </pre>
--   
--   Neat pretty-printing can be achieved with <a>toHex</a>, which converts
--   the binary representation of a message digest into the common
--   hexadecimal one:
--   
--   <pre>
--   &gt;&gt;&gt; toHex $ digest (digestByName "md5") (pack "Hello, world.")
--   "080aef839b95facf73ec599375e92d47"
--   
--   &gt;&gt;&gt; toHex $ digest (digestByName "sha1") (pack "Hello, world.")
--   "2ae01472317d1935a84797ec1983ae243fc6aa28"
--   </pre>
--   
--   The precise set of available digest algorithms provided by OpenSSL
--   depends on the version of the library installed into the system,
--   obviously, but it's reasonable to expect the following algorithms to
--   be present: MD5, RIPEMD160, SHA1, SHA224, SHA256, SHA384, and SHA512.
--   If an algorithm is not available, <a>digestByName</a> will throw an
--   <tt>DigestAlgorithmNotAvailableInOpenSSL</tt> exception. If you don't
--   like exceptions, use the tamer <a>digestByName'</a> variant:
--   
--   <pre>
--   &gt;&gt;&gt; digestByName' "i bet this algorithm won't exist"
--   Nothing
--   </pre>
--   
--   <a>Algorithm</a> is an instance of <tt>IsString</tt>, so with the
--   proper GHC extensions enabled it's possible to simplify the call to
--   <a>digest</a> even further:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; toHex $ digest "sha256" (pack "The 'Through the Universe' podcast rules.")
--   "73624694a9435095c8fdaad711273a23c02226196c452f817cfd86f965895614"
--   </pre>
--   
--   Last but not least, <a>digest</a> is actually a class method of
--   <a>Digestable</a>, which collects things we can compute digests of.
--   The defaults are conservative, i.e. we support all things that
--   correspond roughly to C's construct of "void pointer plus a length".
--   <tt>digest</tt> can use with any of the following signatures:
--   
--   <pre>
--   &gt;&gt;&gt; let shape1 = digest :: Algorithm -&gt; (Ptr (),    CSize) -&gt; MessageDigest
--   
--   &gt;&gt;&gt; let shape2 = digest :: Algorithm -&gt; (Ptr Word8, CSize) -&gt; MessageDigest
--   
--   &gt;&gt;&gt; let shape3 = digest :: Algorithm -&gt; (Ptr Word8, CUInt) -&gt; MessageDigest
--   
--   &gt;&gt;&gt; let shape4 = digest :: Algorithm -&gt; (Ptr (),    Int)   -&gt; MessageDigest
--   
--   &gt;&gt;&gt; let shape5 = digest :: Algorithm -&gt; StrictByteString   -&gt; MessageDigest
--   
--   &gt;&gt;&gt; let shape6 = digest :: Algorithm -&gt; LazyByteString     -&gt; MessageDigest
--   </pre>
--   
--   <a>StrictByteString</a> and <a>LazyByteString</a> are also instances
--   of <tt>IsString</tt> and therefore subject to implicit construction
--   from string literals:
--   
--   <pre>
--   &gt;&gt;&gt; shape5 "sha256" "hello" == shape6 "sha256" "hello"
--   True
--   </pre>
--   
--   Note that this code offers no overloaded <a>digest</a> version for
--   <a>String</a>, because that function would produce non-deterministic
--   results for Unicode characters. There is an instance for
--   <tt>[Word8]</tt>, though, so strings can be hashed after a proper
--   encoding has been applied. For those who don't care about determinism,
--   there is the following specialized function:
--   
--   <pre>
--   &gt;&gt;&gt; toHex $ digestString "md5" "no Digestable instance for this sucker"
--   "a74827f849005794565f83fbd68ad189"
--   </pre>
--   
--   If you don't mind orphaned instances, however, feel free to shoot
--   yourself in the foot:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XFlexibleInstances
--   
--   &gt;&gt;&gt; instance Digestable String where updateChunk ctx str = withCStringLen str (updateChunk ctx)
--   
--   &gt;&gt;&gt; toHex $ digest "sha256" ("now we can hash strings" :: String)
--   "7f2989f173125810aa917c4ffe0e26ae1b5f7fb852274829c210297a43dfc7f9"
--   </pre>
module OpenSSL.Digest

-- | A message digest is essentially an array of <a>Word8</a> octets.
type MessageDigest = StrictByteString

-- | Compute the given message digest of any <a>Digestable</a> thing, i.e.
--   any type that can be converted <i>efficiently</i> and
--   <i>unambiguously</i> into a continuous memory buffer or a sequence of
--   continuous memory buffers. Note that <a>String</a> does <i>not</i>
--   have that property, because the binary representation chosen for
--   Unicode characters during the marshaling process is determined by the
--   system's locale and is therefore non-deterministic.
digest :: Digestable a => Algorithm -> a -> MessageDigest

-- | A class of things that can be part of a digest computations. By
--   default, we define instances only for various representations of plain
--   memory buffers, but in theory that class can be extended to contain
--   all kinds of complex data types.
class Digestable a
updateChunk :: Digestable a => Context -> a -> IO ()

-- | Look up a digest algorithm engine by name. Algorithms usually offered
--   by OpenSSL are "md2", "md5", "sha1", "mdc2", "ripemd160",
--   "blake2b512", "blake2s256", "sha224", "sha256", "sha384", and
--   "sha512", but the exact set may vary between platforms. Throws
--   <a>UnknownAlgorithm</a> if the requested algorithm is not known.
digestByName :: String -> Algorithm

-- | Variant of <a>digestByName</a> that signals failure by evaluating to
--   <a>Nothing</a> rather than failing.
--   
--   <pre>
--   &gt;&gt;&gt; digestByName' "sha256" == Just (digestByName "sha256")
--   True
--   
--   &gt;&gt;&gt; digestByName' "Guess what?" :: Maybe Algorithm
--   Nothing
--   </pre>
digestByName' :: String -> Maybe Algorithm

-- | An opaque handle into OpenSSL's collection of message digest
--   algorithms. Use <a>digestByName</a> to look up any of the available
--   algorithms by name. For the sake of convenience, <a>Algorithm</a> is
--   an instance of <a>IsString</a> so that the compiler can transparently
--   map <a>String</a> literals to algorithms via <a>fromString</a> if the
--   <tt>XOverloadedStrings</tt> extension is enabled.
--   
--   <pre>
--   &gt;&gt;&gt; fromString "sha256" == digestByName "sha256"
--   True
--   </pre>
data Algorithm

-- | We do <i>not</i> define a <a>Digestable</a> instance for
--   <a>String</a>, because there is no one obviously correct way to encode
--   Unicode characters for purposes of calculating a digest. We have,
--   however, this specialized function which computes a digest over a
--   <tt>String</tt> by means of <tt>withCStrinLen</tt>. This means that
--   the representation of Unicode characters depends on the process locale
--   a.k.a. it's non-deterministc!
--   
--   <pre>
--   &gt;&gt;&gt; toHex $ digestString (digestByName "sha1") "Hello, world."
--   "2ae01472317d1935a84797ec1983ae243fc6aa28"
--   </pre>
digestString :: Algorithm -> String -> MessageDigest

-- | Pretty-print a given message digest from binary into hexadecimal
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; toHex (Data.ByteString.pack [0..15])
--   "000102030405060708090a0b0c0d0e0f"
--   </pre>
toHex :: MessageDigest -> StrictByteString

-- | Synonym for the strict <a>ByteString</a> variant to improve
--   readability.
type StrictByteString = ByteString

-- | Synonym for the lazy <a>ByteString</a> variant to improve readability.
type LazyByteString = ByteString
instance OpenSSL.Digest.Digestable OpenSSL.Digest.LazyByteString
instance OpenSSL.Digest.Digestable OpenSSL.Digest.StrictByteString
instance OpenSSL.Digest.Digestable (GHC.Ptr.Ptr a, Foreign.C.Types.CSize)
instance OpenSSL.Digest.Digestable (GHC.Ptr.Ptr a, Foreign.C.Types.CUInt)
instance OpenSSL.Digest.Digestable (GHC.Ptr.Ptr a, Foreign.C.Types.CInt)
instance OpenSSL.Digest.Digestable (GHC.Ptr.Ptr a, GHC.Types.Int)
instance OpenSSL.Digest.Digestable [GHC.Word.Word8]
