7. Serializations (Sérialisations)

Les JWS utilisent l'une des deux sérialisations : la sérialisation compacte JWS (JWS Compact Serialization) ou la sérialisation JSON JWS (JWS JSON Serialization). Les applications utilisant cette spécification doivent spécifier quelle sérialisation et quelles fonctionnalités de sérialisation sont utilisées par cette application. Par exemple, une application peut spécifier que seule la sérialisation JSON JWS est utilisée, que seul le support de la sérialisation JSON JWS pour une seule valeur de signature ou de MAC est utilisé, ou qu'un support pour plusieurs valeurs de signature et/ou de MAC est utilisé. Les implémentations JWS n'ont besoin d'implémenter que les fonctionnalités nécessaires aux applications qu'elles sont conçues pour prendre en charge.

7.1 JWS Compact Serialization (Sérialisation compacte JWS)

La sérialisation compacte JWS représente le contenu signé numériquement ou protégé par MAC comme une chaîne compacte et sûre pour les URL. Cette chaîne est :

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)

La sérialisation compacte JWS ne prend en charge qu'une seule signature/MAC et ne fournit pas de syntaxe pour représenter les valeurs de JWS Unprotected Header.

7.2 JWS JSON Serialization (Sérialisation JSON JWS)

La sérialisation JSON JWS représente le contenu signé numériquement ou protégé par MAC comme un 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 JWS : une syntaxe entièrement générale qui permet d'utiliser plusieurs opérations de signature numérique et/ou de MAC pour protéger le contenu, et une syntaxe aplatie optimisée pour le cas d'une seule signature numérique ou MAC.

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

Les membres suivants sont définis pour l'objet JSON de niveau supérieur pour la syntaxe générale de sérialisation JSON JWS :

payload : Le membre « payload » doit (MUST) être présent et contenir la valeur BASE64URL(JWS Payload).

signatures : La valeur du membre « signatures » doit (MUST) être un tableau d'objets JSON. Chaque objet représente une signature ou un MAC sur le JWS Payload et le JWS Protected Header.

Les membres suivants sont définis pour l'objet JSON des éléments du tableau « signatures » :

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

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

signature : Le membre « signature » doit (MUST) être présent et contenir la valeur BASE64URL(JWS Signature).

Au moins l'un des membres « protected » et « header » doit (MUST) être présent pour chaque calcul de signature/MAC afin de transmettre la valeur du paramètre d'en-tête « alg ».

D'autres membres peuvent être présents dans l'objet JSON défini ci-dessus ; s'ils ne sont pas compris par les implémentations qui les rencontrent, ils doivent (MUST) être ignorés.

Les valeurs de paramètres d'en-tête utilisées lors de la création ou de la vérification d'une valeur de signature ou de MAC individuelle sont l'union des deux ensembles de valeurs de paramètres d'en-tête qui peuvent être présents : (1) le JWS Protected Header représenté dans le membre « protected » de l'élément du tableau pour la signature/MAC, et (2) le JWS Unprotected Header dans le membre « header » de l'élément du tableau pour la signature/MAC. L'union de ces ensembles de paramètres d'en-tête constitue l'en-tête JOSE. Les noms de paramètres d'en-tête dans les deux emplacements doivent (MUST) être disjoints.

Chaque valeur de JWS Signature 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 JWS. Cela a la propriété souhaitable que chaque valeur de JWS Signature représentée dans le tableau « signatures » est la même que la valeur qui serait calculée pour les mêmes paramètres dans la sérialisation compacte JWS, à condition que la valeur du JWS Protected Header pour ce calcul de signature/MAC (représentant les valeurs de paramètres d'en-tête protégées en intégrité) corresponde à celle utilisée dans la sérialisation compacte JWS.

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

{
 "payload":"<contenu de la charge utile>",
 "signatures":[
  {"protected":"<contenu de l'en-tête protégé en intégrité 1>",
   "header":<contenu de l'en-tête non protégé en intégrité 1>,
   "signature":"<contenu de la signature 1>"},
  ...
  {"protected":"<contenu de l'en-tête protégé en intégrité N>",
   "header":<contenu de l'en-tête non protégé en intégrité N>,
   "signature":"<contenu de la signature N>"}]
}

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

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

La syntaxe aplatie de sérialisation JSON JWS est basée sur la syntaxe générale, mais l'aplatit, en l'optimisant pour le cas d'une seule signature numérique/MAC. Elle l'aplatit en supprimant le membre « signatures » et en plaçant ces membres définis pour une utilisation dans le tableau « signatures » (les membres « protected », « header » et « signature ») au niveau de l'objet JSON de niveau supérieur (au même niveau que le membre « payload »).

Lors de l'utilisation de cette syntaxe, le membre « signatures » ne doit (MUST NOT) être présent. Mis à part cette différence de syntaxe, les objets de sérialisation JSON JWS utilisant la syntaxe aplatie sont traités exactement de la même manière que ceux utilisant la syntaxe générale.

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

{
 "payload":"<contenu de la charge utile>",
 "protected":"<contenu de l'en-tête protégé en intégrité>",
 "header":<contenu de l'en-tête non protégé en intégrité>,
 "signature":"<contenu de la signature>"
}

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