diff --git a/Yesod/Auth/HashDB.hs b/Yesod/Auth/HashDB.hs --- a/Yesod/Auth/HashDB.hs +++ b/Yesod/Auth/HashDB.hs @@ -20,7 +20,7 @@ -- Portability : Portable -- -- A yesod-auth AuthPlugin designed to look users up in a Persistent --- database where their user id and a hash of their password is stored. +-- database where the hash of their password is stored. -- -- This module was removed from @yesod-auth-1.3.0.0@ and is now -- maintained separately. @@ -51,24 +51,29 @@ -- and can ignore the salt. -- -- In a system which has been migrated from the old format, passwords --- which are reset using the new format will have an empty salt field. +-- which are reset will use the new format and will have an empty salt field. -- Once all the entries are of this form, it is safe to change the model -- to remove the salt, and change the 'HashDBUser' instance accordingly. -- --- To use this in a Yesod application, it must be an instance of --- YesodPersist, and the username and hashed-passwords should be added --- to the database. The followng steps give an outline of what is required. +-- To use this in a Yesod application, the foundation data type must be an +-- instance of YesodPersist, and the username and hashed passwords should +-- be added to the database. The following steps give an outline of what +-- is required. -- -- You need a database table to store user records: in a scaffolded site it -- might look like: -- -- > User --- > name Text -- user name used by HashDB +-- > name Text -- user name used to uniquely identify users -- > password Text Maybe -- password hash for HashDB -- > UniqueUser name -- --- Create an instance of 'HashDBUser' for this data type: +-- Create an instance of 'HashDBUser' for this data type. For historical +-- reasons "Yesod.Auth.HashDB" exports some names which are quite likely to +-- clash with your own, so it is a good idea to import just the ones you need: -- +-- > import Yesod.Auth.HashDB (HashDBUser(..)) +-- > .... -- > instance HashDBUser User where -- > userPasswordHash = userPassword -- > setPasswordHash h u = u { userPassword = Just h } @@ -76,20 +81,25 @@ -- In the YesodAuth instance declaration for your app, include 'authHashDB' -- like so: -- +-- > import Yesod.Auth.HashDB (authHashDB, getAuthIdHashDB) +-- > .... -- > instance YesodAuth App where -- > .... -- > authPlugins _ = [ authHashDB (Just . UniqueUser), .... ] --- > getAuthId = getAuthIdHashDB AuthR (Just . UniqueUser) +-- > getAuthId = getAuthIdHashDB AuthR (Just . UniqueUser) -- Optional, see below -- -- @AuthR@ should be your authentication route, and the function -- @(Just . UniqueUser)@ supplied to both 'authHashDB' and -- 'getAuthIdHashDB' takes a 'Text' and produces a 'Unique' value to --- look up in the User table. 'getAuthIdHashDB' is just a convenience --- for the case when 'HashDB' is the only plugin, and something else --- would be needed when other plugins are used as well. +-- look up in the User table. In a scaffolded site you may not need to +-- change the definition of @getAuthId@ at all, or you may prefer to modify +-- the function which the scaffolding defines: 'getAuthIdHashDB' is just a +-- convenience for the case when 'HashDB' is the only plugin. -- --- You can create password hashes manually as follows, if you need to --- initialise the database: +-- The application developer should provide an interface for setting passwords; +-- it needs to call 'setPassword' and save the result in the database. +-- You can also create password hashes manually as follows, if you need to +-- initialise the database by hand: -- -- > ghci -XOverloadedStrings -- > > import Crypto.PasswordStore @@ -165,8 +175,9 @@ defaultStrength :: Int defaultStrength = 14 --- | Interface for data type which holds user info. It's just a --- collection of getters and setters +-- | The type representing user information stored in the database should +-- be an instance of this class. It just provides the getters and setters +-- used by the functions in this module. class HashDBUser user where -- | Retrieve password hash from user data userPasswordHash :: user -> Maybe Text diff --git a/test/NonDBTests.hs b/test/NonDBTests.hs --- a/test/NonDBTests.hs +++ b/test/NonDBTests.hs @@ -53,11 +53,12 @@ valid `shouldBe` Just True it "still works after a second upgrade to a stronger setting" $ do newuser <- upgradePasswordHash defaultStrength oldStyleValidUser - neweruser <- case newuser of - Just u -> upgradePasswordHash stronger u - Nothing -> return $ Just oldStyleBadUser1 -- failure - let valid = neweruser >>= flip validatePass mypassword - valid `shouldBe` Just True + case newuser of + Just u -> do + neweruser <- upgradePasswordHash stronger u + let valid = neweruser >>= flip validatePass mypassword + valid `shouldBe` Just True + Nothing -> expectationFailure "Failed to upgrade user!" it "is Nothing if there is no password hash" $ do newuser <- upgradePasswordHash defaultStrength oldStyleBadUser1 newuser `shouldBe` Nothing diff --git a/yesod-auth-hashdb.cabal b/yesod-auth-hashdb.cabal --- a/yesod-auth-hashdb.cabal +++ b/yesod-auth-hashdb.cabal @@ -1,5 +1,5 @@ name: yesod-auth-hashdb -version: 1.4.1 +version: 1.4.1.1 license: MIT license-file: LICENSE author: Patrick Brisbin, later changes Paul Rouse @@ -11,7 +11,21 @@ build-type: Simple homepage: https://github.com/paul-rouse/yesod-auth-hashdb bug-reports: https://github.com/paul-rouse/yesod-auth-hashdb/issues -description: This package is the Yesod.Auth.HashDB plugin, originally included in yesod-auth, but now modified to be more secure and placed in a separate package. +description: + This package is the Yesod.Auth.HashDB plugin, originally included as part + of yesod-auth, but now modified to be more secure and placed in a separate + package. + . + It provides authentication using hashed passwords stored in a database, + and works best in situations where an administrator is involved in + setting up a user with an initial password. + . + The complete login process, including a default form, is implemented by + this plugin, but the application developer must design the interfaces + for setting up users and allowing them to change their own passwords, + since only the low-level password-setting functions are provided by this + package. (Note that other authentication plugins may be more appropriate + if you wish to use email verification to set up accounts). library build-depends: base >= 4 && < 5