RUEN
Пакет · jwt

Установка и требования

Flytachi JWT занимает минимум места — два стандартных расширения PHP и больше ничего. На этой странице описаны требования и то, как получить ключи, которыми вы будете подписывать.

Системные требования

  • Версия PHP — 8.1 или выше.
  • Операционная система — любая. Зависимостей от POSIX нет, поэтому Linux, macOS, BSD и Windows работают одинаково хорошо.
  • Расширения PHP
    • ext-openssl — подпись и проверка RSA- и ECDSA-токенов, а также преобразование ключей JWKS в пригодные для использования публичные ключи.
    • ext-json — кодирование и декодирование сегментов заголовка и payload токена.

Проверить установленные расширения можно командой php -m.

bash
composer require flytachi/jwt

Никаких дополнительных runtime-зависимостей

Библиотеке нужны только ext-openssl и ext-json — оба входят практически в любую сборку PHP. Парсер JWKS собирает PEM-ключи на чистом PHP, так что устанавливать больше ничего не нужно.

Выбор алгоритма

Какие ключи вам нужны, зависит от семейства алгоритмов. Полную матрицу смотрите в «Алгоритмы».

Семейство Тип ключа Когда использовать
HMAC (HS*) одна строка общего секрета Одна и та же сторона подписывает и проверяет (ваш собственный API).
RSA (RS*) пара из приватного и публичного ключа Вы подписываете; другие проверяют вашим публичным ключом.
ECDSA (ES*) пара из приватного и публичного ключа То же, что и RSA, но с меньшими ключами и подписями.

HMAC: просто секрет

Для HS256/HS384/HS512 генерировать файлы не нужно — вам требуется одна надёжная строка секрета, общая для того, кто подписывает, и того, кто проверяет. Сгенерировать её можно так:

bash
# 32 случайных байта, закодированных в base64
openssl rand -base64 32

Держите секрет в секрете

В HMAC один и тот же ключ и подписывает, и проверяет. Любой, у кого он есть, может выпускать валидные токены — храните его как пароль (переменная окружения, менеджер секретов) и никогда не в системе контроля версий.

RSA: генерация пары ключей

bash
# Приватный ключ (используется для подписи)
openssl genrsa -out private.pem 2048

# Публичный ключ (используется для проверки) — выводится из приватного ключа
openssl rsa -in private.pem -pubout -out public.pem

Загрузите их в PHP с помощью OpenSSL:

php
use Flytachi\Jwt\Entity\PrivateKey;
use Flytachi\Jwt\Entity\PublicKey;

$signingKey = new PrivateKey(
  openssl_pkey_get_private(file_get_contents('private.pem')),
  'RS256',
  'my-key-id' // kid — обязателен, чтобы decode() мог найти подходящий публичный ключ
);

$verifyKey = new PublicKey(
  openssl_pkey_get_public(file_get_contents('public.pem')),
  'RS256'
);

ECDSA: генерация пары ключей

ECDSA использует именованные кривые — P-256 для ES256, P-384 для ES384, P-521 для ES512:

bash
# ES256 использует кривую prime256v1 (P-256)
openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem
openssl ec -in ec-private.pem -pubout -out ec-public.pem

Загрузка идентична RSA — передайте объект ключа OpenSSL и соответствующий алгоритм (ES256). Полные примеры подписи и проверки смотрите в «Асимметричные ключи».

Никогда не коммитьте приватные ключи

private.pem и ec-private.pem подписывают токены от вашего имени. Добавьте их в .gitignore и загружайте из защищённого пути или хранилища секретов во время выполнения.

Дальнейшие шаги