Шифрование

Шифрование скрывает содержимое, но только AES-GCM на этой странице одновременно проверяет, что шифротекст и связанные данные не были изменены. Все вызовы используют общую форму функций in-Line.

Что выбрать

Пароль пользователя не шифруют для последующей расшифровки. Для хранения и проверки паролей предназначены парольные функции.

Общие границы безопасности

Объект JSON сначала проходит подстановки in-Line. Значение из переменной может содержать кавычку, обратную косую черту или перевод строки, поэтому перед вставкой внутрь строки JSON применяйте ESCJSON. Ключ, вектор и соль измеряются в байтах после декодирования, а не в видимых символах.

AESENCRYPT и AESDECRYPT

Для новой записи используйте вложенный объект. Он отделяет исходный текст, ключ, режим, начальный вектор и результат, поэтому одна кодировка больше не применяется сразу ко всем значениям.

Обратимая пара со случайным вектором

#beginScript
|DV|[AesPackage]=(|AESENCRYPT|{
  "text":{"value":"hello","encoding":"utf8"},
  "key":{"source":"raw","value":"000102030405060708090a0b0c0d0e0f","encoding":"hex"},
  "cipher":{"mode":"CBC","padding":"PKCS7","keyBits":128,"iv":{"source":"random"}},
  "output":{"encoding":"base64","envelope":"json"}
}|AESENCRYPT|)

|DV|[Plain]=(|AESDECRYPT|{
  "text":{"value":"(|ESCJSON||DV|[AesPackage]|ESCJSON|)","encoding":"json"},
  "key":{"source":"raw","value":"000102030405060708090a0b0c0d0e0f","encoding":"hex"},
  "cipher":{"mode":"CBC","padding":"PKCS7","keyBits":128,"iv":{"source":"envelope"}},
  "output":{"encoding":"utf8","envelope":"none"}
}|AESDECRYPT|)
#endScript

|DV|[AesPackage] получает объект вида {"ct":"...","iv":"..."}, а |DV|[Plain] — hello. Случайный вектор не является секретом, но без него расшифровка невозможна, поэтому он сохраняется в конверте.

Строгий объект AES

При CBC вектор всегда равен 16 байтам. Для шифрования его источник — provided с value и encoding либо random; для расшифровки — provided либо envelope. При ECB объект iv всё равно обязателен, но должен быть ровно {"source":"none"}.

Ключ raw после декодирования должен точно совпасть с keyBits: 16, 24 или 32 байта. envelope:"none" запрещён вместе со случайным вектором или случайной солью, потому что исполнитель не разрешает потерять данные, необходимые для расшифровки. envelope:"json" требует output.encoding:"base64" и возвращает ct, iv, а при производном ключе ещё s; значения iv и s внутри конверта записаны строчными шестнадцатеричными знаками.

Неизвестное или повторяющееся поле строгого объекта возвращает Error: .... Плоская форма со строковыми text и key ещё выполняется для существующих проектов, но смешивать плоский и вложенный договор нельзя.

Ключ AES из пароля

(|AESENCRYPT|{
  "text":{"value":"hello","encoding":"utf8"},
  "key":{"source":"password","value":"correct horse battery staple","encoding":"utf8","derivation":{"algorithm":"pbkdf2","hash":"sha256","iterations":200000,"salt":{"source":"random","bytes":16}}},
  "cipher":{"mode":"CBC","padding":"PKCS7","keyBits":256,"iv":{"source":"random"}},
  "output":{"encoding":"base64","envelope":"json"}
}|AESENCRYPT|)

AESGCMENCRYPT и AESGCMDECRYPT

AES-GCM создаёт случайный начальный вектор и тег подлинности. Тег проверяет шифротекст и дополнительные подтверждаемые данные associatedData; изменение любого из них завершает расшифровку ошибкой. Этот режим определён в NIST SP 800-38D.

Обратимая пара AES-GCM

#beginScript
|DV|[Gcm]=(|AESGCMENCRYPT|{
  "text":"hello",
  "key":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
  "associatedData":"686561646572",
  "keyLength":256,
  "outputFormat":"base64"
}|AESGCMENCRYPT|)

|DV|[Plain]=(|AESGCMDECRYPT|{
  "encryptedText":"|DV|[Gcm]["encryptedText"]",
  "iv":"|DV|[Gcm]["iv"]",
  "tag":"|DV|[Gcm]["tag"]",
  "key":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
  "associatedData":"686561646572",
  "keyLength":256,
  "outputFormat":"base64"
}|AESGCMDECRYPT|)
#endScript

После выполнения |DV|[Plain] равно hello. associatedData здесь содержит шестнадцатеричную запись слова header; эти данные не шифруются, но при расшифровке должны совпасть побайтно.

outputFormat принимает hex, base64, base64url или base32; используйте hex, а не исторический вариант hexa, чтобы одно имя одинаково применялось к шифротексту, вектору и тегу. Необязательный associatedData всегда задаётся шестнадцатеричной строкой.

Результат AESGCMENCRYPT — объект с полями iv, tag, encryptedText, key и outputFormat. Поле key повторяет входной секрет: не отправляйте и не сохраняйте весь объект как готовый пакет, выберите из него только iv, tag, encryptedText и outputFormat. Ошибка обеих функций возвращается объектом {"error":"..."}, а не строкой с началом Error: .

Генерация пары RSA: RSAGENKEY

Правильное имя команды — RSAGENKEY. Запись RSAKEYGEN из старого HTML не существует в исполнителе.

(|RSAGENKEY|2048|RSAGENKEY|)

Аргумент — обычное целое число битов, не объект JSON. Пустая или нечисловая строка выбирает 2048, поэтому ошибочный вызов {"keySize":4096} молча создаст 2048-битную пару. Используемая библиотека принимает размеры от 512 до 8192 бит; создание большого ключа выполняется синхронно и может занять заметное время.

Успешный результат — объект со следующими полями:

• privateKeyPem — незашифрованный закрытый ключ PKCS#1 с заголовком BEGIN RSA PRIVATE KEY;
• publicKeyPem — открытый ключ с заголовком BEGIN PUBLIC KEY;
• privateKey — modulus, d, p, q, dp, dq, inverseQ в Base64;
• publicKey — modulus и exponent в Base64;
• keySize — запрошенный размер в битах.

При ошибке RSAGENKEY возвращает обычный текст сообщения без единого обязательного начала.

RSAENCRYPT и RSADECRYPT

Следующий сценарий создаёт пару, переводит открытые составные части из Base64 в шестнадцатеричную запись, шифрует короткую строку и расшифровывает её закрытым ключом:

#beginScript
|DV|[Keys]=(|RSAGENKEY|2048|RSAGENKEY|)
|DV|[ModulusHex]=(|BASE64TOHEX||DV|[Keys]["publicKey"]["modulus"]|BASE64TOHEX|)
|DV|[ExponentHex]=(|BASE64TOHEX||DV|[Keys]["publicKey"]["exponent"]|BASE64TOHEX|)

|DV|[Cipher]=(|RSAENCRYPT|{
  "text":"session-key-001",
  "modulus":"|DV|[ModulusHex]",
  "publicExponent":"|DV|[ExponentHex]",
  "encType":"oaep",
  "oaepHash":"sha256",
  "oaepMgfHash":"sha256",
  "littleEndian":false
}|RSAENCRYPT|)

|DV|[Plain]=(|RSADECRYPT|{
  "encryptedText":"|DV|[Cipher]",
  "privateKeyPem":"(|ESCJSON||DV|[Keys]["privateKeyPem"]|ESCJSON|)",
  "encType":"oaep",
  "oaepHash":"sha256",
  "oaepMgfHash":"sha256",
  "littleEndian":false
}|RSADECRYPT|)
#endScript

|DV|[Plain] получает session-key-001. RSAENCRYPT возвращает Base64, а RSADECRYPT ожидает шифротекст в том же представлении.

Точный договор RSA

encType равен oaep по умолчанию или v1.5. Для OAEP явно задавайте одинаковые oaepHash и oaepMgfHash на обеих операциях; без них текущая библиотека выбирает SHA-1. Необязательная oaepLabel является шестнадцатеричной строкой и также должна совпасть. littleEndian по умолчанию false; меняйте его только ради внешнего договора и одинаково с обеих сторон.

RSA предназначен для коротких данных. При OAEP предельное число байтов равно размер_ключа_в_байтах − 2 × размер_хеша_в_байтах − 2: для RSA-2048 и SHA-256 это 190 байт. Точные схемы OAEP и PKCS#1 v1.5 определены в RFC 8017.

Неверный объект, ключ, заполнение или слишком длинное сообщение возвращают обычный текст ошибки. Проверяйте, что результат шифрования соответствует ожидаемой Base64-строке, а не просто является непустым.

SALSA20ENCRYPT и CHACHA20ENCRYPT

Обе функции принимают key, nonce и message как обычные строки, превращают их в UTF-8 и возвращают шифротекст Base64. Шестнадцатерично выглядящий ключ здесь остаётся текстом: строка 0011 даёт четыре байта символов, а не два байта 00 11.

(|SALSA20ENCRYPT|{"key":"1234567890abcdef","nonce":"12345678","message":"hello","keyLength":128,"rounds":20}|SALSA20ENCRYPT|)

Фактический ключ должен содержать ровно 16 или 32 байта, а nonce — ровно 8 байт. Поле keyLength принимает 128 или 256 и по умолчанию равно 256, но оно не изменяет ключ и не сверяет указанное число с его фактической длиной. rounds принимает только 8, 12 или 20, по умолчанию 20. Эти требования следуют из используемых исполнителей CryptoLib4Pascal.

Публичных SALSA20DECRYPT и CHACHA20DECRYPT нет. Хотя сам потоковый шифр симметричен, эти обёртки всегда читают message как UTF-8 и возвращают Base64, поэтому надёжно подать их двоичный результат обратно нельзя. Для новой обратимой схемы используйте AES-GCM. Этот вариант CHACHA20ENCRYPT также не совпадает с IETF ChaCha20, где применяется 12-байтовое одноразовое число. Ошибки возвращаются как Error: ....

BLOWFISHENCRYPT и BLOWFISHDECRYPT

Blowfish оставлен для совместимости. У него блок всего 8 байт и нет встроенного тега подлинности, поэтому для новых данных выбирайте AES-GCM.

Обратимая пара Blowfish-CBC

#beginScript
|DV|[Cipher]=(|BLOWFISHENCRYPT|{
  "text":"hello",
  "key":"0123456789abcdef",
  "mode":"CBC",
  "padding":"PKCS7",
  "keyLength":128,
  "blockSize":64,
  "iv":"0001020304050607",
  "includeIV":false,
  "inputFormat":"plaintext",
  "outputFormat":"base64"
}|BLOWFISHENCRYPT|)

|DV|[Plain]=(|BLOWFISHDECRYPT|{
  "text":"|DV|[Cipher]",
  "key":"0123456789abcdef",
  "mode":"CBC",
  "padding":"PKCS7",
  "keyLength":128,
  "blockSize":64,
  "iv":"0001020304050607",
  "includeIV":false,
  "inputFormat":"base64",
  "outputFormat":"plaintext"
}|BLOWFISHDECRYPT|)
#endScript

|DV|[Plain] получает hello. Начальный вектор содержит ровно 8 байт, то есть 16 шестнадцатеричных знаков.

Значения по умолчанию не образуют пару: шифрование возвращает hexa, а расшифрование ожидает base64; обе операции выбирают ECB и 448-битный ключ. Поэтому указывайте режим, длину ключа и оба представления явно.

Для режима кроме ECB отсутствие явного или извлекаемого вектора завершает расшифровку ошибкой. Неверный JSON, размер ключа, вектора, режим, заполнение или шифротекст возвращают строку с началом Error: .