Module HASH

Cryptographic hash functions

An hash is also known as 'message digest', 'digital fingerprint', 'digest' or 'checksum'.

HASH objects can be generated from a number of implemented algorithms: sha256 and sha512 are stable and pass NIST vector tests. There are also sha384, sha3_256 and sha3_512 with experimental implementations that aren't passing NIST vector tests.

Objects are instantiated using HASH.new and then provide the method HASH:process that takes an input OCTET and then returns another fixed-size octet that is uniquely matched to the original data. The process is not reversible (the original data cannot be retrieved from an hash).

Info:

  • Copyright: Dyne.org foundation 2017-2019
  • License: AGPLv3
  • Author: Denis "Jaromil" Roio

Global Hash Functions

new (string) Create a new hash object of a selected algorithm (e.g.sha256 or sha512).
mnemonic_seed (str1, str2) Convert a mnemonic phrase (used in cryptocurrency wallets) into a seed using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm with HMAC-SHA512.

Class Hash

hash:__gc (hash) Decrement the reference count of an hash object and free its memory when no more references exist.
hash:octet () Convert an hash object into an octet object.
hash:process (data) Hash an octet into a new octet.
hash:feed (data) Feed a new octet into a current hashing session.
hash:yeld () Yeld a new octet from the current hashing session.
hash:hmac (key, data) Compute the HMAC of a message using a key.
hash:kdf2 (key) Key Derivation Function (KDF2).
hash:pbkdf2 (key, salt, iterations, length) Password Based Key Derivation Function (PBKDF2).
hash:random_seed (seed) Seed a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
hash:random_int8 () Generate a random 8-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
hash:random_int16 () Generate a random 16-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
hash:random_int32 () Generate a random 32-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.


Global Hash Functions

new (string)
Create a new hash object of a selected algorithm (e.g.sha256 or sha512). The resulting object can then process any OCTET into its hashed equivalent. It is a C function.

Parameters:

  • string indicating the type of hash algorithm (default "sha256")

Returns:

    a new hash object ready to process data via :process() method

See also:

mnemonic_seed (str1, str2)
Convert a mnemonic phrase (used in cryptocurrency wallets) into a seed using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm with HMAC-SHA512. This is commonly used in standards like BIP-39.

Parameters:

  • str1 a mnemonic phrase
  • str2 a passphrase

Returns:

    the derived seed as an octet object

Class Hash

Object Methods
hash:__gc (hash)
Decrement the reference count of an hash object and free its memory when no more references exist. It ensures proper memory management to prevent leaks.

Parameters:

  • hash an hash object

Returns:

    no values are returned
hash:octet ()
Convert an hash object into an octet object. It retrieves the hash object from the Lua stack, creates a new octet object of the same length, copies the hash data into the octet, and returns the octet object to Lua. If any step fails, it throws an error.

Returns:

    the newly created octet object

Usage:

    --define a "sha256" hash object
h1 = HASH.new()
--trasform h1 in hex-octet
print(h1:octet():hex())
--print: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
hash:process (data)
Hash an octet into a new octet. Use the configured hash function to hash an octet string and return a new one containing its hash.

Parameters:

  • data octet containing the data to be hashed

Returns:

    a new octet containing the hash of the data

Usage:

    --create an octet and an hash object
oct = OCTET.from_hex("0xa1b2c3d4")
--create an hash object
h1 = HASH.new()
--apply the method to the octet
print(h1:process(oct):hex())
--print: 97ed8e55519b020c4d9aceb40e0d3bc7eaa22d080d49592bf21206cb697c8a58
hash:feed (data)
Feed a new octet into a current hashing session. This is used to hash multiple chunks until yeld is called.

Parameters:

  • data octet containing the data to be hashed
hash:yeld ()
Yeld a new octet from the current hashing session. This is used to finalize the hashing of multiple chunks after feed is called.

Returns:

    a new octet containing the hash of the data
hash:hmac (key, data)
Compute the HMAC of a message using a key. This method takes any data and any key material to compute an HMAC of the same length of the hash bytes of the keyring. This function works in accordance with RFC2104.

Parameters:

  • key an octet containing the key to compute the HMAC
  • data an octet containing the message to compute the HMAC

Returns:

    a new octet containing the computed HMAC or false on failure

Usage:

    --create the key
key = OCTET.from_hex("0xa1b2c3d4")
--create the hash
h1 = HASH.new()
--create the message
message = OCTET.from_hex("0xc3d2")
--compute the HMAC
print(h1:hmac(key,message):hex())
--print: 844548df11876f644413664403e648fa74ee4a3fb547c2dedb3db0a564c15abb
hash:kdf2 (key)
Key Derivation Function (KDF2). Key derivation is used to strengthen keys against bruteforcing: they impose a number of costly computations to be iterated on the key. This function generates a new key from an existing key applying an octet of key derivation parameters.

Parameters:

  • key octet of the key to be transformed

Returns:

    a new octet containing the derived key
hash:pbkdf2 (key, salt, iterations, length)
Password Based Key Derivation Function (PBKDF2). This function generates a new key from an existing key applying a salt and number of iterations.

Parameters:

  • key octet of the key to be transformed
  • salt octet containing a salt to be used in transformation
  • iterations [opt=5000] number of iterations to be applied
  • length [opt=key length] integer indicating the new length (default same as input key)

Returns:

    a new octet containing the derived key

See also:

hash:random_seed (seed)

Seed a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
It uses an octet object as the seed and optionally "fast-forwards" the CSPRNG to improve randomness.

Parameters:

  • seed an octet object
hash:random_int8 ()
Generate a random 8-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
It ensures that the CSPRNG has been seeded before generating the random number.

Returns:

    a random 8-bit unsigned integer
hash:random_int16 ()
Generate a random 16-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
It ensures that the CSPRNG has been seeded before generating the random number.

Returns:

    a random 16-bit unsigned integer
hash:random_int32 ()
Generate a random 32-bit unsigned integer using a cryptographically secure pseudo-random number generator (CSPRNG) associated with a hash object.
It ensures that the CSPRNG has been seeded before generating the random number.

Returns:

    a random 32-bit unsigned integer
generated by LDoc 1.5.0 Last updated 2025-03-25 10:43:18