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

It provides fixed size algorithms that generate a one-shot message digest of a determinate size.

Implemented Algorithms

Fixed size functions:

SHA-224
SHA-256
SHA-384
SHA-512

For convenience, this module provides output-length type checked functions for the implemented fixed size functions via initSha_224, initSha_256, initSha_384 and initSha_512. These functions provide a digest overload returning a correctly sized message digest array.

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

Example:

import src/checksums/sha2
var hasher = initSha_256()

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

let digest = hasher.digest()

assert $digest == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592"

Example:

import src/checksums/sha2
var hasher = initSha_384()

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

let digest = hasher.digest()

assert $digest == "ca737f1014a48f4c0b6dd43cb177b0afd9e5169367544c494011e3317dbf9a509cb1e5dc1e85a941bbee3d7f2afbc9b1"

Imports

sha_utils

Types

ShaDigest_224 = array[28, char]

SHA-224 output digest.

ShaDigest_256 = array[32, char]

SHA-256 output digest.

ShaDigest_384 = array[48, char]

SHA-384 output digest.

ShaDigest_512 = array[64, char]

SHA-512 output digest.

ShaInstance = enum
  Sha_224,                  ## SHA-224 with an output size of 28 bytes (truncated from SHA-256)
  Sha_256,                  ## SHA-256 with an output size of 32 bytes
  Sha_384,                  ## SHA-384 with an output size of 48 bytes (truncated from SHA-512)
  Sha_512                    ## SHA-512 with an output size of 64 bytes

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

ShaState = distinct ShaContext

An unchecked SHA state created from a specific ShaInstance.

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.

ShaStateStatic[instance] = distinct ShaState

A statically checked SHA state created from a specific ShaInstance.

Procs

proc digest(state: var ShaState; 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 ShaStateStatic[Sha_224]): ShaDigest_224 {....raises: [], tags: [], forbids: [].}: Finishes and returns the completed SHA-224 message digest.
proc digest(state: var ShaStateStatic[Sha_256]): ShaDigest_256 {....raises: [], tags: [], forbids: [].}: Finishes and returns the completed SHA-256 message digest.
proc digest(state: var ShaStateStatic[Sha_384]): ShaDigest_384 {....raises: [], tags: [], forbids: [].}: Finishes and returns the completed SHA-284 message digest.
proc digest(state: var ShaStateStatic[Sha_512]): ShaDigest_512 {....raises: [], tags: [], forbids: [].}: Finishes and returns the completed SHA-512 message digest.
func digestLength(instance: ShaInstance): int {....raises: [], tags: [], forbids: [].}: Returns the message digest size for the selected SHA instance.
func initSha(instance: ShaInstance): ShaState {....raises: [], tags: [], forbids: [].}: Constructs a new unchecked SHA state for the selected instance instance.
func initSha_224(): ShaStateStatic[Sha_224] {....raises: [], tags: [], forbids: [].}: Constructs a new statically checked state for the SHA-224 instance.
func initSha_256(): ShaStateStatic[Sha_256] {....raises: [], tags: [], forbids: [].}: Constructs a new statically checked state for the SHA-256 instance.
func initSha_384(): ShaStateStatic[Sha_384] {....raises: [], tags: [], forbids: [].}: Constructs a new statically checked state for the SHA-384 instance.
func initSha_512(): ShaStateStatic[Sha_512] {....raises: [], tags: [], forbids: [].}: Constructs a new statically checked state for the SHA-512 instance.
func initShaStateStatic(instance: static ShaInstance): ShaStateStatic[instance]: Constructs a new statically checked SHA state for the selected instance instance.
proc secureHash(instance: ShaInstance; 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 ShaInstance; data: openArray[char]): auto: Convenience wrapper around the standard "init, update, digest" sequence with a statically selected SHA instance.
proc update(state: var ShaState; data: openArray[char]) {.borrow, ...raises: [], tags: [], forbids: [].}: Updates the given ShaState with the provided buffer data.
proc update[instance: static ShaInstance](state: var ShaStateStatic[instance]; data: openArray[char]): Updates the given ShaStateStatic with the provided buffer data.