src/checksums/sha3

SHA-3 (Secure Hash Algorithm 3) — это криптографическая хеш-функция, которая принимает входные данные и генерирует значение, известное как дайджест сообщения.

Она предоставляет как алгоритмы с фиксированным размером, генерирующие одноразовый дайджест сообщения определённого размера, так и вариант функции с расширяемым выходом (XOF), который может генерировать дайджесты любого желаемого размера.

Реализованные алгоритмы

Функции с фиксированным размером:

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

Функции с расширяемым выходом:

• SHAKE128
• SHAKE256
• SHAKE512

Для удобства этот модуль предоставляет функции с проверкой типа длины вывода для реализованных функций с фиксированным размером через initSha3_224, initSha3_256, initSha3_384 и initSha3_512. Эти функции предоставляют перегрузку digest возвращающую массив дайджеста сообщения правильного размера.

Если требуются более свободные типы, можно использовать "непроверенную" Sha3State, но необходимо следить за тем, чтобы предоставить digest с массивом dest правильного размера.

Пример:

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"

Пример:

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"

Импорты

sha_utils

Типы

Sha3Digest_224 = array[28, char]

Дайджест вывода SHA3-224.

Sha3Digest_256 = array[32, char]

Дайджест вывода SHA3-256.

Sha3Digest_384 = array[48, char]

Дайджест вывода SHA3-384.

Sha3Digest_512 = array[64, char]

Дайджест вывода SHA3-512.

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

Выбирает конкретный экземпляр SHA3 с хорошо известными длинами и свойствами дайджеста сообщения.

Sha3State = distinct KeccakState

Непроверенное состояние SHA3, созданное на основе конкретного Sha3Instance.

Непроверенное означает, что пользователь должен убедиться, что целевой буфер имеет достаточно места для хранения полученного дайджеста, в противном случае digest обрезает вывод.

Sha3StateStatic[instance] = distinct Sha3State

Статически проверенное состояние SHA3, созданное на основе конкретного Sha3Instance.

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

Выбирает конкретный экземпляр Shake с хорошо известными свойствами.

ShakeState = distinct KeccakState

Состояние Shake, созданное на основе конкретного ShakeInstance.

Процедуры

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

Завершает, сохраняет завершённый дайджест сообщения в dest и возвращает количество записанных байтов в dest.

Если dest недостаточно велик для хранения дайджеста, созданного выбранным экземпляром, всё, что выходит за пределы, обрезается.

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

Завершает и возвращает завершённый дайджест SHA3-224 сообщения.

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

Завершает и возвращает завершённый дайджест SHA3-256 сообщения.

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

Завершает и возвращает завершённый дайджест SHA3-284 сообщения.

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

Завершает и возвращает завершённый дайджест SHA3-512 сообщения.

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

Возвращает размер дайджеста сообщения для выбранного экземпляра SHA3.

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

Возвращает размер дайджеста сообщения для выбранного экземпляра Shake.

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

Завершает состояние переваривания ввода данного ShakeState и готовит его для получения дайджеста сообщения.

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

Создаёт новое непроверенное состояние SHA3 для выбранного экземпляра instance.

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

Создаёт новое статически проверенное состояние для экземпляра SHA3-224.

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

Создаёт новое статически проверенное состояние для экземпляра SHA3-256.

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

Создаёт новое статически проверенное состояние для экземпляра SHA3-384.

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

Создаёт новое статически проверенное состояние для экземпляра SHA3-512.

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

Создаёт новое статически проверенное состояние SHA3 для выбранного экземпляра instance.

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

Создаёт новое состояние Shake для выбранного экземпляра instance.

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

Обёртка для стандартной последовательности "инициализация, обновление, дайджест" с экземпляром SHA, выбранным во время выполнения.

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

Обёртка для стандартной последовательности "инициализация, обновление, дайджест" с статически выбранным экземпляром SHA.

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

"Выдавливает" часть дайджеста сообщения переменной длины Shake. ShakeState должен быть finalized перед вызовом этой процедуры.

Его можно вызывать несколько раз с выбираемыми пользователем размерами буфера. В частности, гарантируется, что тот же дайджест извлекается в обоих следующих примерах, при одинаковом 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: [].}

Обновляет данный Sha3State с предоставленным буфером data.

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

Обновляет данное ShakeState с предоставленным буфером data.

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

Обновляет данное Sha3StateStatic с предоставленным буфером data.