hash.py 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. # Copyright 2013 Donald Stufft and individual contributors
  2. #
  3. # Licensed under the Apache License, Version 2.0 (the "License");
  4. # you may not use this file except in compliance with the License.
  5. # You may obtain a copy of the License at
  6. #
  7. # http://www.apache.org/licenses/LICENSE-2.0
  8. #
  9. # Unless required by applicable law or agreed to in writing, software
  10. # distributed under the License is distributed on an "AS IS" BASIS,
  11. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. # See the License for the specific language governing permissions and
  13. # limitations under the License.
  14. """
  15. The :mod:`nacl.hash` module exposes one-shot interfaces
  16. for libsodium selected hash primitives and the constants needed
  17. for their usage.
  18. """
  19. import nacl.bindings
  20. import nacl.encoding
  21. BLAKE2B_BYTES = nacl.bindings.crypto_generichash_BYTES
  22. """Default digest size for :func:`blake2b` hash"""
  23. BLAKE2B_BYTES_MIN = nacl.bindings.crypto_generichash_BYTES_MIN
  24. """Minimum allowed digest size for :func:`blake2b` hash"""
  25. BLAKE2B_BYTES_MAX = nacl.bindings.crypto_generichash_BYTES_MAX
  26. """Maximum allowed digest size for :func:`blake2b` hash"""
  27. BLAKE2B_KEYBYTES = nacl.bindings.crypto_generichash_KEYBYTES
  28. """Default size of the ``key`` byte array for :func:`blake2b` hash"""
  29. BLAKE2B_KEYBYTES_MIN = nacl.bindings.crypto_generichash_KEYBYTES_MIN
  30. """Minimum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
  31. BLAKE2B_KEYBYTES_MAX = nacl.bindings.crypto_generichash_KEYBYTES_MAX
  32. """Maximum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
  33. BLAKE2B_SALTBYTES = nacl.bindings.crypto_generichash_SALTBYTES
  34. """Maximum allowed length of the ``salt`` byte array for
  35. :func:`blake2b` hash"""
  36. BLAKE2B_PERSONALBYTES = nacl.bindings.crypto_generichash_PERSONALBYTES
  37. """Maximum allowed length of the ``personalization``
  38. byte array for :func:`blake2b` hash"""
  39. SIPHASH_BYTES = nacl.bindings.crypto_shorthash_siphash24_BYTES
  40. """Size of the :func:`siphash24` digest"""
  41. SIPHASH_KEYBYTES = nacl.bindings.crypto_shorthash_siphash24_KEYBYTES
  42. """Size of the secret ``key`` used by the :func:`siphash24` MAC"""
  43. SIPHASHX_AVAILABLE = nacl.bindings.has_crypto_shorthash_siphashx24
  44. """``True`` if :func:`siphashx24` is available to be called"""
  45. SIPHASHX_BYTES = nacl.bindings.crypto_shorthash_siphashx24_BYTES
  46. """Size of the :func:`siphashx24` digest"""
  47. SIPHASHX_KEYBYTES = nacl.bindings.crypto_shorthash_siphashx24_KEYBYTES
  48. """Size of the secret ``key`` used by the :func:`siphashx24` MAC"""
  49. _b2b_hash = nacl.bindings.crypto_generichash_blake2b_salt_personal
  50. _sip_hash = nacl.bindings.crypto_shorthash_siphash24
  51. _sip_hashx = nacl.bindings.crypto_shorthash_siphashx24
  52. def sha256(
  53. message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
  54. ) -> bytes:
  55. """
  56. Hashes ``message`` with SHA256.
  57. :param message: The message to hash.
  58. :type message: bytes
  59. :param encoder: A class that is able to encode the hashed message.
  60. :returns: The hashed message.
  61. :rtype: bytes
  62. """
  63. return encoder.encode(nacl.bindings.crypto_hash_sha256(message))
  64. def sha512(
  65. message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
  66. ) -> bytes:
  67. """
  68. Hashes ``message`` with SHA512.
  69. :param message: The message to hash.
  70. :type message: bytes
  71. :param encoder: A class that is able to encode the hashed message.
  72. :returns: The hashed message.
  73. :rtype: bytes
  74. """
  75. return encoder.encode(nacl.bindings.crypto_hash_sha512(message))
  76. def blake2b(
  77. data: bytes,
  78. digest_size: int = BLAKE2B_BYTES,
  79. key: bytes = b"",
  80. salt: bytes = b"",
  81. person: bytes = b"",
  82. encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
  83. ) -> bytes:
  84. """
  85. Hashes ``data`` with blake2b.
  86. :param data: the digest input byte sequence
  87. :type data: bytes
  88. :param digest_size: the requested digest size; must be at most
  89. :const:`BLAKE2B_BYTES_MAX`;
  90. the default digest size is
  91. :const:`BLAKE2B_BYTES`
  92. :type digest_size: int
  93. :param key: the key to be set for keyed MAC/PRF usage; if set, the key
  94. must be at most :data:`~nacl.hash.BLAKE2B_KEYBYTES_MAX` long
  95. :type key: bytes
  96. :param salt: an initialization salt at most
  97. :const:`BLAKE2B_SALTBYTES` long;
  98. it will be zero-padded if needed
  99. :type salt: bytes
  100. :param person: a personalization string at most
  101. :const:`BLAKE2B_PERSONALBYTES` long;
  102. it will be zero-padded if needed
  103. :type person: bytes
  104. :param encoder: the encoder to use on returned digest
  105. :type encoder: class
  106. :returns: The hashed message.
  107. :rtype: bytes
  108. """
  109. digest = _b2b_hash(
  110. data, digest_size=digest_size, key=key, salt=salt, person=person
  111. )
  112. return encoder.encode(digest)
  113. generichash = blake2b
  114. def siphash24(
  115. message: bytes,
  116. key: bytes = b"",
  117. encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
  118. ) -> bytes:
  119. """
  120. Computes a keyed MAC of ``message`` using the short-input-optimized
  121. siphash-2-4 construction.
  122. :param message: The message to hash.
  123. :type message: bytes
  124. :param key: the message authentication key for the siphash MAC construct
  125. :type key: bytes(:const:`SIPHASH_KEYBYTES`)
  126. :param encoder: A class that is able to encode the hashed message.
  127. :returns: The hashed message.
  128. :rtype: bytes(:const:`SIPHASH_BYTES`)
  129. """
  130. digest = _sip_hash(message, key)
  131. return encoder.encode(digest)
  132. shorthash = siphash24
  133. def siphashx24(
  134. message: bytes,
  135. key: bytes = b"",
  136. encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
  137. ) -> bytes:
  138. """
  139. Computes a keyed MAC of ``message`` using the 128 bit variant of the
  140. siphash-2-4 construction.
  141. :param message: The message to hash.
  142. :type message: bytes
  143. :param key: the message authentication key for the siphash MAC construct
  144. :type key: bytes(:const:`SIPHASHX_KEYBYTES`)
  145. :param encoder: A class that is able to encode the hashed message.
  146. :returns: The hashed message.
  147. :rtype: bytes(:const:`SIPHASHX_BYTES`)
  148. :raises nacl.exceptions.UnavailableError: If called when using a
  149. minimal build of libsodium.
  150. .. versionadded:: 1.2
  151. """
  152. digest = _sip_hashx(message, key)
  153. return encoder.encode(digest)