From 67b5043c69648f0e4b9d9138a03cce154c20e38d Mon Sep 17 00:00:00 2001
From: Benjamin Barenblat <bbaren@google.com>
Date: Tue, 4 Sep 2018 12:27:10 -0500
Subject: Documentation improvements

---
 src/Codec/Crypto/HKDF.hs | 65 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 7 deletions(-)

(limited to 'src/Codec/Crypto/HKDF.hs')

diff --git a/src/Codec/Crypto/HKDF.hs b/src/Codec/Crypto/HKDF.hs
index f40f707..bc1ea61 100644
--- a/src/Codec/Crypto/HKDF.hs
+++ b/src/Codec/Crypto/HKDF.hs
@@ -12,9 +12,44 @@
 -- License for the specific language governing permissions and limitations under
 -- the License.
 
+{-|
+  Module: Codec.Crypto.HKDF
+  Description: Hash-based key derivation
+  Copyright: 2018 Google LLC
+  License: Apache License, version 2.0
+
+  The hash-based key derivation function (HKDF), as specified in
+  [RFC 5869](https://tools.ietf.org/html/rfc5869).
+-}
 module Codec.Crypto.HKDF
-  ( AssociatedData(AssociatedData), Salt(Salt), SecretKey(SecretKey), noSalt
-  , hkdf, extract, expand
+  ( -- * Computing keys
+    SecretKey(SecretKey)
+  , hkdf
+  , extract
+  , expand
+
+    -- * Cryptographic hash algorithms
+  , Algorithm
+  , sha1
+
+    -- ** SHA-2 family
+    -- | The SHA-2 family of hash functions is defined in
+    -- [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final).
+  , sha224, sha256, sha384, sha512
+
+    -- * Salt
+
+    -- | You may salt the hash used to generate the key. If you do not wish to
+    -- do so, specify 'noSalt' as the salt.
+  , Salt(Salt), noSalt
+
+    -- * Associated data
+    -- | You may mix in arbitrary data when generating a key. If you do not wish
+    -- to do so, specify the empty string as the associated data.
+  , AssociatedData(AssociatedData)
+
+    -- * Legacy functions
+  , md5
   ) where
 
 import Foreign (allocaArray)
@@ -27,12 +62,23 @@ import BTLS.Types
   ( Algorithm(Algorithm), AssociatedData(AssociatedData), Salt(Salt)
   , SecretKey(SecretKey), noSalt
   )
+import Data.Digest (md5, sha1, sha224, sha256, sha384, sha512)
 
--- | Computes an HKDF as specified by RFC 5869.
-hkdf :: Algorithm -> Salt -> AssociatedData -> Int -> SecretKey -> SecretKey
+-- | Computes an HKDF. It is defined by
+--
+-- prop> hkdf md salt info len = expand md info len . extract md salt
+--
+-- but may be faster than calling the two functions individually.
+hkdf ::
+     Algorithm
+  -> Salt
+  -> AssociatedData
+  -> Int -- ^ The length of the derived key, in bytes.
+  -> SecretKey
+  -> SecretKey
 hkdf md salt info outLen = expand md info outLen . extract md salt
 
--- | Computes an HKDF pseudorandom key (PRK) as specified by RFC 5869.
+-- | Computes an HKDF pseudorandom key (PRK).
 extract :: Algorithm -> Salt -> SecretKey -> SecretKey
 extract (Algorithm md) (Salt salt) (SecretKey secret) =
   SecretKey $
@@ -40,8 +86,13 @@ extract (Algorithm md) (Salt salt) (SecretKey secret) =
       onBufferOfMaxSize evpMaxMDSize $ \pOutKey pOutLen -> do
         hkdfExtract pOutKey pOutLen md secret salt
 
--- | Computes HKDF output key material (OKM) as specified by RFC 5869.
-expand :: Algorithm -> AssociatedData -> Int -> SecretKey -> SecretKey
+-- | Computes HKDF output key material (OKM).
+expand ::
+     Algorithm
+  -> AssociatedData
+  -> Int -- ^ The length of the OKM, in bytes.
+  -> SecretKey
+  -> SecretKey
 expand (Algorithm md) (AssociatedData info) outLen (SecretKey secret) =
   SecretKey $
     unsafeLocalState $
-- 
cgit v1.2.3