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


-- | Implementation of the SPAKE2 Password-Authenticated Key Exchange algorithm
--   
--   This library implements the SPAKE2 password-authenticated key exchange
--   (<a>PAKE</a>) algorithm. This allows two parties, who share a weak
--   password, to safely derive a strong shared secret (and therefore build
--   an encrypted+authenticated channel).
@package spake2
@version 0.1.0


module Crypto.Spake2.Util

-- | Take an arbitrary sequence of bytes and expand it to be the given
--   number of bytes. Do this by extracting a pseudo-random key and
--   expanding it using HKDF.
expandData :: (ByteArrayAccess input, ByteArray output) => ByteString -> input -> Int -> output

-- | Given a seed value for an arbitrary element (see
--   <tt>arbitraryElement</tt>), expand it to be of the given length.
expandArbitraryElementSeed :: (ByteArrayAccess ikm, ByteArray out) => ikm -> Int -> out

-- | Deserialize a number according to the SPAKE2 protocol.
--   
--   Just kidding, there isn't a SPAKE2 protocol. This just matches the
--   Python implementation.
--   
--   Inverse of <a>numberToBytes</a>.
bytesToNumber :: ByteArrayAccess bytes => bytes -> Integer

-- | Serialize a number according to the SPAKE2 protocol.
--   
--   Just kidding, there isn't a SPAKE2 protocol. This just matches the
--   Python implementation.
--   
--   Inverse of <a>bytesToNumber</a>.
numberToBytes :: ByteArray bytes => Int -> Integer -> Maybe bytes

-- | Serialize a number according to the SPAKE2 protocol.
--   
--   Panics if the number is too big to fit into the given number of bytes.
unsafeNumberToBytes :: ByteArray bytes => Int -> Integer -> bytes


module Crypto.Spake2.Group

-- | A mathematical group intended to be used with SPAKE2.
--   
--   Notes:
--   
--   <ul>
--   <li>This is a much richer interface than one would expect from a group
--   purely derived from abstract algebra</li>
--   <li>jml thinks this is relevant to all Diffie-Hellman cryptography,
--   but too ignorant to say for sure</li>
--   <li>Is this group automatically abelian? cyclic? Must it have these
--   properties?</li>
--   </ul>
class Group group where type Element group :: * type Scalar group :: * elementSubtract group x y = elementAdd group x (elementNegate group y) where {
    type family Element group :: *;
    type family Scalar group :: *;
}

-- | Group addition.
--   
--   <pre>
--   \x y z -&gt; elementAdd group (elementAdd group x y) z == elementAdd group x (elementAdd group y z)
--   </pre>
elementAdd :: Group group => group -> Element group -> Element group -> Element group

-- | Inverse with respect to group addition.
--   
--   <pre>
--   \x -&gt; (elementAdd group x (elementNegate group x)) == groupIdentity
--   </pre>
--   
--   <pre>
--   \x -&gt; (elementNegate group (elementNegate group x)) == x
--   </pre>
elementNegate :: Group group => group -> Element group -> Element group

-- | Subtract one element from another.
--   
--   <pre>
--   \x y -&gt; (elementSubtract group x y) == (elementAdd group x (elementNegate group y))
--   </pre>
elementSubtract :: Group group => group -> Element group -> Element group -> Element group

-- | Identity of the group.
--   
--   Note [Added for completeness]
--   
--   <pre>
--   \x -&gt; (elementAdd group x groupIdentity) == x
--   </pre>
--   
--   <pre>
--   \x -&gt; (elementAdd group groupIdentity x) == x
--   </pre>
groupIdentity :: Group group => group -> Element group

-- | Multiply an element of the group with respect to a scalar.
--   
--   This is equivalent to adding the element to itself N times, where N is
--   a scalar.
scalarMultiply :: Group group => group -> Scalar group -> Element group -> Element group

-- | Get the scalar that corresponds to an integer.
--   
--   Note [Added for completeness]
--   
--   <pre>
--   \x -&gt; scalarToInteger group (integerToScalar group x) == x
--   </pre>
integerToScalar :: Group group => group -> Integer -> Scalar group

-- | Get the integer that corresponds to a scalar.
--   
--   Note [Added for completeness]
--   
--   <pre>
--   \x -&gt; integerToScalar group (scalarToInteger group x) == x
--   </pre>
scalarToInteger :: Group group => group -> Scalar group -> Integer

-- | Encode an element of the group into bytes.
--   
--   Note [Byte encoding in Group]
--   
--   <pre>
--   \x -&gt; decodeElement group (encodeElement group x) == CryptoPassed x
--   </pre>
encodeElement :: (Group group, ByteArray bytes) => group -> Element group -> bytes

-- | Decode an element into the group from some bytes.
--   
--   Note [Byte encoding in Group]
decodeElement :: (Group group, ByteArray bytes) => group -> bytes -> CryptoFailable (Element group)

-- | Encode a scalar into bytes. | Generate a new random element of the
--   group, with corresponding scalar.
generateElement :: (Group group, MonadRandom randomly) => group -> randomly (KeyPair group)

-- | Size of elements, in bits
elementSizeBits :: Group group => group -> Int

-- | Size of scalars, in bits
scalarSizeBits :: Group group => group -> Int

-- | Deterministically create an arbitrary element from a seed bytestring.
--   
--   <b>XXX</b>: jml would much rather this take a scalar, an element, or
--   even an integer, rather than bytes because bytes mean that the group
--   instances have to know about hash algorithms and HKDF. If the
--   IntegerGroup class in SPAKE2 also oversized its input, then it and the
--   ed25519 implementation would have identical decoding.
arbitraryElement :: (Group group, ByteArrayAccess bytes) => group -> bytes -> Element group

-- | Map some arbitrary bytes into a scalar in a group.
decodeScalar :: (ByteArrayAccess bytes, Group group) => group -> bytes -> Scalar group

-- | Size of elements in a group, in bits.
elementSizeBytes :: Group group => group -> Int

-- | Size of scalars in a group, in bytes.
scalarSizeBytes :: Group group => group -> Int

-- | A group key pair composed of the private part (a scalar) and a public
--   part (associated group element).
data KeyPair group
KeyPair :: !(Element group) -> !(Scalar group) -> KeyPair group
[keyPairPublic] :: KeyPair group -> !(Element group)
[keyPairPrivate] :: KeyPair group -> !(Scalar group)


-- | Each of these implements the <a>Group</a> typeclass.
module Crypto.Spake2.Groups
data Ed25519
Ed25519 :: Ed25519

-- | A finite group of integers with respect to multiplication modulo the
--   group order.
--   
--   Construct with <a>makeIntegerGroup</a>.
data IntegerGroup
IntegerGroup :: !Integer -> !Integer -> !Integer -> IntegerGroup
[order] :: IntegerGroup -> !Integer
[subgroupOrder] :: IntegerGroup -> !Integer
[generator] :: IntegerGroup -> !Integer

-- | Construct an <a>IntegerGroup</a>.
--   
--   Will fail if generator is '1', since having the identity for a
--   generator means the subgroup is the entire group.
--   
--   TODO: Find other things to check for validity.
makeIntegerGroup :: Integer -> Integer -> Integer -> Maybe IntegerGroup

-- | 1024 bit integer group.
--   
--   Originally from
--   <a>http://haofeng66.googlepages.com/JPAKEDemo.java</a>, via
--   <a>python-spake2</a>.
i1024 :: IntegerGroup

-- | Simple integer addition group.
--   
--   Do <b>NOT</b> use this for anything cryptographic.
newtype IntegerAddition
IntegerAddition :: Integer -> IntegerAddition
[modulus] :: IntegerAddition -> Integer


-- | This module ignores everything about networks, bytes, encoding, hash
--   functions, and so forth. All it does is provide the mathematical
--   building blocks for SPAKE2, as per <a>Simple Password-Based Encrypted
--   Key Exchange Protocols</a> by Michel Abdalla and David Pointcheval.
--   
--   <h2>How it works</h2>
--   
--   <h3>Preliminaries</h3>
--   
--   Let's say we have two users, user A and user B. They have already
--   agreed on the following public information:
--   
--   <ul>
--   <li>cyclic group, &lt;math&gt; of prime order, &lt;math&gt;</li>
--   <li>generating element &lt;math&gt;, such that &lt;math&gt;</li>
--   <li>hash algorithm to use, &lt;math&gt;</li>
--   </ul>
--   
--   If the connection is asymmetric (e.g. if user A is a client and user B
--   is a server), then they will also have:
--   
--   <ul>
--   <li>two arbitrary elements in &lt;math&gt;, where &lt;math&gt; is
--   associated with user A and &lt;math&gt; with user B.</li>
--   </ul>
--   
--   If the connection is symmetric (e.g. if user A and B are arbitrary
--   peers), then they will instead have:
--   
--   <ul>
--   <li>a single arbitrary element &lt;math&gt;</li>
--   </ul>
--   
--   The discrete log of these arbitrary elements must be difficult to
--   guess.
--   
--   And, they also have a secret password, which in practice will be an
--   arbitrary byte string, but for the purposes of this module is an
--   arbitrary <i>scalar</i> in the group that is a shared secret between
--   both parties (see <a>Crypto.Spake2.Groups</a> for more information on
--   scalars).
--   
--   <h3>The protocol</h3>
--   
--   <i>This is derived from the paper linked above.</i>
--   
--   One side, A, initiates the exchange. They draw a random scalar,
--   &lt;math&gt;, and matching element, &lt;math&gt;, from the group. They
--   then "blind" &lt;math&gt; by adding it to &lt;math&gt; multiplied by
--   the password in scalar form. Call this &lt;math&gt;.
--   
--   &lt;math&gt;
--   
--   to the other side, side B.
--   
--   Side B does the same thing, except they use &lt;math&gt; instead of
--   &lt;math&gt; to blind the result, and they call it &lt;math&gt;
--   instead of &lt;math&gt;.
--   
--   &lt;math&gt;
--   
--   After side A receives &lt;math&gt;, it calculates &lt;math&gt;, which
--   is the last missing input in calculating the session key.
--   
--   &lt;math&gt;
--   
--   That is, &lt;math&gt; is &lt;math&gt; subtracted from &lt;math&gt;
--   scalar multiplied by &lt;math&gt;, all of which is scalar multiplied
--   by &lt;math&gt;.
--   
--   Side B likewise calculates:
--   
--   &lt;math&gt;
--   
--   If both parties were honest and knew the password, the keys will be
--   the same on both sides. That is:
--   
--   &lt;math&gt;
--   
--   <h3>How to use the keys</h3>
--   
--   The keys &lt;math&gt; and &lt;math&gt; are not enough to securely
--   encrypt a session. They must be used as input to create a session key.
--   
--   Constructing a session key is beyond the scope of this module. See
--   <tt>createSessionKey</tt> for more information.
module Crypto.Spake2.Math

-- | An instance of the SPAKE2 protocol. This represents one side of the
--   protocol.
data Spake2 group
Spake2 :: Params group -> Scalar group -> Spake2 group
[params] :: Spake2 group -> Params group
[password] :: Spake2 group -> Scalar group

-- | The parameters of the SPAKE2 protocol. The other side needs to be
--   using the same values, but with swapped values for <a>ourBlind</a> and
--   <a>theirBlind</a>.
data Params group
Params :: group -> Element group -> Element group -> Params group

-- | The cyclic group used for encrypting keys
[group] :: Params group -> group

-- | The "blind" we use when sending out values. Side A refers to this as
--   &lt;math&gt; in the protocol description.
[ourBlind] :: Params group -> Element group

-- | The "blind" the other side uses when sending values. Side A refers to
--   this as &lt;math&gt; in the protocol description.
[theirBlind] :: Params group -> Element group

-- | Initiate the SPAKE2 exchange. Generates a secret (<tt>xy</tt>) that
--   will be held by this side, and transmitted to the other side in
--   "blinded" form.
startSpake2 :: (Group group, MonadRandom randomly) => Spake2 group -> randomly (Spake2Exchange group)

-- | A SPAKE2 exchange that has been initiated.
data Spake2Exchange group

-- | Determine the element (either &lt;math&gt; or &lt;math&gt;) to send to
--   the other side.
computeOutboundMessage :: Group group => Spake2Exchange group -> Element group

-- | Generate key material, &lt;math&gt;, given a message from the other
--   side (either &lt;math&gt; or &lt;math&gt;).
--   
--   This key material is the last piece of input required to make the
--   session key, &lt;math&gt;, which should be generated as:
--   
--   &lt;math&gt;
--   
--   Where:
--   
--   <ul>
--   <li>&lt;math&gt; is a hash function</li>
--   <li>&lt;math&gt; identifies the initiating side</li>
--   <li>&lt;math&gt; identifies the receiving side</li>
--   <li>&lt;math&gt; is the outbound message from the initiating side</li>
--   <li>&lt;math&gt; is the outbound message from the receiving side</li>
--   <li>&lt;math&gt; is the result of this function</li>
--   <li>&lt;math&gt; is the password (this is what makes it SPAKE2, not
--   SPAKE1)</li>
--   </ul>
generateKeyMaterial :: Group group => Spake2Exchange group -> Element group -> Element group


-- | Say that you and someone else share a secret password, and you want to
--   use this password to arrange some secure channel of communication. You
--   want:
--   
--   <ul>
--   <li>to know that the other party also knows the secret password (maybe
--   they're an imposter!)</li>
--   <li>the password to be secure against offline dictionary attacks</li>
--   <li>probably some other things</li>
--   </ul>
--   
--   SPAKE2 is an algorithm for agreeing on a key exchange that meets these
--   criteria. See <a>Simple Password-Based Encrypted Key Exchange
--   Protocols</a> by Michel Abdalla and David Pointcheval for more
--   details.
--   
--   <h2>How it works</h2>
--   
--   <h3>Preliminaries</h3>
--   
--   Before exchanging, two nodes need to agree on the following,
--   out-of-band:
--   
--   In general:
--   
--   <ul>
--   <li>hash algorithm, &lt;math&gt;</li>
--   <li>group to use, &lt;math&gt;</li>
--   <li>arbitrary members of group to use for blinding</li>
--   <li>a means of converting this password to a scalar of group</li>
--   </ul>
--   
--   For a specific exchange:
--   
--   <ul>
--   <li>whether the connection is symmetric or asymmetric</li>
--   <li>the IDs of the respective sides</li>
--   <li>a shared, secret password in bytes</li>
--   </ul>
--   
--   
--   <h3>Protocol</h3>
--   
--   <h4>How we map the password to a scalar</h4>
--   
--   Use HKDF expansion (see <a>expandData</a>) to expand the password by
--   16 bytes, using an empty salt, and "SPAKE2 pw" as the info.
--   
--   Then, use a group-specific mapping from bytes to scalars. Since
--   scalars are normally isomorphic to integers, this will normally be a
--   matter of converting the bytes to an integer using standard
--   deserialization and then turning the integer into a scalar.
--   
--   <h4>How we exchange information</h4>
--   
--   See <a>Math</a> for details on the mathematics of the exchange.
--   
--   <h4>How python-spake2 works</h4>
--   
--   <ul>
--   <li>Message to other side is prepended with a single character,
--   <tt>A</tt>, <tt>B</tt>, or <tt>S</tt>, to indicate which side it came
--   from</li>
--   <li>The hash function for generating the session key has a few
--   interesting properties:</li>
--   <li>uses SHA256 for hashing</li>
--   <li>does not include password or IDs directly, but rather uses
--   <i>their</i> SHA256 digests as inputs to the hash</li>
--   <li>for the symmetric version, it sorts &lt;math&gt; and &lt;math&gt;,
--   because neither side knows which is which</li>
--   <li>By default, the ID of either side is the empty bytestring</li>
--   </ul>
--   
--   <h2>Open questions</h2>
--   
--   <ul>
--   <li>how does endianness come into play?</li>
--   <li>what is Shallue-Woestijne-Ulas and why is it relevant?</li>
--   </ul>
--   
--   <h2>References</h2>
--   
--   <ul>
--   <li><a>Javascript implementation</a>, includes long, possibly relevant
--   discussion</li>
--   <li><a>Python implementation</a></li>
--   <li><a>SPAKE2 random elements</a> - blog post by warner about choosing
--   &lt;math&gt; and &lt;math&gt;</li>
--   <li><a>Simple Password-Based Encrypted Key Exchange Protocols</a> by
--   Michel Abdalla and David Pointcheval</li>
--   <li><a>draft-irtf-cfrg-spake2-03</a> - expired IRTF draft for
--   SPAKE2</li>
--   </ul>
module Crypto.Spake2

-- | Do-nothing function so that we have something to import in our tests.
--   TODO: Actually test something genuine and then remove this.
something :: a -> a

-- | Shared secret password used to negotiate the connection.
--   
--   Constructor deliberately not exported, so that once a <a>Password</a>
--   has been created, the actual password cannot be retrieved by other
--   modules.
--   
--   Construct with <a>makePassword</a>.
data Password

-- | Construct a password.
makePassword :: ByteString -> Password

-- | Everything required for the SPAKE2 protocol.
--   
--   Both sides must agree on these values for the protocol to work. This
--   <i>mostly</i> means value equality, except for <a>us</a>, where each
--   side must have complementary values.
--   
--   Construct with <a>makeAsymmetricProtocol</a> or
--   <a>makeSymmetricProtocol</a>.
data Protocol group hashAlgorithm

-- | Construct an asymmetric SPAKE2 protocol.
makeAsymmetricProtocol :: hashAlgorithm -> group -> Element group -> Element group -> SideID -> SideID -> WhichSide -> Protocol group hashAlgorithm

-- | Construct a symmetric SPAKE2 protocol.
makeSymmetricProtocol :: hashAlgorithm -> group -> Element group -> SideID -> Protocol group hashAlgorithm

-- | Commence a SPAKE2 exchange.
startSpake2 :: (MonadRandom randomly, Group group) => Protocol group hashAlgorithm -> Password -> randomly (Spake2Exchange group)

-- | Determine the element (either &lt;math&gt; or &lt;math&gt;) to send to
--   the other side.
computeOutboundMessage :: Group group => Spake2Exchange group -> Element group

-- | Generate key material, &lt;math&gt;, given a message from the other
--   side (either &lt;math&gt; or &lt;math&gt;).
--   
--   This key material is the last piece of input required to make the
--   session key, &lt;math&gt;, which should be generated as:
--   
--   &lt;math&gt;
--   
--   Where:
--   
--   <ul>
--   <li>&lt;math&gt; is a hash function</li>
--   <li>&lt;math&gt; identifies the initiating side</li>
--   <li>&lt;math&gt; identifies the receiving side</li>
--   <li>&lt;math&gt; is the outbound message from the initiating side</li>
--   <li>&lt;math&gt; is the outbound message from the receiving side</li>
--   <li>&lt;math&gt; is the result of this function</li>
--   <li>&lt;math&gt; is the password (this is what makes it SPAKE2, not
--   SPAKE1)</li>
--   </ul>
generateKeyMaterial :: Group group => Spake2Exchange group -> Element group -> Element group

-- | Extract an element on the group from an incoming message.
--   
--   Returns a <a>MessageError</a> if we cannot decode the message, or the
--   other side does not appear to be the expected other side.
--   
--   TODO: Need to protect against reflection attack at some point.
extractElement :: Group group => Protocol group hashAlgorithm -> ByteString -> Either MessageError (Element group)

-- | An error that occurs when interpreting messages from the other side of
--   the exchange.
data MessageError

-- | Turn a <a>MessageError</a> into human-readable text.
formatError :: MessageError -> Text

-- | Turn an element into a message from this side of the protocol.
elementToMessage :: Group group => Protocol group hashAlgorithm -> Element group -> ByteString

-- | Create a session key based on the output of SPAKE2.
--   
--   &lt;math&gt;
--   
--   Including &lt;math&gt; in the session key is what makes this SPAKE2,
--   not SPAKE1.
createSessionKey :: (Group group, HashAlgorithm hashAlgorithm) => Protocol group hashAlgorithm -> Element group -> Element group -> Element group -> Password -> ByteString

-- | Bytes that identify a side of the protocol
newtype SideID
SideID :: ByteString -> SideID
[unSideID] :: SideID -> ByteString

-- | Which side we are.
data WhichSide
SideA :: WhichSide
SideB :: WhichSide
instance GHC.Enum.Enum Crypto.Spake2.WhichSide
instance GHC.Enum.Bounded Crypto.Spake2.WhichSide
instance GHC.Show.Show Crypto.Spake2.WhichSide
instance GHC.Classes.Ord Crypto.Spake2.WhichSide
instance GHC.Classes.Eq Crypto.Spake2.WhichSide
instance GHC.Show.Show Crypto.Spake2.MessageError
instance GHC.Classes.Eq Crypto.Spake2.MessageError
instance GHC.Show.Show Crypto.Spake2.SideID
instance GHC.Classes.Ord Crypto.Spake2.SideID
instance GHC.Classes.Eq Crypto.Spake2.SideID
instance GHC.Classes.Ord Crypto.Spake2.Password
instance GHC.Classes.Eq Crypto.Spake2.Password