KJUR.jws.JWS: методы и параметры

Библиотека jsrsasign реализует работу с JSON Web Signature (JWS) через пространство имён KJUR.jws.JWS, предоставляя инструменты для создания, проверки и разбора подписанных токенов в форматах JWS Compact Serialization и General/Flattened JSON Serialization.

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

Формат JWS и внутренняя модель обработки

JWS представляет собой структуру:

  • Header — метаданные алгоритма и параметров подписи
  • Payload — полезная нагрузка (данные)
  • Signature — криптографическая подпись

Compact-формат записывается как:

BASE64URL(header) + "." + BASE64URL(payload) + "." + BASE64URL(signature)

В KJUR.jws.JWS эти части обрабатываются как единый объект с возможностью декомпозиции.

Основные методы KJUR.jws.JWS

KJUR.jws.JWS.sign

Метод генерации JWS-подписи и формирования токена.

KJUR.jws.JWS.sign(alg, header, payload, key)
Параметры:

  • alg — алгоритм подписи

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

  • header — JSON-объект заголовка

    • может содержать alg, typ, kid, дополнительные поля

  • payload — данные

    • строка или JSON (автоматически сериализуется при необходимости)

  • key — ключ подписи

    • симметричный ключ (HMAC)
    • приватный RSA/EC ключ в PEM формате
Особенности поведения:
  • header может быть строкой JSON или объектом
  • payload автоматически преобразуется в Base64URL
  • алгоритм в header может быть переопределён значением alg

KJUR.jws.JWS.verify

Проверка подписи JWS токена.

KJUR.jws.JWS.verify(jws, key)
Параметры:

  • jws — строка JWS (Compact Serialization)

  • key — ключ проверки

    • публичный RSA ключ (PEM)
    • симметричный секрет (для HMAC)
    • EC public key
Логика работы:
  • разбор структуры JWS
  • извлечение header.payload.signature
  • пересчёт подписи на основе header и payload
  • сравнение криптографического результата
Возвращаемое значение:
  • true — подпись валидна
  • false — подпись не совпадает или токен повреждён

KJUR.jws.JWS.parse

Разбор JWS без проверки подписи.

KJUR.jws.JWS.parse(jws)
Возвращаемый объект:
{
  headerObj: {...},
  payloadObj: {...} | string,
  signature: "base64url...",
  signingInput: "header.payload"
}
Особенности:
  • payload может быть строкой или JSON-объектом
  • header декодируется в объект автоматически
  • signature остаётся в Base64URL формате

KJUR.jws.JWS.getParsedJWS

Расширенный разбор JWS с нормализацией структуры.

KJUR.jws.JWS.getParsedJWS(jws)
Отличия от parse:
  • более строгая обработка форматов
  • поддержка edge-case токенов
  • нормализация payload

Параметры header: структура и назначение

Header JWS играет ключевую роль в криптографической интерпретации токена.

Типичный пример:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-123"
}

Поддерживаемые поля:

  • alg — алгоритм подписи (обязательное поле)
  • typ — тип токена (обычно JWT)
  • kid — идентификатор ключа
  • crit — критические расширения (редко используется)
  • произвольные пользовательские поля

Payload: обработка данных

Payload в KJUR.jws.JWS может быть:

  • строкой (например, сериализованный JSON)
  • объектом (автоматически сериализуется)
  • бинарным представлением (в ограниченных случаях)

Пример payload:

{
  "sub": "user123",
  "iat": 1710000000,
  "role": "admin"
}

После обработки:

BASE64URL(JSON.stringify(payload))

Алгоритмы подписи и их обработка

HMAC (HS256/384/512)

Использует симметричный ключ:

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

RSA (RS256/384/512)

Использует асимметричную криптографию:

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

ECDSA (ES256/384/512)

Основан на эллиптических кривых:

  • компактные подписи
  • высокая криптографическая стойкость
  • меньший размер токена

Внутренние операции формирования JWS

Процесс создания подписи:

  1. Сериализация header в JSON
  2. Base64URL кодирование header
  3. Сериализация payload
  4. Base64URL кодирование payload
  5. Формирование signing input:
headerB64 + "." + payloadB64
  1. Вычисление подписи выбранным алгоритмом
  2. Base64URL кодирование signature

Проверка подписи: внутренняя логика

При вызове verify выполняется:

  • разбиение строки по .
  • декодирование header и payload
  • повторное формирование signing input
  • вычисление подписи
  • сравнение с входной подписью

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

  • строгая чувствительность к изменению порядка полей JSON
  • Base64URL декодирование без padding
  • игнорирование форматирования JSON при сравнении

Обработка ошибок и крайних случаев

Типовые проблемы:

Некорректный формат JWS

  • отсутствуют сегменты
  • повреждён Base64URL
  • неправильная сериализация JSON

Несовпадение алгоритма

  • alg в header не соответствует ключу
  • попытка проверки RSA ключом HMAC токена

Изменённый payload

  • даже изменение одного символа приводит к invalid signature

Detached payload

Поддерживается сценарий, при котором payload не включён в JWS строку:

header..signature

В этом случае payload передаётся отдельно при проверке или хранится вне токена.

Работа с JSON Serialization JWS

Помимо Compact Serialization, jsrsasign поддерживает расширенный JSON формат:

  • General JWS JSON Serialization
  • Flattened JWS JSON Serialization

Однако KJUR.jws.JWS в основном ориентирован на compact-формат, а JSON-структуры обрабатываются через вспомогательные функции библиотеки.

Критические особенности реализации

  • Base64URL без padding строго обязательно
  • порядок полей JSON не влияет на подпись, но влияет на строковое представление
  • алгоритм всегда берётся из header при отсутствии явного указания
  • ключи PEM должны быть корректно отформатированы (BEGIN/END блоки)

Использование ключей

Поддерживаемые форматы ключей:

  • PEM RSA private/public
  • PEM EC private/public
  • raw secret (HMAC)

При передаче ключа библиотека автоматически определяет тип криптосхемы на основе alg.

Оглавление