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

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

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

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

crc

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

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

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.

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

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

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

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

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

value

строка

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

да

Примеры

Вычисление хэша 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. Его длина должна соответствовать указанному алгоритму.	да

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. Его длина должна соответствовать указанному алгоритму.	да

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"