Hashlib

Hashlib contains almost all the hash functions for Nim and provides uniform interface, hmac, and benchmark for all hashes. The C source codes are collected from RHash, MHash, Sphlib, Team Keccak, BLAKE2, BLAKE3, tiny_sha3, xxHash etc. This module also provides the same interface for libgcrypt, nimcrypto, and Nim builtin MD5/SHA1.

Install

nimble install hashlib

For Linux user:

sudo apt install libgcrypt20 libgcrypt20-dev

This module already includes libgcrypt for Windows (mingw32/64 only).

Usage

How to Import

Hash functions can be imported all-in-one or one-by-one.

import hashlib # import all available hashes
import hashlib/rhash # import all hashes from RHash
import hashlib/mhash # import all hashes from MHash
import hashlib/sph # import all hashes from Sphlib
import hashlib/gcrypt # import all hashes from libgcrypt
import hashlib/misc # import other hashes
import hashlib/lean # import commonly used hashes
import hashlib/bench # import runBench() template

import hashlib/rhash/[aich, crc32, ed2k, edonr, gost, has160, md4, md5, ripemd160, sha1, sha256, sha3, sha512, snefru, streebog, tiger, tth]
import hashlib/mhash/[adler32, crc32, gost, haval, md2, md4, md5, ripemd, sha1, sha256, sha512, snefru, tiger, whirlpool]
import hashlib/sph/[blake, bmw, cubehash, echohash, fugue, groestl, hamsi, haval, jh, keccak, luffa, md2, md4, md5, panama, radiogatun, ripemd, sha0, sha1, sha256, sha512, shabal, shavite, simd, skein, tiger, whirlpool]
import hashlib/misc/[blake2, blake3, crypto, kangarootwelve, nimhash, sha3, tinysha3, tinyshabal, xxhash]

Use import ... as ... to avoid name conflict. For example:

import hashlib/rhash/md5 as rhash_md5
import hashlib/mhash/md5 as mhash_md5
import hashlib/bench

runBench()

Simple API

count[HashType](DataTypes): HashType
count[HashType](DataTypes, DigestTypes)

DataTypes = string | openarray[byte] | openarray[char] | Stream | MemoryBlock
DigestTypes = HashType | Digest | openarray[byte] | openarray[char]

Stream API

init[HashType](): Context[HashType]
init(var Context[HashType])

update(var Context[HashType], DataTypes)

final(var Context[HashType]): HashType
final(var Context[HashType], var DigestTypes)

DataTypes = string | openarray[byte] | openarray[char] | Stream | MemoryBlock
DigestTypes = HashType | Digest | openarray[byte] | openarray[char]

Simple HMAC API

count[Hmac[HashType]](KeyTypes, DataTypes): HashType
count[Hmac[HashType]](KeyTypes, DataTypes, var DigestTypes)

KeyTypes = string | openarray[byte] | openarray[char] | MemoryBlock
DataTypes = string | openarray[byte] | openarray[char] | Stream | MemoryBlock
DigestTypes = HashType | Digest | openarray[byte] | openarray[char]

Stream HMAC API

init[Hmac[HashType]](KeyTypes): Hmac[HashType]
init(var Hmac[HashType], KeyTypes)

update(var Hmac[HashType], DataTypes)

final(var Hmac[HashType]): HashType
final(var Hmac[HashType], var DigestTypes)

KeyTypes = string | openarray[byte] | openarray[char] | MemoryBlock
DataTypes = string | openarray[byte] | openarray[char] | Stream | MemoryBlock
DigestTypes = HashType | Digest | openarray[byte] | openarray[char]

Example

import hashlib/rhash/md5

# Now we have RHASH_MD5
doAssert(declared(RHASH_MD5))
doAssert(RHASH_MD5 is HashType)

# Gets information from HashType
doAssert(RHASH_MD5.digestSize == 16)
doAssert(RHASH_MD5.blockSize == 64)

# Counts the hash for empty string, returns a RHASH_MD5 object
var hash = count[RHASH_MD5]("")
doAssert(hash.type is RHASH_MD5)

# hash.data should be array[16, byte]
doAssert(hash.data == [byte 212, 29, 140, 217, 143, 0, 178, 4, 233, 128, 9, 152, 236, 248, 66, 126])

# `$` convert HashType to string
doAssert($hash == "d41d8cd98f00b204e9800998ecf8427e")

# Result can store in Digest object.
var digest: Digest
count[RHASH_MD5]("", digest)

# digest.data should be seq[byte] in length of RHASH_MD5.digestSize
doAssert(digest.data == @[byte 212, 29, 140, 217, 143, 0, 178, 4, 233, 128, 9, 152, 236, 248, 66, 126])

# `$` convert Digest object to string
doAssert($hash == "d41d8cd98f00b204e9800998ecf8427e")

# Try another input data type: openarray[char]
doAssert($count[RHASH_MD5](toOpenArray("abc", 0, 2)) == "900150983cd24fb0d6963f7d28e17f72")

# Try another ouptut data type: openarray[byte]
var digestSeq = newSeq[byte](16)
count[RHASH_MD5]("abc", digestSeq)
doAssert(digestSeq == @[byte 144, 1, 80, 152, 60, 210, 79, 176, 214, 150, 63, 125, 40, 225, 127, 114])

import strutils
import hashlib/misc/sha3

# Now we have SHAKE128, it support extendable-output functions (XOFs)
doAssert(declared(SHAKE128))
doAssert(SHAKE128.xof == true)

# Gets 1024 bytes output, use initDigest()
digest = initDigest(1024)
count[SHAKE128]("", digest)
doAssert(($digest).startsWith("7f9c2ba4e88f827d616045507605853e"))

# Gets 2048 bytes output, use setLen()
digest.setLen(2048)
count[SHAKE128]("", digest)
doAssert(($digest).endsWith("10e7e33816e581d85fc48a77254c23bb"))

# Try stream API
var ctx = init[RHASH_MD5]()
ctx.update("")
doAssert($ctx.final() == "d41d8cd98f00b204e9800998ecf8427e")

# Reuses the ctx and stores result in digest object
doAssert(ctx.type is Context[RHASH_MD5])
ctx.init()
ctx.update("")
ctx.final(digest)
doAssert($digest == "d41d8cd98f00b204e9800998ecf8427e")

# Try simple HMAC API
doAssert($count[Hmac[RHASH_MD5]]("key", "data") == "9d5c73ef85594d34ec4438b7c97e51d8")

# Try stream HMAC API
var hmac = init[Hmac[RHASH_MD5]]("key")
hmac.update("data")
doAssert($hmac.final() == "9d5c73ef85594d34ec4438b7c97e51d8")

# Reuses the HMAC ctx and stores result in digest object
doAssert(hmac.type is Hmac[RHASH_MD5])
hmac.init("key")
hmac.update("data")
hmac.final(digest)
doAssert($digest == "9d5c73ef85594d34ec4438b7c97e51d8")

import hashlib/bench

# Now we have runBench template
doAssert(declared(runBench))

# Runs benchmark for all available hashes: RHASH_MD5, KECCAKnnn, SHA3_nnn, SHAKEnnn, etc
runBench()

# Runs benchmark for MD5 only
runBench("MD5")

# Runs benchmark for SHA3 and SHAKE
runBench do (name: string) -> bool:
  name.startsWith("SHA3") or name.startsWith("SHAKE")

Available Hashes

<details> <summary>Details</summary>

| Module | Submodule | Hashes | | ------ | ------ | ------ | | rhash | aich | RHASH_AICH | | rhash | crc32 | RHASH_CRC32, RHASH_CRC32C | | rhash | ed2k | RHASH_ED2K | | rhash | edonr | RHASH_EDONR224, RHASH_EDONR256, RHASH_EDONR384, RHASH_EDONR512 | | rhash | gost | RHASH_GOST94, RHASH_GOST94PRO | | rhash | has160 | RHASH_HAS160 | | rhash | md4 | RHASH_MD4 | | rhash | md5 | RHASH_MD5 | | rhash | ripemd | RHASH_RIPEMD160 | | rhash | sha1 | RHASH_SHA1 | | rhash | sha256 | RHASH_SHA224, RHASH_SHA256 | | rhash | sha512 | RHASH_SHA384, RHASH_SHA512 | | rhash | sha3 or keccak | RHASH_KECCAK224, RHASH_KECCAK256, RHASH_KECCAK384, RHASH_KECCAK512, RHASH_SHA3_224, RHASH_SHA3_256, RHASH_SHA3_384, RHASH_SHA3_512 | | rhash | snefru | RHASH_SNEFRU128, RHASH_SNEFRU256 | | rhash | streebog | RHASH_GOST2012_256, RHASH_GOST2012_512, RHASH_STREEBOG256, RHASH_STREEBOG512 | | rhash | tiger | RHASH_TIGER | | rhash | tth | RHASH_TTH | | mhash | adler32 | MHASH_ADLER32 | | mhash | crc32 | MHASH_CRC32, MHASH_CRC32B | | mhash | gost | MHASH_GOST | | mhash | haval | MHASH_HAVAL128_3, MHASH_HAVAL128_4, MHASH_HAVAL128_5, MHASH_HAVAL160_3, MHASH_HAVAL160_4, MHASH_HAVAL160_5, MHASH_HAVAL192_3, MHASH_HAVAL192_4, MHASH_HAVAL192_5, MHASH_HAVAL224_3, MHASH_HAVAL224_4, MHASH_HAVAL224_5, MHASH_HAVAL256_3, MHASH_HAVAL256_4, MHASH_HAVAL256_5 | | mhash | md2 | MHASH_MD2 | | mhash | md4 | MHASH_MD4 | | mhash | md5 | MHASH_MD5 | | mhash | ripemd | MHASH_RIPEMD128, MHASH_RIPEMD160, MHASH_RIPEMD256, MHASH_RIPEMD320 | | mhash | sha1 | MHASH_SHA1 | | mhash | sha256 | MHASH_SHA224, MHASH_SHA256 | | mhash | sha512 | MHASH_SHA384, MHASH_SHA512 | | mhash | snefru | MHASH_SNEFRU128, MHASH_SNEFRU256 | | mhash | tiger | MHASH_TIGER, MHASH_TIGER128, MHASH_TIGER160 | | mhash | whirlpool | MHASH_WHIRLPOOL | | sph | blake | SPH_BLAKE224, SPH_BLAKE256, SPH_BLAKE384, SPH_BLAKE512 | | sph | bmw | SPH_BMW224, SPH_BMW256, SPH_BMW384, SPH_BMW512 | | sph | cubehash | SPH_CUBEHASH224, SPH_CUBEHASH256, SPH_CUBEHASH384, SPH_CUBEHASH512 | | sph | echohash | SPH_ECHO224, SPH_ECHO256, SPH_ECHO384, SPH_ECHO512 | | sph | fugue | SPH_FUGUE224, SPH_FUGUE256, SPH_FUGUE384, SPH_FUGUE512 | | sph | groestl | SPH_GROESTL224, SPH_GROESTL256, SPH_GROESTL384, SPH_GROESTL512 | | sph | hamsi | SPH_HAMSI224, SPH_HAMSI256, SPH_HAMSI384, SPH_HAMSI512 | | sph | haval | SPH_HAVAL128_3, SPH_HAVAL128_4, SPH_HAVAL128_5, SPH_HAVAL160_3, SPH_HAVAL160_4, SPH_HAVAL160_5, SPH_HAVAL192_3, SPH_HAVAL192_4, SPH_HAVAL192_5, SPH_HAVAL224_3, SPH_HAVAL224_4, SPH_HAVAL224_5, SPH_HAVAL256_3, SPH_HAVAL256_4, SPH_HAVAL256_5 | | sph | jh | SPH_JH224, SPH_JH256, SPH_JH384, SPH_JH512 | | sph | luffa | SPH_LUFFA224, SPH_LUFFA256, SPH_LUFFA384, SPH_LUFFA512 | | sph | md2 | SPH_MD2 | | sph | md4 | SPH_MD4 | | sph | md5 | SPH_MD5 | | sph | panama | SPH_PANAMA | | sph | radiogatun | SPH_RADIOGATUN32, SPH_RADIOGATUN64 | | sph | ripemd | SPH_RIPEMD, SPH_RIPEMD128, SPH_RIPEMD160 | | sph | sha0 | SPH_SHA0 | | sph | sha1 | SPH_SHA1 | | sph | sha256 | SPH_SHA224, SPH_SHA256 | | sph | sha512 | SPH_SHA384, SPH_SHA512 | | sph | sha3 or kec