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