HMAC added

Author: Egor-Skriptunoff

README.md

@@ -27,6 +27,7 @@ SHA-512/256 -- sha2.sha512_256()
 -- and a small bonus:
 MD5 -- sha2.md5()
 SHA-1 -- sha2.sha1()
+HMAC -- sha2.hmac()
 ```
 ---
 ### Usage
@@ -49,8 +50,8 @@ See file "sha2_test.lua" for more examples.
 * **Q:** Does this module calculate SHA2 really fast?
 * **A:** 
 Probably, this is the fastest pure Lua implementation of SHA2 you can find. 
- For example, on x64 Lua 5.3 this module calculates SHA256 twice as fast as the implementation published at [lua-users.org](http://lua-users.org/wiki/SecureHashAlgorithmBw) 
- This module has best performance on every Lua version because it contains several version-specific implementation branches: 
+For example, on x64 Lua 5.3 this module calculates SHA256 twice as fast as the implementation published at [lua-users.org](http://lua-users.org/wiki/SecureHashAlgorithmBw) 
+This module has best performance on every Lua version because it contains several version-specific implementation branches: 
  - branch for **Lua 5.1** (emulating bitwise operators using look-up table)
  - branch for **Lua 5.2** (using **bit32** library), suitable also for **Lua 5.1** with external **bit** library
  - branch for **Lua 5.3 / 5.4** (using native **64**-bit bitwise operators)
@@ -62,12 +63,12 @@ Probably, this is the fastest pure Lua implementation of SHA2 you can find.
 
 ---
 * **Q:** How to get SHA2 digest as binary string instead of hexadecimal representation?
-* **A:**
+* **A:** 
+Use function `sha2.hex2bin()` to convert hexadecimal to binary:
 ```lua
 local sha2 = require("sha2")
-local your_hex_hash = sha2.sha256("your string")
-local your_binary_hash = your_hex_hash:gsub("%x%x", function(h) return h.char(tonumber(h, 16)) end)
--- assert(your_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")
+local binary_hash = sha2.hex2bin(sha2.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")
 ```
 
 ---
@@ -83,6 +84,25 @@ local your_hash = append() -- and finally ask for the result
 -- assert(your_hash == "d14d691dac70eada14d9f23ef80091bca1c75cf77cf1cd5cf2d04180ca0d9911")
 ```
 
+---
+* **Q:** How to calculate HMAC-SHA1 ?
+* **A:**
+```lua
+local sha2 = require("sha2")
+local your_hmac = sha2.hmac(sha2.sha1, "your key", "your message")
+-- assert(your_hmac == "317d0dfd868a5c06c9444ac1328aa3e2bfd29fb2")
+```
+The same in chunk-by-chunk mode (for long messages):
+```lua
+local sha2 = require("sha2")
+local append = sha2.hmac(sha2.sha1, "your key")
+append("your")
+append(" mess")
+append("age")
+local your_hmac = append()
+-- assert(your_hmac == "317d0dfd868a5c06c9444ac1328aa3e2bfd29fb2")
+```
+
 ---
 ### Backward-compatibility
 This module will always keep backward-compatibility. 

sha2.lua

@@ -3,12 +3,12 @@
 --------------------------------------------------------------------------------------------------------------------------
 -- MODULE: sha2
 --
--- VERSION: 5 (2018-11-10)
+-- VERSION: 6 (2018-11-12)
 --
 -- DESCRIPTION:
 -- This module contains functions to calculate SHA2 digest:
 -- SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256
--- and a bonus: MD5, SHA-1
+-- and a bonus: MD5, SHA-1, HMAC
 -- Written in pure Lua.
 -- Compatible with:
 -- Lua 5.1, Lua 5.2, Lua 5.3, Lua 5.4, Fengari, LuaJIT 2.0/2.1 (any CPU endianness).
@@ -37,11 +37,12 @@
 -- CHANGELOG:
 -- version date description
 -- ------- ---------- -----------
--- 1 2018-10-06 First release
--- 2 2018-10-07 Decreased module loading time in Lua 5.1 implementation branch (thanks to Peter Melnichenko for giving a hint)
--- 3 2018-11-02 Bug fixed: incorrect hashing of long (2 GByte) data streams on Lua 5.3/5.4 built with "int32" integers
--- 4 2018-11-03 Bonus added: MD5
+-- 6 2018-11-12 HMAC added (applicable to any hash function from this module)
 -- 5 2018-11-10 One more bonus added: SHA-1
+-- 4 2018-11-03 Bonus added: MD5
+-- 3 2018-11-02 Bug fixed: incorrect hashing of long (2 GByte) data streams on Lua 5.3/5.4 built with "int32" integers
+-- 2 2018-10-07 Decreased module loading time in Lua 5.1 implementation branch (thanks to Peter Melnichenko for giving a hint)
+-- 1 2018-10-06 First release
 -----------------------------------------------------------------------------
 
 
@@ -185,7 +186,7 @@ end
 -- BASIC 32-BIT BITWISE FUNCTIONS
 --------------------------------------------------------------------------------
 
-local AND, OR, XOR, SHL, SHR, ROL, ROR, NOT, NORM, HEX
+local AND, OR, XOR, SHL, SHR, ROL, ROR, NOT, NORM, HEX, XOR_BYTE
 -- Only low 32 bits of function arguments matter, high bits are ignored
 -- The result of all functions (except HEX) is an integer inside "correct range":
 -- for "bit" library: (-2^31)..(2^31-1)
@@ -205,6 +206,7 @@ if branch == "FFI" or branch == "LJ" or branch == "LIB32" then
  NORM = b.tobit -- only for LuaJIT
  HEX = b.tohex -- returns string of 8 lowercase hexadecimal digits
  assert(AND and OR and XOR and SHL and SHR and ROL and ROR and NOT, "Library '"..library_name.."' is incomplete")
+ XOR_BYTE = XOR -- XOR of two bytes (only for HMAC), inputs and output are 0..255
 
 elseif branch == "EMUL" then
 
@@ -286,6 +288,10 @@ elseif branch == "EMUL" then
  return and_or_xor(x, y, 2)
  end
 
+ function XOR_BYTE(x, y)
+ return x + y - 2 * AND_of_two_bytes[x + y * 256]
+ end
+
 end
 
 HEX = HEX or
@@ -308,7 +314,8 @@ local sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64
 local sha2_K_lo, sha2_K_hi, sha2_H_lo, sha2_H_hi = {}, {}, {}, {}
 local sha2_H_ext256 = {[224] = {}, [256] = sha2_H_hi}
 local sha2_H_ext512_lo, sha2_H_ext512_hi = {[384] = {}, [512] = sha2_H_lo}, {[384] = {}, [512] = sha2_H_hi}
-local md5_K, md5_sha1_H, md5_next_shift = {}, {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0}, {0, 0, 0, 0, 0, 0, 0, 0, 28, 25, 26, 27, 0, 0, 10, 9, 11, 12, 0, 15, 16, 17, 18, 0, 20, 22, 23, 21}
+local md5_K, md5_sha1_H = {}, {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0}
+local md5_next_shift = {0, 0, 0, 0, 0, 0, 0, 0, 28, 25, 26, 27, 0, 0, 10, 9, 11, 12, 0, 15, 16, 17, 18, 0, 20, 22, 23, 21}
 
 local HEX64, XOR64A5 -- defined only for branches that internally use 64-bit integers: "INT64" and "FFI"
 local common_W = {} -- temporary table shared between all calculations (to avoid creating new temporary table every time)
@@ -945,7 +952,7 @@ if branch == "INT64" then
 
  hi_factor = 4294967296
 
- HEX64, XOR64A5, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64 = load[[
+ HEX64, XOR64A5, XOR_BYTE, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64 = load[[
  local md5_next_shift = ...
  local string_format, string_unpack = string.format, string.unpack
 
@@ -957,6 +964,10 @@ if branch == "INT64" then
  return x ~ 0xa5a5a5a5a5a5a5a5
  end
 
+ local function XOR_BYTE(x, y)
+ return x ~ y
+ end
+
  local common_W = {}
 
  local function sha256_feed_64(H, K, str, offs, size)
@@ -1140,7 +1151,7 @@ if branch == "INT64" then
  H[1], H[2], H[3], H[4], H[5] = h1, h2, h3, h4, h5
  end
 
- return HEX64, XOR64A5, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64
+ return HEX64, XOR64A5, XOR_BYTE, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64
  ]](md5_next_shift)
 
 end
@@ -1156,14 +1167,18 @@ if branch == "INT32" then
  return string_format("%08x", x)
  end
 
- XOR32A5, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64 = load[[
+ XOR32A5, XOR_BYTE, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64 = load[[
  local md5_next_shift = ...
  local string_unpack, floor = string.unpack, math.floor
 
  local function XOR32A5(x)
  return x ~ 0xA5A5A5A5
  end
 
+ local function XOR_BYTE(x, y)
+ return x ~ y
+ end
+
  local common_W = {}
 
  local function sha256_feed_64(H, K, str, offs, size)
@@ -1383,7 +1398,7 @@ if branch == "INT32" then
  H[1], H[2], H[3], H[4], H[5] = h1, h2, h3, h4, h5
  end
 
- return XOR32A5, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64
+ return XOR32A5, XOR_BYTE, sha256_feed_64, sha512_feed_128, md5_feed_64, sha1_feed_64
  ]](md5_next_shift)
 
 end
@@ -1728,7 +1743,7 @@ local function sha256ext(width, text)
  tail = tail..sub(text_part, #text_part + 1 - size_tail)
  return partial
  else
- error("Adding more chunks is not allowed after receiving the final result", 2)
+ error("Adding more chunks is not allowed after receiving the result", 2)
  end
  else
  if tail then
@@ -1787,7 +1802,7 @@ local function sha512ext(width, text)
  tail = tail..sub(text_part, #text_part + 1 - size_tail)
  return partial
  else
- error("Adding more chunks is not allowed after receiving the final result", 2)
+ error("Adding more chunks is not allowed after receiving the result", 2)
  end
  else
  if tail then
@@ -1852,7 +1867,7 @@ local function md5(text)
  tail = tail..sub(text_part, #text_part + 1 - size_tail)
  return partial
  else
- error("Adding more chunks is not allowed after receiving the final result", 2)
+ error("Adding more chunks is not allowed after receiving the result", 2)
  end
  else
  if tail then
@@ -1908,7 +1923,7 @@ local function sha1(text)
  tail = tail..sub(text_part, #text_part + 1 - size_tail)
  return partial
  else
- error("Adding more chunks is not allowed after receiving the final result", 2)
+ error("Adding more chunks is not allowed after receiving the result", 2)
  end
  else
  if tail then
@@ -1944,17 +1959,87 @@ local function sha1(text)
 end
 
 
+local function hex2bin(hex_string)
+ return (gsub(hex_string, "%x%x",
+ function (hh)
+ return char(tonumber(hh, 16))
+ end
+ ))
+end
+
+
+local block_size_for_HMAC -- a table, will be defined at the end of the module
+
+local function pad_and_xor(str, result_length, byte_for_xor)
+ return gsub(str, ".",
+ function(c)
+ return char(XOR_BYTE(byte(c), byte_for_xor))
+ end
+ )..string_rep(char(byte_for_xor), result_length - #str)
+end
+
+local function hmac(hash_func, key, message)
+
+ -- Create an instance (private objects for current calculation)
+ local block_size = block_size_for_HMAC[hash_func]
+ if not block_size then
+ error("Unknown hash function", 2)
+ end
+ if #key > block_size then
+ key = hex2bin(hash_func(key))
+ end
+ local append = hash_func()(pad_and_xor(key, block_size, 0x36))
+ local result
+
+ local function partial(message_part)
+ if not message_part then
+ result = result or hash_func(pad_and_xor(key, block_size, 0x5C)..hex2bin(append()))
+ return result
+ elseif result then
+ error("Adding more chunks is not allowed after receiving the result", 2)
+ else
+ append(message_part)
+ return partial
+ end
+ end
+
+ if message then
+ -- Actually perform calculations and return the HMAC of a message
+ return partial(message)()
+ else
+ -- Return function for chunk-by-chunk loading of a message
+ -- User should feed every chunk of the message as single argument to this function and finally get HMAC by invoking this function without an argument
+ return partial
+ end
+
+end
+
+
 local sha2 = {
- -- SHA2 functions:
+ -- SHA2 hash functions:
  sha256 = function (text) return sha256ext(256, text) end, -- SHA-256
  sha224 = function (text) return sha256ext(224, text) end, -- SHA-224
  sha512 = function (text) return sha512ext(512, text) end, -- SHA-512
  sha384 = function (text) return sha512ext(384, text) end, -- SHA-384
  sha512_224 = function (text) return sha512ext(224, text) end, -- SHA-512/224
  sha512_256 = function (text) return sha512ext(256, text) end, -- SHA-512/256
- -- bonus:
+ -- other hash functions:
  md5 = md5, -- MD5
  sha1 = sha1, -- SHA-1
+ -- misc utilities:
+ hmac = hmac, -- HMAC (applicable to any hash function from this module)
+ hex2bin = hex2bin, -- converts hexadecimal representation to binary string
+}
+
+block_size_for_HMAC = {
+ [sha2.sha256] = 64, -- SHA-256
+ [sha2.sha224] = 64, -- SHA-224
+ [sha2.sha512] = 128, -- SHA-512
+ [sha2.sha384] = 128, -- SHA-384
+ [sha2.sha512_224] = 128, -- SHA-512/224
+ [sha2.sha512_256] = 128, -- SHA-512/256
+ [sha2.md5] = 64, -- MD5
+ [sha2.sha1] = 64, -- SHA-1
 }
 
 return sha2

sha2_test.lua

@@ -23,9 +23,9 @@ local function test_sha256()
  append_next_chunk(" jumps ")
  append_next_chunk("") -- chunk may be an empty string
  append_next_chunk("over the lazy dog")
- assert(append_next_chunk() == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592") -- invocation without an argument means "give me the final result"
+ assert(append_next_chunk() == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592") -- invocation without an argument means "give me the result"
  assert(append_next_chunk() == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592") -- you can ask the same result multiple times if needed
- assert(not pcall(append_next_chunk, "more text")) -- no more chunks are allowed after receiving the final result, append_next_chunk("more text") will fail
+ assert(not pcall(append_next_chunk, "more text")) -- no more chunks are allowed after receiving the result, append_next_chunk("more text") will fail
 
  -- one-liner is possible due to "append_next_chunk(chunk)" returns the function "append_next_chunk"
  assert(sha256()("The quick brown fox")(" jumps ")("")("over the lazy dog")() == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592")
@@ -300,6 +300,31 @@ local function test_sha1()
 end
 
 
+local function test_hmac()
+
+ local hmac = sha2.hmac
+
+ assert(hmac(sha2.sha1, "your key", "your message") == "317d0dfd868a5c06c9444ac1328aa3e2bfd29fb2")
+ assert(hmac(sha2.sha512, "your key", "your message") == "2f5ddcdbd062a5392f07b0cd0262bf52c21bfb3db513296240cca8d5accc09d18d96be0a94995be4494c032f1eda946ad549fb61ccbe985d160f0b2f9588d34b")
+ assert(hmac(sha2.md5, "", "") == "74e6f7298a9c2d168935f58c001bad88")
+ assert(hmac(sha2.sha256, "", "") == "b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad")
+ assert(hmac(sha2.sha1, "", "") == "fbdb1d1b18aa6c08324b7d64b71fb76370690e1d")
+ assert(hmac(sha2.md5, "key", "The quick brown fox jumps over the lazy dog") == "80070713463e7749b90c2dc24911e275")
+ assert(hmac(sha2.sha256, "key", "The quick brown fox jumps over the lazy dog") == "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8")
+ assert(hmac(sha2.sha1, "key", "The quick brown fox jumps over the lazy dog") == "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9")
+
+ -- chunk-by-chunk mode
+ local append = hmac(sha2.sha1, "key")
+ append("The quick brown fox")
+ append("") -- empty string is allowed as a valid chunk
+ append(" jumps over the lazy dog")
+ assert(append() == "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9") -- invocation without an argument receives the result
+
+ assert(not pcall(hmac, function(x) return sha2.sha256(x) end, "key", "message")) -- must generate "unknown hash function" error
+
+end
+
+
 local function test_all()
 
  test_sha256()
@@ -322,6 +347,8 @@ local function test_all()
 
  test_sha1()
 
+ test_hmac()
+
  print"All tests passed"
 
 end