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