src/checksums/sha3

SHA-3 (Secure Hash Algorithm 3) is a cryptographic hash function which takes an input and produces a value known as a message digest.

It provides both fixed size algorithms that generate a one-shot message digest of a determinate size as well as an extendable-output function (XOF) variant that can produce any message digest lengths desired.

Implemented Algorithms

Fixed size functions:

• SHA3-224
• SHA3-256
• SHA3-384
• SHA3-512

Extended-output functions:

• SHAKE128
• SHAKE256
• SHAKE512

For convenience, this module provides output-length type checked functions for the implemented fixed size functions via initSha3_224, initSha3_256, initSha3_384 and initSha3_512. These functions provide a digest overload returning a correctly sized message digest array.

If more relaxed types are required, an "unchecked" Sha3State can be used, but care must be taken to provide digest with a correctly sized dest array.

Example:

import src/checksums/sha3
var hasher = initSha3_256()

hasher.update("The quick brown fox ")
hasher.update("jumps over the lazy dog")

let digest = hasher.digest()

assert $digest == "69070dda01975c8c120c3aada1b282394e7f032fa9cf32f4cb2259a0897dfc04"

Example:

import src/checksums/sha3
var xof = initShake(Shake128)

xof.update("The quick brown fox ")
xof.update("jumps over the lazy dog")
xof.finalize()

var digest: array[16, char]

xof.shakeOut(digest)
assert $digest == "f4202e3c5852f9182a0430fd8144f0a7"

xof.shakeOut(digest)
assert $digest == "4b95e7417ecae17db0f8cfeed0e3e66e"

Imports

sha_utils

Types

Sha3Digest_224 = array[28, char]

SHA3-224 output digest.

Sha3Digest_256 = array[32, char]

SHA3-256 output digest.

Sha3Digest_384 = array[48, char]

SHA3-384 output digest.

Sha3Digest_512 = array[64, char]

SHA3-512 output digest.

Sha3Instance = enum
  Sha3_224,                 ## SHA3-224 with an output size of 28 bytes
  Sha3_256,                 ## SHA3-256 with an output size of 32 bytes
  Sha3_384,                 ## SHA3-384 with an output size of 48 bytes
  Sha3_512                   ## SHA3-512 with an output size of 64 bytes

Selects a specific SHA3 instance with well known message digest lengths and properties.

Sha3State = distinct KeccakState

An unchecked SHA3 state created from a specific Sha3Instance.

Unchecked meaning the user has to make sure that the target buffer has enough room to store the resulting digest, otherwise digest will truncate the output.

Sha3StateStatic[instance] = distinct Sha3State

A statically checked SHA3 state created from a specific Sha3Instance.

ShakeInstance = enum
  Shake128,                 ## Shake-128
  Shake256,                 ## Shake-256
  Shake512                   ## Shake-512 (Keccak proposal; not officially included in SHA3)

Selects a specific Shake instance with well known properties.

ShakeState = distinct KeccakState

A Shake state created from a specific ShakeInstance.

Procs

proc digest(state: var Sha3State; dest: var openArray[char]): int {....raises: [],
    tags: [], forbids: [].}

Finishes, stores the completed message digest in dest and returns the number of bytes written in dest.

If dest is not big enough to contain the digest produced by the selected instance, everything that would overflow is truncated.

proc digest(state: var Sha3StateStatic[Sha3_224]): Sha3Digest_224 {....raises: [],
    tags: [], forbids: [].}

Finishes and returns the completed SHA3-224 message digest.

proc digest(state: var Sha3StateStatic[Sha3_256]): Sha3Digest_256 {....raises: [],
    tags: [], forbids: [].}

Finishes and returns the completed SHA3-256 message digest.

proc digest(state: var Sha3StateStatic[Sha3_384]): Sha3Digest_384 {....raises: [],
    tags: [], forbids: [].}

Finishes and returns the completed SHA3-284 message digest.

proc digest(state: var Sha3StateStatic[Sha3_512]): Sha3Digest_512 {....raises: [],
    tags: [], forbids: [].}

Finishes and returns the completed SHA3-512 message digest.

func digestLength(instance: Sha3Instance): int {....raises: [], tags: [],
    forbids: [].}

Returns the message digest size for the selected SHA3 instance.

func digestLength(instance: ShakeInstance): int {....raises: [], tags: [],
    forbids: [].}

Returns the message digest size for the selected Shake instance.

proc finalize(state: var ShakeState) {....raises: [], tags: [], forbids: [].}

Finishes the input digestion state of the given ShakeState and readies it for message digest retrieval.

func initSha3(instance: Sha3Instance): Sha3State {....raises: [], tags: [],
    forbids: [].}

Constructs a new unchecked SHA3 state for the selected instance instance.

func initSha3_224(): Sha3StateStatic[Sha3_224] {....raises: [], tags: [],
    forbids: [].}

Constructs a new statically checked state for the SHA3-224 instance.

func initSha3_256(): Sha3StateStatic[Sha3_256] {....raises: [], tags: [],
    forbids: [].}

Constructs a new statically checked state for the SHA3-256 instance.

func initSha3_384(): Sha3StateStatic[Sha3_384] {....raises: [], tags: [],
    forbids: [].}

Constructs a new statically checked state for the SHA3-384 instance.

func initSha3_512(): Sha3StateStatic[Sha3_512] {....raises: [], tags: [],
    forbids: [].}

Constructs a new statically checked state for the SHA3-512 instance.

func initSha3StateStatic(instance: static Sha3Instance): Sha3StateStatic[
    instance]

Constructs a new statically checked SHA3 state for the selected instance instance.

func initShake(instance: ShakeInstance): ShakeState {....raises: [], tags: [],
    forbids: [].}

Constructs a new Shake state for the selected instance instance.

proc secureHash(instance: Sha3Instance; data: openArray[char]): seq[char] {.
    ...raises: [], tags: [], forbids: [].}

Convenience wrapper around the standard "init, update, digest" sequence with a runtime selected SHA instance.

proc secureHash(instance: static Sha3Instance; data: openArray[char]): auto

Convenience wrapper around the standard "init, update, digest" sequence with a statically selected SHA instance.

proc shakeOut(state: var ShakeState; dest: var openArray[char]) {....raises: [],
    tags: [], forbids: [].}

"Shakes out" a part of the variable length Shake message digest. The ShakeState must be finalized before calling this procedure.

It can be invoked multiple times with user selectable buffer sizes. In particular, it is guaranteed that the same digest is extracted in both of the following examples, given the same state:

var digest: array[32, byte]
  
  state.shakeOut(digestPart)

var digestA: array[16, byte]
  var digestB: array[16, byte]
  
  state.shakeOut(digestA)
  state.shakeOut(digestB)

proc update(state: var Sha3State; data: openArray[char]) {.borrow, ...raises: [],
    tags: [], forbids: [].}

Updates the given Sha3State with the provided buffer data.

proc update(state: var ShakeState; data: openArray[char]) {.borrow, ...raises: [],
    tags: [], forbids: [].}

Updates the given ShakeState with the provided buffer data.

proc update[instance: static Sha3Instance](state: var Sha3StateStatic[instance];
    data: openArray[char])

Updates the given Sha3StateStatic with the provided buffer data.