1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
============================================
:mod:`passlib.hosts` - OS Password Handling
============================================
.. module:: passlib.hosts
:synopsis: encrypting & verifying operating system passwords
This module provides some preconfigured :ref:`CryptContext <context-overview>`
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.
.. seealso::
for Microsoft Windows, see the list of :ref:`windows-hashes`
in :mod:`passlib.hash`.
.. rst-class:: html-toggle
Usage Example
=============
The :class:`!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'
.. seealso::
the :ref:`CryptContext Tutorial <context-tutorial>`
and :ref:`CryptContext Reference <context-reference>`
for more information about the CryptContext class.
Unix Password Hashes
====================
Passlib provides a number of pre-configured :class:`!CryptContext` instances
which can identify and manipulate all the formats used by Linux and BSD.
See the :ref:`modular crypt identifier list <mcf-identifiers>` for a complete
list of which hashes are supported by which operating system.
Predefined Contexts
-------------------
Passlib provides :class:`!CryptContext` instances
for the following Unix variants:
.. data:: linux_context
context instance which recognizes hashes used
by the majority of Linux distributions.
encryption defaults to :class:`!sha512_crypt`.
.. data:: freebsd_context
context instance which recognizes all hashes used by FreeBSD 8.
encryption defaults to :class:`!bcrypt`.
.. data:: netbsd_context
context instance which recognizes all hashes used by NetBSD.
encryption defaults to :class:`!bcrypt`.
.. data:: openbsd_context
context instance which recognizes all hashes used by OpenBSD.
encryption defaults to :class:`!bcrypt`.
.. note::
All of the above contexts include the :class:`~passlib.hash.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 [#shadow]_.
Current Host OS
---------------
.. data:: host_context
:platform: Unix
This :class:`~passlib.context.CryptContext` instance should detect and support
all the algorithms the native OS :func:`!crypt` offers.
The main differences between this object and :func:`!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 :func:`!crypt` typically defaults to using
:mod:`~passlib.hash.des_crypt`; and provides little introspection.
As an example, this can be used in conjunction with stdlib's :mod:`!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
.. versionchanged:: 1.4
This object is only available on systems where the stdlib :mod:`!crypt` module is present.
In version 1.3 and earlier, it was available on non-Unix systems, though it did nothing useful.
.. rubric:: Footnotes
.. [#shadow] Man page for Linux /etc/shadow - `<http://linux.die.net/man/5/shadow>`_
|
