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

Benchmark

Intel Core i7-8700, 16G DDR4 SDRAM
Nim Compiler Version 1.2.0 [Windows: amd64]
gcc version 10.1.0 (Rev2, Built by MSYS2 project)

nimble all_bench

License

Library and Source Codes

Hashlib

Read license.txt for more details. Copyright (c) 2020 Kai-Hung Chen, Ward. All rights reserved.