☰

# src/checksums/sha1

Theme:

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

Search:

Note: In order to use this module, run `nimble install checksums`.

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

Please note that SHA-1 has been formally deprecated since 2011 and it is strongly recommended to switch to stronger hash functions such as the SHA-2 or SHA-3 family.

Even though SHA-1 is formally deprecated, this module itself is not deprecated and will continue to be usable.

# See also

- base64 module for a Base64 encoder and decoder
- hashes module for efficient computations of hash values for diverse Nim types
- md5 module for the MD5 checksum algorithm
- sha2 module for the newer hash familiy SHA-2
- sha3 module for the newest hash family SHA-3

Example:

    import src/checksums/sha1
    let accessName = secureHash("John Doe")
    assert $accessName == "AE6E4D1209F17B460503904FAD297B31E9CF6362"

Example: cmd: -r:off

    import src/checksums/sha1
    let
      a = secureHashFile("myFile.nim")
      b = parseSecureHash("10DFAEBF6BFDBC7939957068E2EFACEC4972933C")
    assert a == b, "files don't match"

# Types

    SecureHash = distinct Sha1Digest

    Sha1Digest = array[0 .. 20 - 1, uint8]

    Sha1State = object

# Procs

    proc `$`(self: SecureHash): string {....raises: [], tags: [], forbids: [].}

  Returns the string representation of a `SecureHash`.

  See also:

  - secureHash proc for generating a `SecureHash` from a string

  Example:

      let hash = secureHash("Hello World")
      assert $hash == "0A4D55A8D778E5022FAB701977C5D840BBC486D0"

    proc `==`(a, b: SecureHash): bool {....raises: [], tags: [], forbids: [].}

  Checks if two `SecureHash` values are identical.

  Example:

      let
        a = secureHash("Hello World")
        b = secureHash("Goodbye World")
        c = parseSecureHash("0A4D55A8D778E5022FAB701977C5D840BBC486D0")
      assert a != b
      assert a == c

    proc finalize(ctx: var Sha1State): Sha1Digest {....raises: [], tags: [],
        forbids: [].}

  Finalizes the `Sha1State` and returns a `Sha1Digest`.

  If you use the secureHash proc, there's no need to call this function explicitly.

    proc isValidSha1Hash(s: string): bool {....raises: [], tags: [], forbids: [].}

  Checks if a string is a valid sha1 hash sum.

    proc newSha1State(): Sha1State {....raises: [], tags: [], forbids: [].}

  Creates a `Sha1State`.

  If you use the secureHash proc, there's no need to call this function explicitly.

    proc parseSecureHash(hash: string): SecureHash {....raises: [ValueError], tags: [],
        forbids: [].}

  Converts a string `hash` to a `SecureHash`.

  See also:

  - secureHash proc for generating a `SecureHash` from a string
  - secureHashFile proc for generating a `SecureHash` from a file

  Example:

      let
        hashStr = "0A4D55A8D778E5022FAB701977C5D840BBC486D0"
        secureHash = secureHash("Hello World")
      assert secureHash == parseSecureHash(hashStr)

    proc secureHash(str: openArray[char]): SecureHash {....raises: [], tags: [],
        forbids: [].}

  Generates a `SecureHash` from `str`.

  See also:

  - secureHashFile proc for generating a `SecureHash` from a file
  - parseSecureHash proc for converting a string `hash` to `SecureHash`

  Example:

      let hash = secureHash("Hello World")
      assert hash == parseSecureHash("0A4D55A8D778E5022FAB701977C5D840BBC486D0")

    proc secureHashFile(filename: string): SecureHash {....raises: [IOError],
        tags: [ReadIOEffect], forbids: [].}

  Generates a `SecureHash` from a file.

  See also:

  - secureHash proc for generating a `SecureHash` from a string
  - parseSecureHash proc for converting a string `hash` to `SecureHash`

    proc update(ctx: var Sha1State; data: openArray[char]) {....raises: [], tags: [],
        forbids: [].}

  Updates the `Sha1State` with `data`.

  If you use the secureHash proc, there's no need to call this function explicitly.