Documentation

Overview

Package passlib provides a simple password hashing and verification interface abstracting multiple password hashing schemes.

After initialisation, most people need concern themselves only with the functions Hash and Verify, which uses the default context and sensible defaults.

Library Initialization

You should initialise the library before using it with the following line.

// Call this at application startup.
passlib.UseDefaults(passlib.Defaults20180601)

See func UseDefaults for details.

Index

Examples

Constants

View Source
const Defaults20160922 = "20160922"

    This is the first and default set of defaults used by passlib. It prefers scrypt-sha256. It is now obsolete.

    View Source
    const Defaults20180601 = "20180601"

      This is the most up-to-date set of defaults preferred by passlib. It prefers Argon2i. You must opt into it by calling UseDefaults at startup.

      View Source
      const DefaultsLatest = "latest"

        This value, when passed to UseDefaults, causes passlib to always use the very latest set of defaults. DO NOT use this unless you are sure that opportunistic hash upgrades will not cause breakage for your application when future versions of passlib are released. See func UseDefaults.

        Variables

        View Source
        var DefaultSchemes []abstract.Scheme

          The default schemes, most preferred first. The first scheme will be used to hash passwords, and any of the schemes may be used to verify existing passwords. The contents of this value may change with subsequent releases.

          If you want to change this, set DefaultSchemes to a slice to an abstract.Scheme array of your own construction, rather than mutating the array the slice points to.

          To see the default schemes used in the current release of passlib, see default.go. See also the UseDefaults function for more information on how the list of default schemes is determined. The default value of DefaultSchemes (the default defaults) won't change; you need to call UseDefaults to allow your application to upgrade to newer hashing schemes (or set DefaultSchemes manually, or create a custom context with its own schemes set).

          Functions

          func Hash

          func Hash(password string) (hash string, err error)

            Hashes a UTF-8 plaintext password using the default context and produces a password hash. Chooses the preferred password hashing scheme based on the configured policy. The default policy is sensible.

            Example (Signup)

              User signup example.

              Output:
              
              

              func NeedsUpdate

              func NeedsUpdate(stub string) bool

                Uses the default context to determine whether a stub or hash needs updating.

                func UseDefaults

                func UseDefaults(date string) error

                  It is strongly recommended that you call this function like this before using passlib:

                  passlib.UseDefaults("YYYYMMDD")
                  

                  where YYYYMMDD is a date. This will be used to select the preferred scheme to use. If you do not call UseDefaults, the preferred scheme (the first item in the default schemes list) current as of 2016-09-22 will always be used, meaning that upgrade will not occur even though better schemes are now available.

                  Note that even if you don't call this function, new schemes will still be added to DefaultSchemes over time as non-initial values (items not at index 0), so servers will always, by default, be able to validate all schemes which passlib supports at any given time.

                  The reason you must call this function is as follows: If passlib is deployed as part of a web application in a multi-server deployment, and passlib is updated, and the new version of that application with the updated passlib is deployed, that upgrade process is unlikely to be instantaneous. Old versions of the web application may continue to run on some servers. If merely upgrading passlib caused password hashes to be upgraded to the newer scheme on login, the older daemons may not be able to validate these passwords and users may have issues logging in. Although this can be ameliorated to some extent by introducing a new scheme to passlib, waiting some months, and only then making this the default, this could still cause issued if passlib is only updated very occasionally.

                  Thus, you should update your call to UseDefaults only when all servers have been upgraded, and it is thus guaranteed that they will all be able to verify the new scheme. Making this value loadable from a configuration file is recommended.

                  If you are using a single-server configuration, you can use the special value "latest" here (or, equivalently, a date far into the future), which will always use the most preferred scheme. This is hazardous in a multi-server environment.

                  The constants beginning 'Defaults' in this package document dates which are meaningful to this function. The constant values they are equal to will never change, so there is no need to use them instead of string literals, although you may if you wish; they are intended mainly as documentation as to the significance of various dates.

                  Example for opting in to the latest set of defaults:

                  passlib.UseDefaults(passlib.Defaults20180601)
                  

                  func Verify

                  func Verify(password, hash string) (newHash string, err error)

                    Verifies a UTF-8 plaintext password using a previously derived password hash and the default context. Returns nil err only if the password is valid.

                    If the hash is determined to be deprecated based on policy, and the password is valid, the password is hashed using the preferred password hashing scheme and returned in newHash. You should use this to upgrade any stored password hash in your database.

                    newHash is empty if the password was invalid or no upgrade is required.

                    You should treat any non-nil err as a password verification error.

                    Example (Login)

                      User login example.

                      Output:
                      
                      

                      func VerifyNoUpgrade

                      func VerifyNoUpgrade(password, hash string) error

                        Like Verify, but never upgrades.

                        Types

                        type Context

                        type Context struct {
                        	// Slice of schemes to use, most preferred first.
                        	//
                        	// If left uninitialized, a sensible default set of schemes will be used.
                        	//
                        	// An upgrade hash (see the newHash return value of the Verify method of the
                        	// abstract.Scheme interface) will be issued whenever a password is validated
                        	// using a scheme which is not the first scheme in this slice.
                        	Schemes []abstract.Scheme
                        }

                          A password hashing context, that uses a given set of schemes to hash and verify passwords.

                          var DefaultContext Context

                            The default context, which uses sensible defaults. Most users should not reconfigure this. The defaults may change over time, so you may wish to reconfigure the context or use a custom context if you want precise control over the hashes used.

                            func (*Context) Hash

                            func (ctx *Context) Hash(password string) (hash string, err error)

                              Hashes a UTF-8 plaintext password using the context and produces a password hash.

                              If stub is "", one is generated automaticaly for the preferred password hashing scheme; you should specify stub as "" in almost all cases.

                              The provided or randomly generated stub is used to deterministically hash the password. The returned hash is in modular crypt format.

                              If the context has not been specifically configured, a sensible default policy is used. See the fields of Context.

                              func (*Context) NeedsUpdate

                              func (ctx *Context) NeedsUpdate(stub string) bool

                                Determines whether a stub or hash needs updating according to the policy of the context.

                                func (*Context) Verify

                                func (ctx *Context) Verify(password, hash string) (newHash string, err error)

                                  Verifies a UTF-8 plaintext password using a previously derived password hash and the default context. Returns nil err only if the password is valid.

                                  If the hash is determined to be deprecated based on the context policy, and the password is valid, the password is hashed using the preferred password hashing scheme and returned in newHash. You should use this to upgrade any stored password hash in your database.

                                  newHash is empty if the password was not valid or if no upgrade is required.

                                  You should treat any non-nil err as a password verification error.

                                  func (*Context) VerifyNoUpgrade

                                  func (ctx *Context) VerifyNoUpgrade(password, hash string) error

                                    Like Verify, but does not hash an upgrade password when upgrade is required.

                                    Directories

                                    Path Synopsis
                                    Package abstract contains the abstract description of the Scheme interface, plus supporting error definitions.
                                    Package abstract contains the abstract description of the Scheme interface, plus supporting error definitions.
                                    hash
                                    argon2
                                    Package argon2 implements the argon2 password hashing mechanism, wrapped in the argon2 encoded format.
                                    Package argon2 implements the argon2 password hashing mechanism, wrapped in the argon2 encoded format.
                                    argon2/raw
                                    Package raw provides a raw implementation of the modular-crypt-wrapped Argon2i primitive.
                                    Package raw provides a raw implementation of the modular-crypt-wrapped Argon2i primitive.
                                    bcrypt
                                    Package bcrypt implements the bcrypt password hashing mechanism.
                                    Package bcrypt implements the bcrypt password hashing mechanism.
                                    bcryptsha256
                                    Package bcryptsha256 implements bcrypt with a SHA256 prehash in a format that is compatible with Python passlib's equivalent bcrypt-sha256 scheme.
                                    Package bcryptsha256 implements bcrypt with a SHA256 prehash in a format that is compatible with Python passlib's equivalent bcrypt-sha256 scheme.
                                    pbkdf2
                                    Package pbkdf2 implements a modular crypt format for PBKDF2-SHA1, PBKDF2-SHA256 and PBKDF-SHA512.
                                    Package pbkdf2 implements a modular crypt format for PBKDF2-SHA1, PBKDF2-SHA256 and PBKDF-SHA512.
                                    scrypt
                                    Package scrypt implements the scrypt password hashing mechanism, wrapped in the modular crypt format.
                                    Package scrypt implements the scrypt password hashing mechanism, wrapped in the modular crypt format.
                                    scrypt/raw
                                    Package raw provides a raw implementation of the modular-crypt-wrapped scrypt primitive.
                                    Package raw provides a raw implementation of the modular-crypt-wrapped scrypt primitive.
                                    sha2crypt
                                    Package sha2crypt implements sha256-crypt and sha512-crypt.
                                    Package sha2crypt implements sha256-crypt and sha512-crypt.
                                    sha2crypt/raw
                                    Package raw provides a raw implementation of the sha256-crypt and sha512-crypt primitives.
                                    Package raw provides a raw implementation of the sha256-crypt and sha512-crypt primitives.