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

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

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

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

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

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

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

Примеры

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

Пример 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)
Пример 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 для указанного алгоритма.

Примеры

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

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

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

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

нет

Ошибки

Эта функция не возвращает ошибок, если в аргументе 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

строка

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

да

Примеры

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

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

seahash

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

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

seahash(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

строка

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

да

Примеры

Вычисление хеша 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

нет

Примеры

Вычисление хеша 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

нет

Примеры

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

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

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