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.

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());