Хэш-функции и криптографические функции

В данном разделе при описании функций приняты следующие обозначения:

Типы значений, которые принимает аргумент, указаны в угловых скобках.
Перечень необязательных аргументов заключается в квадратные скобки. При вызове функции квадратные скобки вводить не нужно.
После :: в угловых скобках указаны типы значений, которые возвращает функция.

Функции хэширования и контрольных сумм

crc

Вычисляет CRC (контрольную сумму) значения. Используемый алгоритм вычисления задается опционально.

Спецификация функции

crc(value: <строка>, [algorithm: <строка>])
:: <строка>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка, для которой вычисляется контрольная сумма.		да
`algorithm`	строка	Алгоритм CRC. Допустимые значения см. ниже.	`"CRC_32_ISO_HDLC"`	нет

value

строка

Строка, для которой вычисляется контрольная сумма.

да

algorithm

строка

Алгоритм CRC. Допустимые значения см. ниже.

"CRC_32_ISO_HDLC"

нет

Допустимые алгоритмы CRC:

"CRC_3_GSM";
"CRC_3_ROHC";
"CRC_4_G_704";
"CRC_4_INTERLAKEN";
"CRC_5_EPC_C1G2";
"CRC_5_G_704";
"CRC_5_USB";
"CRC_6_CDMA2000_A";
"CRC_6_CDMA2000_B";
"CRC_6_DARC";
"CRC_6_GSM";
"CRC_6_G_704";
"CRC_7_MMC";
"CRC_7_ROHC";
"CRC_7_UMTS";
"CRC_8_AUTOSAR";
"CRC_8_BLUETOOTH";
"CRC_8_CDMA2000";
"CRC_8_DARC";
"CRC_8_DVB_S2";
"CRC_8_GSM_A";
"CRC_8_GSM_B";
"CRC_8_HITAG";
"CRC_8_I_432_1";
"CRC_8_I_CODE";
"CRC_8_LTE";
"CRC_8_MAXIM_DOW";
"CRC_8_MIFARE_MAD";
"CRC_8_NRSC_5";
"CRC_8_OPENSAFETY";
"CRC_8_ROHC";
"CRC_8_SAE_J1850";
"CRC_8_SMBUS";
"CRC_8_TECH_3250";
"CRC_8_WCDMA";
"CRC_10_ATM";
"CRC_10_CDMA2000";
"CRC_10_GSM";
"CRC_11_FLEXRAY";
"CRC_11_UMTS";
"CRC_12_CDMA2000";
"CRC_12_DECT";
"CRC_12_GSM";
"CRC_12_UMTS";
"CRC_13_BBC";
"CRC_14_DARC";
"CRC_14_GSM";
"CRC_15_CAN";
"CRC_15_MPT1327";
"CRC_16_ARC";
"CRC_16_CDMA2000";
"CRC_16_CMS";
"CRC_16_DDS_110";
"CRC_16_DECT_R";
"CRC_16_DECT_X";
"CRC_16_DNP";
"CRC_16_EN_13757";
"CRC_16_GENIBUS";
"CRC_16_GSM";
"CRC_16_IBM_3740";
"CRC_16_IBM_SDLC";
"CRC_16_ISO_IEC_14443_3_A";
"CRC_16_KERMIT";
"CRC_16_LJ1200";
"CRC_16_M17";
"CRC_16_MAXIM_DOW";
"CRC_16_MCRF4XX";
"CRC_16_MODBUS";
"CRC_16_NRSC_5";
"CRC_16_OPENSAFETY_A";
"CRC_16_OPENSAFETY_B";
"CRC_16_PROFIBUS";
"CRC_16_RIELLO";
"CRC_16_SPI_FUJITSU";
"CRC_16_T10_DIF";
"CRC_16_TELEDISK";
"CRC_16_TMS37157";
"CRC_16_UMTS";
"CRC_16_USB";
"CRC_16_XMODEM";
"CRC_17_CAN_FD";
"CRC_21_CAN_FD";
"CRC_24_BLE";
"CRC_24_FLEXRAY_A";
"CRC_24_FLEXRAY_B";
"CRC_24_INTERLAKEN";
"CRC_24_LTE_A";
"CRC_24_LTE_B";
"CRC_24_OPENPGP";
"CRC_24_OS_9";
"CRC_30_CDMA";
"CRC_31_PHILIPS";
"CRC_32_AIXM";
"CRC_32_AUTOSAR";
"CRC_32_BASE91_D";
"CRC_32_BZIP2";
"CRC_32_CD_ROM_EDC";
"CRC_32_CKSUM";
"CRC_32_ISCSI";
"CRC_32_ISO_HDLC";
"CRC_32_JAMCRC";
"CRC_32_MEF";
"CRC_32_MPEG_2";
"CRC_32_XFER";
"CRC_40_GSM";
"CRC_64_ECMA_182";
"CRC_64_GO_ISO";
"CRC_64_MS";
"CRC_64_REDIS";
"CRC_64_WE";
"CRC_64_XZ";
"CRC_82_DARC";

Ошибки

Функция может возвращать ошибки, для которых требуется обработка:

value не является строкой.
algorithm не является поддерживаемым алгоритмом.

Примеры

Вычислить контрольную сумму CRC согласно алгоритму по умолчанию

Пример 1. Исходный код

crc("foo")

Пример 2. Результат

"2356372769"

Вычислить контрольную сумму CRC согласно алгоритму CRC_32_CKSUM

Пример 3. Исходный код

crc("foo", algorithm: "CRC_32_CKSUM")

Пример 4. Результат

"4271552933"

hmac

Вычисляет HMAC для значения value с использованием указанного ключа key. Используемый алгоритм хэширования можно указать опционально.

В большинстве случаев полученный байтовый поток следует закодировать в шестнадцатеричную строку, используя функцию encode_base16, или в строку в формате Base64, используя функцию encode_base64.

Спецификация функции

hmac(value: <строка>, key: <строка>, [algorithm: <строка>])
:: <строка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка для вычисления HMAC.		да
`key`	строка	Строка для использования в качестве криптографического ключа.		да
`algorithm`	строка	Алгоритм хэширования. Допустимые значения: `"SHA1"`; `"SHA-224"`; `"SHA-256"`; `"SHA-384"`; `"SHA-512"`.	`SHA-256`	нет

value

строка

Строка для вычисления HMAC.

да

key

строка

Строка для использования в качестве криптографического ключа.

да

algorithm

строка

Алгоритм хэширования. Допустимые значения:

"SHA1";
"SHA-224";
"SHA-256";
"SHA-384";
"SHA-512".

SHA-256

нет

Ошибки

Эта функция не возвращает ошибок, если в аргументе algorithm указано значение по умолчанию или строковый литерал с названием алгоритма, распознаваемым и допустимым на этапе компиляции. В противном случае функция будет возвращать ошибки.

Примеры

Вычислить HMAC сообщения (по умолчанию: SHA-256) и закодировать его в строку Base64

Пример 5. Исходный код

encode_base64(hmac("Hello there", "super-secret-key"))

Пример 6. Результат

eLGE8YMviv85NPXgISRUZxstBNSU47JQdcXkUWcClmI=

Вычислить HMAC сообщения с использованием SHA-224 и закодировать его в шестнадцатеричную строку

Пример 7. Исходный код

encode_base16(hmac("Hello there", "super-secret-key", algorithm: "SHA-224"))

Пример 8. Результат

42fccbc2b7d22a143b92f265a8046187558a94d11ddbb30622207e90

Вычислить HMAC сообщения с использованием переменного алгоритма хэширования

Пример 9. Исходный код

.hash_algo = "SHA-256"
hmac_bytes, err = hmac("Hello there", "super-secret-key", algorithm: .hash_algo)
if err == null {
  .hmac = encode_base16(hmac_bytes)
}

Пример 10. Результат

78b184f1832f8aff3934f5e0212454671b2d04d494e3b25075c5e45167029662

md5

Вычисляет хэш md5 для value.

Спецификация функции

md5(value: <строка>)
:: <строка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка для вычисления хэша.		да

value

строка

Строка для вычисления хэша.

да

Примеры

Создание хэша md5

Пример 11. Исходный код

md5("foo")

Пример 12. Результат

acbd18db4cc2f85cedef654fccc4a4d8

seahash

Вычисляет хэш Seahash для value.

Спецификация функции

seahash(value: <строка>)
:: <целое число>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка, для которой вычисляется хэш.		да

value

строка

Строка, для которой вычисляется хэш.

да

Примечания

Эта функция имеет особое поведение, о котором следует знать:

Из-за ограничений в типах данных VRL функция преобразует результат Seahash из беззнакового 64-битного целого числа в знаковый формат. Значения, превышающие максимальное значение знакового 64-битного целого числа, становятся отрицательными.

Примеры

Вычисление хэша Seahash

Пример 13. Исходный код

seahash("foobar")

Пример 14. Результат

5348458858952426000

Вычисление отрицательного хэша Seahash

Пример 15. Исходный код

seahash("bar")

Пример 16. Результат

-2796170501982571500

sha1

Вычисляет хэш SHA-1 для value.

Спецификация функции

sha1(value: <строка>)
:: <строка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка, для которой вычисляется хэш.		да

value

строка

Строка, для которой вычисляется хэш.

да

Примеры

Вычисление хэша SHA-1

Пример 17. Исходный код

sha1("foo")

Пример 18. Результат

0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

sha2

Вычисляет хэш SHA-2 для value.

Спецификация функции

sha2(value: <строка>, [variant: <строка>])
:: <строка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка, для которой вычисляется хэш.		да
`variant`	строка	Вариант алгоритма хэширования: `"SHA-224"`; `"SHA-256"`; `"SHA-384"`; `"SHA-512"`; `"SHA-512/224"`; `"SHA-512/256"`.	`SHA-512/256`	нет

value

строка

Строка, для которой вычисляется хэш.

да

variant

строка

Вариант алгоритма хэширования:

"SHA-224";
"SHA-256";
"SHA-384";
"SHA-512";
"SHA-512/224";
"SHA-512/256".

SHA-512/256

нет

Примеры

Вычисление хэша SHA-2

Пример 19. Исходный код

sha2("foo", variant: "SHA-512/224")

Пример 20. Результат

d68f258d37d670cfc1ec1001a0394784233f88f056994f9a7e5e99be

sha3

Вычисляет хэш SHA-3 для value.

Спецификация функции

sha3(value: <строка>, [variant: <строка>])
:: <строка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	строка	Строка, для которой вычисляется хэш.		да
`variant`	строка	Вариант алгоритма хэширования: `"SHA3-224"`; `"SHA3-256"`; `"SHA3-384"`; `"SHA3-512"`.	`SHA3-512`	нет

value

строка

Строка, для которой вычисляется хэш.

да

variant

строка

Вариант алгоритма хэширования:

"SHA3-224";
"SHA3-256";
"SHA3-384";
"SHA3-512".

SHA3-512

нет

Примеры

Вычисление хэша SHA-3

Пример 21. Исходный код

sha3("foo", variant: "SHA3-224")

Пример 22. Результат

f4f6779e153c391bbd29c95e72b0708e39d9166c7cea51d1f10ef58a

Функции шифрования

encrypt

Шифрует строку с использованием симметричного алгоритма шифрования.

Поддерживаемые алгоритмы:

AES-256-CFB (ключ = 32 байта, IV = 16 байт)
AES-192-CFB (ключ = 24 байта, IV = 16 байт)
AES-128-CFB (ключ = 16 байт, IV = 16 байт)
AES-256-OFB (ключ = 32 байта, IV = 16 байт)
AES-192-OFB (ключ = 24 байта, IV = 16 байт)
AES-128-OFB (ключ = 16 байт, IV = 16 байт)
AES-128-SIV (ключ = 32 байта, IV = 16 байт)
AES-256-SIV (ключ = 64 байта, IV = 16 байт)
AES-256-CTR-LE (ключ = 32 байта, IV = 16 байт)
AES-192-CTR-LE (ключ = 24 байта, IV = 16 байт)
AES-128-CTR-LE (ключ = 16 байт, IV = 16 байт)
AES-256-CTR-BE (ключ = 32 байта, IV = 16 байт)
AES-192-CTR-BE (ключ = 24 байта, IV = 16 байт)
AES-128-CTR-BE (ключ = 16 байт, IV = 16 байт)
AES-256-CBC-PKCS7 (ключ = 32 байта, IV = 16 байт)
AES-192-CBC-PKCS7 (ключ = 24 байта, IV = 16 байт)
AES-128-CBC-PKCS7 (ключ = 16 байт, IV = 16 байт)
AES-256-CBC-ANSIX923 (ключ = 32 байта, IV = 16 байт)
AES-192-CBC-ANSIX923 (ключ = 24 байта, IV = 16 байт)
AES-128-CBC-ANSIX923 (ключ = 16 байт, IV = 16 байт)
AES-256-CBC-ISO7816 (ключ = 32 байта, IV = 16 байт)
AES-192-CBC-ISO7816 (ключ = 24 байта, IV = 16 байт)
AES-128-CBC-ISO7816 (ключ = 16 байт, IV = 16 байт)
AES-256-CBC-ISO10126 (ключ = 32 байта, IV = 16 байт)
AES-192-CBC-ISO10126 (ключ = 24 байта, IV = 16 байт)
AES-128-CBC-ISO10126 (ключ = 16 байт, IV = 16 байт)
CHACHA20-POLY1305 (ключ = 32 байта, IV = 12 байт)
XCHACHA20-POLY1305 (ключ = 32 байта, IV = 24 байта)
XSALSA20-POLY1305 (ключ = 32 байта, IV = 24 байта)

Спецификация функции

encrypt(plaintext: <строка>, algorithm: <строка>, key: <строка>, iv: <строка>)
:: <строка> , <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	Обязателен
`plaintext`	строка	Строка для шифрования.	да
`algorithm`	строка	Алгоритм, используемый для шифрования.	да
`key`	строка	Ключ для шифрования. Он должен представлять собой сырые (не закодированные) байты. Его длина должна соответствовать указанному алгоритму.	да
`iv`	строка	Вектор инициализации (IV) для шифрования. Он должен представлять собой сырые (не закодированные) байты IV. Его длина должна соответствовать указанному алгоритму. Для каждого сообщения следует генерировать новый IV. Вы можете использовать `random_bytes` для генерации криптографически безопасного случайного значения.	да

plaintext

строка

Строка для шифрования.

да

algorithm

строка

Алгоритм, используемый для шифрования.

да

key

строка

Ключ для шифрования. Он должен представлять собой сырые (не закодированные) байты. Его длина должна соответствовать указанному алгоритму.

да

iv

строка

Вектор инициализации (IV) для шифрования. Он должен представлять собой сырые (не закодированные) байты IV. Его длина должна соответствовать указанному алгоритму.

Для каждого сообщения следует генерировать новый IV. Вы можете использовать random_bytes для генерации криптографически безопасного случайного значения.

да

Ошибки

Функция encrypt может возвращать ошибки, для которых требуется обработка:

Алгоритм algorithm не поддерживается.
Длина key не соответствует требуемому размеру ключа для указанного алгоритма.
Длина iv не соответствует требуемому размеру вектора инициализации для указанного алгоритма.

Примеры

Шифрование значения

Пример 23. Исходный код

plaintext = "super secret message"
iv = "1234567890123456" # обычно следует вызывать random_bytes(16)
key = "16_byte_keyxxxxx"
encrypted_message = encrypt!(plaintext, "AES-128-CBC-PKCS7", key, iv: iv)
encode_base64(encrypted_message)

Пример 24. Результат

GBw8Mu00v0Kc38+/PvsVtGgWuUJ+ZNLgF8Opy8ohIYE=

decrypt

Дешифрует строку с помощью симметричного алгоритма шифрования.

Поддерживаемые алгоритмы:

AES-256-CFB (ключ = 32 байта, iv = 16 байт)
AES-192-CFB (ключ = 24 байта, iv = 16 байт)
AES-128-CFB (ключ = 16 байт, iv = 16 байт)
AES-256-OFB (ключ = 32 байта, iv = 16 байт)
AES-192-OFB (ключ = 24 байта, iv = 16 байт)
AES-128-OFB (ключ = 16 байт, iv = 16 байт)
AES-128-SIV (ключ = 32 байта, IV = 16 байт)
AES-256-SIV (ключ = 64 байта, IV = 16 байт)
AES-256-CTR-LE (ключ = 32 байта, IV = 16 байт)
AES-192-CTR-LE (ключ = 24 байта, IV = 16 байт)
AES-128-CTR-LE (ключ = 16 байт, IV = 16 байт)
AES-256-CTR-BE (ключ = 32 байта, IV = 16 байт)
AES-192-CTR-BE (ключ = 24 байта, IV = 16 байт)
AES-128-CTR-BE (ключ = 16 байт, IV = 16 байт)
AES-256-CBC-PKCS7 (ключ = 32 байта, iv = 16 байт)
AES-192-CBC-PKCS7 (ключ = 24 байта, iv = 16 байт)
AES-128-CBC-PKCS7 (ключ = 16 байт, iv = 16 байт)
AES-256-CBC-ANSIX923 (ключ = 32 байта, iv = 16 байт)
AES-192-CBC-ANSIX923 (ключ = 24 байта, iv = 16 байт)
AES-128-CBC-ANSIX923 (ключ = 16 байт, iv = 16 байт)
AES-256-CBC-ISO7816 (ключ = 32 байта, iv = 16 байт)
AES-192-CBC-ISO7816 (ключ = 24 байта, iv = 16 байт)
AES-128-CBC-ISO7816 (ключ = 16 байт, iv = 16 байт)
AES-256-CBC-ISO10126 (ключ = 32 байта, iv = 16 байт)
AES-192-CBC-ISO10126 (ключ = 24 байта, iv = 16 байт)
AES-128-CBC-ISO10126 (ключ = 16 байт, iv = 16 байт)
CHACHA20-POLY1305 (ключ = 32 байта, IV = 12 байт)
XCHACHA20-POLY1305 (ключ = 32 байта, IV = 24 байта)
XSALSA20-POLY1305 (ключ = 32 байта, IV = 24 байта)

Спецификация функции

decrypt(ciphertext: <строка>, algorithm: <строка>, key: <строка>, iv: <строка>)
:: <строка>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	Обязателен
`ciphertext`	строка	Строка, которую необходимо расшифровать. Она должна представлять собой сырые байты (не закодированные).	да
`algorithm`	строка	Алгоритм, который необходимо использовать.	да
`key`	строка	Ключ для расшифровки. Он должен представлять собой сырые (не закодированные) байты. Его длина должна соответствовать указанному алгоритму.	да
`iv`	строка	Вектор инициализации (IV) для расшифровки. Он должен представлять собой сырые (не закодированные) байты IV. Его длина должна соответствовать указанному алгоритму. Для каждого сообщения следует генерировать новый IV. Вы можете использовать `random_bytes` для генерации криптографически безопасного случайного значения. Значение должно совпадать с тем, что использовалось во время шифрования.	да

ciphertext

строка

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

да

algorithm

строка

Алгоритм, который необходимо использовать.

да

key

строка

Ключ для расшифровки. Он должен представлять собой сырые (не закодированные) байты. Его длина должна соответствовать указанному алгоритму.

да

iv

строка

Вектор инициализации (IV) для расшифровки. Он должен представлять собой сырые (не закодированные) байты IV. Его длина должна соответствовать указанному алгоритму.

Для каждого сообщения следует генерировать новый IV. Вы можете использовать random_bytes для генерации криптографически безопасного случайного значения. Значение должно совпадать с тем, что использовалось во время шифрования.

да

Ошибки

Функция decrypt может возвращать ошибки, для которых требуется обработка:

Алгоритм algorithm не поддерживается.
Длина key не соответствует требуемому размеру ключа для указанного алгоритма.
Длина iv не соответствует требуемому размеру IV для указанного алгоритма.

Примеры

Расшифровка значения

Пример 25. Исходный код

ciphertext = decode_base64!("5fLGcu1VHdzsPcGNDio7asLqE1P43QrVfPfmP4i4zOU=")
iv = decode_base64!("fVEIRkIiczCRWNxaarsyxA==")
key = "16_byte_keyxxxxx"
decrypt!(ciphertext, "AES-128-CBC-PKCS7", key, iv: iv)

Пример 26. Результат

super_secret_message