JWK a odtlačky

JWK je JSON podoba verejného kľúča. Jose\Jwk funguje oboma smermi a jeho odtlačok (thumbprint) podľa RFC 7638 je základom autorizácie kľúča v ACME:

use RoundlyConsulting\Crypto\Facades\Crypto;

$jwk = Crypto::jwk(Crypto::keys()->ec()->private($pem));   // a P-384 key ⇒ crv P-384
$jwk->thumbprint();                                         // RFC 7638

$key = Crypto::jwkFromJson($json)->publicKey();             // EcKey | RsaKey | OkpKey
$jwk = Crypto::jwkFromArray($members);                      // strict parse of decoded members

Alebo volajte priamo triedy, ktoré fasáda sprístupňuje:

use RoundlyConsulting\Crypto\Jose\Jwk;
use RoundlyConsulting\Crypto\Signature\Key\EcKey;

$jwk = Jwk::fromPublicKey(EcKey::private($pem));   // a P-384 key ⇒ crv P-384, 48-byte coordinates

$jwk->algorithm();          // Algorithm::ES384 — derived from kty + crv, never read from `alg`
$jwk->thumbprint();         // base64url(sha256(canonical JSON)) — RFC 7638
$keyAuthorization = $token.'.'.$jwk->thumbprint();          // RFC 8555 §8.1

// It is JsonSerializable, so it drops straight into a JOSE protected header:
$protected = ['alg' => $jwk->algorithm()->value, 'jwk' => $jwk, 'nonce' => $nonce, 'url' => $url];

// …and back again, into a policy-checked verification key:
$key = Jwk::fromJson($json)->publicKey();          // EcKey | RsaKey | OkpKey

Členy a prístupy

Voliteľné členy (kid, alg, use) sa prenášajú v toArray(), ale nikdy nevstupujú do odtlačku. withKid(), withAlg() a withUse() vracajú kópiu; alg musí byť jeden z tých, ktoré kľúč pripúšťa, a use musí byť sig:

$jwk->withKid('k1')->thumbprint();   // unchanged — kid, alg and use are never thumbprinted
$jwk->withKid('k1')->toArray();      // members, lexicographically ordered
$jwk->keyType();                     // JwkKeyType::Ec
$jwk->thumbprintRaw();               // the raw SHA-256 digest bytes
$jwk->requiredMembers();             // the RFC 7638 thumbprint input

$jwk = Jwk::fromArray($members);     // strict parse of already-decoded members

Vstup odtlačku

Do odtlačku vstupujú iba povinné členy daného typu kľúča — zoradené, zakódované do JSON bez medzier, zahašované (predvolene SHA-256) a zakódované do base64url. Táto hodnota je kritická pre komunikáciu: odchýlka o jediný bajt znemožní vydanie certifikátu u CA, preto ju pripínajú zmrazené testovacie vektory:

Striktné parsovanie

RFC 7517 hovorí, že neznáme členy sa majú ignorovať; tento balík ich odmieta, pretože člen, ktorý potichu prenášate, je člen, ktorý si zvolil útočník. Všetko nižšie vyhodí MalformedJwkException s názvom člena a dôvodom:

• Neznáme členy (x5c, key_ops, …) — zoznam povolených je pre každý kty zvlášť, takže n na EC kľúči je rovnako neznáme ako x5c.
• Akýkoľvek súkromný člen: d, p, q, dp, dq, qi, oth, k — JWK tu nikdy nie je súkromný kľúč.
• Hodnoty, ktoré nie sú base64url, a súradnice, ktorých dĺžka nezodpovedá uvedenej krivke crv.
• Neminimálne RSA n alebo e (s úvodným nulovým oktetom).
• alg, ktorý kľúč nepripúšťa — pri EC a OKP iný než ten, ktorý určuje krivka, pri RSA iný než úroveň RS* (ES256, HS256, PS256 či none na RSA kľúči sa odmietne) — alebo use iné než sig.
• Dokumenty nad 16 KiB (Jwk::MAX_JSON_BYTES); členy nad 8 KiB sa odmietnu ešte pred dekódovaním.

Vstup fromArray() / fromJson() — aj Crypto::jwkFromArray() / jwkFromJson() — je #[\SensitiveParameter], rovnako ako každý krok parsovania, ktorý ho vidí skôr, než sa súkromné členy odmietnu. Súkromný či symetrický JWK odovzdaný omylom tak zostane mimo stack trace výnimky MalformedJwkException, ktorá ho odmietne.

publicKey() uplatní politiku kľúčov balíka (RSA 2048–8192 bitov s rozumným exponentom, podporovaná krivka) a vráti EcKey, RsaKey alebo OkpKey.

Algoritmus, na ktorý JWK pripína

Pri kľúčoch EC a OKP sa algorithm() odvodzuje z kty a crv — algoritmus určuje krivka, takže člen alg s ňou môže len súhlasiť. RSA kľúč sa hodí pre každú úroveň RS*, preto pri RSA JWK úroveň určuje zvalidovaný alg (RS256, RS384 alebo RS512) a algorithm() ho vráti — ak člen chýba, RS256. Overujte s touto úrovňou:

use RoundlyConsulting\Crypto\Jose\Jwk;
use RoundlyConsulting\Crypto\Signature\Rs;

// An RSA JWK's alg names the tier — RS256, RS384 or RS512 (RS256 when absent):
$jwk = Jwk::fromJson($json);
$verifier = new Rs($jwk->publicKey(), $jwk->algorithm());