Aller au contenu principal

7. Serializations (Sérialisations)

Les JWE utilisent l'une des deux sérialisations : la sérialisation compacte JWE ou la sérialisation JSON JWE. Les applications utilisant cette spécification doivent spécifier quelle sérialisation et quelles fonctionnalités de sérialisation sont utilisées pour cette application. Par exemple, les applications peuvent spécifier que seule la sérialisation JSON JWE est utilisée, que seul le support de sérialisation JSON JWE pour un seul destinataire est utilisé, ou que le support pour plusieurs destinataires est utilisé. Les implémentations JWE ne doivent implémenter que les fonctionnalités nécessaires pour les applications qu'elles sont conçues pour prendre en charge.

7.1 JWE Compact Serialization (Sérialisation compacte JWE)​

La sérialisation compacte JWE représente le contenu chiffré sous forme de chaîne compacte et sûre pour les URL. Cette chaîne est :

BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)

Un seul destinataire est pris en charge par la sérialisation compacte JWE et elle ne fournit aucune syntaxe pour représenter les valeurs d'en-tête non protégé partagé JWE, d'en-tête non protégé par destinataire JWE ou JWE AAD.

7.2 JWE JSON Serialization (Sérialisation JSON JWE)​

La sérialisation JSON JWE représente le contenu chiffré sous forme d'objet JSON. Cette représentation n'est ni optimisée pour la compacité ni sûre pour les URL.

Deux syntaxes étroitement liées sont définies pour la sérialisation JSON JWE : une syntaxe entièrement générale, avec laquelle le contenu peut être chiffré pour plus d'un destinataire, et une syntaxe aplatie, qui est optimisée pour le cas d'un seul destinataire.

7.2.1 General JWE JSON Serialization Syntax (Syntaxe de sérialisation JSON JWE générale)​

Les membres suivants sont définis pour une utilisation dans les objets JSON de niveau supérieur utilisés pour la syntaxe de sérialisation JSON JWE entièrement générale :

protected : Le membre "protected" doit (MUST) être présent et contenir la valeur BASE64URL(UTF8(JWE Protected Header)) lorsque la valeur de l'en-tête protégé JWE n'est pas vide; sinon, il doit (MUST) être absent. Ces valeurs de paramètres d'en-tête sont protégées en intégrité.

unprotected : Le membre "unprotected" doit (MUST) être présent et contenir la valeur d'en-tête non protégé partagé JWE lorsque la valeur de l'en-tête non protégé partagé JWE n'est pas vide; sinon, il doit (MUST) être absent. Cette valeur est représentée comme un objet JSON non encodé, plutôt que comme une chaîne. Ces valeurs de paramètres d'en-tête ne sont pas protégées en intégrité.

iv : Le membre "iv" doit (MUST) être présent et contenir la valeur BASE64URL(JWE Initialization Vector) lorsque la valeur du vecteur d'initialisation JWE n'est pas vide; sinon, il doit (MUST) être absent.

aad : Le membre "aad" doit (MUST) être présent et contenir la valeur BASE64URL(JWE AAD) lorsque la valeur JWE AAD n'est pas vide; sinon, il doit (MUST) être absent. Une valeur JWE AAD peut être incluse pour fournir une valeur encodée en base64url qui est protégée en intégrité mais non chiffrée.

ciphertext : Le membre "ciphertext" doit (MUST) être présent et contenir la valeur BASE64URL(JWE Ciphertext).

tag : Le membre "tag" doit (MUST) être présent et contenir la valeur BASE64URL(JWE Authentication Tag) lorsque la valeur du tag d'authentification JWE n'est pas vide; sinon, il doit (MUST) être absent.

recipients : La valeur du membre "recipients" doit (MUST) être un tableau d'objets JSON. Chaque objet contient des informations spécifiques à un seul destinataire. Ce membre doit (MUST) être présent avec exactement un élément de tableau par destinataire, même si certaines ou toutes les valeurs d'éléments de tableau sont l'objet JSON vide "" (ce qui peut se produire lorsque toutes les valeurs de paramètres d'en-tête sont partagées entre tous les destinataires et qu'aucune clé chiffrée n'est utilisée, comme lors du chiffrement direct).

Les membres suivants sont définis pour une utilisation dans les objets JSON qui sont des éléments du tableau "recipients" :

header : Le membre "header" doit (MUST) être présent et contenir la valeur d'en-tête non protégé par destinataire JWE lorsque la valeur de l'en-tête non protégé par destinataire JWE n'est pas vide; sinon, il doit (MUST) être absent. Cette valeur est représentée comme un objet JSON non encodé, plutôt que comme une chaîne. Ces valeurs de paramètres d'en-tête ne sont pas protégées en intégrité.

encrypted_key : Le membre "encrypted_key" doit (MUST) être présent et contenir la valeur BASE64URL(JWE Encrypted Key) lorsque la valeur de la clé chiffrée JWE n'est pas vide; sinon, il doit (MUST) être absent.

Au moins l'un des membres "header", "protected" et "unprotected" doit (MUST) être présent afin que les valeurs de paramètres d'en-tête "alg" et "enc" soient transmises pour chaque calcul de destinataire.

Des membres supplémentaires peuvent être présents dans les deux objets JSON définis ci-dessus; s'ils ne sont pas compris par les implémentations qui les rencontrent, ils doivent (MUST) être ignorés.

Certains paramètres d'en-tête, y compris le paramètre "alg", peuvent être partagés entre tous les calculs de destinataires. Les valeurs de paramètres d'en-tête dans l'en-tête protégé JWE et les valeurs d'en-tête non protégé partagé JWE sont partagées entre tous les destinataires.

Les valeurs de paramètres d'en-tête utilisées lors de la création ou de la validation des valeurs de texte chiffré et de tag d'authentification par destinataire sont l'union des trois ensembles de valeurs de paramètres d'en-tête qui peuvent être présents : (1) l'en-tête protégé JWE représenté dans le membre "protected", (2) l'en-tête non protégé partagé JWE représenté dans le membre "unprotected", et (3) l'en-tête non protégé par destinataire JWE représenté dans le membre "header" de l'élément de tableau du destinataire. L'union de ces ensembles de paramètres d'en-tête comprend l'en-tête JOSE. Les noms de paramètres d'en-tête dans les trois emplacements doivent (MUST) être disjoints.

Chaque valeur de clé chiffrée JWE est calculée en utilisant les paramètres de la valeur d'en-tête JOSE correspondante de la même manière que pour la sérialisation compacte JWE. Cela a la propriété souhaitable que chaque valeur de clé chiffrée JWE dans le tableau "recipients" est identique à la valeur qui aurait été calculée pour les mêmes paramètres dans une sérialisation compacte JWE. De même, les valeurs de texte chiffré JWE et de tag d'authentification JWE correspondent à celles produites pour la sérialisation compacte JWE, à condition que la valeur d'en-tête protégé JWE (qui représente les valeurs de paramètres d'en-tête protégées en intégrité) corresponde à celle utilisée dans la sérialisation compacte JWE.

Tous les destinataires utilisent les mêmes valeurs d'en-tête protégé JWE, de vecteur d'initialisation JWE, de texte chiffré JWE et de tag d'authentification JWE, lorsqu'elles sont présentes, ce qui entraîne des économies d'espace potentiellement importantes si le message est volumineux. Par conséquent, tous les paramètres d'en-tête qui spécifient le traitement de la valeur de texte en clair doivent (MUST) être les mêmes pour tous les destinataires. Cela signifie principalement que la valeur du paramètre d'en-tête "enc" (algorithme de chiffrement) dans l'en-tête JOSE pour chaque destinataire et tous les paramètres de cet algorithme doivent (MUST) être les mêmes.

En résumé, la syntaxe d'un JWE utilisant la sérialisation JSON JWE générale est la suivante :

{
 "protected":"<integrity-protected shared header contents>",
 "unprotected":<non-integrity-protected shared header contents>,
 "recipients":[
  {"header":<per-recipient unprotected header 1 contents>,
   "encrypted_key":"<encrypted key 1 contents>"},
  ...
  {"header":<per-recipient unprotected header N contents>,
   "encrypted_key":"<encrypted key N contents>"}],
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

Voir l'annexe A.4 pour un exemple de JWE utilisant la syntaxe de sérialisation JSON JWE générale.

7.2.2 Flattened JWE JSON Serialization Syntax (Syntaxe de sérialisation JSON JWE aplatie)​

La syntaxe de sérialisation JSON JWE aplatie est basée sur la syntaxe générale mais l'aplatit, l'optimisant pour le cas d'un seul destinataire. Elle l'aplatit en supprimant le membre "recipients" et en plaçant à la place les membres définis pour une utilisation dans le tableau "recipients" (les membres "header" et "encrypted_key") dans l'objet JSON de niveau supérieur (au même niveau que le membre "ciphertext").

Le membre "recipients" ne doit pas (MUST NOT) être présent lors de l'utilisation de cette syntaxe. Outre cette différence de syntaxe, les objets de sérialisation JSON JWE utilisant la syntaxe aplatie sont traités de manière identique à ceux utilisant la syntaxe générale.

En résumé, la syntaxe d'un JWE utilisant la sérialisation JSON JWE aplatie est la suivante :

{
 "protected":"<integrity-protected header contents>",
 "unprotected":<non-integrity-protected header contents>,
 "header":<more non-integrity-protected header contents>,
 "encrypted_key":"<encrypted key contents>",
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

Notez que lors de l'utilisation de la syntaxe aplatie, tout comme lors de l'utilisation de la syntaxe générale, toutes les valeurs de paramètres d'en-tête non protégés peuvent résider soit dans le membre "unprotected", soit dans le membre "header", soit dans les deux.

Voir l'annexe A.5 pour un exemple de JWE utilisant la syntaxe de sérialisation JSON JWE aplatie.

Dernière mise à jour le