diff --git a/docs/manual.md b/docs/manual.md index f19307d..3fb7909 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -1446,6 +1446,7 @@ function divint(dividend, divisor) ### Генерация случайных данных Функции генерируют raw строку указанного размера , состоящую из случайных байт. +Случайные данные не являются криптографически стойкими. ``` function brandom(size) function brandom_az(size) @@ -1456,4 +1457,73 @@ function brandom_az09(size) * brandom_az - символы от 'a' до 'z' * brandom_az09 - символы от 'a' до 'z' и числа от '0' до '9' +### Парсинг +``` +function parse_hex(hex_string) +``` + +Возвращает raw строку с байтами из hex строки. "1234ABCD" => "\0x11\x34\0xAB\0xCD". +В случае некорректности hex_string возвращается nil. + +### Криптография + +``` +function bcryptorandom(size) +``` + +Генерирует криптографически стойкий блок случайных данных указанного размера. Источник - `/dev/random` + +``` +function hash(hash_type, data) +``` + +Возвращает raw строку - hash от блока данных - raw строки data. hash_type может быть "sha256" или "sha224". + +``` +function aes(encrypt, key, data) +``` + +Простое шифрование или дешифрование одного блока aes. +* encrypt - true - encrypt , false - decrypt +* key - raw строка. размер key должен быть 16,24,32 байт, что соответствует aes128,aes192,aes256 +* data - raw строка. должен быть 16 байт +* возвращается raw строка 16 байт с результатом операции +* в случае неверных размеров key или data вызывается error + +``` +function aes_gcm(encrypt, key, iv, data, associated_data) +``` + +Шифрование в режиме aes-gcm. +* encrypt - true - encrypt , false - decrypt +* key - raw строка. размер key должен быть 16,24,32 байт, что соответствует aes128,aes192,aes256 +* iv - raw строка 12 байт. ОБЯЗАТЕЛЬНО ГЕНЕРИРУЕТСЯ СЛУЧАЙНО ДЛЯ КАЖДОГО ШИФРУЕМОГО БЛОКА ДАННЫХ И ПЕРЕДАЕТСЯ ВМЕСТЕ С НИМ. При **ПОВТОРНОМ ИСПОЛЬЗОВАНИИ iv С ТЕМ ЖЕ КЛЮЧОМ ШИФРОВАНИЕ ЛЕГКО ВЗЛАМЫВАЕТСЯ**. Для генерации iv следует использовать bcryptorandom. +* data - raw строка произвольного размера. Шифр использует гамму, поэтому исходные данные не привязаны к размеру блока AES. +* associated_data - нешифруемые данные, передаваемые вместе с шифрованным сообщением и участвующие в подсчете atag. Может быть nil. +* возвращается 2 значения : raw строка - блок шифрованных данных и raw строка atag (authentication tag). atag может быть передан вместе с шифрованным сообщением и associated_data для проверки их целостности. +* в случае неверных размеров key или iv вызывается error + +``` +function aes_ctr(key, iv, data) +``` +Шифрование в режиме aes-ctr. +* key - raw строка. размер key должен быть 16,24,32 байт, что соответствует aes128,aes192,aes256 +* iv - raw строка 16 байт. ОБЯЗАТЕЛЬНО ГЕНЕРИРУЕТСЯ СЛУЧАЙНО ДЛЯ КАЖДОГО ШИФРУЕМОГО БЛОКА ДАННЫХ И ПЕРЕДАЕТСЯ ВМЕСТЕ С НИМ. При **ПОВТОРНОМ ИСПОЛЬЗОВАНИИ iv С ТЕМ ЖЕ КЛЮЧОМ ШИФРОВАНИЕ ЛЕГКО ВЗЛАМЫВАЕТСЯ**. Для генерации iv следует использовать bcryptorandom. +* data - raw строка произвольного размера. Шифр использует гамму, поэтому исходные данные не привязаны к размеру блока AES. +* шифрование работает по принципу xor с гаммой, поэтому симметрично. шифрование и дешифрование - одна операция. +* возвращается raw строка - блок шифрованных данных +* в случае неверных размеров key или iv вызывается error + +``` +function hkdf(hash_type, salt, ikm, info, okm_len) +``` + +HKDF - HMAC-based Key Derivation Function. Генератор ключей на базе произвольных входных данных - input keying material (ikm). + +* hash_type может быть "sha256" или "sha224" +* salt - raw строка произвольного размера, может быть nil. "соль". несекретная информация. позволяет сделать результат разным на тех же ikm для разных значений salt. если nil, используется блок нулевых байт размером, равным размеру результата hash функции. +* ikm - raw строка - input keying material. на базе этих данных и salt генерируется okm - output keying material +* info - raw строка произвольного размера, может быть nil. аналогично salt, но salt подмешивается на extraction phase, а info - на expansion. если nil, то используется info нулевого размера. +* okm_len - требуемая длина okm - output keying material +* возвращается raw строка - okm