Класс KJUR.crypto.Cipher

KJUR.crypto.Cipher — это высокоуровневая обёртка в библиотеке jsrsasign, предназначенная для симметричного шифрования и расшифрования данных. Класс скрывает сложность работы с алгоритмами блочного шифрования, режимами работы и производными ключами, предоставляя единый интерфейс для криптографических операций.

Основная идея заключается в том, чтобы разработчик мог оперировать строками и ключевыми фразами, не погружаясь в детали низкоуровневого криптографического API.

Класс ориентирован на сценарии:

  • шифрование строковых данных (текст, JSON)
  • хранение секретов в зашифрованном виде
  • обмен зашифрованными сообщениями между клиентами
  • совместимость с OpenSSL-подобным форматом

Архитектура и принципы работы

KJUR.crypto.Cipher работает поверх набора симметричных алгоритмов, где один и тот же ключ используется для шифрования и расшифрования.

Процесс включает несколько этапов:

  1. Преобразование пароля в криптографический ключ Используются функции деривации ключа (обычно PBKDF2 или OpenSSL EVP_BytesToKey-подобный механизм).

  2. Выбор алгоритма шифрования Например AES-128-CBC или AES-256-CBC.

  3. Генерация случайного IV (инициализационного вектора)

  4. Шифрование данных в бинарном режиме

  5. Кодирование результата (обычно Base64 или hex)

Поддерживаемые алгоритмы

В зависимости от конфигурации jsrsasign доступны следующие классы алгоритмов:

  • AES (AES-128, AES-192, AES-256)
  • DES / 3DES
  • RC2 (в некоторых сборках)
  • режимы CBC как основной вариант

На практике наиболее часто используется AES-256-CBC как баланс безопасности и производительности.

Формат входных и выходных данных

KJUR.crypto.Cipher работает преимущественно со строками.

Вход:

  • строка (UTF-8 текст)
  • пароль (string)

Выход:

  • строка, закодированная в Base64 (по умолчанию)
  • иногда hex (в зависимости от параметров)

Результат обычно содержит:

  • IV (инициализационный вектор)
  • соль (salt, если используется KDF)
  • зашифрованные данные

Эти компоненты объединяются в один пакет.

Основные методы API

Шифрование

Типичный метод шифрования:

KJUR.crypto.Cipher.encrypt(plaintext, password, options)

Параметры:

  • plaintext — исходный текст
  • password — пароль или ключевая фраза
  • options — объект конфигурации

Пример опций:

  • alg — алгоритм (например “AES-256-CBC”)
  • iter — количество итераций PBKDF2
  • iv — фиксированный IV (не рекомендуется)
  • out — формат вывода (“base64” или “hex”)

Расшифрование

KJUR.crypto.Cipher.decrypt(ciphertext, password, options)

Параметры аналогичны шифрованию, за исключением того, что ciphertext — это ранее зашифрованная строка.

Пример использования

Шифрование строки:

const plain = "Секретное сообщение";
const pass = "strong-password";

const encrypted = KJUR.crypto.Cipher.encrypt(
  plain,
  pass,
  { alg: "AES-256-CBC" }
);

Расшифрование:

const decrypted = KJUR.crypto.Cipher.decrypt(
  encrypted,
  pass,
  { alg: "AES-256-CBC" }
);

Режимы работы и особенности реализации

Cipher в jsrsasign опирается на блочные режимы, где ключевые параметры:

  • CBC (Cipher Block Chaining) — основной режим
  • IV обязателен для обеспечения уникальности шифрования
  • padding используется для выравнивания блока (PKCS#5 / PKCS#7)

Критически важный момент — даже при одинаковом тексте результат шифрования будет различаться из-за случайного IV.

Производные ключи (KDF)

Пароль напрямую не используется как ключ. Он проходит через функцию деривации:

  • PBKDF2 (наиболее распространённый вариант)
  • соль (salt) генерируется случайно
  • количество итераций влияет на стойкость

Пример логики:

password + salt → PBKDF2 → key + iv

Это делает невозможным простое перебирание пароля без затрат вычислений.

Формат совместимости OpenSSL

KJUR.crypto.Cipher может генерировать данные, совместимые с OpenSSL форматом:

  • “Salted__” заголовок
  • соль в первых байтах
  • далее зашифрованный блок

Это позволяет обмениваться данными между JavaScript и системными утилитами OpenSSL.

Обработка ошибок

Типичные ситуации, приводящие к ошибкам:

  • неверный пароль при дешифровании
  • несовпадение алгоритма между encrypt/decrypt
  • повреждённый ciphertext
  • отсутствие IV в структуре данных

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

Безопасность использования

Класс предоставляет удобный интерфейс, но безопасность зависит от правильного использования:

  • нельзя фиксировать IV
  • нельзя использовать слабые пароли
  • необходимо увеличивать число итераций KDF
  • предпочтительно использовать AES-256

Слабые конфигурации приводят к уязвимостям даже при использовании корректной библиотеки.

Типичные сценарии применения

Шифрование локального хранилища:

localStorage.setItem(
  "data",
  KJUR.crypto.Cipher.encrypt(JSON.stringify(obj), password)
);

Защищённая передача данных:

const payload = KJUR.crypto.Cipher.encrypt(message, sessionKey);
socket.send(payload);

Хранение конфигураций:

const config = KJUR.crypto.Cipher.decrypt(encryptedConfig, masterPassword);

Особенности работы в браузере и Node.js

В браузере Cipher использует встроенные криптографические реализации jsrsasign без доступа к системным API.

В Node.js поведение аналогично, но при сборке с поддержкой Node Crypto возможно ускорение операций.

Совместимость с другими частями jsrsasign

KJUR.crypto.Cipher часто используется совместно с:

  • KJUR.crypto.ECDSA — для гибридного шифрования
  • KJUR.crypto.CipherParams — для структурированных данных
  • KJUR.asn1 — при работе с низкоуровневыми форматами

В гибридных схемах Cipher используется для шифрования данных, а асимметричная криптография — для передачи ключей.

Формат внутреннего представления

Внутри Cipher формирует структуру:

  • salt (8 байт)
  • IV (16 байт для AES)
  • ciphertext (переменная длина)

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

Практические ограничения

  • не предназначен для потокового шифрования больших файлов
  • оптимизирован для строковых данных
  • производительность ниже WebCrypto API в современных браузерах
  • зависит от корректной настройки параметров

Расширенные настройки

Некоторые реализации позволяют управлять:

  • длиной ключа
  • режимом padding
  • функцией KDF
  • форматом вывода

Пример расширенной конфигурации:

{
  alg: "AES-256-CBC",
  iter: 2048,
  out: "base64"
}

Взаимодействие с JSON-данными

Cipher часто применяется для сериализации структур:

const encrypted = KJUR.crypto.Cipher.encrypt(
  JSON.stringify(data),
  password
);

При расшифровании необходимо восстанавливать структуру:

const obj = JSON.parse(
  KJUR.crypto.Cipher.decrypt(encrypted, password)
);
Оглавление