diff options
author | Benjamin Barenblat <bbaren@google.com> | 2018-09-04 12:27:10 -0500 |
---|---|---|
committer | Benjamin Barenblat <bbaren@google.com> | 2018-09-04 12:27:10 -0500 |
commit | 67b5043c69648f0e4b9d9138a03cce154c20e38d (patch) | |
tree | 9c73bceb27205c112fe97fad14eae6683e2d8d41 /src/Data/Digest.hs | |
parent | fadd7434be6bfc11483dc188aa6e4267e01d5c40 (diff) |
Documentation improvements
Diffstat (limited to 'src/Data/Digest.hs')
-rw-r--r-- | src/Data/Digest.hs | 60 |
1 files changed, 52 insertions, 8 deletions
diff --git a/src/Data/Digest.hs b/src/Data/Digest.hs index 336b38d..a17c438 100644 --- a/src/Data/Digest.hs +++ b/src/Data/Digest.hs @@ -12,15 +12,33 @@ -- License for the specific language governing permissions and limitations under -- the License. +{-| + Module: Data.Digest + Description: Cryptographic hash functions + Copyright: 2017 Google LLC + License: Apache License, version 2.0 + + Cryptographic hash functions. +-} module Data.Digest - ( Algorithm - , Digest + ( -- * Computing digests + Digest , hash + + -- * Digest algorithms + , Algorithm + + -- ** 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 + + -- * Legacy functions , md5 , sha1 - , sha224, sha256, sha384, sha512 ) where +import qualified Data.ByteString.Lazy as Lazy (ByteString) import qualified Data.ByteString.Lazy as ByteString.Lazy import Foreign (withForeignPtr) import Foreign.Marshal.Unsafe (unsafeLocalState) @@ -30,18 +48,44 @@ import BTLS.BoringSSL.Digest import BTLS.Buffer (onBufferOfMaxSize) import BTLS.Types (Algorithm(Algorithm), Digest(Digest)) -type LazyByteString = ByteString.Lazy.ByteString +-- | Message Digest 5, a 128-bit digest defined in +-- [RFC 1321](https://tools.ietf.org/html/rfc1321). This algorithm is +-- cryptographically broken; do not use it except to interface with legacy +-- applications. +md5 :: Algorithm +md5 = Algorithm evpMD5 + +-- | Secure Hash Algorithm 1, a 160-bit digest defined in +-- [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final). +-- Hashing with this algorithm is cryptographically broken, although +-- constructing HMACs with it is safe. +sha1 :: Algorithm +sha1 = Algorithm evpSHA1 -md5, sha1, sha224, sha256, sha384, sha512 :: Algorithm -md5 = Algorithm evpMD5 -sha1 = Algorithm evpSHA1 +-- | The SHA224 digest, a 224-bit digest and Secure Hash Algorithm 2 family +-- member. +sha224 :: Algorithm sha224 = Algorithm evpSHA224 + +-- | The SHA256 digest, a 256-bit digest and Secure Hash Algorithm 2 family +-- member. Prefer this algorithm on 32-bit CPUs; it will run faster than +-- 'sha384' or 'sha512'. +sha256 :: Algorithm sha256 = Algorithm evpSHA256 + +-- | The SHA384 digest, a 384-bit digest and Secure Hash Algorithm 2 family +-- member. +sha384 :: Algorithm sha384 = Algorithm evpSHA384 + +-- | The SHA512 digest, a 512-bit digest and Secure Hash Algorithm 2 family +-- member. Prefer this algorithm on 64-bit CPUs; it will run faster than +-- 'sha224' or 'sha256'. +sha512 :: Algorithm sha512 = Algorithm evpSHA512 -- | Hashes according to the given 'Algorithm'. -hash :: Algorithm -> LazyByteString -> Digest +hash :: Algorithm -> Lazy.ByteString -> Digest hash (Algorithm md) bytes = unsafeLocalState $ do ctxFP <- mallocEVPMDCtx |