diff --git a/Crypto/PasswordStore.hs b/Crypto/PasswordStore.hs --- a/Crypto/PasswordStore.hs +++ b/Crypto/PasswordStore.hs @@ -27,15 +27,15 @@ -- The API here is very simple. What you store are called /password hashes/. -- They are strings (technically, ByteStrings) that look like this: -- --- > "sha256|12|Ge9pg8a/r4JW356Uux2JHg==|Fdv4jchzDlRAs6WFNUarxLngaittknbaHFFc0k8hAy0=" +-- > "sha256|14|jEWU94phx4QzNyH94Qp4CQ==|5GEw+jxP/4WLgzt9VS3Ee3nhqBlDsrKiB+rq7JfMckU=" -- -- Each password hash shows the algorithm, the strength (more on that later), -- the salt, and the hashed-and-salted password. You store these on your server, -- in a database, for when you need to verify a password. You make a password -- hash with the 'makePassword' function. Here's an example: -- --- > >>> makePassword "hunter2" 12 --- > "sha256|12|lMzlNz0XK9eiPIYPY96QCQ==|1ZJ/R3qLEF0oCBVNtvNKLwZLpXPM7bLEy/Nc6QBxWro=" +-- > >>> makePassword "hunter2" 14 +-- > "sha256|14|Zo4LdZGrv/HYNAUG3q8WcA==|zKjbHZoTpuPLp1lh6ATolWGIKjhXvY4TysuKvqtNFyk=" -- -- This will hash the password @\"hunter2\"@, with strength 12, which is a good -- default value. The strength here determines how long the hashing will @@ -48,8 +48,8 @@ -- the 'IO' monad, you can generate your own salt and pass it to -- 'makePasswordSalt'. -- --- Your strength value should not be less than 10, and 12 is a good default --- value at the time of this writing, in 2011. +-- Your strength value should not be less than 12, and 14 is a good default +-- value at the time of this writing, in 2013. -- -- Once you've got your password hashes, the second big thing you need to do -- with them is verify passwords against them. When a user gives you a password, @@ -66,12 +66,26 @@ -- password hash with that strength value, which will match the same password as -- the old password hash. -- +-- Note that, as of version 2.4, you can also use PBKDF2, and specify the exact +-- iteration count. This does not have a significant effect on security, but can +-- be handy for compatibility with other code. module Crypto.PasswordStore ( + + -- * Algorithms + pbkdf1, -- :: ByteString -> Salt -> Int -> ByteString + pbkdf2, -- :: ByteString -> Salt -> Int -> ByteString + -- * Registering and verifying passwords makePassword, -- :: ByteString -> Int -> IO ByteString + makePasswordWith, -- :: (ByteString -> Salt -> Int -> ByteString) -> + -- ByteString -> Int -> IO ByteString makePasswordSalt, -- :: ByteString -> ByteString -> Int -> ByteString + makePasswordSaltWith, -- :: (ByteString -> Salt -> Int -> ByteString) -> + -- ByteString -> Salt -> Int -> ByteString verifyPassword, -- :: ByteString -> ByteString -> Bool + verifyPasswordWith, -- :: (ByteString -> Salt -> Int -> ByteString) -> + -- (Int -> Int) -> ByteString -> ByteString -> Bool -- * Updating password hash strength strengthenPassword, -- :: ByteString -> Int -> ByteString @@ -83,11 +97,21 @@ genSaltIO, -- :: IO Salt genSaltRandom, -- :: (RandomGen b) => b -> (Salt, b) makeSalt, -- :: ByteString -> Salt - exportSalt -- :: Salt -> ByteString + exportSalt, -- :: Salt -> ByteString + importSalt -- :: ByteString -> Salt ) where + import qualified Crypto.Hash.SHA256 as H import qualified Data.ByteString.Char8 as B +import qualified Data.ByteString as BS +import qualified Data.ByteString.Lazy as BL +import qualified Data.Binary as Binary +import Control.Monad +import Control.Monad.ST +import Data.STRef +import qualified Data.Digest.Pure.SHA as SHA +import Data.Bits import Data.ByteString.Char8 (ByteString) import Data.ByteString.Base64 (encode, decodeLenient) import System.IO @@ -117,6 +141,57 @@ hashRounds (!bs) 0 = bs hashRounds bs rounds = hashRounds (H.hash bs) (rounds - 1) +-- | Computes the hmacSHA256 of the given message, with the given 'Salt'. +hmacSHA256 :: ByteString + -- ^ The secret (the salt) + -> ByteString + -- ^ The clear-text message + -> ByteString + -- ^ The encoded message +hmacSHA256 secret msg = + let digest = SHA.hmacSha256 (BL.fromStrict secret) (BL.fromStrict msg) + in BL.toStrict . SHA.bytestringDigest $ digest + +-- | PBKDF2 key-derivation function. +-- For details see @http://tools.ietf.org/html/rfc2898@. +-- @32@ is the most common digest size for @SHA256@, and is +-- what the algorithm internally uses. +-- @HMAC+SHA256@ is used as @PRF@, because @HMAC+SHA1@ is considered too weak. +pbkdf2 :: ByteString -> Salt -> Int -> ByteString +pbkdf2 password (SaltBS salt) c = + let hLen = 32 + dkLen = hLen in go hLen dkLen + where + go hLen dkLen | dkLen > (2^32 - 1) * hLen = error "Derived key too long." + | otherwise = + let !l = ceiling ((fromIntegral dkLen / fromIntegral hLen) :: Double) + !r = dkLen - (l - 1) * hLen + chunks = [f i | i <- [1 .. l]] + in (B.concat . init $ chunks) `B.append` B.take r (last chunks) + + -- The @f@ function, as defined in the spec. + -- It calls 'u' under the hood. + f :: Int -> ByteString + f i = let !u1 = hmacSHA256 password (salt `B.append` int i) + -- Using the ST Monad, for maximum performance. + in runST $ do + u <- newSTRef u1 + accum <- newSTRef u1 + forM_ [2 .. c] $ \_ -> do + modifySTRef' u (hmacSHA256 password) + currentU <- readSTRef u + modifySTRef' accum (`xor'` currentU) + readSTRef accum + + -- int(i), as defined in the spec. + int :: Int -> ByteString + int i = let str = BL.unpack . Binary.encode $ i + in BS.pack $ drop (length str - 4) str + + -- | A convenience function to XOR two 'ByteString' together. + xor' :: ByteString -> ByteString -> ByteString + xor' !b1 !b2 = BS.pack $ BS.zipWith xor b1 b2 + -- | Generate a 'Salt' from 128 bits of data from @\/dev\/urandom@, with the -- system RNG as a fallback. This is the function used to generate salts by -- 'makePassword'. @@ -168,36 +243,90 @@ -- High level API ----------------- --- | Hash a password with a given strength (12 is a good default). The output of +-- | Hash a password with a given strength (14 is a good default). The output of -- this function can be written directly to a password file or -- database. Generates a salt using high-quality randomness from -- @\/dev\/urandom@ or (if that is not available, for example on Windows) -- 'System.Random', which is included in the hashed output. makePassword :: ByteString -> Int -> IO ByteString -makePassword password strength = do +makePassword = makePasswordWith pbkdf1 + +-- | A generic version of 'makePassword', which allow the user +-- to choose the algorithm to use. +-- +-- >>> makePasswordWith pbkdf1 "password" 14 +-- +makePasswordWith :: (ByteString -> Salt -> Int -> ByteString) + -- ^ The algorithm to use (e.g. pbkdf1) + -> ByteString + -- ^ The password to encrypt + -> Int + -- ^ log2 of the number of iterations + -> IO ByteString +makePasswordWith algorithm password strength = do salt <- genSaltIO - return $ makePasswordSalt password salt strength + return $ makePasswordSaltWith algorithm (2^) password salt strength --- | Hash a password with a given strength (12 is a good default), using a given +-- | A generic version of 'makePasswordSalt', meant to give the user +-- the maximum control over the generation parameters. +-- Note that, unlike 'makePasswordWith', this function takes the @raw@ +-- number of iterations. This means the user will need to specify a +-- sensible value, typically @10000@ or @20000@. +makePasswordSaltWith :: (ByteString -> Salt -> Int -> ByteString) + -- ^ A function modeling an algorithm (e.g. 'pbkdf1') + -> (Int -> Int) + -- ^ A function to modify the strength + -> ByteString + -- ^ A password, given as clear text + -> Salt + -- ^ A hash 'Salt' + -> Int + -- ^ The password strength (e.g. @10000, 20000, etc.@) + -> ByteString +makePasswordSaltWith algorithm strengthModifier pwd salt strength = writePwHash (strength, salt, hash) + where hash = encode $ algorithm pwd salt (strengthModifier strength) + +-- | Hash a password with a given strength (14 is a good default), using a given -- salt. The output of this function can be written directly to a password file -- or database. Example: -- --- > >>> makePasswordSalt "hunter2" "72cd18b5ebfe6e96" 12 --- > "sha256|12|72cd18b5ebfe6e96|Xkki10Vus/a2SN/LgCVLTT5R30lvHSCCxH6QboV+U3E=" +-- > >>> makePasswordSalt "hunter2" (makeSalt "72cd18b5ebfe6e96") 14 +-- > "sha256|14|NzJjZDE4YjVlYmZlNmU5Ng==|yuiNrZW3KHX+pd0sWy9NTTsy5Yopmtx4UYscItSsoxc=" makePasswordSalt :: ByteString -> Salt -> Int -> ByteString -makePasswordSalt password salt strength = writePwHash (strength, salt, hash) - where hash = encode $ pbkdf1 password salt (2^strength) +makePasswordSalt = makePasswordSaltWith pbkdf1 (2^) --- | @verifyPassword userInput pwHash@ verifies the password @userInput@ given --- by the user against the stored password hash @pwHash@. Returns 'True' if the +-- | 'verifyPasswordWith' @algorithm userInput pwHash@ verifies +-- the password @userInput@ given by the user against the stored password +-- hash @pwHash@, with the hashing algorithm @algorithm@. Returns 'True' if the -- given password is correct, and 'False' if it is not. -verifyPassword :: ByteString -> ByteString -> Bool -verifyPassword userInput pwHash = +-- This function allows the programmer to specify the algorithm to use, +-- e.g. 'pbkdf1' or 'pbkdf2'. +-- Note: If you want to verify a password previously generated with +-- 'makePasswordSaltWith', but without modifying the number of iterations, +-- you can do: +-- +-- > >>> verifyPasswordWith pbkdf2 id "hunter2" "sha256..." +-- > True +-- +verifyPasswordWith :: (ByteString -> Salt -> Int -> ByteString) + -- ^ A function modeling an algorithm (e.g. pbkdf1) + -> (Int -> Int) + -- ^ A function to modify the strength + -> ByteString + -- ^ User password + -> ByteString + -- ^ The generated hash (e.g. sha256|14...) + -> Bool +verifyPasswordWith algorithm strengthModifier userInput pwHash = case readPwHash pwHash of Nothing -> False Just (strength, salt, goodHash) -> - (encode $ pbkdf1 userInput salt (2^strength)) == goodHash + encode (algorithm userInput salt (strengthModifier strength)) == goodHash +-- | Like 'verifyPasswordWith', but uses 'pbkdf1' as algorithm. +verifyPassword :: ByteString -> ByteString -> Bool +verifyPassword = verifyPasswordWith pbkdf1 (2^) + -- | Try to strengthen a password hash, by hashing it some more -- times. @'strengthenPassword' pwHash new_strength@ will return a new password -- hash with strength at least @new_strength@. If the password hash already has @@ -243,7 +372,7 @@ -- this function. makeSalt :: ByteString -> Salt makeSalt = SaltBS . encode . check_length - where check_length salt | B.length salt < 8 = + where check_length salt | B.length salt < 8 = error "Salt too short. Minimum length is 8 characters." | otherwise = salt @@ -252,6 +381,12 @@ exportSalt :: Salt -> ByteString exportSalt (SaltBS bs) = bs +-- | Convert a raw 'ByteString' into a 'Salt'. +-- Use this function with caution, since using a weak salt will result in a +-- weak password. +importSalt :: ByteString -> Salt +importSalt = SaltBS + -- | Is the format of a password hash valid? Attempts to parse a given password -- hash. Returns 'True' if it parses correctly, and 'False' otherwise. isPasswordFormatValid :: ByteString -> Bool @@ -268,4 +403,3 @@ where (a, g') = randomR ('\NUL', '\255') g salt = makeSalt $ B.pack $ map fst (rands gen 16) newgen = snd $ last (rands gen 16) - diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -25,19 +25,19 @@ The API here is very simple. What you store are called *password hashes*. They are strings (technically, ByteStrings) that look like this: - "sha256|12|Ge9pg8a/r4JW356Uux2JHg==|Fdv4jchzDlRAs6WFNUarxLngaittknbaHFFc0k8hAy0=" + "sha256|14|Ge9pg8a/r4JW356Uux2JHg==|Fdv4jchzDlRAs6WFNUarxLngaittknbaHFFc0k8hAy0=" Each password hash shows the algorithm, the strength (more on that later), the salt, and the hashed-and-salted password. You store these on your server, in a database, for when you need to verify a password. You make a password hash with the 'makePassword' function. Here's an example: - >>> makePassword "hunter2" 12 - "sha256|12|lMzlNz0XK9eiPIYPY96QCQ==|1ZJ/R3qLEF0oCBVNtvNKLwZLpXPM7bLEy/Nc6QBxWro=" + >>> makePassword "hunter2" 14 + "sha256|14|Zo4LdZGrv/HYNAUG3q8WcA==|zKjbHZoTpuPLp1lh6ATolWGIKjhXvY4TysuKvqtNFyk=" -This will hash the password "hunter2", with strength 12, which is a good default value. The strength here determines how long the hashing will take. When doing the hashing, we iterate the SHA256 hash function `2^strength` times, so increasing the strength by 1 makes the hashing take twice as long. When computers get faster, you can bump up the strength a little bit to compensate. You can strengthen existing password hashes with the `strengthenPassword` function. Note that `makePassword` needs to generate random numbers, so its return type is `IO ByteString`. If you want to avoid the IO monad, you can generate your own salt and pass it to `makePasswordSalt`. +This will hash the password "hunter2", with strength 14, which is a good default value. The strength here determines how long the hashing will take. When doing the hashing, we iterate the SHA256 hash function `2^strength` times, so increasing the strength by 1 makes the hashing take twice as long. When computers get faster, you can bump up the strength a little bit to compensate. You can strengthen existing password hashes with the `strengthenPassword` function. Note that `makePassword` needs to generate random numbers, so its return type is `IO ByteString`. If you want to avoid the IO monad, you can generate your own salt and pass it to `makePasswordSalt`. -Your strength value should not be less than 10, and 12 is a good default value at the time of this writing, in 2011. +Your strength value should not be less than 12, and 14 is a good default value at the time of this writing, in 2013. Once you've got your password hashes, the second big thing you need to do with them is verify passwords against them. When a user gives you a password, you compare it with a password hash using the `verifyPassword` function: diff --git a/pwstore-fast.cabal b/pwstore-fast.cabal --- a/pwstore-fast.cabal +++ b/pwstore-fast.cabal @@ -1,5 +1,5 @@ Name: pwstore-fast -Version: 2.3 +Version: 2.4 Synopsis: Secure password storage. Description: To store passwords securely, they should be salted, then hashed with a slow hash function. This library @@ -29,6 +29,8 @@ Exposed-modules: Crypto.PasswordStore Build-depends: base >= 4, base < 5, bytestring >= 0.9, base64-bytestring >= 0.1, + binary >= 0.5, + SHA >= 1.6.1, cryptohash >= 0.6, random >= 1 ghc-options: -Wall