Использование в браузере без сборщика

Jsrsasign используется в браузере как обычная глобальная библиотека, без необходимости сборки и настройки webpack, vite или других инструментов. Основной способ подключения — через CDN.

Подключение через jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/jsrsasign/lib/jsrsasign-all-min.js"></script>

Подключение через unpkg:

<script src="https://unpkg.com/jsrsasign/lib/jsrsasign-all-min.js"></script>

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

  • KJUR — основной набор криптографических функций
  • KEYUTIL — работа с ключами
  • hextob64, b64tohex — утилиты кодирования
  • X509 — работа с сертификатами X.509

Особенность такого подключения заключается в синхронной загрузке: порядок подключения скриптов критичен, так как библиотека не использует ES-модули.

Глобальная структура API

После подключения Jsrsasign в браузере появляется несколько ключевых объектов:

KJUR.crypto

  • криптографические операции (подписи, хэши, ключи)

KJUR.jws

  • работа с JWT (JSON Web Signature)

KJUR.jwe

  • работа с JWE (шифрование JWT)

KEYUTIL

  • импорт и экспорт ключей RSA/EC

X509

  • парсинг и проверка сертификатов

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

Хэширование данных в браузере

Jsrsasign предоставляет реализацию хэш-функций без использования WebCrypto API.

Пример вычисления SHA-256:

const hash = KJUR.crypto.Util.hashString("hello world", "sha256");
console.log(hash);

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

  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512
  • MD5 (устаревший, но доступен)

Хэш возвращается в hex-формате. Для преобразования часто используются встроенные утилиты:

const b64 = hextob64(hash);

Подпись данных RSA в браузере

Одна из ключевых возможностей — создание цифровой подписи.

Пример RSA-SHA256 подписи:

const sig = new KJUR.crypto.Signature({ "alg": "SHA256withRSA" });

sig.init(privateKeyPem);
sig.updateString("message to sign");

const signatureHex = sig.sign();
const signatureBase64 = hextob64(signatureHex);

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

  • SHA1withRSA
  • SHA256withRSA
  • SHA512withRSA
  • SHA256withECDSA

Ключ передаётся в формате PEM.

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

Проверка выполняется тем же объектом Signature:

const sig = new KJUR.crypto.Signature({ "alg": "SHA256withRSA" });

sig.init(publicKeyPem);
sig.updateString("message to sign");

const isValid = sig.verify(b64tohex(signatureBase64));

Важно учитывать, что данные должны совпадать побайтно, включая кодировку строки.

Работа с PEM-ключами

Jsrsasign позволяет импортировать и использовать ключи в формате PEM без преобразования в ArrayBuffer.

Пример RSA ключа:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

Загрузка ключа:

const keyObj = KEYUTIL.getKey(privateKeyPem);

Извлечение публичного ключа:

const pubKey = KEYUTIL.getKey(publicKeyPem);

Генерация PEM из объекта:

const pem = KEYUTIL.getPEM(keyObj);

Генерация RSA ключей в браузере

Jsrsasign поддерживает генерацию ключей RSA:

const kp = KEYUTIL.generateKeypair("RSA", 2048);

const privatePem = KEYUTIL.getPEM(kp.prvKeyObj, "PKCS8PRV");
const publicPem = KEYUTIL.getPEM(kp.pubKeyObj);

Параметры:

  • RSA 1024 / 2048 / 4096
  • генерация синхронная (может блокировать UI поток)

JWT (JSON Web Token)

Одна из самых используемых функций — работа с JWT.

Создание JWT

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

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

Проверка JWT

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

Извлечение payload

const parsed = KJUR.jws.JWS.parse(token);
console.log(parsed.payloadPP);

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

  • HS256 / HS384 / HS512
  • RS256 / RS384 / RS512
  • ES256 / ES384 / ES512

Работа с RSA в формате JWS

Пример использования RSA ключей:

const token = KJUR.jws.JWS.sign(
  "RS256",
  JSON.stringify({ alg: "RS256", typ: "JWT" }),
  JSON.stringify({ data: "payload" }),
  privateKeyPem
);

Проверка:

const valid = KJUR.jws.JWS.verify(token, publicKeyPem, ["RS256"]);

Кодирование и декодирование

Jsrsasign включает утилиты для работы с Base64 и Hex:

const hex = "48656c6c6f";
const base64 = hextob64(hex);
const backToHex = b64tohex(base64);

Также доступно URL-safe Base64:

const urlSafe = hextob64u(hex);

Работа с сертификатами X.509

Jsrsasign позволяет анализировать сертификаты:

const cert = new X509();
cert.readCertPEM(certPem);

const subject = cert.getSubjectString();
const issuer = cert.getIssuerString();

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

const isValid = cert.verifySignature();

Использование без модульной системы

В браузере без сборщика важно учитывать особенности загрузки:

Порядок подключения

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

Нарушение порядка приведёт к отсутствию глобального KJUR.

Асинхронная загрузка

При использовании defer:

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

Скрипт становится доступен только после построения DOM.

Content Security Policy (CSP)

Jsrsasign может конфликтовать с жёсткими CSP-политиками, если запрещены:

  • unsafe-eval
  • inline scripts (в некоторых режимах JWT)

Ограничения браузерного режима

При использовании без сборщика и WebCrypto:

  • часть операций выполняется синхронно и может блокировать UI
  • генерация ключей RSA может быть медленной
  • отсутствует потоковая криптография
  • производительность ниже, чем у native crypto.subtle

Совместное использование с WebCrypto API

Jsrsasign может использоваться параллельно с WebCrypto:

  • Jsrsasign — для JWT, PEM, совместимости
  • WebCrypto — для производительных операций

Пример гибридного подхода:

  • WebCrypto генерирует ключи
  • Jsrsasign форматирует PEM и JWT

Частые ошибки при использовании в браузере

Ошибка: KJUR is not defined

  • библиотека не подключена или подключена после использования

Ошибка подписи

  • несовпадение кодировки строки (UTF-8 vs UTF-16)

JWT invalid signature

  • неверный ключ или алгоритм

Проблемы с PEM

  • лишние пробелы или переносы строк

Практическая модель использования в чистом HTML

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/jsrsasign/lib/jsrsasign-all-min.js"></script>
</head>
<body>
<script>
const token = KJUR.jws.JWS.sign(
  "HS256",
  JSON.stringify({ alg: "HS256", typ: "JWT" }),
  JSON.stringify({ user: "demo" }),
  "secret"
);

console.log(token);
</script>
</body>
</html>

Поведение в старых браузерах

Jsrsasign поддерживает старые версии браузеров благодаря:

  • отсутствию ES6-зависимостей
  • чистому JavaScript без транспиляции
  • встроенным polyfill-решениям

Поддержка включает даже устаревшие окружения, где WebCrypto отсутствует полностью.

Оглавление