Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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"""
15The :mod:`nacl.hash` module exposes one-shot interfaces
16for libsodium selected hash primitives and the constants needed
17for their usage.
18"""
20import nacl.bindings
21import nacl.encoding
24BLAKE2B_BYTES = nacl.bindings.crypto_generichash_BYTES
25"""Default digest size for :func:`blake2b` hash"""
26BLAKE2B_BYTES_MIN = nacl.bindings.crypto_generichash_BYTES_MIN
27"""Minimum allowed digest size for :func:`blake2b` hash"""
28BLAKE2B_BYTES_MAX = nacl.bindings.crypto_generichash_BYTES_MAX
29"""Maximum allowed digest size for :func:`blake2b` hash"""
30BLAKE2B_KEYBYTES = nacl.bindings.crypto_generichash_KEYBYTES
31"""Default size of the ``key`` byte array for :func:`blake2b` hash"""
32BLAKE2B_KEYBYTES_MIN = nacl.bindings.crypto_generichash_KEYBYTES_MIN
33"""Minimum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
34BLAKE2B_KEYBYTES_MAX = nacl.bindings.crypto_generichash_KEYBYTES_MAX
35"""Maximum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
36BLAKE2B_SALTBYTES = nacl.bindings.crypto_generichash_SALTBYTES
37"""Maximum allowed length of the ``salt`` byte array for
38:func:`blake2b` hash"""
39BLAKE2B_PERSONALBYTES = nacl.bindings.crypto_generichash_PERSONALBYTES
40"""Maximum allowed length of the ``personalization``
41byte array for :func:`blake2b` hash"""
43SIPHASH_BYTES = nacl.bindings.crypto_shorthash_siphash24_BYTES
44"""Size of the :func:`siphash24` digest"""
45SIPHASH_KEYBYTES = nacl.bindings.crypto_shorthash_siphash24_KEYBYTES
46"""Size of the secret ``key`` used by the :func:`siphash24` MAC"""
48SIPHASHX_AVAILABLE = nacl.bindings.has_crypto_shorthash_siphashx24
49"""``True`` if :func:`siphashx24` is available to be called"""
51SIPHASHX_BYTES = nacl.bindings.crypto_shorthash_siphashx24_BYTES
52"""Size of the :func:`siphashx24` digest"""
53SIPHASHX_KEYBYTES = nacl.bindings.crypto_shorthash_siphashx24_KEYBYTES
54"""Size of the secret ``key`` used by the :func:`siphashx24` MAC"""
56_b2b_hash = nacl.bindings.crypto_generichash_blake2b_salt_personal
57_sip_hash = nacl.bindings.crypto_shorthash_siphash24
58_sip_hashx = nacl.bindings.crypto_shorthash_siphashx24
61def sha256(
62 message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
63) -> bytes:
64 """
65 Hashes ``message`` with SHA256.
67 :param message: The message to hash.
68 :type message: bytes
69 :param encoder: A class that is able to encode the hashed message.
70 :returns: The hashed message.
71 :rtype: bytes
72 """
73 return encoder.encode(nacl.bindings.crypto_hash_sha256(message))
76def sha512(
77 message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
78) -> bytes:
79 """
80 Hashes ``message`` with SHA512.
82 :param message: The message to hash.
83 :type message: bytes
84 :param encoder: A class that is able to encode the hashed message.
85 :returns: The hashed message.
86 :rtype: bytes
87 """
88 return encoder.encode(nacl.bindings.crypto_hash_sha512(message))
91def blake2b(
92 data: bytes,
93 digest_size: int = BLAKE2B_BYTES,
94 key: bytes = b"",
95 salt: bytes = b"",
96 person: bytes = b"",
97 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
98) -> bytes:
99 """
100 Hashes ``data`` with blake2b.
102 :param data: the digest input byte sequence
103 :type data: bytes
104 :param digest_size: the requested digest size; must be at most
105 :const:`BLAKE2B_BYTES_MAX`;
106 the default digest size is
107 :const:`BLAKE2B_BYTES`
108 :type digest_size: int
109 :param key: the key to be set for keyed MAC/PRF usage; if set, the key
110 must be at most :data:`~nacl.hash.BLAKE2B_KEYBYTES_MAX` long
111 :type key: bytes
112 :param salt: an initialization salt at most
113 :const:`BLAKE2B_SALTBYTES` long;
114 it will be zero-padded if needed
115 :type salt: bytes
116 :param person: a personalization string at most
117 :const:`BLAKE2B_PERSONALBYTES` long;
118 it will be zero-padded if needed
119 :type person: bytes
120 :param encoder: the encoder to use on returned digest
121 :type encoder: class
122 :returns: The hashed message.
123 :rtype: bytes
124 """
126 digest = _b2b_hash(
127 data, digest_size=digest_size, key=key, salt=salt, person=person
128 )
129 return encoder.encode(digest)
132generichash = blake2b
135def siphash24(
136 message: bytes,
137 key: bytes = b"",
138 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
139) -> bytes:
140 """
141 Computes a keyed MAC of ``message`` using the short-input-optimized
142 siphash-2-4 construction.
144 :param message: The message to hash.
145 :type message: bytes
146 :param key: the message authentication key for the siphash MAC construct
147 :type key: bytes(:const:`SIPHASH_KEYBYTES`)
148 :param encoder: A class that is able to encode the hashed message.
149 :returns: The hashed message.
150 :rtype: bytes(:const:`SIPHASH_BYTES`)
151 """
152 digest = _sip_hash(message, key)
153 return encoder.encode(digest)
156shorthash = siphash24
159def siphashx24(
160 message: bytes,
161 key: bytes = b"",
162 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
163) -> bytes:
164 """
165 Computes a keyed MAC of ``message`` using the 128 bit variant of the
166 siphash-2-4 construction.
168 :param message: The message to hash.
169 :type message: bytes
170 :param key: the message authentication key for the siphash MAC construct
171 :type key: bytes(:const:`SIPHASHX_KEYBYTES`)
172 :param encoder: A class that is able to encode the hashed message.
173 :returns: The hashed message.
174 :rtype: bytes(:const:`SIPHASHX_BYTES`)
175 :raises nacl.exceptions.UnavailableError: If called when using a
176 minimal build of libsodium.
178 .. versionadded:: 1.2
179 """
180 digest = _sip_hashx(message, key)
181 return encoder.encode(digest)