Lib: Hash

Description

This Library provides functions to calculate message digest.
This library is a port of the pureluaSHA module made by Egor Skriptunoff: Github Project

Supported hashes:

lua MD5 -- LH.md5(message) SHA-1 -- LH.sha1(message) -- SHA2 SHA-224 -- LH.sha224(message) SHA-256 -- LH.sha256(message) SHA-384 -- LH.sha384(message) SHA-512 -- LH.sha512(message) SHA-512/224 -- LH.sha512_224(message) SHA-512/256 -- LH.sha512_256(message) -- SHA3 SHA3-224 -- LH.sha3_224(message) SHA3-256 -- LH.sha3_256(message) SHA3-384 -- LH.sha3_384(message) SHA3-512 -- LH.sha3_512(message) SHAKE128 -- LH.shake128(digest_size_in_bytes, message) SHAKE256 -- LH.shake256(digest_size_in_bytes, message) -- HMAC (applicable to any hash-function from this module except SHAKE) HMAC -- LH.hmac(LH.any_hash_func, key, message)

Usage

Input data should be provided as a binary string: either as a whole string or as a sequence of substrings (chunk-by-chunk loading).
Result (SHA digest) is returned in hexadecimal representation (as a string of lowercase hex digits).

Simplest usage example:

lua local LH = LibStub("LibHash-1.0") local your_hash = LH.sha256("your string") -- assert(your_hash == "d14d691dac70eada14d9f23ef80091bca1c75cf77cf1cd5cf2d04180ca0d9911")

FAQ

Q: How to get SHA digest as binary string instead of hexadecimal representation?
A:
Use function LH.hex2bin() to convert hexadecimal to binary:

lua local LH = LibStub("LibHash-1.0") local binary_hash = LH.hex2bin(LH.sha256("your string")) -- assert(binary_hash == "\209Mi\29\172p\234\218\20\217\242>\248\0\145\188\161\199\\\247|\241\205\\\242\208A\128\202\r\153\17")

Q: How to get SHA digest as base64 string?
A:
There are functions LH.bin2base64() and LH.base642bin() for converting between binary and base64:

lua local LH = LibStub("LibHash-1.0") local binary_hash = LH.hex2bin(LH.sha256("your string")) local base64_hash = LH.bin2base64(binary_hash) -- assert(base64_hash == "0U1pHaxw6toU2fI++ACRvKHHXPd88c1c8tBBgMoNmRE=")

Q: How to calculate SHA digest of long data stream?
A:

lua local LH = LibStub("LibHash-1.0") local append = LH.sha256() -- if the "message" argument is omitted then "append" function is returned append("your") append(" st") -- you should pass all parts of your long message to the "append" function (chunk-by-chunk) append("ring") local your_hash = append() -- and finally ask for the result (by invoking the "append" function without argument) -- assert(your_hash == "d14d691dac70eada14d9f23ef80091bca1c75cf77cf1cd5cf2d04180ca0d9911")

Q: How to calculate HMAC-SHA1, HMAC-SHA256, etc. ?
A:

lua -- Calculating HMAC-SHA1 local LH = LibStub("LibHash-1.0") local your_hmac = LH.hmac(LH.sha1, "your key", "your message") -- assert(your_hmac == "317d0dfd868a5c06c9444ac1328aa3e2bfd29fb2")

The same in chunk-by-chunk mode (for long messages):

lua local LH = LibStub("LibHash-1.0") local append = LH.hmac(LH.sha1, "your key") append("your") append(" mess") append("age") local your_hmac = append() -- assert(your_hmac == "317d0dfd868a5c06c9444ac1328aa3e2bfd29fb2")

Q: Can SHAKE128/SHAKE256 be used to generate digest of infinite length ?
A:
Yes!
For example, you can convert your password into infinite stream of pseudo-random bytes.
Set digest_size_in_bytes to -1 and obtain the function get_next_part(part_size_in_bytes).
Invoke this function repeatedly to get consecutive parts of the infinite digest.

lua local LH = LibStub("LibHash-1.0") local get_next_part_of_digest = LH.shake128(-1, "The quick brown fox jumps over the lazy dog") assert(get_next_part_of_digest(5) == "f4202e3c58") -- 5 bytes in hexadecimal representation assert(get_next_part_of_digest() == "52") -- size=1 is assumed when omitted assert(get_next_part_of_digest(0) == "") -- size=0 is a valid size assert(get_next_part_of_digest(4) == "f9182a04") -- and so on to the infinity... -- Note: you can use LH.hex2bin() to convert these hexadecimal parts to binary strings -- By definition, the result of SHAKE with finite "digest_size_in_bytes" is just a finite prefix of "infinite digest": assert(LH.shake128(4, "The quick brown fox jumps over the lazy dog")) == "f4202e3c")

For SHAKE, it's possible to combine "chunk-by-chunk" input mode with "chunk-by-chunk" output mode:

lua local LH = LibStub("LibHash-1.0") local append_input_message = LH.shake128(-1) append_input_message("The quick brown fox") append_input_message(" jumps over") append_input_message(" the lazy dog") local get_next_part_of_digest = append_input_message() -- input stream is terminated, now we can start receiving the output stream assert(get_next_part_of_digest(5) == "f4202e3c58") assert(get_next_part_of_digest(5) == "52f9182a04") -- and so on...