1============================================ 2:mod:`passlib.hosts` - OS Password Handling 3============================================ 4 5.. module:: passlib.hosts 6 :synopsis: hashing & verifying operating system passwords 7 8This module provides some preconfigured :ref:`CryptContext <context-reference>` 9instances for hashing & verifying password hashes tied to user accounts of various operating systems. 10While (most) of the objects are available cross-platform, 11their use is oriented primarily towards Linux and BSD variants. 12 13.. seealso:: 14 for Microsoft Windows, see the list of :ref:`windows-hashes` 15 in :mod:`passlib.hash`. 16 17.. rst-class:: html-toggle 18 19Usage Example 20============= 21The :class:`!CryptContext` class itself has a large number of features, 22but to give an example of how to quickly use the instances in this module: 23 24Each of the objects in this module can be imported directly:: 25 26 >>> # as an example, this imports the linux_context object, 27 >>> # which is configured to recognized most hashes found in Linux /etc/shadow files. 28 >>> from passlib.apps import linux_context 29 30Hashing a password is simple (and salt generation is handled automatically):: 31 32 >>> hash = linux_context.hash("toomanysecrets") 33 >>> hash 34 '$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4' 35 36Verifying a password against an existing hash is just as quick:: 37 38 >>> linux_context.verify("toomanysocks", hash) 39 False 40 >>> linux_context.verify("toomanysecrets", hash) 41 True 42 43You can also identify hashes:: 44 >>> linux_context.identify(hash) 45 'sha512_crypt' 46 47Or encrypt using a specific algorithm:: 48 >>> linux_context.schemes() 49 ('sha512_crypt', 'sha256_crypt', 'md5_crypt', 'des_crypt', 'unix_disabled') 50 >>> linux_context.hash("password", scheme="des_crypt") 51 '2fmLLcoHXuQdI' 52 >>> linux_context.identify('2fmLLcoHXuQdI') 53 'des_crypt' 54 55.. seealso:: 56 the :ref:`CryptContext Tutorial <context-tutorial>` 57 and :ref:`CryptContext Reference <context-reference>` 58 for more information about the CryptContext class. 59 60Unix Password Hashes 61==================== 62Passlib provides a number of pre-configured :class:`!CryptContext` instances 63which can identify and manipulate all the formats used by Linux and BSD. 64See the :ref:`modular crypt identifier list <mcf-identifiers>` for a complete 65list of which hashes are supported by which operating system. 66 67Predefined Contexts 68------------------- 69Passlib provides :class:`!CryptContext` instances 70for the following Unix variants: 71 72.. data:: linux_context 73 74 context instance which recognizes hashes used 75 by the majority of Linux distributions. 76 encryption defaults to :class:`!sha512_crypt`. 77 78.. data:: freebsd_context 79 80 context instance which recognizes all hashes used by FreeBSD 8. 81 encryption defaults to :class:`!bcrypt`. 82 83.. data:: netbsd_context 84 85 context instance which recognizes all hashes used by NetBSD. 86 encryption defaults to :class:`!bcrypt`. 87 88.. data:: openbsd_context 89 90 context instance which recognizes all hashes used by OpenBSD. 91 encryption defaults to :class:`!bcrypt`. 92 93.. note:: 94 95 All of the above contexts include the :class:`~passlib.hash.unix_disabled` handler 96 as a final fallback. This special handler treats all strings as invalid passwords, 97 particularly the common strings ``!`` and ``*`` which are used to indicate 98 that an account has been disabled [#shadow]_. 99 100Current Host OS 101--------------- 102 103.. data:: host_context 104 105 :platform: Unix 106 107 This :class:`~passlib.context.CryptContext` instance should detect and support 108 all the algorithms the native OS :func:`!crypt` offers. 109 The main differences between this object and :func:`!crypt`: 110 111 * this object provides introspection about *which* schemes 112 are available on a given system (via ``host_context.schemes()``). 113 * it defaults to the strongest algorithm available, 114 automatically configured to an appropriate strength 115 for hashing new passwords. 116 * whereas :func:`!crypt` typically defaults to using 117 :mod:`~passlib.hash.des_crypt`; and provides little introspection. 118 119 As an example, this can be used in conjunction with stdlib's :mod:`!spwd` module 120 to verify user passwords on the local system:: 121 122 >>> # NOTE/WARNING: this example requires running as root on most systems. 123 >>> import spwd, os 124 >>> from passlib.hosts import host_context 125 >>> hash = spwd.getspnam(os.environ['USER']).sp_pwd 126 >>> host_context.verify("toomanysecrets", hash) 127 True 128 129 .. versionchanged:: 1.4 130 This object is only available on systems where the stdlib :mod:`!crypt` module is present. 131 In version 1.3 and earlier, it was available on non-Unix systems, though it did nothing useful. 132 133.. rubric:: Footnotes 134 135.. [#shadow] Man page for Linux /etc/shadow - `<http://linux.die.net/man/5/shadow>`_ 136