← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/library/hashlib.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/hashlib.rst
 
1
:mod:`hashlib` --- Secure hashes and message digests
 
2
====================================================
 
3
 
 
4
.. module:: hashlib
 
5
   :synopsis: Secure hash and message digest algorithms.
 
6
.. moduleauthor:: Gregory P. Smith <greg@krypto.org>
 
7
.. sectionauthor:: Gregory P. Smith <greg@krypto.org>
 
8
 
 
9
 
 
10
.. index::
 
11
   single: message digest, MD5
 
12
   single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
 
13
 
 
14
**Source code:** :source:`Lib/hashlib.py`
 
15
 
 
16
--------------
 
17
 
 
18
This module implements a common interface to many different secure hash and
 
19
message digest algorithms.  Included are the FIPS secure hash algorithms SHA1,
 
20
SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
 
21
algorithm (defined in Internet :rfc:`1321`).  The terms "secure hash" and
 
22
"message digest" are interchangeable.  Older algorithms were called message
 
23
digests.  The modern term is secure hash.
 
24
 
 
25
.. note::
 
26
 
 
27
   If you want the adler32 or crc32 hash functions, they are available in
 
28
   the :mod:`zlib` module.
 
29
 
 
30
.. warning::
 
31
 
 
32
   Some algorithms have known hash collision weaknesses, refer to the "See
 
33
   also" section at the end.
 
34
 
 
35
 
 
36
Hash algorithms
 
37
---------------
 
38
 
 
39
There is one constructor method named for each type of :dfn:`hash`.  All return
 
40
a hash object with the same simple interface. For example: use :func:`sha1` to
 
41
create a SHA1 hash object. You can now feed this object with :term:`bytes-like
 
42
object`\ s (normally :class:`bytes`) using the :meth:`update` method.
 
43
At any point you can ask it for the :dfn:`digest` of the
 
44
concatenation of the data fed to it so far using the :meth:`digest` or
 
45
:meth:`hexdigest` methods.
 
46
 
 
47
.. note::
 
48
 
 
49
   For better multithreading performance, the Python :term:`GIL` is released for
 
50
   data larger than 2047 bytes at object creation or on update.
 
51
 
 
52
.. note::
 
53
 
 
54
   Feeding string objects into :meth:`update` is not supported, as hashes work
 
55
   on bytes, not on characters.
 
56
 
 
57
.. index:: single: OpenSSL; (use in module hashlib)
 
58
 
 
59
Constructors for hash algorithms that are always present in this module are
 
60
:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`,
 
61
:func:`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, and
 
62
:func:`sha3_512`. Additional algorithms may also be available depending upon
 
63
the OpenSSL library that Python uses on your platform.
 
64
 
 
65
   .. versionchanged:: 3.4
 
66
      Add sha3 family of hash algorithms.
 
67
 
 
68
For example, to obtain the digest of the byte string ``b'Nobody inspects the
 
69
spammish repetition'``::
 
70
 
 
71
   >>> import hashlib
 
72
   >>> m = hashlib.md5()
 
73
   >>> m.update(b"Nobody inspects")
 
74
   >>> m.update(b" the spammish repetition")
 
75
   >>> m.digest()
 
76
   b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
 
77
   >>> m.digest_size
 
78
   16
 
79
   >>> m.block_size
 
80
   64
 
81
 
 
82
More condensed:
 
83
 
 
84
   >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
 
85
   'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
 
86
 
 
87
.. function:: new(name[, data])
 
88
 
 
89
   Is a generic constructor that takes the string name of the desired
 
90
   algorithm as its first parameter.  It also exists to allow access to the
 
91
   above listed hashes as well as any other algorithms that your OpenSSL
 
92
   library may offer.  The named constructors are much faster than :func:`new`
 
93
   and should be preferred.
 
94
 
 
95
Using :func:`new` with an algorithm provided by OpenSSL:
 
96
 
 
97
   >>> h = hashlib.new('ripemd160')
 
98
   >>> h.update(b"Nobody inspects the spammish repetition")
 
99
   >>> h.hexdigest()
 
100
   'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
 
101
 
 
102
Hashlib provides the following constant attributes:
 
103
 
 
104
.. data:: algorithms_guaranteed
 
105
 
 
106
   Contains the names of the hash algorithms guaranteed to be supported
 
107
   by this module on all platforms.
 
108
 
 
109
   .. versionadded:: 3.2
 
110
 
 
111
.. data:: algorithms_available
 
112
 
 
113
   Contains the names of the hash algorithms that are available
 
114
   in the running Python interpreter.  These names will be recognized
 
115
   when passed to :func:`new`.  :attr:`algorithms_guaranteed`
 
116
   will always be a subset.  Duplicate algorithms with different
 
117
   name formats may appear in this set (thanks to OpenSSL).
 
118
 
 
119
   .. versionadded:: 3.2
 
120
 
 
121
The following values are provided as constant attributes of the hash objects
 
122
returned by the constructors:
 
123
 
 
124
 
 
125
.. data:: hash.digest_size
 
126
 
 
127
   The size of the resulting hash in bytes.
 
128
 
 
129
.. data:: hash.block_size
 
130
 
 
131
   The internal block size of the hash algorithm in bytes.
 
132
 
 
133
A hash object has the following attributes:
 
134
 
 
135
.. attribute:: hash.name
 
136
 
 
137
   The canonical name of this hash, always lowercase and always suitable as a
 
138
   parameter to :func:`new` to create another hash of this type.
 
139
 
 
140
   .. versionchanged:: 3.4
 
141
      The name attribute has been present in CPython since its inception, but
 
142
      until Python 3.4 was not formally specified, so may not exist on some
 
143
      platforms.
 
144
 
 
145
A hash object has the following methods:
 
146
 
 
147
 
 
148
.. method:: hash.update(arg)
 
149
 
 
150
   Update the hash object with the object *arg*, which must be interpretable as
 
151
   a buffer of bytes.  Repeated calls are equivalent to a single call with the
 
152
   concatenation of all the arguments: ``m.update(a); m.update(b)`` is
 
153
   equivalent to ``m.update(a+b)``.
 
154
 
 
155
   .. versionchanged:: 3.1
 
156
      The Python GIL is released to allow other threads to run while hash
 
157
      updates on data larger than 2047 bytes is taking place when using hash
 
158
      algorithms supplied by OpenSSL.
 
159
 
 
160
 
 
161
.. method:: hash.digest()
 
162
 
 
163
   Return the digest of the data passed to the :meth:`update` method so far.
 
164
   This is a bytes object of size :attr:`digest_size` which may contain bytes in
 
165
   the whole range from 0 to 255.
 
166
 
 
167
 
 
168
.. method:: hash.hexdigest()
 
169
 
 
170
   Like :meth:`digest` except the digest is returned as a string object of
 
171
   double length, containing only hexadecimal digits.  This may be used to
 
172
   exchange the value safely in email or other non-binary environments.
 
173
 
 
174
 
 
175
.. method:: hash.copy()
 
176
 
 
177
   Return a copy ("clone") of the hash object.  This can be used to efficiently
 
178
   compute the digests of data sharing a common initial substring.
 
179
 
 
180
 
 
181
Key Derivation Function
 
182
-----------------------
 
183
 
 
184
Key derivation and key stretching algorithms are designed for secure password
 
185
hashing. Naive algorithms such as ``sha1(password)`` are not resistant
 
186
against brute-force attacks. A good password hashing function must be tunable,
 
187
slow and include a salt.
 
188
 
 
189
 
 
190
.. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None)
 
191
 
 
192
   The function provides PKCS#5 password-based key derivation function 2. It
 
193
   uses HMAC as pseudorandom function.
 
194
 
 
195
   The string *name* is the desired name of the hash digest algorithm for
 
196
   HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
 
197
   buffers of bytes. Applications and libraries should limit *password* to
 
198
   a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from
 
199
   a proper source, e.g. :func:`os.urandom`.
 
200
 
 
201
   The number of *rounds* should be chosen based on the hash algorithm and
 
202
   computing power. As of 2013 a value of at least 100,000 rounds of SHA-256
 
203
   have been suggested.
 
204
 
 
205
   *dklen* is the length of the derived key. If *dklen* is ``None`` then the
 
206
   digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512.
 
207
 
 
208
   >>> import hashlib, binascii
 
209
   >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
 
210
   >>> binascii.hexlify(dk)
 
211
   b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'
 
212
 
 
213
   .. versionadded:: 3.4
 
214
 
 
215
   .. note:: A fast implementation of *pbkdf2_hmac* is available with OpenSSL.
 
216
      The Python implementation uses an inline version of :mod:`hmac`. It is
 
217
      about three times slower and doesn't release the GIL.
 
218
 
 
219
 
 
220
.. seealso::
 
221
 
 
222
   Module :mod:`hmac`
 
223
      A module to generate message authentication codes using hashes.
 
224
 
 
225
   Module :mod:`base64`
 
226
      Another way to encode binary hashes for non-binary environments.
 
227
 
 
228
   http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
 
229
      The FIPS 180-2 publication on Secure Hash Algorithms.
 
230
 
 
231
   http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms
 
232
      Wikipedia article with information on which algorithms have known issues and
 
233
      what that means regarding their use.
 
234
 
 
235
   http://www.ietf.org/rfc/rfc2898.txt
 
236
      PKCS #5: Password-Based Cryptography Specification Version 2.0