1.. hazmat:: 2 3Message digests (Hashing) 4========================= 5 6.. module:: cryptography.hazmat.primitives.hashes 7 8.. class:: Hash(algorithm, backend) 9 10 A cryptographic hash function takes an arbitrary block of data and 11 calculates a fixed-size bit string (a digest), such that different data 12 results (with a high probability) in different digests. 13 14 This is an implementation of 15 :class:`~cryptography.hazmat.primitives.hashes.HashContext` meant to 16 be used with 17 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` 18 implementations to provide an incremental interface to calculating 19 various message digests. 20 21 .. doctest:: 22 23 >>> from cryptography.hazmat.backends import default_backend 24 >>> from cryptography.hazmat.primitives import hashes 25 >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) 26 >>> digest.update(b"abc") 27 >>> digest.update(b"123") 28 >>> digest.finalize() 29 b'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' 30 31 If the backend doesn't support the requested ``algorithm`` an 32 :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be 33 raised. 34 35 Keep in mind that attacks against cryptographic hashes only get stronger 36 with time, and that often algorithms that were once thought to be strong, 37 become broken. Because of this it's important to include a plan for 38 upgrading the hash algorithm you use over time. For more information, see 39 `Lifetimes of cryptographic hash functions`_. 40 41 :param algorithm: A 42 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` 43 instance such as those described in 44 :ref:`below <cryptographic-hash-algorithms>`. 45 :param backend: A 46 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 47 instance. 48 49 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 50 provided ``backend`` does not implement 51 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 52 53 .. method:: update(data) 54 55 :param bytes data: The bytes to be hashed. 56 :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. 57 :raises TypeError: This exception is raised if ``data`` is not ``bytes``. 58 59 .. method:: copy() 60 61 Copy this :class:`Hash` instance, usually so that you may call 62 :meth:`finalize` to get an intermediate digest value while we continue 63 to call :meth:`update` on the original instance. 64 65 :return: A new instance of :class:`Hash` that can be updated 66 and finalized independently of the original instance. 67 :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. 68 69 .. method:: finalize() 70 71 Finalize the current context and return the message digest as bytes. 72 73 After ``finalize`` has been called this object can no longer be used 74 and :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise an 75 :class:`~cryptography.exceptions.AlreadyFinalized` exception. 76 77 :return bytes: The message digest as bytes. 78 79 80.. _cryptographic-hash-algorithms: 81 82SHA-2 family 83~~~~~~~~~~~~ 84 85.. class:: SHA224() 86 87 SHA-224 is a cryptographic hash function from the SHA-2 family and is 88 standardized by NIST. It produces a 224-bit message digest. 89 90.. class:: SHA256() 91 92 SHA-256 is a cryptographic hash function from the SHA-2 family and is 93 standardized by NIST. It produces a 256-bit message digest. 94 95.. class:: SHA384() 96 97 SHA-384 is a cryptographic hash function from the SHA-2 family and is 98 standardized by NIST. It produces a 384-bit message digest. 99 100.. class:: SHA512() 101 102 SHA-512 is a cryptographic hash function from the SHA-2 family and is 103 standardized by NIST. It produces a 512-bit message digest. 104 105.. class:: SHA512_224() 106 107 .. versionadded:: 2.5 108 109 SHA-512/224 is a cryptographic hash function from the SHA-2 family and is 110 standardized by NIST. It produces a 224-bit message digest. 111 112.. class:: SHA512_256() 113 114 .. versionadded:: 2.5 115 116 SHA-512/256 is a cryptographic hash function from the SHA-2 family and is 117 standardized by NIST. It produces a 256-bit message digest. 118 119BLAKE2 120~~~~~~ 121 122`BLAKE2`_ is a cryptographic hash function specified in :rfc:`7693`. BLAKE2's 123design makes it immune to `length-extension attacks`_, an advantage over the 124SHA-family of hashes. 125 126.. note:: 127 128 While the RFC specifies keying, personalization, and salting features, 129 these are not supported at this time due to limitations in OpenSSL 1.1.0. 130 131.. class:: BLAKE2b(digest_size) 132 133 BLAKE2b is optimized for 64-bit platforms and produces an 1 to 64-byte 134 message digest. 135 136 :param int digest_size: The desired size of the hash output in bytes. Only 137 ``64`` is supported at this time. 138 139 :raises ValueError: If the ``digest_size`` is invalid. 140 141.. class:: BLAKE2s(digest_size) 142 143 BLAKE2s is optimized for 8 to 32-bit platforms and produces a 144 1 to 32-byte message digest. 145 146 :param int digest_size: The desired size of the hash output in bytes. Only 147 ``32`` is supported at this time. 148 149 :raises ValueError: If the ``digest_size`` is invalid. 150 151SHA-3 family 152~~~~~~~~~~~~ 153 154SHA-3 is the most recent NIST secure hash algorithm standard. Despite the 155larger number SHA-3 is not considered to be better than SHA-2. Instead, it uses 156a significantly different internal structure so that **if** an attack appears 157against SHA-2 it is unlikely to apply to SHA-3. SHA-3 is significantly slower 158than SHA-2 so at this time most users should choose SHA-2. 159 160.. class:: SHA3_224() 161 162 .. versionadded:: 2.5 163 164 SHA3/224 is a cryptographic hash function from the SHA-3 family and is 165 standardized by NIST. It produces a 224-bit message digest. 166 167.. class:: SHA3_256() 168 169 .. versionadded:: 2.5 170 171 SHA3/256 is a cryptographic hash function from the SHA-3 family and is 172 standardized by NIST. It produces a 256-bit message digest. 173 174.. class:: SHA3_384() 175 176 .. versionadded:: 2.5 177 178 SHA3/384 is a cryptographic hash function from the SHA-3 family and is 179 standardized by NIST. It produces a 384-bit message digest. 180 181.. class:: SHA3_512() 182 183 .. versionadded:: 2.5 184 185 SHA3/512 is a cryptographic hash function from the SHA-3 family and is 186 standardized by NIST. It produces a 512-bit message digest. 187 188.. class:: SHAKE128(digest_size) 189 190 .. versionadded:: 2.5 191 192 SHAKE128 is an extendable output function (XOF) based on the same core 193 permutations as SHA3. It allows the caller to obtain an arbitrarily long 194 digest length. Longer lengths, however, do not increase security or 195 collision resistance and lengths shorter than 128 bit (16 bytes) will 196 decrease it. 197 198 :param int digest_size: The length of output desired. Must be greater than 199 zero. 200 201 :raises ValueError: If the ``digest_size`` is invalid. 202 203.. class:: SHAKE256(digest_size) 204 205 .. versionadded:: 2.5 206 207 SHAKE256 is an extendable output function (XOF) based on the same core 208 permutations as SHA3. It allows the caller to obtain an arbitrarily long 209 digest length. Longer lengths, however, do not increase security or 210 collision resistance and lengths shorter than 256 bit (32 bytes) will 211 decrease it. 212 213 :param int digest_size: The length of output desired. Must be greater than 214 zero. 215 216 :raises ValueError: If the ``digest_size`` is invalid. 217 218SHA-1 219~~~~~ 220 221.. warning:: 222 223 SHA-1 is a deprecated hash algorithm that has practical known collision 224 attacks. You are strongly discouraged from using it. Existing applications 225 should strongly consider moving away. 226 227.. class:: SHA1() 228 229 SHA-1 is a cryptographic hash function standardized by NIST. It produces an 230 160-bit message digest. Cryptanalysis of SHA-1 has demonstrated that it is 231 vulnerable to practical collision attacks, and collisions have been 232 demonstrated. 233 234MD5 235~~~ 236 237.. warning:: 238 239 MD5 is a deprecated hash algorithm that has practical known collision 240 attacks. You are strongly discouraged from using it. Existing applications 241 should strongly consider moving away. 242 243.. class:: MD5() 244 245 MD5 is a deprecated cryptographic hash function. It produces a 128-bit 246 message digest and has practical known collision attacks. 247 248 249Interfaces 250~~~~~~~~~~ 251 252.. class:: HashAlgorithm 253 254 .. attribute:: name 255 256 :type: str 257 258 The standard name for the hash algorithm, for example: ``"sha256"`` or 259 ``"blake2b"``. 260 261 .. attribute:: digest_size 262 263 :type: int 264 265 The size of the resulting digest in bytes. 266 267 268.. class:: HashContext 269 270 .. attribute:: algorithm 271 272 A :class:`HashAlgorithm` that will be used by this context. 273 274 .. method:: update(data) 275 276 :param bytes data: The data you want to hash. 277 278 .. method:: finalize() 279 280 :return: The final digest as bytes. 281 282 .. method:: copy() 283 284 :return: A :class:`HashContext` that is a copy of the current context. 285 286 287.. _`Lifetimes of cryptographic hash functions`: https://valerieaurora.org/hash.html 288.. _`BLAKE2`: https://blake2.net 289.. _`length-extension attacks`: https://en.wikipedia.org/wiki/Length_extension_attack 290