# "Hash Functions"
_Path: en/lua/security/hash_
> "Cryptographic hashes, HMAC, key derivation and streaming MinHash signatures."
## Table of Contents
- Hash Functions
## Content
# Hash Functions
The `hash` module computes cryptographic hashes, HMAC values, PBKDF2-derived keys, and non-cryptographic FNV-1 hashes. This page is an API reference of isolated calls. Literal inputs illustrate successful use; when data, secrets, passwords, or salts come from the application, capture and handle the documented second `error` return before consuming the result.
A hash is not encryption and does not conceal low-entropy input. Do not log passwords, HMAC keys, derived keys, or raw secret-dependent digests. Use HMAC-SHA256 or HMAC-SHA512 for new message-authentication designs and PBKDF2 with a unique random salt for password verifiers.
## Loading
```lua
local hash = require("hash")
```
### MD5
MD5 is not collision-resistant. Use it only for compatibility with protocols that require MD5, not for security decisions.
```lua
local hex = hash.md5("data")
local raw = hash.md5("data", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### SHA-1
SHA-1 is not collision-resistant. Use it only for compatibility with protocols that require SHA-1, not for security decisions.
```lua
local hex = hash.sha1("data")
local raw = hash.sha1("data", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### SHA-256
```lua
local hex = hash.sha256("data")
local raw = hash.sha256("data", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### SHA-512
```lua
local hex = hash.sha512("data")
local raw = hash.sha512("data", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### HMAC-MD5
Use HMAC-MD5 only for compatibility with a protocol that requires it; prefer HMAC-SHA256 or HMAC-SHA512 for new designs.
```lua
local hex = hash.hmac_md5("message", "secret")
local raw = hash.hmac_md5("message", "secret", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### HMAC-SHA1
Use HMAC-SHA1 only for compatibility with a protocol that requires it; prefer HMAC-SHA256 or HMAC-SHA512 for new designs.
```lua
local hex = hash.hmac_sha1("message", "secret")
local raw = hash.hmac_sha1("message", "secret", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### HMAC-SHA256
```lua
local hex = hash.hmac_sha256("message", "secret")
local raw = hash.hmac_sha256("message", "secret", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### HMAC-SHA512
```lua
local hex = hash.hmac_sha512("message", "secret")
local raw = hash.hmac_sha512("message", "secret", true)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |
**Returns:** `string, error`
### FNV-1 32-bit
Compute a hash for uses such as hash tables and partitioning.
```lua
local n = hash.fnv32("data")
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
**Returns:** `number, error`
### FNV-1 64-bit
Compute a 64-bit FNV-1 hash. In runtime v0.3.62a, the result is a string preserving all 64 bits: 16 lowercase hexadecimal characters by default, or eight big-endian bytes with `raw = true`.
```lua
local hex, err = hash.fnv64("data")
if err then return nil, err end
local raw, raw_err = hash.fnv64("data", true)
if raw_err then return nil, raw_err end
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return eight raw bytes instead of hex; default `false` |
**Returns:** `string, error`
Callers upgrading from the previous numeric return must consume the string directly. Converting it to a floating-point number can lose the low bits again. `fnv32` continues to return an exact 32-bit number.
## MinHash
Available in runtime v0.3.62a. `hash.minhash` computes deterministic sketches of token shingles, locality-sensitive hashing (LSH) band keys, and estimates of Jaccard similarity for near-duplicate text.
Text is split into runs of ASCII letters, digits, underscore and bytes at or above `0x80`. ASCII letters are lowercased. An array of non-empty token strings supplies tokens unchanged. Compare sketches produced with the same tokenization, shingle width and algorithm.
### Functions
| Function | Returns | Options |
|----------|---------|---------|
| `hash.minhash.signature(input, options?)` | `Signature, error` | `k`, `shingle`, `bands`, `rows`, `domain` |
| `hash.minhash.sketch(input, options?)` | `string, error` | `k`, `shingle` |
| `hash.minhash.bands(sketch, options?)` | `{string}, error` | `bands`, `rows`, `domain` |
| `hash.minhash.similarity(a, b)` | `number, error` | None |
| `hash.minhash.new(options?)` | `MinHasher, error` | `k`, `shingle`, `bands`, `rows`, `domain` |
`input` is text or an array of tokens. `similarity` takes two non-empty serialized sketches of the same size and returns a value in `0..1`. Band keys select candidates; use the similarity estimate to compare them.
| Option | Default | Constraint |
|--------|---------|------------|
| `k` | `128` | Sketch bins, `1..65536`, not a multiple of `5` or `11` |
| `shingle` | `5` | Tokens per shingle, `1..1024` |
| `bands` | `16` | `bands * rows` equals the sketch bin count |
| `rows` | `8` | Bins per band |
| `domain` | `"minhash.lsh.v1"` | Namespace included in each band key |
Unknown options, wrong types, invalid dimensions and mismatched sketch sizes return non-retryable `errors.INVALID`.
A signature contains `tokens` (token count), `normalized` (hex SHA-256 of tokens joined by one space), `sketch` and `bands`. The sketch is `4*k` bytes, storing 32-bit big-endian words; each band key is 16 lowercase hex characters. Input without tokens has no `sketch` or `bands` in its signature; `sketch(input)` returns `""` for that input. Serialized sketches do not carry their configuration, so store the parameters alongside persisted sketches. The [algorithm specification](https://github.com/wippyai/runtime/blob/v0.3.62a/runtime/lua/modules/hash/spec.md#algorithm) defines the deterministic hashing and serialization.
```lua
local a, a_err = hash.minhash.signature("the quick brown fox jumps over the lazy dog")
if a_err then return nil, a_err end
local b, b_err = hash.minhash.signature("the quick brown fox jumps over the sleepy dog")
if b_err then return nil, b_err end
local score, score_err = hash.minhash.similarity(a.sketch, b.sketch)
if score_err then return nil, score_err end
return score
```
### Streaming
A MinHasher keeps the current token's hash, shingle window, sketch bins and normalized digest. Chunks may split a token; `sum()` equals the signature of the concatenated text and retains the state for further updates.
| Method | Returns | Behavior |
|--------|---------|----------|
| `hasher:update(chunk)` | `boolean, error` | Append a text chunk |
| `hasher:sum()` | `Signature, error` | Snapshot the current signature |
| `hasher:reset()` | No values | Discard accumulated input |
```lua
local hasher, create_err = hash.minhash.new()
if create_err then return nil, create_err end
local ok, update_err = hasher:update("the quick bro")
if not ok then return nil, update_err end
ok, update_err = hasher:update("wn fox jumps over the lazy dog")
if not ok then return nil, update_err end
local signature, sum_err = hasher:sum()
if sum_err then return nil, sum_err end
return signature
```
### PBKDF2
```lua
local key, err = hash.pbkdf2(password, salt, iterations, key_length)
local key, err = hash.pbkdf2(password, salt, iterations, key_length, "sha512")
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `password` | string | Password/passphrase (non-empty) |
| `salt` | string | Salt value (non-empty) |
| `iterations` | integer | Iteration count (1 to 10,000,000) |
| `key_length` | integer | Desired key length in bytes |
| `hash` | string? | `sha256` or `sha512` (default: `sha256`) |
**Returns:** `string, error` (raw key bytes)
## Errors
| Condition | Kind | Retryable |
|-----------|------|-----------|
| Input not a string | `errors.INVALID` | no |
| Secret not a string (HMAC) | `errors.INVALID` | no |
| Empty password/salt, non-positive or excessive iterations, unsupported hash (PBKDF2) | `errors.INVALID` | no |
See [Error Handling](lua/core/errors.md) for working with errors.
## Navigation
Previous: "Encryption & Signing" (lua/security/crypto)
Next: "UUID Generation" (lua/security/uuid)