# src/checksums/sha3

Theme:

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

Search:

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

# Exports

$