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
23BLAKE2B_BYTES = nacl.bindings.crypto_generichash_BYTES
24"""Default digest size for :func:`blake2b` hash"""
25BLAKE2B_BYTES_MIN = nacl.bindings.crypto_generichash_BYTES_MIN
26"""Minimum allowed digest size for :func:`blake2b` hash"""
27BLAKE2B_BYTES_MAX = nacl.bindings.crypto_generichash_BYTES_MAX
28"""Maximum allowed digest size for :func:`blake2b` hash"""
29BLAKE2B_KEYBYTES = nacl.bindings.crypto_generichash_KEYBYTES
30"""Default size of the ``key`` byte array for :func:`blake2b` hash"""
31BLAKE2B_KEYBYTES_MIN = nacl.bindings.crypto_generichash_KEYBYTES_MIN
32"""Minimum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
33BLAKE2B_KEYBYTES_MAX = nacl.bindings.crypto_generichash_KEYBYTES_MAX
34"""Maximum allowed size of the ``key`` byte array for :func:`blake2b` hash"""
35BLAKE2B_SALTBYTES = nacl.bindings.crypto_generichash_SALTBYTES
36"""Maximum allowed length of the ``salt`` byte array for
37:func:`blake2b` hash"""
38BLAKE2B_PERSONALBYTES = nacl.bindings.crypto_generichash_PERSONALBYTES
39"""Maximum allowed length of the ``personalization``
40byte array for :func:`blake2b` hash"""
42SIPHASH_BYTES = nacl.bindings.crypto_shorthash_siphash24_BYTES
43"""Size of the :func:`siphash24` digest"""
44SIPHASH_KEYBYTES = nacl.bindings.crypto_shorthash_siphash24_KEYBYTES
45"""Size of the secret ``key`` used by the :func:`siphash24` MAC"""
47SIPHASHX_AVAILABLE = nacl.bindings.has_crypto_shorthash_siphashx24
48"""``True`` if :func:`siphashx24` is available to be called"""
50SIPHASHX_BYTES = nacl.bindings.crypto_shorthash_siphashx24_BYTES
51"""Size of the :func:`siphashx24` digest"""
52SIPHASHX_KEYBYTES = nacl.bindings.crypto_shorthash_siphashx24_KEYBYTES
53"""Size of the secret ``key`` used by the :func:`siphashx24` MAC"""
55_b2b_hash = nacl.bindings.crypto_generichash_blake2b_salt_personal
56_sip_hash = nacl.bindings.crypto_shorthash_siphash24
57_sip_hashx = nacl.bindings.crypto_shorthash_siphashx24
60def sha256(
61 message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
62) -> bytes:
63 """
64 Hashes ``message`` with SHA256.
66 :param message: The message to hash.
67 :type message: bytes
68 :param encoder: A class that is able to encode the hashed message.
69 :returns: The hashed message.
70 :rtype: bytes
71 """
72 return encoder.encode(nacl.bindings.crypto_hash_sha256(message))
75def sha512(
76 message: bytes, encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder
77) -> bytes:
78 """
79 Hashes ``message`` with SHA512.
81 :param message: The message to hash.
82 :type message: bytes
83 :param encoder: A class that is able to encode the hashed message.
84 :returns: The hashed message.
85 :rtype: bytes
86 """
87 return encoder.encode(nacl.bindings.crypto_hash_sha512(message))
90def blake2b(
91 data: bytes,
92 digest_size: int = BLAKE2B_BYTES,
93 key: bytes = b"",
94 salt: bytes = b"",
95 person: bytes = b"",
96 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
97) -> bytes:
98 """
99 Hashes ``data`` with blake2b.
101 :param data: the digest input byte sequence
102 :type data: bytes
103 :param digest_size: the requested digest size; must be at most
104 :const:`BLAKE2B_BYTES_MAX`;
105 the default digest size is
106 :const:`BLAKE2B_BYTES`
107 :type digest_size: int
108 :param key: the key to be set for keyed MAC/PRF usage; if set, the key
109 must be at most :data:`~nacl.hash.BLAKE2B_KEYBYTES_MAX` long
110 :type key: bytes
111 :param salt: an initialization salt at most
112 :const:`BLAKE2B_SALTBYTES` long;
113 it will be zero-padded if needed
114 :type salt: bytes
115 :param person: a personalization string at most
116 :const:`BLAKE2B_PERSONALBYTES` long;
117 it will be zero-padded if needed
118 :type person: bytes
119 :param encoder: the encoder to use on returned digest
120 :type encoder: class
121 :returns: The hashed message.
122 :rtype: bytes
123 """
125 digest = _b2b_hash(
126 data, digest_size=digest_size, key=key, salt=salt, person=person
127 )
128 return encoder.encode(digest)
131generichash = blake2b
134def siphash24(
135 message: bytes,
136 key: bytes = b"",
137 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
138) -> bytes:
139 """
140 Computes a keyed MAC of ``message`` using the short-input-optimized
141 siphash-2-4 construction.
143 :param message: The message to hash.
144 :type message: bytes
145 :param key: the message authentication key for the siphash MAC construct
146 :type key: bytes(:const:`SIPHASH_KEYBYTES`)
147 :param encoder: A class that is able to encode the hashed message.
148 :returns: The hashed message.
149 :rtype: bytes(:const:`SIPHASH_BYTES`)
150 """
151 digest = _sip_hash(message, key)
152 return encoder.encode(digest)
155shorthash = siphash24
158def siphashx24(
159 message: bytes,
160 key: bytes = b"",
161 encoder: nacl.encoding.Encoder = nacl.encoding.HexEncoder,
162) -> bytes:
163 """
164 Computes a keyed MAC of ``message`` using the 128 bit variant of the
165 siphash-2-4 construction.
167 :param message: The message to hash.
168 :type message: bytes
169 :param key: the message authentication key for the siphash MAC construct
170 :type key: bytes(:const:`SIPHASHX_KEYBYTES`)
171 :param encoder: A class that is able to encode the hashed message.
172 :returns: The hashed message.
173 :rtype: bytes(:const:`SIPHASHX_BYTES`)
174 :raises nacl.exceptions.UnavailableError: If called when using a
175 minimal build of libsodium.
177 .. versionadded:: 1.2
178 """
179 digest = _sip_hashx(message, key)
180 return encoder.encode(digest)