# src/checksums/sha2

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:

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`.

# Exports

$