7. Serializations (Serializzazioni)

I JWS utilizzano una di due serializzazioni: la JWS Compact Serialization o la JWS JSON Serialization. Le applicazioni che utilizzano questa specifica devono specificare quale serializzazione e quali funzionalità di serializzazione sono utilizzate da tale applicazione. Ad esempio, un'applicazione può specificare che viene utilizzata solo la JWS JSON Serialization, che viene utilizzato solo il supporto per la JWS JSON Serialization per un singolo valore di firma o MAC, o che viene utilizzato il supporto per più valori di firma e/o MAC. Le implementazioni JWS devono implementare solo le funzionalità necessarie per le applicazioni che sono progettate per supportare.

7.1 JWS Compact Serialization (Serializzazione compatta JWS)

La JWS Compact Serialization rappresenta contenuti firmati digitalmente o protetti da MAC come una stringa compatta e URL-safe. Questa stringa è:

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

La JWS Compact Serialization supporta solo una singola firma/MAC e non fornisce sintassi per rappresentare i valori JWS Unprotected Header.

7.2 JWS JSON Serialization (Serializzazione JSON JWS)

La JWS JSON Serialization rappresenta contenuti firmati digitalmente o protetti da MAC come un oggetto JSON. Questa rappresentazione non è ottimizzata né per la compattezza né per la sicurezza URL.

Sono definite due sintassi strettamente correlate per la JWS JSON Serialization: una sintassi completamente generale che consente l'uso di più operazioni di firma digitale e/o MAC per proteggere il contenuto, e una sintassi appiattita ottimizzata per il caso di una singola firma digitale o MAC.

7.2.1 General JWS JSON Serialization Syntax (Sintassi generale di serializzazione JSON JWS)

I seguenti membri sono definiti per l'oggetto JSON di livello superiore per la sintassi generale di serializzazione JSON JWS:

payload : Il membro "payload" deve (MUST) essere presente e contenere il valore BASE64URL(JWS Payload).

signatures : Il valore del membro "signatures" deve (MUST) essere un array di oggetti JSON. Ogni oggetto rappresenta una firma o un MAC sul JWS Payload e sul JWS Protected Header.

I seguenti membri sono definiti per gli oggetti JSON degli elementi dell'array "signatures":

protected : Il membro "protected" deve (MUST) essere presente e contenere il valore BASE64URL(UTF8(JWS Protected Header)) quando il valore del JWS Protected Header non è vuoto; altrimenti, non deve (MUST) essere presente. Questi valori dei parametri header sono protetti in integrità.

header : Il membro "header" deve (MUST) essere presente e contenere il valore JWS Unprotected Header quando il valore del JWS Unprotected Header non è vuoto; altrimenti, non deve (MUST) essere presente. Questo valore è rappresentato come un oggetto JSON non codificato, anziché una stringa. Questi valori dei parametri header non sono protetti in integrità.

signature : Il membro "signature" deve (MUST) essere presente e contenere il valore BASE64URL(JWS Signature).

Almeno uno dei membri "protected" e "header" deve (MUST) essere presente per ciascun calcolo di firma/MAC per trasmettere il valore del parametro header "alg".

Altri membri possono essere presenti nell'oggetto JSON definito sopra; se non sono compresi dalle implementazioni che li incontrano, devono (MUST) essere ignorati.

I valori dei parametri header utilizzati durante la creazione o la verifica di un singolo valore di firma o MAC sono l'unione dei due insiemi di valori dei parametri header che possono essere presenti: (1) il JWS Protected Header rappresentato nel membro "protected" dell'elemento dell'array per la firma/MAC, e (2) il JWS Unprotected Header nel membro "header" dell'elemento dell'array per la firma/MAC. L'unione di questi insiemi di parametri header costituisce l'header JOSE. I nomi dei parametri header in entrambe le posizioni devono (MUST) essere disgiunti.

Ogni valore JWS Signature è calcolato utilizzando i parametri del valore dell'header JOSE corrispondente nello stesso modo della JWS Compact Serialization. Ciò ha la proprietà desiderabile che ogni valore JWS Signature rappresentato nell'array "signatures" è lo stesso del valore che verrebbe calcolato per gli stessi parametri nella JWS Compact Serialization, a condizione che il valore del JWS Protected Header per quel calcolo di firma/MAC (che rappresenta i valori dei parametri header protetti in integrità) corrisponda a quello utilizzato nella JWS Compact Serialization.

In sintesi, la sintassi di un JWS utilizzando la serializzazione JSON JWS generale è la seguente:

{
 "payload":"<contenuto payload>",
 "signatures":[
  {"protected":"<contenuto header protetto in integrità 1>",
   "header":<contenuto header non protetto in integrità 1>,
   "signature":"<contenuto firma 1>"},
  ...
  {"protected":"<contenuto header protetto in integrità N>",
   "header":<contenuto header non protetto in integrità N>,
   "signature":"<contenuto firma N>"}]
}

Vedere l'appendice A.6 per un esempio di JWS utilizzando la sintassi generale di serializzazione JSON JWS.

7.2.2 Flattened JWS JSON Serialization Syntax (Sintassi appiattita di serializzazione JSON JWS)

La sintassi appiattita di serializzazione JSON JWS si basa sulla sintassi generale, ma la appiattisce, ottimizzandola per il caso di una singola firma digitale/MAC. La appiattisce rimuovendo il membro "signatures" e posizionando questi membri definiti per l'uso nell'array "signatures" (i membri "protected", "header" e "signature") al livello dell'oggetto JSON di livello superiore (allo stesso livello del membro "payload").

Quando si utilizza questa sintassi, il membro "signatures" non deve (MUST NOT) essere presente. A parte questa differenza di sintassi, gli oggetti di serializzazione JSON JWS utilizzando la sintassi appiattita sono trattati esattamente nello stesso modo di quelli utilizzando la sintassi generale.

In sintesi, la sintassi di un JWS utilizzando la serializzazione JSON JWS appiattita è la seguente:

{
 "payload":"<contenuto payload>",
 "protected":"<contenuto header protetto in integrità>",
 "header":<contenuto header non protetto in integrità>,
 "signature":"<contenuto firma>"
}

Vedere l'appendice A.7 per un esempio di JWS utilizzando la sintassi appiattita di serializzazione JSON JWS.