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


-- | Cryptography that's easy to digest (NaCl/libsodium bindings).
--   
--   <i>NaCl</i> (pronounced "salt") is a new easy-to-use high-speed
--   software library for network communication, encryption, decryption,
--   signatures, etc. NaCl's goal is to provide all of the core operations
--   needed to build higher-level cryptographic tools.
--   
--   <a>http://nacl.cr.yp.to/</a>
--   
--   <i>Sodium</i> is a portable, cross-compilable, installable,
--   packageable crypto library based on NaCl, with a compatible API.
--   
--   <a>https://github.com/jedisct1/libsodium</a>
--   
--   <i>Saltine</i> is a Haskell binding to the NaCl primitives going
--   through Sodium for build convenience and, eventually, portability.
@package saltine
@version 0.1.0.1

module Crypto.Saltine

-- | Runs Sodiums's initialization routine. This must be called before
--   using any other function. It is thread-safe since libsodium 1.0.11.
sodiumInit :: IO ()


-- | Saltine type classes
module Crypto.Saltine.Class

-- | Class for all keys and nonces in Saltine which have a representation
--   as ByteString. <a>encoded</a> is a <tt>Prism</tt> of type <tt>Prism'
--   ByteString a</tt> compatible with <a>Control.Lens</a> and is
--   automatically deduced.
class IsEncoding a
encode :: IsEncoding a => a -> ByteString
decode :: IsEncoding a => ByteString -> Maybe a
encoded :: (IsEncoding a, Choice p, Applicative f) => p a (f a) -> p ByteString (f ByteString)

-- | A generic class for interacting with nonces.
class IsNonce n

-- | Some privileged nonce value.
zero :: IsNonce n => n

-- | Some perturbation on nonces such that <tt>n /= nudge n</tt> with high
--   probability. Since nonces are finite, repeats may happen in
--   particularly small cases, but no nonces in Saltine are so small. This
--   is not guaranteed to be difficult to predict---if a nonce had an
--   <a>Enum</a> instance <a>succ</a> would be a good implementation
--   excepting that <a>succ</a> is partial.
nudge :: IsNonce n => n -> n


-- | Various sizes
--   
--   While technically these sizes are hidden behind opaque newtype
--   wrappers, they can be useful for computation and sizing and are thus
--   exposed.
--   
--   As of <tt>libsodium-4.1</tt> some of these sizes are not exported and
--   thus are hardcoded here. This limitation should be removed in later
--   versions of <tt>libsodium</tt>.
module Crypto.Saltine.Internal.ByteSizes

-- | Size of a <tt>crypto_auth</tt> authenticator.
auth :: Int

-- | Size of a <tt>crypto_auth</tt> authenticator key.
authKey :: Int

-- | Size of a <tt>crypto_box</tt> public key
boxPK :: Int

-- | Size of a <tt>crypto_box</tt> secret key
boxSK :: Int

-- | Size of a <tt>crypto_box</tt> nonce
boxNonce :: Int

-- | Size of 0-padding prepended to messages before using
--   <tt>crypto_box</tt> or after using <tt>crypto_box_open</tt>
boxZero :: Int

-- | Size of 0-padding prepended to ciphertext before using
--   <tt>crypto_box_open</tt> or after using <tt>crypto_box</tt>.
boxBoxZero :: Int
boxMac :: Int

-- | Size of a <tt>crypto_box_beforenm</tt>-generated combined key
boxBeforeNM :: Int

-- | Amount by which ciphertext is longer than plaintext in sealed boxes
sealedBox :: Int

-- | Size of a <tt>crypto_onetimeauth</tt> authenticator.
onetime :: Int

-- | Size of a <tt>crypto_onetimeauth</tt> authenticator key.
onetimeKey :: Int

-- | Size of a group element string representation for
--   <tt>crypto_scalarmult</tt>.
mult :: Int

-- | Size of a integer string representation for
--   <tt>crypto_scalarmult</tt>.
multScalar :: Int

-- | Size of a <tt>crypto_secretbox</tt> secret key
secretBoxKey :: Int

-- | Size of a <tt>crypto_secretbox</tt> nonce
secretBoxNonce :: Int

-- | Size of a <tt>crypto_secretbox</tt> mac
secretBoxMac :: Int

-- | Size of 0-padding prepended to messages before using
--   <tt>crypto_secretbox</tt> or after using
--   <tt>crypto_secretbox_open</tt>
secretBoxZero :: Int

-- | Size of 0-padding prepended to ciphertext before using
--   <tt>crypto_secretbox_open</tt> or after using
--   <tt>crypto_secretbox</tt>
secretBoxBoxZero :: Int
aead_xchacha20poly1305_ietf_ABYTES :: Int

-- | The maximum size of a signature prepended to a message to form a
--   signed message.
sign :: Int

-- | The size of a public key for signing verification
signPK :: Int

-- | The size of a secret key for signing
signSK :: Int

-- | The size of a key for the cryptographic stream generation
streamKey :: Int

-- | The size of a nonce for the cryptographic stream generation
streamNonce :: Int

-- | The size of a hash resulting from <a>hash</a>.
hash :: Int

-- | The size of a keyed hash resulting from <a>shorthash</a>.
shorthash :: Int

-- | The size of a hashing key for the keyed hash function
--   <a>shorthash</a>.
shorthashKey :: Int

module Crypto.Saltine.Core.Utils

-- | Build a sized random <a>ByteString</a> using Sodium's bindings to
--   <tt><i>dev</i>urandom</tt>.
randomByteString :: Int -> IO ByteString


-- | Secret-key encryption: <a>Crypto.Saltine.Core.Stream</a>
--   
--   The <a>stream</a> function produces a sized stream <a>ByteString</a>
--   as a function of a secret key and a nonce. The <a>xor</a> function
--   encrypts a message <a>ByteString</a> using a secret key and a nonce.
--   The <a>xor</a> function guarantees that the ciphertext has the same
--   length as the plaintext, and is the <tt>plaintext <a>xor</a> stream k
--   n</tt>. Consequently <a>xor</a> can also be used to decrypt.
--   
--   The <a>stream</a> function, viewed as a function of the nonce for a
--   uniform random key, is designed to meet the standard notion of
--   unpredictability ("PRF"). For a formal definition see, e.g., Section
--   2.3 of Bellare, Kilian, and Rogaway, "The security of the cipher block
--   chaining message authentication code," Journal of Computer and System
--   Sciences 61 (2000), 362–399;
--   <a>http://www-cse.ucsd.edu/~mihir/papers/cbc.html</a>. This means that
--   an attacker cannot distinguish this function from a uniform random
--   function. Consequently, if a series of messages is encrypted by
--   <a>xor</a> with <i>a different nonce for each message</i>, the
--   ciphertexts are indistinguishable from uniform random strings of the
--   same length.
--   
--   Note that the length is not hidden. Note also that it is the caller's
--   responsibility to ensure the uniqueness of nonces—for example, by
--   using nonce 1 for the first message, nonce 2 for the second message,
--   etc. Nonces are long enough that randomly generated nonces have
--   negligible risk of collision.
--   
--   Saltine does not make any promises regarding the resistance of
--   crypto_stream to "related-key attacks." It is the caller's
--   responsibility to use proper key-derivation functions.
--   
--   <a>Crypto.Saltine.Core.Stream</a> is <tt>crypto_stream_xsalsa20</tt>,
--   a particular cipher specified in "Cryptography in NaCl"
--   (<a>http://nacl.cr.yp.to/valid.html</a>), Section 7. This cipher is
--   conjectured to meet the standard notion of unpredictability.
--   
--   This is version 2010.08.30 of the stream.html web page.
module Crypto.Saltine.Core.Stream

-- | An opaque <a>stream</a> cryptographic key.
data Key

-- | An opaque <a>stream</a> nonce.
data Nonce

-- | Creates a random key of the correct size for <a>stream</a> and
--   <a>xor</a>.
newKey :: IO Key

-- | Creates a random nonce of the correct size for <a>stream</a> and
--   <a>xor</a>.
newNonce :: IO Nonce

-- | Generates a cryptographic random stream indexed by the <a>Key</a> and
--   <a>Nonce</a>. These streams are indistinguishable from random noise so
--   long as the <a>Nonce</a> is not used more than once.
stream :: Key -> Nonce -> Int -> ByteString

-- | Computes the exclusive-or between a message and a cryptographic random
--   stream indexed by the <a>Key</a> and the <a>Nonce</a>. This renders
--   the output indistinguishable from random noise so long as the
--   <a>Nonce</a> is not used more than once. <i>Note:</i> while this can
--   be used for encryption and decryption, it is <i>possible for an
--   attacker to</i> <i>manipulate the message in transit without
--   detection</i>. USE AT YOUR OWN RISK.
xor :: Key -> Nonce -> ByteString -> ByteString
instance GHC.Classes.Ord Crypto.Saltine.Core.Stream.Nonce
instance GHC.Classes.Eq Crypto.Saltine.Core.Stream.Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.Stream.Key
instance GHC.Classes.Eq Crypto.Saltine.Core.Stream.Key
instance Crypto.Saltine.Class.IsNonce Crypto.Saltine.Core.Stream.Nonce
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Stream.Nonce
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Stream.Key


-- | Signatures: <a>Crypto.Saltine.Core.Sign</a>
--   
--   The <a>newKeypair</a> function randomly generates a secret key and a
--   corresponding public key. The <a>sign</a> function signs a message
--   <a>ByteString</a> using the signer's secret key and returns the
--   resulting signed message. The <a>signOpen</a> function verifies the
--   signature in a signed message using the signer's public key then
--   returns the message without its signature.
--   
--   <a>Crypto.Saltine.Core.Sign</a> is an EdDSA signature using
--   elliptic-curve Curve25519 (see: <a>http://ed25519.cr.yp.to/</a>). See
--   also, "Daniel J. Bernstein, Niels Duif, Tanja Lange, Peter Schwabe,
--   Bo-Yin Yang. High-speed high-security signatures. Journal of
--   Cryptographic Engineering 2 (2012), 77–89."
--   <a>http://ed25519.cr.yp.to/ed25519-20110926.pdf</a>.
--   
--   This is current information as of 2013 June 6.
module Crypto.Saltine.Core.Sign

-- | An opaque <tt>box</tt> cryptographic secret key.
data SecretKey

-- | An opaque <tt>box</tt> cryptographic public key.
data PublicKey

-- | A convenience type for keypairs
type Keypair = (SecretKey, PublicKey)

-- | Creates a random key of the correct size for <a>sign</a> and
--   <a>signOpen</a> of form <tt>(secretKey, publicKey)</tt>.
newKeypair :: IO Keypair

-- | Augments a message with a signature forming a "signed message".
sign :: SecretKey -> ByteString -> ByteString

-- | Checks a "signed message" returning <a>Just</a> the original message
--   iff the signature was generated using the <a>SecretKey</a>
--   corresponding to the given <a>PublicKey</a>. Returns <a>Nothing</a>
--   otherwise.
signOpen :: PublicKey -> ByteString -> Maybe ByteString

-- | Returns just the signature for a message using a SecretKey.
signDetached :: SecretKey -> ByteString -> ByteString

-- | Returns <tt>True</tt> if the signature is valid for the given public
--   key and message.
signVerifyDetached :: PublicKey -> ByteString -> ByteString -> Bool
instance GHC.Classes.Ord Crypto.Saltine.Core.Sign.PublicKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Sign.PublicKey
instance GHC.Classes.Ord Crypto.Saltine.Core.Sign.SecretKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Sign.SecretKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Sign.PublicKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Sign.SecretKey


-- | Secret-key authenticated encryption:
--   <a>Crypto.Saltine.Core.SecretBox</a>
--   
--   The <a>secretbox</a> function encrypts and authenticates a message
--   <a>ByteString</a> using a secret key and a nonce. The
--   <a>secretboxOpen</a> function verifies and decrypts a ciphertext
--   <a>ByteString</a> using a secret key and a nonce. If the ciphertext
--   fails validation, <a>secretboxOpen</a> returns <a>Nothing</a>.
--   
--   The <a>Crypto.Saltine.Core.SecretBox</a> module is designed to meet
--   the standard notions of privacy and authenticity for a secret-key
--   authenticated-encryption scheme using nonces. For formal definitions
--   see, e.g., Bellare and Namprempre, "Authenticated encryption:
--   relations among notions and analysis of the generic composition
--   paradigm," Lecture Notes in Computer Science 1976 (2000), 531–545,
--   <a>http://www-cse.ucsd.edu/~mihir/papers/oem.html</a>.
--   
--   Note that the length is not hidden. Note also that it is the caller's
--   responsibility to ensure the uniqueness of nonces—for example, by
--   using nonce 1 for the first message, nonce 2 for the second message,
--   etc. Nonces are long enough that randomly generated nonces have
--   negligible risk of collision.
--   
--   <a>Crypto.Saltine.Core.SecretBox</a> is
--   <tt>crypto_secretbox_xsalsa20poly1305</tt>, a particular combination
--   of Salsa20 and Poly1305 specified in "Cryptography in NaCl"
--   (<a>http://nacl.cr.yp.to/valid.html</a>). This function is conjectured
--   to meet the standard notions of privacy and authenticity.
--   
--   This is version 2010.08.30 of the secretbox.html web page.
module Crypto.Saltine.Core.SecretBox

-- | An opaque <a>secretbox</a> cryptographic key.
data Key

-- | An opaque <a>secretbox</a> nonce.
data Nonce

-- | Encrypts a message. It is infeasible for an attacker to decrypt the
--   message so long as the <a>Nonce</a> is never repeated.
secretbox :: Key -> Nonce -> ByteString -> ByteString

-- | Decrypts a message. Returns <a>Nothing</a> if the keys and message do
--   not match.
secretboxOpen :: Key -> Nonce -> ByteString -> Maybe ByteString

-- | Encrypts a message. In contrast with <a>secretbox</a>, the result is
--   not serialized as one element and instead provided as an
--   authentication tag and ciphertext.
secretboxDetached :: Key -> Nonce -> ByteString -> (ByteString, ByteString)

-- | Decrypts a message. Returns <a>Nothing</a> if the keys and message do
--   not match.
secretboxOpenDetached :: Key -> Nonce -> ByteString -> ByteString -> Maybe ByteString

-- | Creates a random key of the correct size for <a>secretbox</a>.
newKey :: IO Key

-- | Creates a random nonce of the correct size for <a>secretbox</a>.
newNonce :: IO Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.SecretBox.Nonce
instance GHC.Classes.Eq Crypto.Saltine.Core.SecretBox.Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.SecretBox.Key
instance GHC.Classes.Eq Crypto.Saltine.Core.SecretBox.Key
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.SecretBox.Nonce
instance Crypto.Saltine.Class.IsNonce Crypto.Saltine.Core.SecretBox.Nonce
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.SecretBox.Key


-- | Scalar multiplication: <a>Crypto.Saltine.Core.ScalarMult</a>
--   
--   The <a>mult</a> function multiplies a group element by an integer of
--   length <a>multScalar</a>. It returns the resulting group element of
--   length <a>mult</a>. The <a>multBase</a> function multiplies a standard
--   group element by an integer of length <a>multScalar</a>. It returns
--   the resulting group element of length <a>mult</a>.
--   
--   The correspondence between strings and group elements depends on the
--   primitive implemented by <a>mult</a>. The correspondence is not
--   necessarily injective in either direction, but it is compatible with
--   scalar multiplication in the group. The correspondence does not
--   necessarily include all group elements, but it does include all
--   strings; i.e., every string represents at least one group element.
--   
--   The correspondence between strings and integers also depends on the
--   primitive implemented by <a>mult</a>. Every string represents at least
--   one integer.
--   
--   <a>mult</a> is designed to be strong as a component of various
--   well-known "hashed Diffie–Hellman" applications. In particular, it is
--   designed to make the "computational Diffie–Hellman" problem (CDH)
--   difficult with respect to the standard base. <a>mult</a> is also
--   designed to make CDH difficult with respect to other nontrivial bases.
--   In particular, if a represented group element has small order, then it
--   is annihilated by all represented scalars. This feature allows
--   protocols to avoid validating membership in the subgroup generated by
--   the standard base.
--   
--   NaCl does not make any promises regarding the "decisional
--   Diffie–Hellman" problem (DDH), the "static Diffie–Hellman" problem
--   (SDH), etc. Users are responsible for hashing group elements.
--   
--   <a>mult</a> is the function <tt>crypto_scalarmult_curve25519</tt>
--   specified in "Cryptography in NaCl", Sections 2, 3, and 4
--   (<a>http://nacl.cr.yp.to/valid.html</a>). This function is conjectured
--   to be strong. For background see Bernstein, "Curve25519: new
--   Diffie-Hellman speed records," Lecture Notes in Computer Science 3958
--   (2006), 207–228, <a>http://cr.yp.to/papers.html#curve25519</a>.
--   
--   This is version 2010.08.30 of the scalarmult.html web page.
module Crypto.Saltine.Core.ScalarMult

-- | A scalar integer.
data Scalar

-- | A group element.
data GroupElement
mult :: Scalar -> GroupElement -> GroupElement
multBase :: Scalar -> GroupElement
instance GHC.Classes.Eq Crypto.Saltine.Core.ScalarMult.Scalar
instance GHC.Classes.Eq Crypto.Saltine.Core.ScalarMult.GroupElement
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.ScalarMult.Scalar
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.ScalarMult.GroupElement


-- | Secret-key single-message authentication:
--   <a>Crypto.Saltine.Core.OneTimeAuth</a>
--   
--   The <a>auth</a> function authenticates a message <a>ByteString</a>
--   using a secret key The function returns an authenticator. The
--   <a>verify</a> function checks if it's passed a correct authenticator
--   of a message under the given secret key.
--   
--   The <a>auth</a> function, viewed as a function of the message for a
--   uniform random key, is designed to meet the standard notion of
--   unforgeability after a single message. After the sender authenticates
--   one message, an attacker cannot find authenticators for any other
--   messages.
--   
--   The sender must not use <a>auth</a> to authenticate more than one
--   message under the same key. Authenticators for two messages under the
--   same key should be expected to reveal enough information to allow
--   forgeries of authenticators on other messages.
--   
--   <a>Crypto.Saltine.Core.OneTimeAuth</a> is
--   <tt>crypto_onetimeauth_poly1305</tt>, an authenticator specified in
--   "Cryptography in NaCl" (<a>http://nacl.cr.yp.to/valid.html</a>),
--   Section 9. This authenticator is proven to meet the standard notion of
--   unforgeability after a single message.
--   
--   This is version 2010.08.30 of the onetimeauth.html web page.
module Crypto.Saltine.Core.OneTimeAuth

-- | An opaque <a>auth</a> cryptographic key.
data Key

-- | An opaque <a>auth</a> authenticator.
data Authenticator

-- | Creates a random key of the correct size for <a>auth</a> and
--   <a>verify</a>.
newKey :: IO Key

-- | Builds a keyed <a>Authenticator</a> for a message. This
--   <a>Authenticator</a> is <i>impossible</i> to forge so long as the
--   <a>Key</a> is never used twice.
auth :: Key -> ByteString -> Authenticator

-- | Verifies that an <a>Authenticator</a> matches a given message and key.
verify :: Key -> Authenticator -> ByteString -> Bool
instance GHC.Classes.Ord Crypto.Saltine.Core.OneTimeAuth.Authenticator
instance GHC.Classes.Eq Crypto.Saltine.Core.OneTimeAuth.Authenticator
instance GHC.Classes.Ord Crypto.Saltine.Core.OneTimeAuth.Key
instance GHC.Classes.Eq Crypto.Saltine.Core.OneTimeAuth.Key
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.OneTimeAuth.Authenticator
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.OneTimeAuth.Key


-- | Hashing: <a>Crypto.Saltine.Core.Hash</a>
--   
--   The <a>hash</a> function hashes a message <a>ByteString</a> and
--   returns a hash. Hashes are always of length <a>hash</a>. The
--   <a>shorthash</a> function hashes a message <a>ByteString</a> with
--   respect to a secret key and returns a very short hash. Short hashes
--   are always of length <a>shorthash</a>.
--   
--   The <a>hash</a> function is designed to be usable as a strong
--   component of DSA, RSA-PSS, key derivation, hash-based
--   message-authentication codes, hash-based ciphers, and various other
--   common applications. <a>Strong</a> means that the security of these
--   applications, when instantiated with <a>hash</a>, is the same as the
--   security of the applications against generic attacks. In particular,
--   the <a>hash</a> function is designed to make finding collisions
--   difficult.
--   
--   <a>hash</a> is currently an implementation of SHA-512.
--   <a>shorthash</a> is currently an implementation of SipHash-2-4
--   (<a>https://131002.net/siphash/</a>).
--   
--   There has been considerable degradation of public confidence in the
--   security conjectures for many hash functions, including SHA-512.
--   However, for the moment, there do not appear to be alternatives that
--   inspire satisfactory levels of confidence. One can hope that NIST's
--   SHA-3 competition will improve the situation.
--   
--   Sodium includes an implementation of the Blake2 hash
--   (<a>https://blake2.net/</a>) but since this is not standard NaCl nor
--   was Blake2 selected to be SHA-3 the library doesn't bind it.
--   
--   This is version 2010.08.30 of the hash.html web page. Information
--   about SipHash has been added.
module Crypto.Saltine.Core.Hash

-- | An opaque <a>shorthash</a> cryptographic secret key.
data ShorthashKey

-- | Computes a cryptographically collision-resistant hash making <tt>hash
--   m == hash m' ==&gt; m == m'</tt> highly likely even when under attack.
hash :: ByteString -> ByteString

-- | Computes a very short, fast keyed hash.
shorthash :: ShorthashKey -> ByteString -> ByteString

-- | Randomly generates a new key for <a>shorthash</a>.
newShorthashKey :: IO ShorthashKey
instance GHC.Classes.Ord Crypto.Saltine.Core.Hash.ShorthashKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Hash.ShorthashKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Hash.ShorthashKey


-- | Public-key cryptography abstraction: <a>Crypto.Saltine.Core.Box</a>
--   
--   This module consists of functions dealing with two public-key
--   cryptography concepts in libsodium.
--   
--   The first one is an authenticated encryption scheme. In this scheme,
--   the <a>box</a> function encrypts and authenticates a message
--   <a>ByteString</a> using the sender's secret key, the receiver's public
--   key, and a nonce. The <a>boxOpen</a> function verifies and decrypts a
--   ciphertext <a>ByteString</a> using the receiver's secret key, the
--   sender's public key, and a nonce. If the ciphertext fails
--   verification, <a>boxOpen</a> returns <a>Nothing</a>.
--   
--   The set of box functions is designed to meet the standard notions of
--   privacy and third-party unforgeability for a public-key
--   authenticated-encryption scheme using nonces. For formal definitions
--   see, e.g., Jee Hea An, "Authenticated encryption in the public-key
--   setting: security notions and analyses,"
--   <a>http://eprint.iacr.org/2001/079</a>.
--   
--   Distinct messages between the same <tt>{sender, receiver}</tt> set are
--   required to have distinct nonces. For example, the lexicographically
--   smaller public key can use nonce 1 for its first message to the other
--   key, nonce 3 for its second message, nonce 5 for its third message,
--   etc., while the lexicographically larger public key uses nonce 2 for
--   its first message to the other key, nonce 4 for its second message,
--   nonce 6 for its third message, etc. Nonces are long enough that
--   randomly generated nonces have negligible risk of collision.
--   
--   There is no harm in having the same nonce for different messages if
--   the <tt>{sender, receiver}</tt> sets are different. This is true even
--   if the sets overlap. For example, a sender can use the same nonce for
--   two different messages if the messages are sent to two different
--   public keys.
--   
--   The second concept is sealed boxes, which provide encryption and
--   preservation of integrity, but not authentication. Technically, the
--   sender of a message generates a keypair, uses the regular box
--   mechanism, attaches the public key to the message and then immediately
--   destroys the private key. This is useful, e.g. when the receiver
--   cannot know the sender's public key in advance and hence cannot use
--   the regular box functions, or when you want to send messages
--   anonymously.
--   
--   The <a>Crypto.Saltine.Core.Box</a> module is not meant to provide
--   non-repudiation. On the contrary: the crypto_box function guarantees
--   repudiability. A receiver can freely modify a boxed message, and
--   therefore cannot convince third parties that this particular message
--   came from the sender. The sender and receiver are nevertheless
--   protected against forgeries by other parties. In the terminology of
--   <a>http://groups.google.com/group/sci.crypt/msg/ec5c18b23b11d82c</a>,
--   crypto_box uses "public-key authenticators" rather than "public-key
--   signatures."
--   
--   Users who want public verifiability (or receiver-assisted public
--   verifiability) should instead use signatures (or signcryption).
--   Signatures are documented in the <a>Crypto.Saltine.Core.Sign</a>
--   module.
--   
--   <a>Crypto.Saltine.Core.Box</a> is <tt>curve25519xsalsa20poly1305</tt>,
--   a particular combination of Curve25519, Salsa20, and Poly1305
--   specified in "Cryptography in NaCl"
--   (<a>http://nacl.cr.yp.to/valid.html</a>). This function is conjectured
--   to meet the standard notions of privacy and third-party
--   unforgeability.
--   
--   This is version 2010.08.30 of the box.html web page.
module Crypto.Saltine.Core.Box

-- | An opaque <a>box</a> cryptographic secret key.
data SecretKey

-- | An opaque <a>box</a> cryptographic public key.
data PublicKey

-- | A convenience type for keypairs
type Keypair = (SecretKey, PublicKey)

-- | An opaque <a>boxAfterNM</a> cryptographic combined key.
data CombinedKey

-- | An opaque <a>box</a> nonce.
data Nonce

-- | Randomly generates a secret key and a corresponding public key.
newKeypair :: IO Keypair

-- | Build a <a>CombinedKey</a> for sending from <a>SecretKey</a> to
--   <a>PublicKey</a>. This is a precomputation step which can accelerate
--   later encryption calls.
beforeNM :: SecretKey -> PublicKey -> CombinedKey

-- | Randomly generates a nonce for usage with <a>box</a> and
--   <a>boxOpen</a>.
newNonce :: IO Nonce

-- | Encrypts a message for sending to the owner of the public key. They
--   must have your public key in order to decrypt the message. It is
--   infeasible for an attacker to decrypt the message so long as the
--   <a>Nonce</a> is not repeated.
box :: PublicKey -> SecretKey -> Nonce -> ByteString -> ByteString

-- | Decrypts a message sent from the owner of the public key. They must
--   have encrypted it using your public key. Returns <a>Nothing</a> if the
--   keys and message do not match.
boxOpen :: PublicKey -> SecretKey -> Nonce -> ByteString -> Maybe ByteString

-- | <a>box</a> using a <a>CombinedKey</a> and thus faster.
boxAfterNM :: CombinedKey -> Nonce -> ByteString -> ByteString

-- | <a>boxOpen</a> using a <a>CombinedKey</a> and is thus faster.
boxOpenAfterNM :: CombinedKey -> Nonce -> ByteString -> Maybe ByteString

-- | Encrypts a message for sending to the owner of the public key. The
--   message is unauthenticated, but permits integrity checking.
boxSeal :: PublicKey -> ByteString -> IO ByteString

-- | Decrypts a sealed box message. The message must have been encrypted
--   using the receiver's public key. Returns <a>Nothing</a> if keys and
--   message do not match or integrity is violated.
boxSealOpen :: PublicKey -> SecretKey -> ByteString -> Maybe ByteString
instance GHC.Classes.Ord Crypto.Saltine.Core.Box.Nonce
instance GHC.Classes.Eq Crypto.Saltine.Core.Box.Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.Box.CombinedKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Box.CombinedKey
instance GHC.Classes.Ord Crypto.Saltine.Core.Box.PublicKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Box.PublicKey
instance GHC.Classes.Ord Crypto.Saltine.Core.Box.SecretKey
instance GHC.Classes.Eq Crypto.Saltine.Core.Box.SecretKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Box.Nonce
instance Crypto.Saltine.Class.IsNonce Crypto.Saltine.Core.Box.Nonce
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Box.CombinedKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Box.PublicKey
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Box.SecretKey


-- | Secret-key message authentication: <a>Crypto.Saltine.Core.Auth</a>
--   
--   The <a>auth</a> function authenticates a message <a>ByteString</a>
--   using a secret key The function returns an authenticator. The
--   <a>verify</a> function checks if it's passed a correct authenticator
--   of a message under the given secret key.
--   
--   The <a>auth</a> function, viewed as a function of the message for a
--   uniform random key, is designed to meet the standard notion of
--   unforgeability. This means that an attacker cannot find authenticators
--   for any messages not authenticated by the sender, even if the attacker
--   has adaptively influenced the messages authenticated by the sender.
--   For a formal definition see, e.g., Section 2.4 of Bellare, Kilian, and
--   Rogaway, "The security of the cipher block chaining message
--   authentication code," Journal of Computer and System Sciences 61
--   (2000), 362–399;
--   <a>http://www-cse.ucsd.edu/~mihir/papers/cbc.html</a>.
--   
--   Saltine does not make any promises regarding "strong" unforgeability;
--   perhaps one valid authenticator can be converted into another valid
--   authenticator for the same message. NaCl also does not make any
--   promises regarding "truncated unforgeability."
--   
--   <a>Crypto.Saltine.Core.Auth</a> is currently an implementation of
--   HMAC-SHA-512-256, i.e., the first 256 bits of HMAC-SHA-512.
--   HMAC-SHA-512-256 is conjectured to meet the standard notion of
--   unforgeability.
--   
--   This is version 2010.08.30 of the auth.html web page.
module Crypto.Saltine.Core.Auth

-- | An opaque <a>auth</a> cryptographic key.
data Key

-- | An opaque <a>auth</a> authenticator.
data Authenticator

-- | Creates a random key of the correct size for <a>auth</a> and
--   <a>verify</a>.
newKey :: IO Key

-- | Computes an keyed authenticator <a>ByteString</a> from a message. It
--   is infeasible to forge these authenticators without the key, even if
--   an attacker observes many authenticators and messages and has the
--   ability to influence the messages sent.
auth :: Key -> ByteString -> Authenticator

-- | Checks to see if an authenticator is a correct proof that a message
--   was signed by some key.
verify :: Key -> Authenticator -> ByteString -> Bool
instance GHC.Classes.Ord Crypto.Saltine.Core.Auth.Authenticator
instance GHC.Classes.Eq Crypto.Saltine.Core.Auth.Authenticator
instance GHC.Classes.Ord Crypto.Saltine.Core.Auth.Key
instance GHC.Classes.Eq Crypto.Saltine.Core.Auth.Key
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Auth.Authenticator
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.Auth.Key


-- | Secret-key authenticated encryption with additional data (AEAD):
--   <a>Crypto.Saltine.Core.AEAD</a>
--   
--   The <a>aead</a> function encrypts and authenticates a message
--   <a>ByteString</a> and additional authenticated data <a>ByteString</a>
--   using a secret key and a nonce. The <a>aeadOpen</a> function verifies
--   and decrypts a ciphertext <a>ByteString</a> using a secret key and a
--   nonce. If the ciphertext fails validation, <a>aeadOpen</a> returns
--   <a>Nothing</a>.
--   
--   The <a>Crypto.Saltine.Core.AEAD</a> module is designed to meet the
--   standard notions of privacy and authenticity for a secret-key
--   authenticated-encryption scheme using nonces. For formal definitions
--   see, e.g., Bellare and Namprempre, "Authenticated encryption:
--   relations among notions and analysis of the generic composition
--   paradigm," Lecture Notes in Computer Science 1976 (2000), 531–545,
--   <a>http://www-cse.ucsd.edu/~mihir/papers/oem.html</a>.
--   
--   Note that the length is not hidden. Note also that it is the caller's
--   responsibility to ensure the uniqueness of nonces—for example, by
--   using nonce 1 for the first message, nonce 2 for the second message,
--   etc. Nonces are long enough that randomly generated nonces have
--   negligible risk of collision.
module Crypto.Saltine.Core.AEAD

-- | An opaque <tt>secretbox</tt> cryptographic key.
data Key

-- | An opaque <tt>secretbox</tt> nonce.
data Nonce

-- | Encrypts a message. It is infeasible for an attacker to decrypt the
--   message so long as the <a>Nonce</a> is never repeated.
aead :: Key -> Nonce -> ByteString -> ByteString -> ByteString

-- | Decrypts a message. Returns <a>Nothing</a> if the keys and message do
--   not match.
aeadOpen :: Key -> Nonce -> ByteString -> ByteString -> Maybe ByteString

-- | Encrypts a message. It is infeasible for an attacker to decrypt the
--   message so long as the <a>Nonce</a> is never repeated.
aeadDetached :: Key -> Nonce -> ByteString -> ByteString -> (ByteString, ByteString)

-- | Decrypts a message. Returns <a>Nothing</a> if the keys and message do
--   not match.
aeadOpenDetached :: Key -> Nonce -> ByteString -> ByteString -> ByteString -> Maybe ByteString

-- | Creates a random key of the correct size for <tt>secretbox</tt>.
newKey :: IO Key

-- | Creates a random nonce of the correct size for <tt>secretbox</tt>.
newNonce :: IO Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.AEAD.Nonce
instance GHC.Classes.Eq Crypto.Saltine.Core.AEAD.Nonce
instance GHC.Classes.Ord Crypto.Saltine.Core.AEAD.Key
instance GHC.Classes.Eq Crypto.Saltine.Core.AEAD.Key
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.AEAD.Nonce
instance Crypto.Saltine.Class.IsNonce Crypto.Saltine.Core.AEAD.Nonce
instance Crypto.Saltine.Class.IsEncoding Crypto.Saltine.Core.AEAD.Key
