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 ¶
const Defaults20160922 = "20160922"
This is the first and default set of defaults used by passlib. It prefers scrypt-sha256. It is now obsolete.
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.
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 ¶
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 ¶
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.
// User signup example.
// NOTE: Call UseDefaults at application initialisation time to initialise
// passlib before using Hash() or Verify(). See func UseDefaults.
// ... signup code ...
// Get the password the user chose by whatever means.
password := getSignupPassword()
username := getSignupUsername()
hash, err := Hash(password)
if err != nil {
// couldn't hash password for some reason
return
}
// hash now contains a hash in modular crypt form.
// Store hash in database, etc.
storeHashInDatabase(username, hash)
Output:
func NeedsUpdate ¶
Uses the default context to determine whether a stub or hash needs updating.
func UseDefaults ¶ added in v1.0.10
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 ¶
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.
// User login example.
// NOTE: Call UseDefaults at application initialisation time to initialise
// passlib before using Hash() or Verify(). See func UseDefaults.
// Get the password for the user we have stored in the database.
hash := getUserHashFromDatabase()
// Get the plaintext password the user tried to login with.
password := getLoginPassword()
newHash, err := Verify(password, hash)
if err != nil {
// Incorrect password, malformed hash, etc.
return
}
if newHash != "" {
// passlib thinks we should upgrade to a new stronger hash.
// ... store the new hash in the database ...
}
// ... log the user in ...
Output:
func VerifyNoUpgrade ¶
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 ¶
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 ¶
Determines whether a stub or hash needs updating according to the policy of the context.
func (*Context) Verify ¶
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 ¶
Like Verify, but does not hash an upgrade password when upgrade is required.
Source Files
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. |