RUEN
Пакет · jwt

Алгоритмы

Каждый алгоритм, поддерживаемый Flytachi JWT, материал ключа, который каждый из них ожидает, и то, как на них отображаются типы ключей JWK. Это авторитетный список — другие страницы ссылаются сюда.

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

Девять алгоритмов в трёх семействах. Значение в заголовке alg должно быть одним из них, иначе encode()/decode() выбрасывает «Algorithm ‘…’ is not supported.»

alg Семейство Механизм Хеш Материал ключа
HS256 HMAC hash_hmac SHA-256 строка общего секрета
HS384 HMAC hash_hmac SHA-384 строка общего секрета
HS512 HMAC hash_hmac SHA-512 строка общего секрета
RS256 RSA openssl_sign SHA-256 пара ключей RSA
RS384 RSA openssl_sign SHA-384 пара ключей RSA
RS512 RSA openssl_sign SHA-512 пара ключей RSA
ES256 ECDSA openssl_sign SHA-256 пара ключей EC (P-256)
ES384 ECDSA openssl_sign SHA-384 пара ключей EC (P-384)
ES512 ECDSA openssl_sign SHA-512 пара ключей EC (P-521)

Симметричные против асимметричных

HMAC (HS*) RSA / ECDSA (RS* / ES*)
Ключ подписи общий секрет приватный ключ
Ключ проверки тот же общий секрет публичный ключ
Выбор ключа при decode по kid, иначе единственный переданный то же самое
нужен kid когда ключей несколько когда ключей несколько
Кто может подделать любой, у кого есть секрет только держатель приватного ключа

Алгоритм привязан к ключу

И PrivateKey, и PublicKey несут свой алгоритм. При decode алгоритм ключа проверки должен совпадать с alg из заголовка токена — несовпадение отвергается до проверки. См. Модель безопасности.

Формат подписи ECDSA

Стоит знать, если сверяете токены побайтово или отлаживаете совместимость: ES* несут подпись сырой парой чисел R || S, каждое дополнено нулями слева до ширины кривой (RFC 7515 §3.4). Никакой ASN.1 обёртки в токене нет, хотя openssl_sign() возвращает именно её.

alg Кривая Длина подписи
ES256 P-256 64 байта (32 + 32)
ES384 P-384 96 байт (48 + 48)
ES512 P-521 132 байта (66 + 66)

Библиотека конвертирует в обе стороны сама. Признак неверной реализации — подпись, начинающаяся с байта 0x30: это DER-структура, попавшая в токен как есть, и принять её не сможет ни один сторонний верификатор.

Типы ключей JWK

Парсер JWK принимает три стандартных значения kty и отображает их на семейства выше:

kty Обязательные поля JWK Проверяет Поле кривой
RSA n, e, alg RS* —
EC crv, x, y, alg ES* crv (ниже)
oct k, alg HS* —

Соответствие кривых EC

JWK crv Алгоритм Размер координаты
P-256 ES256 32 байта
P-384 ES384 48 байт
P-521 ES512 66 байт

Любая другая кривая выбрасывает «Unsupported EC curve». См. Проверка через JWKS для разбора наборов ключей.

Генерация ключей по семействам

bash
# HMAC — случайный общий секрет
openssl rand -base64 32

# RSA — пара ключей на 2048 бит
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

# ECDSA (ES256) — пара ключей P-256
openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem
openssl ec -in ec-private.pem -pubout -out ec-public.pem

Для ES384 используйте -name secp384r1; для ES512 используйте -name secp521r1.

Связанное