Объект KJUR и пространства имён

KJUR представляет собой глобальный объект, через который в библиотеке jsrsasign организован доступ ко всем основным криптографическим, ASN.1 и криптографическим протоколам. Архитектура построена на строгом разделении функциональности по пространствам имён, что позволяет изолировать компоненты и упрощает навигацию по API при работе с различными криптографическими задачами.

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

Основная идея заключается в том, что криптографические операции, работа с ASN.1 структурами и реализация протоколов (JWT, JWS, PKCS) не смешиваются в одном пространстве, а распределяются по подпространствам:

  • KJUR.crypto — криптографические примитивы и алгоритмы
  • KJUR.asn1 — генерация и разбор ASN.1 структур
  • KJUR.jws — работа с JSON Web Signature
  • KJUR.jws.JWS — реализация JWS операций
  • KJUR.jws.JWT — операции с JWT
  • вспомогательные модули и утилиты

Такая структура позволяет воспринимать библиотеку как набор независимых, но согласованных подсистем.

Пространство имён KJUR.crypto

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

Ключевые компоненты:

KJUR.crypto.Signature

Основной класс для создания и проверки цифровых подписей.

const sig = new KJUR.crypto.Signature({ "alg": "SHA256withRSA" });
sig.init(privateKeyPem);
sig.updateString("data to sign");
const signature = sig.sign();

Поддерживаются алгоритмы:

  • RSA (SHA256withRSA, SHA1withRSA)
  • ECDSA
  • DSA

KJUR.crypto.KEYUTIL

Хотя формально находится на верхнем уровне, тесно связан с KJUR.crypto. Используется для импорта и экспорта ключей.

const key = KEYUTIL.getKey(privateKeyPem);

Поддерживает:

  • PEM формат
  • PKCS#1 / PKCS#8
  • JSON Web Key (JWK)

KJUR.crypto.Cipher

Обеспечивает симметричное шифрование.

const encrypted = KJUR.crypto.Cipher.encrypt("plaintext", key, "AES");

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

  • AES
  • DES
  • 3DES (в зависимости от сборки)

KJUR.crypto.ECDSA / DSA / RSA

Низкоуровневые реализации алгоритмов:

  • KJUR.crypto.RSAKey — работа с RSA-ключами
  • KJUR.crypto.ECDSA — операции на эллиптических кривых
  • KJUR.crypto.DSA — алгоритм DSA

Эти классы редко используются напрямую, так как обычно обёрнуты в Signature, однако доступны для тонкой настройки.

Пространство имён KJUR.asn1

KJUR.asn1 реализует работу с ASN.1 — структурированным форматом, используемым в сертификатах X.509, PKCS и криптографических сообщениях.

Основная концепция

ASN.1 представляется в виде дерева объектов, где каждый элемент имеет тип и значение.

KJUR.asn1.DERInteger

Представление целого числа в DER-формате.

const int = new KJUR.asn1.DERInteger({ int: 123 });

KJUR.asn1.DERSequence

Последовательность ASN.1 объектов.

const seq = new KJUR.asn1.DERSequence({
  array: [
    new KJUR.asn1.DERInteger({ int: 1 }),
    new KJUR.asn1.DERUTF8String({ str: "test" })
  ]
});

KJUR.asn1.DERBitString

Используется для представления битовых строк, например, публичных ключей.

KJUR.asn1.x509

Подмодуль для работы с X.509 сертификатами:

  • генерация сертификатов
  • разбор сертификатов
  • работа с расширениями

Пространство имён KJUR.jws

KJUR.jws реализует работу с JSON Web Signature (JWS), стандартом цифровой подписи JSON-данных.

KJUR.jws.JWS.sign

Создание подписанного JWT/JWS:

const header = { alg: "HS256", typ: "JWT" };
const payload = { sub: "1234567890", name: "John Doe" };

const token = KJUR.jws.JWS.sign(
  "HS256",
  JSON.stringify(header),
  JSON.stringify(payload),
  "secret"
);

KJUR.jws.JWS.verify

Проверка подписи:

const result = KJUR.jws.JWS.verify(token, "secret", ["HS256"]);

Возвращает true или false.

Пространство имён KJUR.jws.JWT

Более высокоуровневая абстракция над JWS, ориентированная на работу с JWT.

Основные функции:

  • создание токенов
  • декодирование payload
  • валидация структуры
const parsed = KJUR.jws.JWT.parse(token);

Результат включает:

  • header
  • payload
  • signature

Организация зависимостей между пространствами имён

Архитектура KJUR построена иерархически:

  • KJUR.crypto предоставляет базовые алгоритмы
  • KJUR.asn1 использует криптографические примитивы для кодирования ключей и сертификатов
  • KJUR.jws опирается на KJUR.crypto для подписи и проверки
  • KJUR.jws.JWT использует KJUR.jws как нижний уровень

Такая структура позволяет менять внутренние реализации криптографии без изменения верхнеуровневых API.

Глобальная доступность и загрузка

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

<script src="jsrsasign-all-min.js"></script>

После этого доступ становятся доступны:

KJUR.crypto
KJUR.asn1
KJUR.jws

В Node.js используется импорт:

const jsrsasign = require("jsrsasign");

При этом структура остаётся идентичной, включая вложенные пространства имён.

Особенности проектирования пространства имён

Ключевые принципы, заложенные в KJUR:

  • изолированность модулей — каждый домен криптографии отделён
  • предсказуемая иерархия — доступ строится по пути KJUR.<domain>.<module>
  • совместимость с глобальной средой браузера
  • минимизация конфликтов имён

Пример комплексного использования пространств имён

Комбинация криптографии, ASN.1 и JWS:

const key = KEYUTIL.getKey(privateKeyPem);

const sig = new KJUR.crypto.Signature({ alg: "SHA256withRSA" });
sig.init(key);
sig.updateString("message");
const signature = sig.sign();

const asn1 = new KJUR.asn1.DERSequence({
  array: [
    new KJUR.asn1.DERUTF8String({ str: "signature" }),
    new KJUR.asn1.DEROctetString({ hex: signature })
  ]
});

const token = KJUR.jws.JWS.sign(
  "RS256",
  JSON.stringify({ alg: "RS256" }),
  JSON.stringify({ data: "example" }),
  key
);

Взаимодействие с ключами через KJUR

Ключевая роль в архитектуре отведена объектам ключей, которые используются всеми пространствами имён:

  • KJUR.crypto.Signature
  • KJUR.jws.JWS
  • KJUR.asn1.x509

Импорт и унификация выполняется через KEYUTIL, который связывает PEM, DER и JWK форматы в единую модель представления.

Роль KJUR в экосистеме jsrsasign

KJUR выступает центральной точкой доступа ко всем возможностям библиотеки:

  • криптография
  • сертификаты
  • подписи
  • токены
  • ASN.1 структуры

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

Оглавление