4. JOSE Header
Per un JWS, i membri dell'header JOSE sono l'unione dei membri del JWS Protected Header e del JWS Unprotected Header. Il JWS Protected Header contiene i parametri header che sono protetti in integrità dalla firma JWS o dal calcolo del MAC. Il JWS Unprotected Header contiene i parametri header che non sono protetti in integrità.
4.1 Registered Header Parameter Names (Nomi dei parametri header registrati)
I seguenti nomi di parametri header per l'uso negli header JOSE sono registrati nel registro IANA "JSON Web Signature and Encryption Header Parameters" stabilito dalla sezione 9.1.
4.1.1 "alg" (Algorithm) Header Parameter (Parametro header "alg" (Algoritmo))
Il parametro header "alg" (algorithm, algoritmo) identifica l'algoritmo crittografico utilizzato per proteggere il JWS. Il valore della JWS Signature o del JWS MAC dipende dal valore "alg".
Il parametro header "alg" deve (MUST) essere presente nell'header JOSE. Deve (MUST) essere compreso e elaborato dalle implementazioni.
Un elenco dei valori "alg" definiti è fornito nel registro IANA "JSON Web Signature and Encryption Algorithms" stabilito da [JWA]. I valori iniziali sono definiti nella sezione 3.1 di [JWA]. Il valore utilizzato deve essere un valore registrato o un valore che è un collision-resistant name (nome resistente alle collisioni).
Gli implementatori devono (MUST) rifiutare i valori "alg" che non comprendono o trattarli utilizzando una politica che li associa a valori compresi. Vedere la sezione 10.6 per considerazioni sulla sicurezza della validazione dell'algoritmo.
4.1.2 "jku" (JWK Set URL) Header Parameter (Parametro header "jku" (URL JWK Set))
Il parametro header "jku" (JWK Set URL) è un URI [RFC3986] che fa riferimento a una risorsa per un set di chiavi Web JSON codificato in JSON [JWK]. Le chiavi pubbliche rappresentate possono essere utilizzate per verificare la firma digitale o il MAC del JWS.
Quando questo parametro viene utilizzato, la risorsa JWK Set deve (MUST) rappresentare un JWK Set JSON [JWK]. I protocolli utilizzati per acquisire la risorsa devono (MUST) fornire autenticazione e integrità. L'applicazione che utilizza "jku" dovrebbe (SHOULD) specificare, in un documento di contesto, i meccanismi di sicurezza utilizzati per acquisire le chiavi.
Questo parametro header è opzionale (OPTIONAL).
4.1.3 "jwk" (JSON Web Key) Header Parameter (Parametro header "jwk" (Chiave Web JSON))
Il parametro header "jwk" (JSON Web Key) è la chiave pubblica corrispondente alla chiave utilizzata per firmare digitalmente il JWS. Questa chiave è rappresentata come una JSON Web Key [JWK]. L'uso di questo parametro header è opzionale (OPTIONAL).
Quando questo parametro viene utilizzato, il JWK rappresentato deve (MUST) contenere solo i parametri JWK che rappresentano la chiave pubblica. Il JWK non deve (MUST NOT) contenere parametri JWK che rappresentano la chiave privata.
4.1.4 "kid" (Key ID) Header Parameter (Parametro header "kid" (ID chiave))
Il parametro header "kid" (key ID, ID chiave) è un suggerimento che indica quale chiave è stata utilizzata per proteggere il JWS. Questo parametro consente agli emittenti di indicare esplicitamente un cambio di chiave ai destinatari. La struttura del valore "kid" non è specificata. Il suo valore deve (MUST) essere una stringa case-sensitive.
L'uso di questo parametro header è opzionale (OPTIONAL).
Quando utilizzato con JWK, il valore "kid" può essere utilizzato per corrispondere a un parametro "kid" di JWK.
4.1.5 "x5u" (X.509 URL) Header Parameter (Parametro header "x5u" (URL X.509))
Il parametro header "x5u" (X.509 URL) è un URI [RFC3986] che fa riferimento a una risorsa per il certificato X.509 [RFC5280] o la catena di certificati [RFC5280] corrispondente alla chiave utilizzata per firmare digitalmente il JWS. Il certificato o la catena di certificati identificati è codificato in formato PEM [RFC1421].
Questo parametro header è opzionale (OPTIONAL).
4.1.6 "x5c" (X.509 Certificate Chain) Header Parameter (Parametro header "x5c" (Catena di certificati X.509))
Il parametro header "x5c" (X.509 certificate chain, catena di certificati X.509) contiene la catena di certificati X.509 [RFC5280] o il percorso di certificazione [RFC5280] corrispondente alla chiave utilizzata per firmare digitalmente il JWS. La catena di certificati è rappresentata come un array JSON di stringhe di certificati. Ogni stringa nell'array è un certificato PKIX codificato in base64 (non codificato in base64url) DER [RFC5280].
Il certificato contenente la chiave pubblica corrispondente alla chiave utilizzata per firmare digitalmente il JWS deve (MUST) essere il primo certificato. Questo può (MAY) essere seguito da certificati aggiuntivi, con ciascun certificato successivo che certifica il precedente.
Questo parametro header è opzionale (OPTIONAL).
Vedere l'appendice B per un esempio di utilizzo di "x5c".
4.1.7 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter (Parametro header "x5t" (Impronta SHA-1 del certificato X.509))
Il parametro header "x5t" (X.509 certificate SHA-1 thumbprint, impronta SHA-1 del certificato X.509) è un'impronta codificata in base64url (abbreviazione per impronta digitale) della codifica DER del certificato X.509 [RFC5280] corrispondente alla chiave utilizzata per firmare digitalmente il JWS. Si noti che le codifiche dei certificati (e quindi le impronte) dipendono dall'ordine degli attributi del certificato; vedere [RFC4945] per ulteriori informazioni.
Questo parametro header è opzionale (OPTIONAL).
Nota: Questo parametro è mantenuto solo per compatibilità retroattiva. Le implementazioni dovrebbero utilizzare "x5t#S256" (impronta SHA-256) invece.
4.1.8 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter (Parametro header "x5t#S256" (Impronta SHA-256 del certificato X.509))
Il parametro header "x5t#S256" (X.509 certificate SHA-256 thumbprint, impronta SHA-256 del certificato X.509) è un'impronta codificata in base64url della codifica DER del certificato X.509 [RFC5280] corrispondente alla chiave utilizzata per firmare digitalmente il JWS, utilizzando la funzione hash SHA-256.
Questo parametro header è opzionale (OPTIONAL).
4.1.9 "typ" (Type) Header Parameter (Parametro header "typ" (Tipo))
Il parametro header "typ" (type, tipo) viene utilizzato dalle applicazioni JWS per dichiarare il tipo di media [IANA.MediaTypes] di questo oggetto JWS completo. Questo è destinato all'uso da parte dell'applicazione quando più tipi di contenuto possono essere presenti nella stessa struttura dati.
Questo parametro header è opzionale (OPTIONAL).
Per massimizzare la compatibilità, è raccomandato (RECOMMENDED) che le applicazioni JWS omettano la porzione "application/" del tipo di media quando si utilizza "typ". Ad esempio, un valore "JWT" potrebbe essere utilizzato per indicare che questo oggetto è un JWT [JWT], anziché "application/jwt".
4.1.10 "cty" (Content Type) Header Parameter (Parametro header "cty" (Tipo di contenuto))
Il parametro header "cty" (content type, tipo di contenuto) viene utilizzato dalle applicazioni JWS per dichiarare il tipo di media [IANA.MediaTypes] del contenuto protetto (il payload). Questo è destinato all'uso da parte dell'applicazione quando più tipi di contenuto del payload possono essere presenti.
Questo parametro header è opzionale (OPTIONAL).
Nel caso normale in cui vengono utilizzati JWS o JWE nidificati, l'uso di questo parametro header è raccomandato (RECOMMENDED). Nel caso normale in cui i JWS non sono nidificati, l'uso di questo parametro header non è raccomandato (NOT RECOMMENDED).
Per massimizzare la compatibilità, è raccomandato (RECOMMENDED) che le applicazioni JWS omettano la porzione "application/" del tipo di media quando si utilizza "cty".
4.1.11 "crit" (Critical) Header Parameter (Parametro header "crit" (Critico))
Il parametro header "crit" (critical, critico) indica che sono utilizzate estensioni a questa specifica e/o [JWA] che devono (MUST) essere comprese ed elaborate. Il suo valore è un array che elenca i nomi dei parametri header presenti nell'header JOSE che utilizzano tali estensioni.
Se uno dei nomi dei parametri header elencati non è compreso e supportato dal destinatario, allora il JWS è invalido. Il destinatario deve (MUST) elaborare questi parametri header o rifiutare il JWS.
Questo parametro header è opzionale (OPTIONAL).
I produttori dovrebbero (SHOULD) includere solo nomi di parametri header di estensione nel valore "crit". I nomi dei parametri header definiti da questa specifica o [JWA] non dovrebbero (SHOULD NOT) essere elencati.
Vedere l'appendice E per un test case negativo per "crit".
4.2 Public Header Parameter Names (Nomi dei parametri header pubblici)
Nomi di parametri header aggiuntivi possono essere definiti da coloro che producono e consumano JWS. Tuttavia, per prevenire collisioni, tutti i nuovi nomi di parametri header dovrebbero (SHOULD) essere registrati nel registro IANA "JSON Web Signature and Encryption Header Parameters" stabilito dalla sezione 9.1, o essere un public name (nome pubblico): un valore che contiene un collision-resistant name (nome resistente alle collisioni).
In ogni caso, la definizione del nome del parametro header dovrebbe specificare se e come il parametro header è destinato all'uso con JWS Protected Headers, con JWS Unprotected Headers, o entrambi.
I nuovi parametri header dovrebbero essere introdotti con parsimonia, poiché i parametri header non compresi devono (MUST) essere ignorati, a meno che non siano elencati nel parametro header "crit".
4.3 Private Header Parameter Names (Nomi dei parametri header privati)
Un produttore e un consumatore di un JWS possono (MAY) concordare di utilizzare nomi di parametri header che sono private names (nomi privati): nomi che non sono registrati nel registro IANA "JSON Web Signature and Encryption Header Parameters" (Sezione 9.1) e non sono public names (Sezione 4.2). A differenza dei public names, i private names sono soggetti a collisioni e dovrebbero essere utilizzati con cautela.