Aller au contenu principal

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

Un JWK est un objet JSON qui représente une clé cryptographique (Cryptographic Key). Les membres de l'objet représentent les propriétés de la clé, y compris sa valeur. Cet objet JSON peut (MAY) contenir des espaces et/ou des sauts de ligne avant ou après n'importe quelle valeur JSON ou caractère structurel, conformément à la section 2 de RFC 7159 [RFC7159]. Ce document définit les paramètres de clé qui ne sont pas spécifiques à un algorithme et, par conséquent, communs à de nombreuses clés.

En plus des paramètres communs, chaque JWK aura des membres spécifiques au type de clé. Ces membres représentent les paramètres de la clé. La section 6 de la spécification JSON Web Algorithms (JWA) [JWA] définit plusieurs types de clés cryptographiques et leurs membres associés.

Les noms de membres dans un JWK doivent (MUST) être uniques ; les analyseurs JWK doivent (MUST) soit rejeter les JWK avec des noms de membres en double, soit utiliser un analyseur JSON qui ne renvoie que le dernier nom de membre en double lexicalement, comme spécifié dans la section 15.12 (The JSON Object) d'ECMAScript 5.1 [ECMAScript].

Des membres supplémentaires peuvent être présents dans le JWK ; s'ils ne sont pas compris par les implémentations qui les rencontrent, ils doivent (MUST) être ignorés. Les noms de membres utilisés pour représenter les paramètres de clé pour différents types de clés n'ont pas besoin d'être distincts. Tout nouveau nom de membre devrait (SHOULD) soit être enregistré dans le registre IANA « JSON Web Key Parameters » établi par la section 8.1, soit être une valeur qui contient un nom résistant aux collisions (Collision-Resistant Name).

4.1. Paramètre "kty" (Key Type)​

Le paramètre « kty » (key type, type de clé) identifie la famille d'algorithmes cryptographiques (Cryptographic Algorithm Family) utilisée avec la clé, telle que « RSA » ou « EC ». Les valeurs « kty » devraient (SHOULD) soit être enregistrées dans le registre IANA « JSON Web Key Types » établi par [JWA], soit être une valeur qui contient un nom résistant aux collisions. La valeur « kty » est une chaîne sensible à la casse. Ce membre doit (MUST) être présent dans un JWK.

Une liste des valeurs « kty » définies peut être trouvée dans le registre IANA « JSON Web Key Types » établi par [JWA] ; le contenu initial de ce registre est constitué des valeurs définies dans la section 6.1 de [JWA].

Les définitions de type de clé incluent la spécification des membres à utiliser pour ces types de clés. Les membres utilisés avec des valeurs « kty » spécifiques peuvent être trouvés dans le registre IANA « JSON Web Key Parameters » établi par la section 8.1.

4.2. Paramètre "use" (Public Key Use)​

Le paramètre « use » (public key use, utilisation de clé publique) identifie l'utilisation prévue de la clé publique. Le paramètre « use » est employé pour indiquer si une clé publique est utilisée pour chiffrer des données ou vérifier la signature sur des données.

Les valeurs définies par cette spécification sont :

  • "sig" (signature)
  • "enc" (encryption, chiffrement)

D'autres valeurs peuvent (MAY) être utilisées. La valeur « use » est une chaîne sensible à la casse. L'utilisation du membre « use » est optionnelle (OPTIONAL), sauf si l'application exige sa présence.

Lorsqu'une clé est utilisée pour envelopper (Wrap) une autre clé et qu'une désignation d'utilisation de clé publique pour la première clé est souhaitée, la valeur d'utilisation de clé « enc » (encryption, chiffrement) est utilisée, car l'enveloppement de clé est une forme de chiffrement. La valeur « enc » doit également être utilisée pour les clés publiques utilisées pour les opérations d'accord de clé (Key Agreement).

Des valeurs « use » (public key use) supplémentaires peuvent être enregistrées dans le registre IANA « JSON Web Key Use » établi par la section 8.2. L'enregistrement de toute valeur d'extension utilisée est fortement recommandé (RECOMMENDED) lorsque cette spécification est utilisée dans des environnements ouverts, dans lesquels plusieurs organisations doivent avoir une compréhension commune de toutes les extensions utilisées. Cependant, des valeurs d'extension non enregistrées peuvent être utilisées dans des environnements fermés, dans lesquels l'organisation productrice et consommatrice sera toujours la même.

4.3. Paramètre "key_ops" (Key Operations)​

Le paramètre « key_ops » (key operations, opérations de clé) identifie la ou les opérations pour lesquelles la clé est destinée à être utilisée. Le paramètre « key_ops » est destiné aux cas d'utilisation dans lesquels des clés publiques, privées ou symétriques peuvent être présentes.

Sa valeur est un tableau de valeurs d'opération de clé. Les valeurs définies par cette spécification sont :

  • "sign" (compute digital signature or MAC, calculer une signature numérique ou un MAC)
  • "verify" (verify digital signature or MAC, vérifier une signature numérique ou un MAC)
  • "encrypt" (encrypt content, chiffrer le contenu)
  • "decrypt" (decrypt content and validate decryption, if applicable, déchiffrer le contenu et valider le déchiffrement, le cas échéant)
  • "wrapKey" (encrypt key, chiffrer la clé)
  • "unwrapKey" (decrypt key and validate decryption, if applicable, déchiffrer la clé et valider le déchiffrement, le cas échéant)
  • "deriveKey" (derive key, dériver une clé)
  • "deriveBits" (derive bits not to be used as a key, dériver des bits non utilisés comme clé)

(Notez que les valeurs « key_ops » correspondent intentionnellement aux valeurs « KeyUsage » définies dans la spécification Web Cryptography API [W3C.CR-WebCryptoAPI-20141211].)

D'autres valeurs peuvent (MAY) être utilisées. Les valeurs d'opération de clé sont des chaînes sensibles à la casse. Les valeurs d'opération de clé en double ne doivent pas (MUST NOT) être présentes dans le tableau. L'utilisation du membre « key_ops » est optionnelle (OPTIONAL), sauf si l'application exige sa présence.

Plusieurs opérations de clé non liées ne devraient pas (SHOULD NOT) être spécifiées pour une clé en raison des vulnérabilités potentielles associées à l'utilisation de la même clé avec plusieurs algorithmes. Ainsi, les combinaisons « sign » avec « verify », « encrypt » avec « decrypt », et « wrapKey » avec « unwrapKey » sont autorisées, mais d'autres combinaisons ne devraient pas (SHOULD NOT) être utilisées.

Des valeurs « key_ops » (key operations) supplémentaires peuvent être enregistrées dans le registre IANA « JSON Web Key Operations » établi par la section 8.3. Les mêmes considérations concernant l'enregistrement des valeurs d'extension s'appliquent au membre « key_ops » comme pour le membre « use ».

Les membres JWK « use » et « key_ops » ne devraient pas (SHOULD NOT) être utilisés ensemble ; cependant, si les deux sont utilisés, les informations qu'ils transmettent doivent (MUST) être cohérentes. Les applications devraient (SHOULD) spécifier lequel de ces membres elles utilisent, si l'un d'eux doit être utilisé par l'application.

4.4. Paramètre "alg" (Algorithm)​

Le paramètre « alg » (algorithm, algorithme) identifie l'algorithme destiné à être utilisé avec la clé. Les valeurs utilisées devraient (SHOULD) soit être enregistrées dans le registre IANA « JSON Web Signature and Encryption Algorithms » établi par [JWA], soit être une valeur qui contient un nom résistant aux collisions. La valeur « alg » est une chaîne ASCII sensible à la casse. L'utilisation de ce membre est optionnelle (OPTIONAL).

4.5. Paramètre "kid" (Key ID)​

Le paramètre « kid » (key ID, identifiant de clé) est utilisé pour faire correspondre une clé spécifique. Ceci est utilisé, par exemple, pour choisir parmi un ensemble de clés dans un JWK Set pendant le roulement de clé (Key Rollover). La structure de la valeur « kid » n'est pas spécifiée. Lorsque les valeurs « kid » sont utilisées dans un JWK Set, différentes clés dans le JWK Set devraient (SHOULD) utiliser des valeurs « kid » distinctes. (Un exemple dans lequel différentes clés pourraient utiliser la même valeur « kid » est si elles ont des valeurs « kty » (key type, type de clé) différentes mais sont considérées comme des alternatives équivalentes par l'application qui les utilise.) La valeur « kid » est une chaîne sensible à la casse. L'utilisation de ce membre est optionnelle (OPTIONAL). Lorsqu'elle est utilisée avec JWS ou JWE, la valeur « kid » est utilisée pour faire correspondre une valeur de paramètre d'en-tête « kid » JWS ou JWE.

4.6. Paramètre "x5u" (X.509 URL)​

Le paramètre « x5u » (X.509 URL) est un URI [RFC3986] qui fait référence à une ressource pour un certificat de clé publique X.509 ou une chaîne de certificats (Certificate Chain) [RFC5280]. La ressource identifiée doit (MUST) fournir une représentation du certificat ou de la chaîne de certificats conforme à RFC 5280 [RFC5280] sous forme encodée PEM, avec chaque certificat délimité comme spécifié dans la section 6.1 de RFC 4945 [RFC4945]. La clé dans le premier certificat doit (MUST) correspondre à la clé publique représentée par les autres membres du JWK. Le protocole utilisé pour acquérir la ressource doit (MUST) fournir une protection d'intégrité (Integrity Protection) ; une requête HTTP GET pour récupérer le certificat doit (MUST) utiliser TLS [RFC2818] [RFC5246] ; l'identité du serveur doit (MUST) être validée, conformément à la section 6 de RFC 6125 [RFC6125]. L'utilisation de ce membre est optionnelle (OPTIONAL).

Bien qu'il ne soit pas nécessaire que des membres JWK optionnels fournissant l'utilisation de la clé, l'algorithme ou d'autres informations soient présents lorsque le membre « x5u » est utilisé, le faire peut améliorer l'interopérabilité pour les applications qui ne traitent pas les certificats PKIX [RFC5280]. Si d'autres membres sont présents, le contenu de ces membres doit (MUST) être sémantiquement cohérent avec les champs pertinents du premier certificat. Par exemple, si le membre « use » est présent, il doit (MUST) correspondre à l'utilisation spécifiée dans le certificat, lorsque le certificat inclut cette information. De même, si le membre « alg » est présent, il doit (MUST) correspondre à l'algorithme spécifié dans le certificat.

4.7. Paramètre "x5c" (X.509 Certificate Chain)​

Le paramètre « x5c » (X.509 certificate chain, chaîne de certificats X.509) contient une chaîne d'un ou plusieurs certificats PKIX [RFC5280]. La chaîne de certificats est représentée sous forme de tableau JSON de chaînes de valeurs de certificat. Chaque chaîne dans le tableau est une valeur de certificat PKIX DER [ITU.X690.1994] encodée en base64 (section 4 de [RFC4648] -- pas encodée en base64url). Le certificat PKIX contenant la valeur de clé doit (MUST) être le premier certificat. Ceci peut (MAY) être suivi de certificats supplémentaires, chaque certificat suivant étant celui utilisé pour certifier le précédent. La clé dans le premier certificat doit (MUST) correspondre à la clé publique représentée par les autres membres du JWK. L'utilisation de ce membre est optionnelle (OPTIONAL).

Comme pour le membre « x5u », des membres JWK optionnels fournissant l'utilisation de la clé, l'algorithme ou d'autres informations peuvent (MAY) également être présents lorsque le membre « x5c » est utilisé. Si d'autres membres sont présents, le contenu de ces membres doit (MUST) être sémantiquement cohérent avec les champs pertinents du premier certificat. Voir le dernier paragraphe de la section 4.6 pour des conseils supplémentaires à ce sujet.

4.8. Paramètre "x5t" (X.509 Certificate SHA-1 Thumbprint)​

Le paramètre « x5t » (X.509 certificate SHA-1 thumbprint, empreinte SHA-1 de certificat X.509) est une empreinte (thumbprint, alias digest) SHA-1 encodée en base64url de l'encodage DER d'un certificat X.509 [RFC5280]. Notez que les empreintes de certificat sont aussi parfois appelées empreintes digitales de certificat (certificate fingerprints). La clé dans le certificat doit (MUST) correspondre à la clé publique représentée par les autres membres du JWK. L'utilisation de ce membre est optionnelle (OPTIONAL).

Comme pour le membre « x5u », des membres JWK optionnels fournissant l'utilisation de la clé, l'algorithme ou d'autres informations peuvent (MAY) également être présents lorsque le membre « x5t » est utilisé. Si d'autres membres sont présents, le contenu de ces membres doit (MUST) être sémantiquement cohérent avec les champs pertinents du certificat référencé. Voir le dernier paragraphe de la section 4.6 pour des conseils supplémentaires à ce sujet.

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

Le paramètre « x5t#S256 » (X.509 certificate SHA-256 thumbprint, empreinte SHA-256 de certificat X.509) est une empreinte (thumbprint, alias digest) SHA-256 encodée en base64url de l'encodage DER d'un certificat X.509 [RFC5280]. Notez que les empreintes de certificat sont aussi parfois appelées empreintes digitales de certificat (certificate fingerprints). La clé dans le certificat doit (MUST) correspondre à la clé publique représentée par les autres membres du JWK. L'utilisation de ce membre est optionnelle (OPTIONAL).

Comme pour le membre « x5u », des membres JWK optionnels fournissant l'utilisation de la clé, l'algorithme ou d'autres informations peuvent (MAY) également être présents lorsque le membre « x5t#S256 » est utilisé. Si d'autres membres sont présents, le contenu de ces membres doit (MUST) être sémantiquement cohérent avec les champs pertinents du certificat référencé. Voir le dernier paragraphe de la section 4.6 pour des conseils supplémentaires à ce sujet.

Dernière mise à jour le