hash

import hash

This module provides a framework for cryptographic and non-cryptographic encryption.

Examples,

%> import hash
%>
%> hash.md5('Hello, World')
'82bb413746aee42f89dea2b59614f9ef'
%>
%> hash.sha256('Hello, World')
'03675ac53ff9cd1535ccc7dfcdfa2c458c5218371f418dc136f2d19ac1fbe8a5'
%>
%> hash.hmac_sha256('mykey', 'Hello, World')
'61035d3d2119ffdfd710913bf4161d5fba1c2d9431f7de7ef398d359eb1d2481'
%>
%> hash.hmac_sha256(bytes([10, 11, 12]), 'My secure text!')
'd782079145a3476fd4e018d44dd024034fa91f626f7f30f2009200c5ac757723'

The hash API

Every public name in hash, wherever it is declared. Each links to the page that documents it.

Functions

id()

hash.id(value) -> number

Returns the identification hash of a value as used in the underlying dictionary implementation.

A class may override the result of this function by implementing the to_hash decorator.

Parameters

• value (any)

Returns number

hash()

hash.hash(algorithm, data, as_bytes) -> string|bytes

Returns the hash digest for the given data using the given algorithm.

Supported algorithms includes:

• FNV1 family: fnv1, fnv1a, fnv164, fnv1a64. - MD family: md2, md4, md5. - SHA family: sha, sha1, sha224, sha256, sha384, sha512, sha512-224, sha512-256, md5-sha1. - SHA3 family: sha3-224, sha3-256, sha3-384, sha3-512. - SHAKE family (XOF): shake128, shake256. - RIPEMD family: ripemd160. - WHIRLPOOL family: whirlpool. - Blake family: blake2s256, blake2b512. - SM family: sm3.

By default, this function returns the hexadecimal string representing the hash (since this is the most common application level usage). The function accepts a third boolean argument as_bytes which allows callers to specify if the result should be returned in the raw digest byte stream or not.

Parameters

• algorithm (string)
• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

Note: Algorithm names are not case-sensitive.

md4()

hash.md4(str, as_bytes) -> string|bytes

Returns the md4 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

md5()

hash.md5(str, as_bytes) -> string|bytes

Returns the md5 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

md5_file()

hash.md5_file(f, as_bytes) -> string|bytes

Returns the md5 hash of the given file.

Parameters

• file (file)
• as_bytes (?bool)

Returns string|bytes

sha1()

hash.sha1(str, as_bytes) -> string|bytes

Returns the sha1 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha224()

hash.sha224(str, as_bytes) -> string|bytes

Returns the sha224 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha256()

hash.sha256(str, as_bytes) -> string|bytes

Returns the sha256 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha384()

hash.sha384(str, as_bytes) -> string|bytes

Returns the sha384 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha512()

hash.sha512(str, as_bytes) -> string|bytes

Returns the sha512 hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

fnv1()

hash.fnv1(data, as_bytes) -> string|bytes

Returns the 32 bit fnv1 hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

fnv1_64()

hash.fnv1_64(data, as_bytes) -> string|bytes

Returns the 64 bit fnv1 hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

fnv1a()

hash.fnv1a(data, as_bytes) -> string|bytes

Returns the 32 bit fnv1a hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

fnv1a_64()

hash.fnv1a_64(data, as_bytes) -> string|bytes

Returns the 64 bit fnv1a hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

whirlpool()

hash.whirlpool(str, as_bytes) -> string|bytes

Returns the whirlpool hash of the given string or bytes.

Parameters

• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

gost()

hash.gost(data, as_bytes) -> string|bytes

Returns the Gost cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha3_224()

hash.sha3_224(data, as_bytes) -> string|bytes

Returns the SHA3-224 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha3_256()

hash.sha3_256(data, as_bytes) -> string|bytes

Returns the SHA3-256 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha3_384()

hash.sha3_384(data, as_bytes) -> string|bytes

Returns the SHA3-384 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

sha3_512()

hash.sha3_512(data, as_bytes) -> string|bytes

Returns the SHA3-512 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

shake128()

hash.shake128(data, as_bytes) -> string|bytes

Returns the SHAKE-128 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

shake256()

hash.shake256(data, as_bytes) -> string|bytes

Returns the SHAKE-256 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

blake2b512()

hash.blake2b512(data, as_bytes) -> string|bytes

Returns the BLAKE2B-512 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

blake2s256()

hash.blake2s256(data, as_bytes) -> string|bytes

Returns the BLAKE2S-256 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

ripemd160()

hash.ripemd160(data, as_bytes) -> string|bytes

Returns the RIPEMD-160 cryptographic hash of the given string or bytes.

Parameters

• data (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac()

hash.hmac(method, key, str, as_bytes) -> string|bytes

Computes an HMAC with the key and str using the given method.

Parameters

• method (function)
• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_md4()

hash.hmac_md4(key, str, as_bytes) -> string|bytes

Returns the HMAC-MD4 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_md5()

hash.hmac_md5(key, str, as_bytes) -> string|bytes

Returns the HMAC-MD5 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_sha1()

hash.hmac_sha1(key, str, as_bytes) -> string|bytes

Returns the HMAC-SHA1 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_sha224()

hash.hmac_sha224(key, str, as_bytes) -> string|bytes

Returns the HMAC-SHA224 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_sha256()

hash.hmac_sha256(key, str, as_bytes) -> string|bytes

Returns the HMAC-SHA256 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_sha384()

hash.hmac_sha384(key, str, as_bytes) -> string|bytes

Returns the HMAC-SHA384 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_sha512()

hash.hmac_sha512(key, str, as_bytes) -> string|bytes

Returns the HMAC-SHA512 cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_whirlpool()

hash.hmac_whirlpool(key, str, as_bytes) -> string|bytes

Returns the HMAC-WHIRLPOOL cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

hmac_gost()

hash.hmac_gost(key, str, as_bytes) -> string|bytes

Returns the HMAC-GOST cryptographic hash of the given string or bytes.

Parameters

• key (string|bytes)
• str (string|bytes)
• as_bytes (?bool)

Returns string|bytes

pbkdf2()

hash.pbkdf2(algorithm, password, salt, iterations, dk_len, as_bytes) -> string

Derives a cryptographic key from a password using the PBKDF2 key derivation function defined in RFC 2898 §5.2 (PKCS #5 v2.0), as updated by RFC 8018.

Examples

Password storage (derive then verify)

import hash

var salt = 'f3a8c2b104d7e569'   # 16 random bytes in production
var dk   = hash.pbkdf2('sha256', 'correct horse battery staple', salt, 600000)
# → 64 lowercase hex characters (32 bytes)

# Verification: re-derive and compare.
if hash.pbkdf2('sha256', candidate, salt, 600000) == dk {
  echo 'Password correct'
}

Raw-bytes key for symmetric encryption

import hash

# 32-byte key for AES-256, returned as a bytes object.
var key = hash.pbkdf2('sha256', passphrase, salt, 600000, 32, true)

Longer key with SHA-512

import hash

# 64 bytes; dk_len == hLen so only one T block is needed.
var dk = hash.pbkdf2('sha512', password, salt, 210000, 64)
echo dk.length()   # 128 hex characters = 64 bytes

Key that spans multiple PRF blocks

import hash

# 40 bytes with SHA-1 (hLen = 20) requires two T blocks.
var dk = hash.pbkdf2('sha1', 'secret', 'nacl', 4096, 40)
echo dk.length()   # 80 hex characters = 40 bytes

Security notes

• Always use a unique, randomly generated salt for every password. Never derive the salt from the username, email, or any other predictable input. - Tune iterations so that derivation takes ~100 ms on your target hardware. Re-benchmark as server capacity increases over time. - For pure password storage where output size is not a concern, consider bcrypt (built into Zuri’s hash module). PBKDF2 is most appropriate when you need an arbitrarily long output : symmetric keys, key wrapping, or protocol key schedules. - When comparing derived keys, use a constant-time equality function to prevent timing side-channel attacks.

Parameters

• algorithm (string) — HMAC variant used as the PRF. One of: 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'md5'. Prefer 'sha256' or 'sha512' for new designs.
• password (string|bytes) — The password (HMAC key). Any string or bytes value is accepted.
• salt (string|bytes) — The cryptographic salt. Use at least 16 bytes of random data per password. Never reuse a salt across different passwords.
• iterations (number) — Iteration count c (must be >= 1). OWASP 2023 minimums: ‘sha1’ → 1 300 000 ‘sha256’ → 600 000 ‘sha512’ → 210 000
• dk_len (number) — Derived key length in bytes. Defaults to the PRF output length (hLen) when nil or omitted. Maximum: (2^32 - 1) * hLen.
• as_bytes (bool) — true → return a bytes object. false → return a lowercase hex string (default).

Returns string — | bytes The derived key.

Raises Error

2021, Richard Ore and Zuri contributors