passlib.hosts - OS Password Handling

This module provides some preconfigured CryptContext instances for encrypting & verifying password hashes tied to user accounts of various operating systems. While (most) of the objects are available cross-platform, their use is oriented primarily towards Linux and BSD variants.

See also

for Microsoft Windows, see the list of MS Windows Hashes in passlib.hash.

Usage Example

The CryptContext class itself has a large number of features, but to give an example of how to quickly use the instances in this module:

Each of the objects in this module can be imported directly:

>>> # as an example, this imports the linux_context object,
>>> # which is configured to recognized most hashes found in Linux /etc/shadow files.
>>> from passlib.apps import linux_context

Encrypting a password is simple (and salt generation is handled automatically):

>>> hash = linux_context.encrypt("toomanysecrets")
>>> hash
'$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4'

Verifying a password against an existing hash is just as quick:

>>> linux_context.verify("toomanysocks", hash)
False
>>> linux_context.verify("toomanysecrets", hash)
True
You can also identify hashes::
>>> linux_context.identify(hash)
'sha512_crypt'
Or encrypt using a specific algorithm::
>>> linux_context.schemes()
('sha512_crypt', 'sha256_crypt', 'md5_crypt', 'des_crypt', 'unix_disabled')
>>> linux_context.encrypt("password", scheme="des_crypt")
'2fmLLcoHXuQdI'
>>> linux_context.identify('2fmLLcoHXuQdI')
'des_crypt'

See also

the CryptContext Tutorial and CryptContext Reference for more information about the CryptContext class.

Unix Password Hashes

Passlib provides a number of pre-configured CryptContext instances which can identify and manipulate all the formats used by Linux and BSD. See the modular crypt identifier list for a complete list of which hashes are supported by which operating system.

Predefined Contexts

Passlib provides CryptContext instances for the following Unix variants:

passlib.hosts.linux_context

context instance which recognizes hashes used by the majority of Linux distributions. encryption defaults to sha512_crypt.

passlib.hosts.freebsd_context

context instance which recognizes all hashes used by FreeBSD 8. encryption defaults to bcrypt.

passlib.hosts.netbsd_context

context instance which recognizes all hashes used by NetBSD. encryption defaults to bcrypt.

passlib.hosts.openbsd_context

context instance which recognizes all hashes used by OpenBSD. encryption defaults to bcrypt.

Note

All of the above contexts include the unix_disabled handler as a final fallback. This special handler treats all strings as invalid passwords, particularly the common strings ! and * which are used to indicate that an account has been disabled [1].

Current Host OS

passlib.hosts.host_context
Platform:Unix

This CryptContext instance should detect and support all the algorithms the native OS crypt() offers. The main differences between this object and crypt():

  • this object provides introspection about which schemes are available on a given system (via host_context.schemes()).
  • it defaults to the strongest algorithm available, automatically configured to an appropriate strength for encrypting new passwords.
  • whereas crypt() typically defaults to using des_crypt; and provides little introspection.

As an example, this can be used in conjunction with stdlib’s spwd module to verify user passwords on the local system:

>>> # NOTE/WARNING: this example requires running as root on most systems.
>>> import spwd, os
>>> from passlib.hosts import host_context
>>> hash = spwd.getspnam(os.environ['USER']).sp_pwd
>>> host_context.verify("toomanysecrets", hash)
True

Changed in version 1.4: This object is only available on systems where the stdlib crypt module is present. In version 1.3 and earlier, it was available on non-Unix systems, though it did nothing useful.

Footnotes

[1]Man page for Linux /etc/shadow - http://linux.die.net/man/5/shadow