SRP6: review, refactor, fix issue #28

This includes only the relevant modules from `botan-bindings` and `botan-low`.

In particular, we work around a bug in `srp6ServerSessionStep1` in `botan-low`
where an exception is thrown from C code by `botan_srp6_server_session_step1`
because it is called twice by `srp6ServerSessionStep1`. This is bug in the Botan
C++ library, see randombit/botan#5112.

The best we can do for now is to try to not trigger the exception. The
work-around we introduce is to make sure we call the erroring function
(`botan_srp6_server_session_step1`) only once. Previously, we were calling it
once to "query" the size of output buffers, and then again with the correct
sizes of output buffers. We can instead use
`botan_srp6_group_size`/`srp6GroupSize` to determine the correct sizes of output
buffers immediately. This is now done this way automatically where appropriate
in `botan-low`, but not in `botan-bindings`. Moreover, users can still call
`botan_srp6_server_session_step1`/`srp6ServerSessionStep1` twice if they want
to, meaning that the exception can still be triggered. To warn against this, we
make sure to include appropriate warnings in the Haddock documentation.

The other smaller changes do not affect the functionality of the code, only
documentation and such.

Author: jorisdral

botan-bindings/src/Botan/Bindings/SRP6.hs

@@ -8,26 +8,9 @@ Maintainer  : [email protected], [email protected]
 Stability   : experimental
 Portability : POSIX
 
-The library contains an implementation of the SRP6-a password
-authenticated key exchange protocol.
-
-A SRP client provides what is called a SRP verifier to the server.
-This verifier is based on a password, but the password cannot be
-easily derived from the verifier (however brute force attacks are
-possible). Later, the client and server can perform an SRP exchange,
-which results in a shared secret key. This key can be used for
-mutual authentication and/or encryption.
-
-SRP works in a discrete logarithm group. Special parameter sets for
-SRP6 are defined, denoted in the library as “modp/srp/<size>”, for
-example “modp/srp/2048”.
-
-Warning
-
-While knowledge of the verifier does not easily allow an attacker to
-get the raw password, they could still use the verifier to impersonate
-the server to the client, so verifiers should be protected as carefully
-as a plaintext password would be.
+This module is based on the [Secure Remote
+Password](https://botan.randombit.net/handbook/api_ref/srp.html) section of the
+C++ API reference.
 -}
 
 {-# LANGUAGE CApiFFI #-}
@@ -50,12 +33,15 @@ import           Botan.Bindings.RNG
 -- | Opaque SRP-6 server session struct
 data {-# CTYPE "botan/ffi.h" "struct botan_srp6_server_session_struct" #-} BotanSRP6ServerSessionStruct
 
--- | Botan SRP-6 server session object
+-- | SRP-6 server session object
 newtype {-# CTYPE "botan/ffi.h" "botan_srp6_server_session_t" #-} BotanSRP6ServerSession
   = MkBotanSRP6ServerSession { runBotanSRP6ServerSession :: Ptr BotanSRP6ServerSessionStruct }
       deriving newtype (Eq, Ord, Storable)
 
 -- | Frees all resources of the SRP-6 server session object
+--
+-- NOTE: this a binding to the /address/ of the
+-- @botan_srp6_server_session_destroy@ C function.
 foreign import capi safe "botan/ffi.h &botan_srp6_server_session_destroy"
   botan_srp6_server_session_destroy
     :: FinalizerPtr BotanSRP6ServerSessionStruct
@@ -66,7 +52,14 @@ foreign import capi safe "botan/ffi.h botan_srp6_server_session_init"
     :: Ptr BotanSRP6ServerSession -- ^ __srp6__: SRP-6 server session object
     -> IO CInt
 
--- | SRP-6 Server side step 1: Generate a server B-value
+-- | SRP-6 Server side step 1
+--
+-- NOTE: this function should be not be invoked twice on the same server
+-- session. Regardless of the result of the first invocation, the second
+-- invocation will result in an error. See
+-- https://github.com/randombit/botan/issues/5112 for more information. If a
+-- second invocation can not be prevented, try it on a newly initialised server
+-- session instead.
 foreign import capi safe "botan/ffi.h botan_srp6_server_session_step1"
   botan_srp6_server_session_step1
     :: BotanSRP6ServerSession -- ^ __srp6__: SRP-6 server session object
@@ -79,7 +72,7 @@ foreign import capi safe "botan/ffi.h botan_srp6_server_session_step1"
     -> Ptr CSize              -- ^ __B_pub_len__: SRP-6 B value length
     -> IO CInt                -- ^ 0 on success, negative on failure
 
--- | SRP-6 Server side step 2:  Generate the server shared key
+-- | SRP-6 Server side step 2
 foreign import capi safe "botan/ffi.h botan_srp6_server_session_step2"
   botan_srp6_server_session_step2
     :: BotanSRP6ServerSession -- ^ __srp6__: SRP-6 server session object
@@ -89,7 +82,7 @@ foreign import capi safe "botan/ffi.h botan_srp6_server_session_step2"
     -> Ptr CSize              -- ^ __key_len__: symmetric key length
     -> IO CInt                -- ^ 0 on success, negative on failure
 
--- | SRP-6 Client side step 1:  Generate a new SRP-6 verifier
+-- | Generate a new SRP-6 verifier
 foreign import capi safe "botan/ffi.h botan_srp6_generate_verifier"
   botan_srp6_generate_verifier
     :: ConstPtr CChar -- ^ __identifier__: a username or other client identifier
@@ -102,7 +95,7 @@ foreign import capi safe "botan/ffi.h botan_srp6_generate_verifier"
     -> Ptr CSize      -- ^ __verifier_len__: SRP-6 verifier value length
     -> IO CInt        -- ^ 0 on success, negative on failure
 
--- | SRP6a Client side step 2:  Generate a client A-value and the client shared key
+-- | SRP6a Client side
 foreign import capi safe "botan/ffi.h botan_srp6_client_agree"
   botan_srp6_client_agree
     :: ConstPtr CChar -- ^ __username__: the username we are attempting login for
@@ -111,7 +104,7 @@ foreign import capi safe "botan/ffi.h botan_srp6_client_agree"
     -> ConstPtr CChar -- ^ __hash_id__: specifies a secure hash function
     -> ConstPtr Word8 -- ^ __salt[]__: is the salt value sent by the server
     -> CSize          -- ^ __salt_len__: the length of salt
-    -> ConstPtr Word8 -- ^ __uint8_t__: B[] is the server's public value
+    -> ConstPtr Word8 -- ^ __B[]__: is the server's public value
     -> CSize          -- ^ __B_len__: is the server's public value length
     -> BotanRNG       -- ^ __rng_obj__: is a random number generator object
     -> Ptr Word8      -- ^ __A[]__: out buffer to store the SRP-6 A value
@@ -121,6 +114,11 @@ foreign import capi safe "botan/ffi.h botan_srp6_client_agree"
     -> IO CInt        -- ^ 0 on success, negative on failure
 
 -- | Return the size, in bytes, of the prime associated with group_id
+--
+-- This function can be used to determine the size of output buffers for
+-- generated keys in the SRP6 algorithm. Such buffers need to be allocated
+-- before calling SRP6 functions. An example of such a buffer is the
+-- @verifier[]@ buffer in the 'botan_srp6_generate_verifier' function.
 foreign import capi safe "botan/ffi.h botan_srp6_group_size"
   botan_srp6_group_size
     :: ConstPtr CChar -- ^ __group_id__