4. JOSE Header (En-tête JOSE)
Pour un JWS, les membres de l'en-tête JOSE sont l'union des membres du JWS Protected Header et du JWS Unprotected Header. Le JWS Protected Header contient des paramètres d'en-tête qui sont protégés en intégrité par la signature JWS ou le calcul du MAC. Le JWS Unprotected Header contient des paramètres d'en-tête qui ne sont pas protégés en intégrité.
4.1 Registered Header Parameter Names (Noms de paramètres d'en-tête enregistrés)
Les noms de paramètres d'en-tête suivants pour être utilisés dans les en-têtes JOSE sont enregistrés dans le registre IANA "JSON Web Signature and Encryption Header Parameters" établi par la section 9.1.
4.1.1 "alg" (Algorithm) Header Parameter (Paramètre d'en-tête "alg" (Algorithme))
Le paramètre d'en-tête « alg » (algorithm, algorithme) identifie l'algorithme cryptographique utilisé pour sécuriser le JWS. La valeur de la JWS Signature ou du JWS MAC dépend de la valeur « alg ».
Le paramètre d'en-tête « alg » doit (MUST) être présent dans l'en-tête JOSE. Il doit (MUST) être compris et traité par les implémentations.
Une liste des valeurs « alg » définies est fournie dans le registre IANA "JSON Web Signature and Encryption Algorithms" établi par [JWA]. Les valeurs initiales sont définies dans la section 3.1 de [JWA]. La valeur utilisée doit être soit une valeur enregistrée, soit une valeur qui est une collision-resistant name (nom résistant aux collisions).
Les implémenteurs doivent (MUST) soit rejeter les valeurs « alg » qu'ils ne comprennent pas, soit les traiter en utilisant une politique qui les associe à des valeurs comprises. Voir la section 10.6 pour les considérations de sécurité sur la validation de l'algorithme.
4.1.2 "jku" (JWK Set URL) Header Parameter (Paramètre d'en-tête "jku" (URL de JWK Set))
Le paramètre d'en-tête « jku » (JWK Set URL) est un URI [RFC3986] qui fait référence à une ressource pour un ensemble de clés Web JSON codées en JSON [JWK]. Les clés publiques représentées peuvent être utilisées pour vérifier la signature numérique ou le MAC du JWS.
Lorsque ce paramètre est utilisé, la ressource JWK Set doit (MUST) représenter un JWK Set JSON [JWK]. Les protocoles utilisés pour acquérir la ressource doivent (MUST) fournir l'authentification et l'intégrité. L'application utilisant « jku » doit (SHOULD) spécifier, dans un document de contexte, les mécanismes de sécurité utilisés pour acquérir les clés.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
4.1.3 "jwk" (JSON Web Key) Header Parameter (Paramètre d'en-tête "jwk" (Clé Web JSON))
Le paramètre d'en-tête « jwk » (JSON Web Key) est la clé publique correspondant à la clé utilisée pour signer numériquement le JWS. Cette clé est représentée comme un JSON Web Key [JWK]. L'utilisation de ce paramètre d'en-tête est optionnelle (OPTIONAL).
Lorsque ce paramètre est utilisé, le JWK représenté doit (MUST) contenir uniquement les paramètres JWK représentant la clé publique. Le JWK ne doit (MUST NOT) contenir de paramètres JWK représentant la clé privée.
4.1.4 "kid" (Key ID) Header Parameter (Paramètre d'en-tête "kid" (Identifiant de clé))
Le paramètre d'en-tête « kid » (key ID, identifiant de clé) est un indice indiquant quelle clé a été utilisée pour sécuriser le JWS. Ce paramètre permet aux émetteurs d'indiquer explicitement un changement de clé aux destinataires. La structure de la valeur « kid » n'est pas spécifiée. Sa valeur doit (MUST) être une chaîne sensible à la casse.
L'utilisation de ce paramètre d'en-tête est optionnelle (OPTIONAL).
Lorsqu'il est utilisé avec des JWK, la valeur « kid » peut être utilisée pour correspondre à un paramètre « kid » de JWK.
4.1.5 "x5u" (X.509 URL) Header Parameter (Paramètre d'en-tête "x5u" (URL X.509))
Le paramètre d'en-tête « x5u » (X.509 URL) est un URI [RFC3986] qui fait référence à une ressource pour le certificat X.509 [RFC5280] ou la chaîne de certificats [RFC5280] correspondant à la clé utilisée pour signer numériquement le JWS. Le certificat ou la chaîne de certificats identifié est encodé au format PEM [RFC1421].
Ce paramètre d'en-tête est optionnel (OPTIONAL).
4.1.6 "x5c" (X.509 Certificate Chain) Header Parameter (Paramètre d'en-tête "x5c" (Chaîne de certificats X.509))
Le paramètre d'en-tête « x5c » (X.509 certificate chain, chaîne de certificats X.509) contient la chaîne de certificats X.509 [RFC5280] ou le chemin de certification [RFC5280] correspondant à la clé utilisée pour signer numériquement le JWS. La chaîne de certificats est représentée comme un tableau JSON de chaînes de certificats. Chaque chaîne dans le tableau est un certificat PKIX encodé en base64 (pas en base64url encodé) [RFC5280].
Le certificat contenant la clé publique correspondant à la clé utilisée pour signer numériquement le JWS doit (MUST) être le premier certificat. Cela peut (MAY) être suivi par des certificats supplémentaires, avec chaque certificat suivant certifiant le précédent.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
Voir l'annexe B pour un exemple d'utilisation de « x5c ».
4.1.7 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter (Paramètre d'en-tête "x5t" (Empreinte SHA-1 du certificat X.509))
Le paramètre d'en-tête « x5t » (X.509 certificate SHA-1 thumbprint, empreinte SHA-1 du certificat X.509) est une empreinte encodée en base64url (nom abrégé pour empreinte numérique) de l'encodage DER du certificat X.509 [RFC5280] correspondant à la clé utilisée pour signer numériquement le JWS. Notez que les encodages de certificat (et donc les empreintes) sont dépendants de l'ordre des attributs du certificat ; voir [RFC4945] pour plus d'informations.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
Note : Ce paramètre est conservé uniquement pour la compatibilité ascendante. Les implémentations devraient utiliser « x5t#S256 » (empreinte SHA-256) à la place.
4.1.8 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter (Paramètre d'en-tête "x5t#S256" (Empreinte SHA-256 du certificat X.509))
Le paramètre d'en-tête « x5t#S256 » (X.509 certificate SHA-256 thumbprint, empreinte SHA-256 du certificat X.509) est une empreinte encodée en base64url de l'encodage DER du certificat X.509 [RFC5280] correspondant à la clé utilisée pour signer numériquement le JWS, en utilisant la fonction de hachage SHA-256.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
4.1.9 "typ" (Type) Header Parameter (Paramètre d'en-tête "typ" (Type))
Le paramètre d'en-tête « typ » (type) est utilisé par les applications JWS pour déclarer le type de média [IANA.MediaTypes] de cet objet complet JWS. Ceci est destiné à être utilisé par l'application lorsque plusieurs types de contenu peuvent être présents dans la même structure de données.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
Pour maximiser la compatibilité, il est recommandé (RECOMMENDED) que les applications JWS omettent la portion « application/ » du type de média lors de l'utilisation de « typ ». Par exemple, une valeur « JWT » pourrait être utilisée pour indiquer que cet objet est un JWT [JWT], plutôt que « application/jwt ».
4.1.10 "cty" (Content Type) Header Parameter (Paramètre d'en-tête "cty" (Type de contenu))
Le paramètre d'en-tête « cty » (content type, type de contenu) est utilisé par les applications JWS pour déclarer le type de média [IANA.MediaTypes] du contenu sécurisé (la charge utile). Ceci est destiné à être utilisé par l'application lorsque plusieurs types de contenu de charge utile peuvent être présents.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
Dans le cas normal où des JWS imbriqués ou des JWE sont utilisés, l'utilisation de ce paramètre d'en-tête est recommandée (RECOMMENDED). Dans le cas normal où les JWS ne sont pas imbriqués, l'utilisation de ce paramètre d'en-tête est déconseillée (NOT RECOMMENDED).
Pour maximiser la compatibilité, il est recommandé (RECOMMENDED) que les applications JWS omettent la portion « application/ » du type de média lors de l'utilisation de « cty ».
4.1.11 "crit" (Critical) Header Parameter (Paramètre d'en-tête "crit" (Critique))
Le paramètre d'en-tête « crit » (critical, critique) indique que des extensions à cette spécification et/ou [JWA] sont utilisées qui doivent (MUST) être comprises et traitées. Sa valeur est un tableau répertoriant les noms de paramètres d'en-tête présents dans l'en-tête JOSE qui utilisent ces extensions.
Si l'un des noms de paramètres d'en-tête répertoriés n'est pas compris et pris en charge par le destinataire, alors le JWS est invalide. Le destinataire doit (MUST) soit traiter ces paramètres d'en-tête, soit rejeter le JWS.
Ce paramètre d'en-tête est optionnel (OPTIONAL).
Les producteurs devraient (SHOULD) seulement inclure des noms de paramètres d'en-tête d'extension dans la valeur « crit ». Les noms de paramètres d'en-tête définis par cette spécification ou [JWA] ne devraient (SHOULD NOT) être répertoriés.
Voir l'annexe E pour un cas de test négatif pour « crit ».
4.2 Public Header Parameter Names (Noms de paramètres d'en-tête publics)
Des noms de paramètres d'en-tête supplémentaires peuvent être définis par ceux qui produisent et consomment des JWS. Cependant, afin de prévenir les collisions, tous les nouveaux noms de paramètres d'en-tête devraient (SHOULD) soit être enregistrés dans le registre IANA "JSON Web Signature and Encryption Header Parameters" établi par la section 9.1, soit être un public name (nom public) : une valeur qui contient un collision-resistant name (nom résistant aux collisions).
Dans chaque cas, la définition du nom de paramètre d'en-tête devrait spécifier si et comment le paramètre d'en-tête est destiné à être utilisé avec les JWS Protected Headers, avec les JWS Unprotected Headers, ou les deux.
De nouveaux paramètres d'en-tête doivent être introduits avec parcimonie, car les paramètres d'en-tête non compris doivent (MUST) être ignorés, à moins d'être répertoriés dans le paramètre d'en-tête « crit ».
4.3 Private Header Parameter Names (Noms de paramètres d'en-tête privés)
Un producteur et un consommateur d'un JWS peuvent (MAY) convenir d'utiliser des noms de paramètres d'en-tête qui sont des private names (noms privés) : des noms qui ne sont pas enregistrés dans le registre IANA "JSON Web Signature and Encryption Header Parameters" (Section 9.1) et ne sont pas des public names (Section 4.2). Contrairement aux public names, les private names sont sujets à collision et devraient être utilisés avec précaution.