diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,6 +1,17 @@ # ChangeLog / ReleaseNotes +## Version 0.6.1.1 + +* Cleanup of version dependencies, most importantly: + * Bumped transformers dependency from `< 0.4` to `0.5`. + * Bumped criterion minimal version to 1.0.0.0. This required update of + benchmarking code. +* Documentation updates. +* Uploaded to [Hackage][]: + + + ## Version 0.6.1.0 * Function `mkSalt` rejects empty `ByteString` and returns `Nothing` for it. diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2009, 2010, 2012 - 2014, Peter Trsko +Copyright (c) 2009, 2010, 2012-2015, Peter Trsko All rights reserved. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,22 +1,24 @@ -Apache MD5 -========== +# Apache MD5 +[![Hackage](http://img.shields.io/hackage/v/apache-md5.svg)][Hackage: apache-md5] +[![Haskell Programming Language](https://img.shields.io/badge/language-Haskell-blue.svg)][Haskell.org] +[![BSD3 License](http://img.shields.io/badge/license-BSD3-brightgreen.svg)][tl;dr Legal: BSD3] -Description ------------ + +## Description + Haskell implementation of Apache specific MD5 digest algorithm that uses OpenSSL MD5. -Documentation -------------- +## Documentation -Stable releases with API documentation are available on [Hackage][]. +Stable releases with API documentation are available on +[Hackage][Hackage: apache-md5]. -Installation ------------- +## Installation Requires OpenSSL library with header files. On Debian and Ubuntu Linux it's provided by [`libssl-dev`][libssl-dev] package that can be installed using @@ -31,9 +33,15 @@ For details see [HaskellWiki: How to install a Cabal package][]. -Example -------- +### Building Options +* `-fpedantic` (disabled by default) + + Pass additional warning flags to GHC. + + +## Example + Create htpasswd like entry and print it to stdout: ```Haskell @@ -98,8 +106,7 @@ foo:$apr1$yM9AMlr2$EHssuHrqSAe8HPrAdN7HC/ -Unit Tests ----------- +## Unit Tests Requires `htpasswd` command line utility installed. On Debian and Ubuntu Linux it is provided by [`apache2-utils`][apache2-utils] package that can be @@ -115,8 +122,7 @@ $ cabal configure --enable-tests && cabal build && cabal test -Benchmarks ----------- +## Benchmarks This package provides [Criterion][] benchmarks, to run them you can use something like: @@ -131,25 +137,37 @@ Where `benchmarks.html` is the name of [Criterion][] generated HTML file. -Contributions -------------- +## Contributions Contributions, pull requests and bug reports are welcome! Please don't be -afraid to contact author using GitHub or by e-mail (see `.cabal` file for -that). +afraid to contact the author. + +[apache2-utils]: + http://packages.debian.org/stable/apache2-utils + "apache2-utils Debian package" [apt-get-howto]: https://help.ubuntu.com/community/AptGet/Howto -[libssl-dev]: - http://packages.debian.org/lenny/libssl-dev + "apt-get Howto" [cabal-install]: http://haskell.org/haskellwiki/Cabal-Install + "HaskellWiki: Cabal-install" [Criterion]: http://hackage.haskell.org/package/criterion -[Hackage]: + "criterion package on Hackage" +[Hackage: apache-md5]: http://hackage.haskell.org/package/apache-md5 + "apache-md5 package on Hackage" +[Haskell.org]: + http://www.haskell.org + "The Haskell Programming Language" [HaskellWiki: How to install a Cabal package]: http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package -[apache2-utils]: - http://packages.debian.org/stable/apache2-utils + "HaskellWiki: How to install a Cabal package" +[libssl-dev]: + http://packages.debian.org/lenny/libssl-dev + "libssl-dev Debian package" +[tl;dr Legal: BSD3]: + https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29 + "BSD 3-Clause License (Revised)" diff --git a/apache-md5.cabal b/apache-md5.cabal --- a/apache-md5.cabal +++ b/apache-md5.cabal @@ -1,21 +1,18 @@ name: apache-md5 -version: 0.6.1.0 +version: 0.6.1.1 synopsis: Apache specific MD5 digest algorighm. description: Haskell implementation of Apache HTTP server specific MD5 digest algorithm that uses OpenSSL @MD5()@ function. . - README and ChangeLog can be found in source code package and on GitHub: - . - * - . - * + For usage example see "Data.Digest.ApacheMD5" module or + . homepage: https://github.com/trskop/apache-md5 bug-reports: https://github.com/trskop/apache-md5/issues license: BSD3 license-File: LICENSE -copyright: (c) 2009, 2010, 2012 - 2014 Peter Trško +copyright: (c) 2009, 2010, 2012-2015 Peter Trško author: Peter Trško maintainer: peter.trsko@gmail.com category: Data, Cryptography @@ -29,9 +26,9 @@ flag pedantic - description: - Pass additional warning flags including -Werror to GHC during compilation. + description: Pass additional warning flags to GHC. default: False + manual: True flag deepseq description: @@ -57,10 +54,11 @@ extra-libraries: crypto ghc-options: -Wall - if impl(ghc >= 6.8) - ghc-options: -fwarn-tabs if flag(pedantic) - ghc-options: -Werror + ghc-options: + -fwarn-tabs + -fwarn-implicit-prelude +-- -Werror test-suite apache-md5-unit-tests hs-source-dirs: src, test @@ -71,40 +69,35 @@ , Data.Digest.ApacheMD5.Internal build-depends: + -- {{{ Distributed with GHC or Haskell Platform --------------------------- + -- {{{ Dependencies of apache-md5 library --------------------------------- base >= 4 && < 5 , bytestring >= 0.10 && < 0.11 - , transformers < 0.4 + -- }}} Dependencies of apache-md5 library --------------------------------- - , MonadRandom - , process - , random + , process > 1.1.0.1 && < 1.3 + , random >= 1.0.1.1 && < 2 + , transformers >= 0.3 && < 0.5 + -- }}} Distributed with GHC or Haskell Platform --------------------------- - -- Test dependencies: + , MonadRandom >= 0.2.0.1 && < 0.4 , HUnit >= 1.2 && < 2 -- ^ Same constraints as test-framework-hunit - -- , QuickCheck >= 2.4 && < 2.6 - -- ^ Same constraints as test-framework-quickcheck2 , test-framework >= 0.8 && < 1 -- ^ Same constraint as test-framework-skip, other packages that -- depend on it have less restrictive bounds. - , test-framework-hunit >= 0.2.6 + , test-framework-hunit >= 0.2.6 && < 1 -- ^ Lower versions have more restrictive bounds on test-framework. - -- , test-framework-quickcheck2 >= 0.3 - -- ^ There were changes in QuickCheck bounds in 0.2 branch and last one - -- on it had a compilation failure on Hackage. - -- Not required right now: - -- , test-framework-skip == 1.* - -- ^ Currently there is only version 1.0. - Includes: openssl/md5.h Extra-Libraries: crypto ghc-options: -Wall - if impl(ghc >= 6.8) - ghc-options: -fwarn-tabs if flag(pedantic) - ghc-options: -Werror + ghc-options: + -fwarn-tabs + -fwarn-implicit-prelude +-- -Werror benchmark apache-md5-benchmark hs-source-dirs: src, test @@ -115,23 +108,27 @@ , Data.Digest.ApacheMD5.Internal build-depends: + -- {{{ Distributed with GHC or Haskell Platform --------------------------- + -- {{{ Dependencies of apache-md5 library --------------------------------- base >= 4 && < 5 , bytestring >= 0.10 && < 0.11 - - , criterion , deepseq >= 1.1.0.0 - -- Same minimal bound as criterion has since version 0.4.0. - , MonadRandom + -- ^ Same minimal bound as criterion has since version 0.4.0. + -- }}} Dependencies of apache-md5 library --------------------------------- + , criterion >= 1.0.0.0 && < 2 + , MonadRandom >= 0.2.0.1 && < 0.4 + includes: openssl/md5.h extra-libraries: crypto cpp-options: -DWITH_deepseq ghc-options: -Wall - if impl(ghc >= 6.8) - ghc-options: -fwarn-tabs if flag(pedantic) - ghc-options: -Werror + ghc-options: + -fwarn-tabs + -fwarn-implicit-prelude +-- -Werror source-repository head type: git @@ -140,4 +137,4 @@ source-repository this type: git location: git://github.com/trskop/apache-md5.git - tag: v0.6.1.0 + tag: v0.6.1.1 diff --git a/src/Data/Digest/ApacheMD5.hs b/src/Data/Digest/ApacheMD5.hs --- a/src/Data/Digest/ApacheMD5.hs +++ b/src/Data/Digest/ApacheMD5.hs @@ -1,12 +1,11 @@ {-# LANGUAGE NoImplicitPrelude #-} -- | -- Module: Data.Digest.ApacheMD5 --- Copyright: (c) 2009, 2010, 2012 - 2014 Peter Trško +-- Copyright: (c) 2009, 2010, 2012-2015 Peter Trško -- License: BSD3 -- Maintainer: Peter Trško -- Stability: Provisional --- Portability: non-portable (NoImplicitPrelude, depends on non-portable --- internal module) +-- Portability: NoImplicitPrelude; depends on non-portable internal module -- -- ApacheMD5 is one of the hash algorithms used by Apache HTTP server for basic -- authentication. It is Apache specific, but e.g. nginx supports this @@ -34,18 +33,20 @@ -- | Output of 'apacheMD5' function is not identical to what @htpasswd@ -- does. To create @htpasswd@-like entry one needs to do: -- - -- > import Data.ByteString (ByteString) - -- > import qualified Data.ByteString.Char8 as C8 (concat, pack, singleton) - -- > import Data.Digest.ApacheMD5 (Salt, apacheMD5, unSalt) - -- > - -- > htpasswdEntry :: ByteString -> ByteString -> Salt -> ByteString - -- > htpasswdEntry username password salt = C8.concat - -- > [ username - -- > , C8.pack ":$apr1$" - -- > , unSalt salt - -- > , C8.singleton '$' - -- > , apacheMD5 password salt - -- > ] + -- @ + -- import Data.ByteString (ByteString) + -- import qualified Data.ByteString.Char8 as C8 (concat, pack, singleton) + -- import Data.Digest.ApacheMD5 ('Salt', 'apacheMD5', 'unSalt') + -- + -- htpasswdEntry :: ByteString -> ByteString -> 'Salt' -> ByteString + -- htpasswdEntry username password salt = C8.concat + -- [ username + -- , C8.pack \":$apr1$\" + -- , 'unSalt' salt + -- , C8.singleton \'$\' + -- , 'apacheMD5' password salt + -- ] + -- @ -- * API Documentation apacheMD5 diff --git a/src/Data/Digest/ApacheMD5/Internal.hs b/src/Data/Digest/ApacheMD5/Internal.hs --- a/src/Data/Digest/ApacheMD5/Internal.hs +++ b/src/Data/Digest/ApacheMD5/Internal.hs @@ -16,12 +16,12 @@ -- | -- Module: Data.Digest.ApacheMD5.Internal --- Copyright: (c) 2009, 2010, 2012 - 2014 Peter Trško +-- Copyright: (c) 2009, 2010, 2012-2015 Peter Trško -- License: BSD3 -- Maintainer: Peter Trško -- Stability: Provisional --- Portability: non-portable (BangPatterns, CPP, DeriveDataTypeable, --- DeriveGeneric, ForeignFunctionInterface, NoImplicitPrelude) +-- Portability: BangPatterns, CPP, DeriveDataTypeable, DeriveGeneric, +-- ForeignFunctionInterface, NoImplicitPrelude -- -- Internal and unsafe functions used for implementing Apache MD5 -- hash algorithm. @@ -64,7 +64,7 @@ import Data.Function ((.), ($)) import Data.Int (Int) import Data.List (concatMap, foldl1, iterate, map, replicate, take) -import Data.Ord (Ord((<), (<=), (>), (>=))) +import Data.Ord (Ord((<=), (>), (>=))) import Data.Word (Word8, Word16, Word32) import Foreign (Ptr) import Foreign.C.Types (CChar(..), CULong(..)) @@ -107,7 +107,8 @@ -- | Apache MD5 hash salt. When constructing @.htpasswd@ file it is necessary -- for the salt to be consisting of octets from 'alpha64' \"set\". This newtype --- along with @mkSalt@ smart constructor are here to ensure such invariant. +-- along with 'Data.Digest.ApacheMD5.mkSalt' smart constructor are here to +-- ensure such invariant. newtype Salt = Salt ByteString deriving ( Eq, Ord, Read, Show @@ -124,7 +125,10 @@ #endif -- | Raw Apache MD5 implementation that is parametrized by MD5 implementation --- and doesn't encode result in to base 64. +-- and doesn't encode result in to Base64. +-- +-- This module provides 'encode64' for producing Apache `htpasswd` compatible +-- Base64 encoding. apacheMD5 :: (ByteString -> ByteString) -- ^ MD5 hash function. @@ -160,12 +164,12 @@ -- 999. g' :: Word16 -> ByteString -> ByteString g' !i !digest - | i < 1000 = g' (i + 1) . md5 + | i >= 1000 = digest + | otherwise = g' (i + 1) . md5 $ (if i .&. 1 == 1 then password else digest) <> (if i `mod` 3 > 0 then salt else BS.empty) <> (if i `mod` 7 > 0 then password else BS.empty) <> (if i .&. 1 == 1 then digest else password) - | otherwise = digest -- | Alphabet used by 'encode64'. alpha64 :: ByteString @@ -188,7 +192,7 @@ _a = 97 -- 'a' _z = 122 -- 'z' --- | Encode raw MD5 hash in to Base64-like encoding. +-- | Encode raw MD5 hash in to Base64-like encoding used by Apache `htpasswd`. encode64 :: ByteString -> ByteString encode64 str = BS.pack $ concatMap (encode64' str) -- Index --. ,-- Shift bits left this much diff --git a/test/benchmark-main.hs b/test/benchmark-main.hs --- a/test/benchmark-main.hs +++ b/test/benchmark-main.hs @@ -5,7 +5,6 @@ import Control.Applicative ((<$>)) import Control.Monad (Monad((>>=), return), replicateM) -import Data.Bool (Bool(True)) import Data.Function ((.), ($)) import Data.Int (Int) import Data.String (String) @@ -15,8 +14,7 @@ import Data.ByteString (ByteString) import Control.Monad.Random -import Criterion.Config (Config(cfgPerformGC), defaultConfig, ljust) -import Criterion.Main (bench, defaultMainWith, nf) +import Criterion.Main (bench, defaultMain, nf) import qualified Data.ByteString as BS import qualified Data.ByteString.Char8 as C8 @@ -49,7 +47,7 @@ (!inputData256, _) <- genData' 256 (!inputData512, _) <- genData' 512 - defaultMainWith defaultConfig{cfgPerformGC = ljust True} (return ()) + defaultMain [ bench "Random passwords of length 8" $ test inputData8 , bench "Random passwords of length 16" $ test inputData16 , bench "Random passwords of length 32" $ test inputData32