Module crypto.shash
Low-level Lua interface to the Linux Kernel Crypto API for synchronous message digest (hash) algorithms, including HMAC.
This module provides a new function to create SHASH transform objects, which can then be used for various hashing operations.
Class SHASH
| shash:digest (data) | Computes the hash of the given data in a single operation. |
| shash:digestsize () | Gets the digest size (output length) of the hash algorithm. |
| shash:export () | Exports the internal state of the hash operation. |
| shash:final () | Finalizes the multi-part hash operation and returns the digest. |
| shash:finup (data) | Combines update and finalization for a multi-part hash operation. |
| shash:import (state) | Imports a previously exported hash state. |
| shash:init () | Initializes a multi-part hash operation. |
| shash:setkey (key) | Sets the key for the SHASH transform (used for HMAC). |
| shash:update (data) | Updates the hash state with more data. |
shash
| new (algname) | Creates a new SHASH object. |
Class SHASH
SHASH object methods.
These methods are available on SHASH objects created by
crypto_shash.new().
- shash:digest (data)
-
Computes the hash of the given data in a single operation.
For HMAC,
setkey()must have been called first. This function initializes, updates, and finalizes the hash calculation.Parameters:
- data string The data to hash.
Returns:
-
string
The computed digest (hash output).
Raises:
Error on failure (e.g., allocation error, crypto API error). - shash:digestsize ()
-
Gets the digest size (output length) of the hash algorithm.
Returns:
-
integer
The digest size in bytes.
- shash:export ()
-
Exports the internal state of the hash operation.
This allows suspending and later resuming a hash calculation via
import(). Must be called afterinit()and anyupdate()calls if part of a multi-step operation.Returns:
-
string
The internal hash state as a binary string.
Raises:
Error on failure (e.g., allocation error). - shash:final ()
-
Finalizes the multi-part hash operation and returns the digest.
Must be called after
init()and anyupdate()calls.Returns:
-
string
The computed digest.
Raises:
Error on failure. - shash:finup (data)
-
Combines update and finalization for a multi-part hash operation.
Updates the hash state with the given data, then finalizes and returns the digest.
init()must have been called prior to callingfinup().Parameters:
- data string The final data chunk.
Returns:
-
string
The computed digest.
Raises:
Error on failure. - shash:import (state)
-
Imports a previously exported hash state.
This overwrites the current hash state and allows resuming a hash calculation.
The imported state must be compatible with the current hash algorithm.
Parameters:
- state string The previously exported hash state (binary string).
Raises:
Error on failure or if the provided state length is incorrect for the algorithm. - shash:init ()
-
Initializes a multi-part hash operation.
This must be called before using
update()orfinal().Raises:
Error on failure. - shash:setkey (key)
-
Sets the key for the SHASH transform (used for HMAC).
Parameters:
- key string The key to use for HMAC.
Raises:
Error if setting the key fails. - shash:update (data)
-
Updates the hash state with more data.
Must be called after
init(). Can be called multiple times.Parameters:
- data string The data chunk to add to the hash.
Raises:
Error on failure.
shash
- new (algname)
-
Creates a new SHASH object.
This is the constructor function for the
crypto_shashmodule.Parameters:
- algname string The name of the hash algorithm (e.g., "sha256", "hmac(sha256)").
Returns:
-
crypto_shash
The new SHASH object.
Raises:
Error if the TFM object or kernel descriptor cannot be allocated/initialized.Usage:
local shash_mod = require("crypto.shash") local hasher = shash_mod.new("sha256")