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