Passa al contenuto principale

4. JSON Web Key (JWK) Format (Formato JSON Web Key)

Un JWK e un oggetto JSON che rappresenta una chiave crittografica (Cryptographic Key). I membri dell'oggetto rappresentano le proprieta della chiave, incluso il suo valore. Questo oggetto JSON puo (MAY) contenere spazi e/o interruzioni di riga prima o dopo qualsiasi valore JSON o carattere strutturale, in conformita alla Sezione 2 di RFC 7159 [RFC7159]. Questo documento definisce i parametri di chiave che non sono specifici di un algoritmo e che quindi sono comuni a molte chiavi.

Oltre ai parametri comuni, ogni JWK avra membri specifici del tipo di chiave. Questi membri rappresentano i parametri della chiave. La Sezione 6 della specifica JSON Web Algorithms (JWA) [JWA] definisce diversi tipi di chiavi crittografiche e i relativi membri.

I nomi dei membri in un JWK devono (MUST) essere univoci; i parser JWK devono (MUST) rifiutare i JWK con nomi di membri duplicati oppure usare un parser JSON che restituisca solo l'ultimo nome di membro duplicato lessicalmente, come specificato nella Sezione 15.12 (The JSON Object) di ECMAScript 5.1 [ECMAScript].

Nel JWK possono essere presenti membri aggiuntivi; se non sono compresi dalle implementazioni che li incontrano, devono (MUST) essere ignorati. I nomi dei membri usati per rappresentare parametri di chiave per tipi di chiave diversi non devono necessariamente essere distinti. Qualsiasi nuovo nome di membro dovrebbe (SHOULD) essere registrato nel registro IANA "JSON Web Key Parameters" istituito dalla Sezione 8.1 oppure essere un valore che contiene un nome resistente alle collisioni (Collision-Resistant Name).

4.1. Parametro "kty" (Key Type)​

Il parametro "kty" (key type, tipo di chiave) identifica la famiglia di algoritmi crittografici (Cryptographic Algorithm Family) usata con la chiave, come "RSA" o "EC". I valori "kty" dovrebbero (SHOULD) essere registrati nel registro IANA "JSON Web Key Types" istituito da [JWA] oppure essere un valore che contiene un nome resistente alle collisioni. Il valore "kty" e una stringa sensibile alle maiuscole/minuscole. Questo membro deve (MUST) essere presente in un JWK.

Un elenco dei valori "kty" definiti si trova nel registro IANA "JSON Web Key Types" istituito da [JWA]; il contenuto iniziale di questo registro e costituito dai valori definiti nella Sezione 6.1 di [JWA].

Le definizioni del tipo di chiave includono la specifica dei membri da usare per tali tipi di chiave. I membri usati con specifici valori "kty" si trovano nel registro IANA "JSON Web Key Parameters" istituito dalla Sezione 8.1.

4.2. Parametro "use" (Public Key Use)​

Il parametro "use" (public key use, uso della chiave pubblica) identifica l'uso previsto della chiave pubblica. Il parametro "use" viene impiegato per indicare se una chiave pubblica e usata per cifrare dati o per verificare la firma sui dati.

I valori definiti da questa specifica sono:

  • "sig" (signature, firma)
  • "enc" (encryption, cifratura)

Altri valori possono (MAY) essere usati. Il valore "use" e una stringa sensibile alle maiuscole/minuscole. L'uso del membro "use" e opzionale (OPTIONAL), salvo che l'applicazione ne richieda la presenza.

Quando una chiave viene usata per avvolgere (Wrap) un'altra chiave e si desidera una designazione dell'uso della chiave pubblica per la prima chiave, viene usato il valore di uso della chiave "enc" (encryption, cifratura), poiche l'avvolgimento di chiave e una forma di cifratura. Il valore "enc" deve essere usato anche per le chiavi pubbliche usate nelle operazioni di accordo di chiave (Key Agreement).

Valori aggiuntivi di "use" (public key use) possono essere registrati nel registro IANA "JSON Web Key Use" istituito dalla Sezione 8.2. La registrazione di qualsiasi valore di estensione usato e fortemente raccomandata (RECOMMENDED) quando questa specifica viene usata in ambienti aperti, nei quali piu organizzazioni devono condividere una comprensione comune di tutte le estensioni usate. Tuttavia, valori di estensione non registrati possono essere usati in ambienti chiusi, nei quali l'organizzazione che produce e quella che consuma saranno sempre la stessa.

4.3. Parametro "key_ops" (Key Operations)​

Il parametro "key_ops" (key operations, operazioni di chiave) identifica l'operazione o le operazioni per cui la chiave e destinata a essere usata. Il parametro "key_ops" e destinato ai casi d'uso in cui possono essere presenti chiavi pubbliche, private o simmetriche.

Il suo valore e un array di valori di operazione di chiave. I valori definiti da questa specifica sono:

  • "sign" (compute digital signature or MAC, calcolare una firma digitale o un MAC)
  • "verify" (verify digital signature or MAC, verificare una firma digitale o un MAC)
  • "encrypt" (encrypt content, cifrare il contenuto)
  • "decrypt" (decrypt content and validate decryption, if applicable, decifrare il contenuto e validare la decifratura, se applicabile)
  • "wrapKey" (encrypt key, cifrare la chiave)
  • "unwrapKey" (decrypt key and validate decryption, if applicable, decifrare la chiave e validare la decifratura, se applicabile)
  • "deriveKey" (derive key, derivare una chiave)
  • "deriveBits" (derive bits not to be used as a key, derivare bit non destinati a essere usati come chiave)

Si noti che i valori "key_ops" corrispondono intenzionalmente ai valori "KeyUsage" definiti nella specifica Web Cryptography API [W3C.CR-WebCryptoAPI-20141211].

Altri valori possono (MAY) essere usati. I valori di operazione di chiave sono stringhe sensibili alle maiuscole/minuscole. Valori di operazione di chiave duplicati non devono (MUST NOT) essere presenti nell'array. L'uso del membro "key_ops" e opzionale (OPTIONAL), salvo che l'applicazione ne richieda la presenza.

Operazioni di chiave multiple e non correlate non dovrebbero (SHOULD NOT) essere specificate per una chiave, a causa delle potenziali vulnerabilita associate all'uso della stessa chiave con piu algoritmi. Pertanto, le combinazioni "sign" con "verify", "encrypt" con "decrypt" e "wrapKey" con "unwrapKey" sono consentite, ma altre combinazioni non dovrebbero (SHOULD NOT) essere usate.

Valori aggiuntivi di "key_ops" (key operations) possono essere registrati nel registro IANA "JSON Web Key Operations" istituito dalla Sezione 8.3. Le stesse considerazioni sulla registrazione dei valori di estensione si applicano al membro "key_ops" come al membro "use".

I membri JWK "use" e "key_ops" non dovrebbero (SHOULD NOT) essere usati insieme; tuttavia, se vengono usati entrambi, le informazioni che trasmettono devono (MUST) essere coerenti. Le applicazioni dovrebbero (SHOULD) specificare quale di questi membri usano, se uno di essi deve essere usato dall'applicazione.

4.4. Parametro "alg" (Algorithm)​

Il parametro "alg" (algorithm, algoritmo) identifica l'algoritmo destinato a essere usato con la chiave. I valori usati dovrebbero (SHOULD) essere registrati nel registro IANA "JSON Web Signature and Encryption Algorithms" istituito da [JWA] oppure essere un valore che contiene un nome resistente alle collisioni. Il valore "alg" e una stringa ASCII sensibile alle maiuscole/minuscole. L'uso di questo membro e opzionale (OPTIONAL).

4.5. Parametro "kid" (Key ID)​

Il parametro "kid" (key ID, identificatore di chiave) viene usato per far corrispondere una chiave specifica. Questo viene usato, per esempio, per scegliere tra un insieme di chiavi in un JWK Set durante la rotazione delle chiavi (Key Rollover). La struttura del valore "kid" non e specificata. Quando i valori "kid" vengono usati in un JWK Set, chiavi diverse nel JWK Set dovrebbero (SHOULD) usare valori "kid" distinti. Un esempio in cui chiavi diverse potrebbero usare lo stesso valore "kid" e il caso in cui abbiano valori "kty" (key type, tipo di chiave) diversi ma siano considerate alternative equivalenti dall'applicazione che le usa. Il valore "kid" e una stringa sensibile alle maiuscole/minuscole. L'uso di questo membro e opzionale (OPTIONAL). Quando viene usato con JWS o JWE, il valore "kid" viene usato per far corrispondere un valore del parametro di intestazione "kid" JWS o JWE.

4.6. Parametro "x5u" (X.509 URL)​

Il parametro "x5u" (X.509 URL) e un URI [RFC3986] che fa riferimento a una risorsa per un certificato di chiave pubblica X.509 o una catena di certificati (Certificate Chain) [RFC5280]. La risorsa identificata deve (MUST) fornire una rappresentazione del certificato o della catena di certificati conforme a RFC 5280 [RFC5280] in forma codificata PEM, con ogni certificato delimitato come specificato nella Sezione 6.1 di RFC 4945 [RFC4945]. La chiave nel primo certificato deve (MUST) corrispondere alla chiave pubblica rappresentata dagli altri membri del JWK. Il protocollo usato per acquisire la risorsa deve (MUST) fornire protezione dell'integrita (Integrity Protection); una richiesta HTTP GET per recuperare il certificato deve (MUST) usare TLS [RFC2818] [RFC5246]; l'identita del server deve (MUST) essere validata, in conformita alla Sezione 6 di RFC 6125 [RFC6125]. L'uso di questo membro e opzionale (OPTIONAL).

Sebbene non sia necessario che membri JWK opzionali che forniscono l'uso della chiave, l'algoritmo o altre informazioni siano presenti quando viene usato il membro "x5u", farlo puo migliorare l'interoperabilita per le applicazioni che non elaborano certificati PKIX [RFC5280]. Se sono presenti altri membri, il contenuto di tali membri deve (MUST) essere semanticamente coerente con i campi rilevanti del primo certificato. Per esempio, se il membro "use" e presente, deve (MUST) corrispondere all'uso specificato nel certificato, quando il certificato include tale informazione. Analogamente, se il membro "alg" e presente, deve (MUST) corrispondere all'algoritmo specificato nel certificato.

4.7. Parametro "x5c" (X.509 Certificate Chain)​

Il parametro "x5c" (X.509 certificate chain, catena di certificati X.509) contiene una catena di uno o piu certificati PKIX [RFC5280]. La catena di certificati e rappresentata come un array JSON di stringhe di valori di certificato. Ogni stringa nell'array e un valore di certificato PKIX DER [ITU.X690.1994] codificato in base64 (Sezione 4 di [RFC4648] -- non codificato in base64url). Il certificato PKIX che contiene il valore della chiave deve (MUST) essere il primo certificato. Questo puo (MAY) essere seguito da certificati aggiuntivi, ognuno dei quali e il certificato usato per certificare il precedente. La chiave nel primo certificato deve (MUST) corrispondere alla chiave pubblica rappresentata dagli altri membri del JWK. L'uso di questo membro e opzionale (OPTIONAL).

Come per il membro "x5u", membri JWK opzionali che forniscono l'uso della chiave, l'algoritmo o altre informazioni possono (MAY) essere presenti anche quando viene usato il membro "x5c". Se sono presenti altri membri, il contenuto di tali membri deve (MUST) essere semanticamente coerente con i campi rilevanti del primo certificato. Vedere l'ultimo paragrafo della Sezione 4.6 per ulteriori indicazioni su questo punto.

4.8. Parametro "x5t" (X.509 Certificate SHA-1 Thumbprint)​

Il parametro "x5t" (X.509 certificate SHA-1 thumbprint, impronta SHA-1 di certificato X.509) e un'impronta (thumbprint, alias digest) SHA-1 codificata in base64url della codifica DER di un certificato X.509 [RFC5280]. Si noti che le impronte dei certificati sono talvolta chiamate anche impronte digitali dei certificati (certificate fingerprints). La chiave nel certificato deve (MUST) corrispondere alla chiave pubblica rappresentata dagli altri membri del JWK. L'uso di questo membro e opzionale (OPTIONAL).

Come per il membro "x5u", membri JWK opzionali che forniscono l'uso della chiave, l'algoritmo o altre informazioni possono (MAY) essere presenti anche quando viene usato il membro "x5t". Se sono presenti altri membri, il contenuto di tali membri deve (MUST) essere semanticamente coerente con i campi rilevanti del certificato referenziato. Vedere l'ultimo paragrafo della Sezione 4.6 per ulteriori indicazioni su questo punto.

4.9. Parametro "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)​

Il parametro "x5t#S256" (X.509 certificate SHA-256 thumbprint, impronta SHA-256 di certificato X.509) e un'impronta (thumbprint, alias digest) SHA-256 codificata in base64url della codifica DER di un certificato X.509 [RFC5280]. Si noti che le impronte dei certificati sono talvolta chiamate anche impronte digitali dei certificati (certificate fingerprints). La chiave nel certificato deve (MUST) corrispondere alla chiave pubblica rappresentata dagli altri membri del JWK. L'uso di questo membro e opzionale (OPTIONAL).

Come per il membro "x5u", membri JWK opzionali che forniscono l'uso della chiave, l'algoritmo o altre informazioni possono (MAY) essere presenti anche quando viene usato il membro "x5t#S256". Se sono presenti altri membri, il contenuto di tali membri deve (MUST) essere semanticamente coerente con i campi rilevanti del certificato referenziato. Vedere l'ultimo paragrafo della Sezione 4.6 per ulteriori indicazioni su questo punto.

Ultimo aggiornamento il