KJUR.crypto.Cipher: методы и параметры

KJUR.crypto.Cipher представляет собой высокоуровневый интерфейс шифрования в библиотеке jsrsasign, ориентированный на симметричное и частично асимметричное шифрование через унифицированный API. Он используется как обёртка над различными криптографическими примитивами (AES, DES, RSA и др.), обеспечивая единый способ работы с алгоритмами, режимами и кодировками данных.

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

Внутри jsrsasign шифрование организовано через фабрику, которая по имени алгоритма и параметрам создает соответствующий криптографический процессор. Поддерживаются как симметричные алгоритмы (AES-CBC, AES-GCM, DES-EDE3), так и асимметричные схемы (RSAES-PKCS1-v1_5, RSA-OAEP через другие модули библиотеки).

Ключевые сущности:

  • алгоритм шифрования (cipher algorithm)
  • режим работы (mode: CBC, ECB, CFB и др.)
  • padding (PKCS#5, PKCS#7, NoPadding)
  • ключ (key)
  • вектор инициализации (IV)
  • формат входных/выходных данных (hex, base64, string, array)

Основной набор параметров

KJUR.crypto.Cipher принимает конфигурационный объект или набор аргументов, определяющих поведение криптографической операции.

Алгоритм (alg)

Параметр определяет криптографический алгоритм:

  • AES
  • DES
  • DESede (3DES)
  • RSA (в контексте RSA encryption schemes)

Пример:

  • AES
  • AES/CBC/PKCS5Padding
  • DESede/CBC/NoPadding

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

Режим шифрования (mode)

Режим определяет способ обработки блоков данных:

  • CBC (Cipher Block Chaining) — наиболее часто используемый режим
  • ECB (Electronic Codebook) — упрощённый, небезопасный для большинства сценариев
  • CFB (Cipher Feedback)
  • OFB (Output Feedback)

Режим напрямую влияет на необходимость использования IV.

Padding

Дополнение данных до размера блока:

  • PKCS5Padding / PKCS7Padding — стандартное дополнение
  • NoPadding — данные должны быть кратны размеру блока

Padding критически важен для блочных алгоритмов (AES, DES).

Ключ (key)

Ключ передается в зависимости от алгоритма:

  • симметричные алгоритмы — строка, hex или byte array
  • RSA — PEM-структура или объект ключа (PublicKey/PrivateKey)

Ключ может предварительно обрабатываться через KJUR.crypto.KEYUTIL.

IV (initialization vector)

IV используется в режимах CBC, CFB, OFB.

  • Должен быть случайным
  • Обычно 16 байт для AES
  • Может передаваться в hex или byte array

Отсутствие IV в CBC-режиме делает шифрование предсказуемым.

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

Поддерживаемые форматы:

  • hex
  • base64
  • string
  • arraybuffer (в некоторых конфигурациях)

Формат задается через параметры:

  • informat
  • outformat

Статические методы KJUR.crypto.Cipher

В jsrsasign предусмотрены удобные статические методы для быстрого шифрования и расшифрования без создания экземпляра класса.

encrypt(data, key, alg, iv, pass, options)

Метод выполняет шифрование данных.

Параметры:

  • data — исходная строка или байтовый массив
  • key — ключ шифрования
  • alg — алгоритм
  • iv — вектор инициализации (если требуется)
  • pass — пароль (в некоторых схемах PBKDF2)
  • options — дополнительные параметры (форматы, padding)

Поведение метода зависит от выбранного алгоритма:

  • для AES используется симметричное шифрование
  • для RSA — асимметричное шифрование публичным ключом

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

var encrypted = KJUR.crypto.Cipher.encrypt(
  "message",
  "00112233445566778899aabbccddeeff",
  "AES/CBC/PKCS5Padding",
  "0102030405060708"
);

decrypt(data, key, alg, iv, pass, options)

Метод выполняет обратную операцию — расшифрование.

Параметры идентичны encrypt, за исключением направления операции.

Пример:

var decrypted = KJUR.crypto.Cipher.decrypt(
  encrypted,
  "00112233445566778899aabbccddeeff",
  "AES/CBC/PKCS5Padding",
  "0102030405060708"
);

Внутренние методы экземпляра KJUR.crypto.Cipher

При использовании объектного подхода создается экземпляр шифратора, который хранит состояние конфигурации.

constructor(params)

Конструктор принимает объект конфигурации:

  • alg
  • key
  • iv
  • mode
  • padding
  • format

Пример структуры:

var cipher = new KJUR.crypto.Cipher({
  alg: "AES",
  mode: "CBC",
  padding: "PKCS5Padding",
  key: keyHex,
  iv: ivHex
});

init(params)

Метод инициализации состояния шифрования.

  • устанавливает ключ
  • настраивает режим
  • подготавливает внутренний блок cipher engine

Используется при повторной конфигурации экземпляра.

update(data)

Добавляет данные в поток шифрования.

Используется при блочной или потоковой обработке.

Особенности:

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

doFinal()

Завершает процесс шифрования или расшифрования.

Возвращает финальный результат с учетом padding.

Обязательный вызов после update.

cipher() / encryptBlock()

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

  • работает с фиксированным размером блока
  • используется внутри doFinal
  • редко вызывается напрямую

decipher() / decryptBlock()

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

Поддержка RSA в KJUR.crypto.Cipher

Для RSA шифрования Cipher работает через PEM-ключи и схему RSAES.

Параметры:

  • ключ публичный (encryption)
  • ключ приватный (decryption)
  • padding: PKCS1 v1.5 или OAEP (в зависимости от сборки)

Особенности:

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

Пример:

var encrypted = KJUR.crypto.Cipher.encrypt(
  "secret",
  publicKeyPEM,
  "RSA"
);

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

При использовании KJUR.crypto.Cipher возможны типовые ошибки:

  • неверный формат ключа
  • несовпадение длины IV и алгоритма
  • неподдерживаемый режим
  • некорректный padding

Ошибки обычно выбрасываются как исключения JavaScript (throw Error).

Взаимодействие с KJUR.crypto.KEYUTIL

Для работы с ключами часто используется вспомогательный модуль:

  • парсинг PEM → объект ключа
  • генерация ключей
  • конвертация форматов

Пример:

var rsaKey = KEYUTIL.getKey(publicKeyPEM);

Далее ключ передается в Cipher.

Пример полного сценария AES

var key = "00112233445566778899aabbccddeeff";
var iv  = "0102030405060708";

var enc = KJUR.crypto.Cipher.encrypt(
  "test data",
  key,
  "AES/CBC/PKCS5Padding",
  iv
);

var dec = KJUR.crypto.Cipher.decrypt(
  enc,
  key,
  "AES/CBC/PKCS5Padding",
  iv
);

Пример сценария RSA

var encrypted = KJUR.crypto.Cipher.encrypt(
  "data",
  publicKeyPEM,
  "RSA"
);

var decrypted = KJUR.crypto.Cipher.decrypt(
  encrypted,
  privateKeyPEM,
  "RSA"
);

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

  • библиотека ориентирована на совместимость с WebCrypto-подобной моделью, но не является оберткой над WebCrypto API
  • поддержка алгоритмов зависит от сборки jsrsasign
  • часть параметров передается в строковом виде (в отличие от строго типизированных API)
  • криптографические операции выполняются в JavaScript без нативного ускорения

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

Часто используемые форматы:

  • hex — для ключей и бинарных данных
  • base64 — для передачи зашифрованных сообщений
  • string — UTF-8 текст

Конвертация выполняется автоматически при указании параметров informat / outformat.

Типичная структура конфигурации Cipher

{
  alg: "AES",
  mode: "CBC",
  padding: "PKCS5Padding",
  key: "...",
  iv: "...",
  inFormat: "string",
  outFormat: "base64"
}

Ограничения

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