Криптографические функции

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

  • Типы значений, которые принимает аргумент, указаны в угловых скобках.

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

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

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

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-256-CTR (ключ = 32 байта, IV = 16 байт)

  • AES-192-CTR (ключ = 24 байта, IV = 16 байт)

  • AES-128-CTR (ключ = 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 байт)

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

encrypt(plaintext: <строка>, algorithm: <строка>, key: <строка>, iv: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

plaintext

строка

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

да

algorithm

строка

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

да

key

строка

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

да

iv

строка

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

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

да

Ошибки

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

  • Алгоритм algorithm не поддерживается.

  • Длина key не соответствует требуемому размеру ключа для указанного алгоритма.

  • Длина iv не соответствует требуемому размеру вектора инициализации для указанного алгоритма.

Примеры

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

Example 1. Исходный код
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)
Example 2. Результат
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-256-CTR (ключ = 32 байта, iv = 16 байт)

  • AES-192-CTR (ключ = 24 байта, iv = 16 байт)

  • AES-128-CTR (ключ = 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 байт)

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

decrypt(ciphertext: <строка>, algorithm: <строка>, key: <строка>, iv: <строка>)
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

ciphertext

строка

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

да

algorithm

строка

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

да

key

строка

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

да

iv

строка

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

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

да

Ошибки

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

  • Алгоритм algorithm не поддерживается.

  • Длина key не соответствует требуемому размеру ключа для указанного алгоритма.

  • Длина iv не соответствует требуемому размеру IV для указанного алгоритма.

Примеры

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

Example 3. Исходный код
ciphertext = decode_base64!("5fLGcu1VHdzsPcGNDio7asLqE1P43QrVfPfmP4i4zOU=")
iv = decode_base64!("fVEIRkIiczCRWNxaarsyxA==")
key = "16_byte_keyxxxxx"
decrypt!(ciphertext, "AES-128-CBC-PKCS7", key, iv: iv)
Example 4. Результат
super_secret_message

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

hmac

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

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

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

hmac(значение: <строка>, key: <строка>, [algorithm: <строка>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

key

строка

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

да

algorithm

строка

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

  • "SHA1";

  • "SHA-224";

  • "SHA-256";

  • "SHA-384";

  • "SHA-512";

SHA-256

нет

Ошибки

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

Примеры

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

Example 5. Исходный код
encode_base64(hmac("Hello there", "super-secret-key"))
Example 6. Результат
eLGE8YMviv85NPXgISRUZxstBNSU47JQdcXkUWcClmI=

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

Example 7. Исходный код
encode_base16(hmac("Hello there", "super-secret-key", algorithm: "SHA-224"))
Example 8. Результат
42fccbc2b7d22a143b92f265a8046187558a94d11ddbb30622207e90

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

Example 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)
}
Example 10. Результат
78b184f1832f8aff3934f5e0212454671b2d04d494e3b25075c5e45167029662

md5

Вычисляет хеш md5 для значения.

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

md5(значение: <строка>)
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

Примеры

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

Example 11. Исходный код
md5("foo")
Example 12. Результат
acbd18db4cc2f85cedef654fccc4a4d8

seahash

Вычисляет хеш Seahash для значения.

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

seahash(значение: <строка>)
:: <целое число>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

Примечания

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

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

Примеры

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

Example 13. Исходный код
seahash("foobar")
Example 14. Результат
5348458858952426000

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

Example 15. Исходный код
seahash("bar")
Example 16. Результат
-2796170501982571500

sha1

Вычисляет хеш SHA-1 для значения.

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

sha1(значение: <строка>)
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

Примеры

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

Example 17. Исходный код
sha1("foo")
Example 18. Результат
0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

sha2

Вычисляет хеш SHA-2 для значения.

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

sha2(значение: <строка>, [variant: <строка>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

variant

строка

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

  • "SHA-224";

  • "SHA-256";

  • "SHA-384";

  • "SHA-512";

  • "SHA-512/224";

  • "SHA-512/256".

SHA-512/256

нет

Примеры

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

Example 19. Исходный код
sha2("foo", variant: "SHA-512/224")
Example 20. Результат
d68f258d37d670cfc1ec1001a0394784233f88f056994f9a7e5e99be

sha3

Вычисляет хеш SHA-3 для значения.

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

sha3(значение: <строка>, [variant: <строка>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

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

да

variant

строка

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

  • "SHA3-224";

  • "SHA3-256";

  • "SHA3-384";

  • "SHA3-512".

SHA3-512

нет

Примеры

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

Example 21. Исходный код
sha3("foo", variant: "SHA3-224")
Example 22. Результат
f4f6779e153c391bbd29c95e72b0708e39d9166c7cea51d1f10ef58a
+7 (499) 322 80 40 sales@rvision.ru

О компании Политика конфиденциальности Пользовательское соглашение