Source: https://docs.italia.it/AgID/documenti-in-consultazione/lg-spid-firma-docs/it/1.1/main/05/05.2_secure-dataio.html
Timestamp: 2019-12-11 10:49:23+00:00

Document:
Regole Tecniche per la sottoscrizione elettronica di documenti ai sensi dell’art. 20 del CAD | 5.2. Sistema di trasferimento sicuro dei documenti
Torna a 5.1. SAML
5.2. Sistema di trasferimento sicuro dei documenti¶
Ogni ente federato si dota di un sistema di trasferimento dedicato ai documenti oggetto delle presenti Linee guida, costituito da uno storage dedicato, un protocollo di comunicazione sicura che garantisce un adeguato livello di confidenzialità, integrità e disponibilità, e da un sistema di gestione dei file ricevuti.
L’interfaccia applicativa fornita dal protocollo di comunicazione per il trasferimento di documenti dall’esterno è resa nota da ciascun ente federato verso tutti gli enti federati, mediante l’URL che l’ente medesimo pubblica nel metadata SPID e il cui dominio è contestualmente riportato nei campi commonName e subjectAltName del proprio certificato qualificato di sigillo elettronico, di cui al §4.5, punti 1.b e 5. Tale URL indica esplicitamente il protocollo di comunicazione sicuro, i cui dettagli sono dati in §5.2.1.
Il sistema di trasferimento è, nella sua interezza, protetto da misure di sicurezza logica, fisica e amministrativa conformi almeno alle LL.GG. sulle misure minime di sicurezza. Esso è inoltre adeguatamente protetto logicamente affinché solamente gli enti federati possano trasferire file mediante uno dei seguenti due flussi:
il sistema dell’IdP è configurato per la sola ricezione di evidenze informatiche provenienti dagli SP in modalità push (cioè con trasferimenti iniziati in upstream dal SP);
il sistema del SP è configurato per la sola ricezione di evidenze informatiche provenienti dagli IdP in modalità push (cioè con trasferimenti iniziati in upstream dall’IdP).
Il sistema di trasferimento possiede, inoltre, le seguenti caratteristiche:
SP e IdP controllano che ogni file creato presso il proprio storage soddisfi quanto prescritto nel §4.2.
L’IdP rimuove dallo storage i file ricevuti per i quali non sia pervenuta, entro un tempo limite di 10 secondi, una richiesta di autenticazione proveniente dal SP.
IdP e SP verificano l’integrità dei documenti ricevuti ricalcolandone l’impronta e confrontandola con quella contenuta, rispettivamente, nella richiesta e nella risposta di autenticazione che le accompagnano.
IdP e SP verificano l’autenticità dei QSeal della controparte e l’integrità del documento ricevuto.
5.2.1. Interfaccia applicativa¶
SP e IdP si scambiano evidenze informatiche in formato JWS, su canale HTTPS (porta 443/TCP) tramite un’API che prevede lo scambio di messaggi tramite metodo HTTP POST. Le evidenze sono formate mediate la seguente procedura:
predisposizione di una struttura JSON contenente sia il dato (cioè il documento oggetto di sottoscrizione) che i suoi metadati, di seguito elencati:
il nome del documento da inviare, predisposto come da §4.2,
l’impronta del docuento da inviare sigillato elettronicamente,
la funzione di hash impiegata al punto 1.b,
la posizione ove collocare la/le componente/i grafica/he del QSeal (§4.4),
l’eventuale obbligatorietà di ciascuna firma.
codifica del messaggio di cui al punto 1 in un pacchetto JWT;
conversione in JWS del pacchetto di cui al punto 2, mediante metodo JWS Compact Serialization (cfr. RFC 7515), utilizzando il QSeal di cui al §4.5.
Gli algoritmi crittografici utilizzati lungo l’intera procedura sopra descritta sono definiti in §6. I pacchetti JWS sono caratterizzati dalla presenza degli identificativi unici di sessione (cfr. §5).
Le strutture JSON in base alle quali sono prodotti i pacchetti JWS scambiati durante i flussi A e B sono chiamate, rispettivamente, pacchetto di andata e pacchetto di ritorno.
L’intestazione (header) comune ai pacchetti di andata e ritorno contiene i seguenti parametri obbligatori:
typ — valorizzato con la stringa “JOSE”;
alg — valorizzato con l’identificativo JWA dell’algoritmo crittografico utilizzato per la firma del pacchetto JWS, secondo quanto indicato al §6;
x5c — valorizzato con il certificato qualificato di sigillo elettronico dell’ente inviante (codificato in Base64, cfr. RFC 4648), come definito al §4.5;
crit — valorizzato con una lista di un unico elemento “x5c”, ad indicare che la convalida del certificato di cui al punto precedente è obbligatoria;
Un esempio di intestazione sopra definita è:
"typ" : "JOSE",
"alg" : "ES256",
"x5c" : "Certificato/codificato+Base64",
"crit": ["x5c"]
Il payload dei pacchetti di andata e ritorno contiene i seguenti parametri obbligatori:
jti — valorizzato con identificativo unico del pacchetto JWT;
iss — valorizzato con l’entityId: (URL con schema HTTPS) dell’ente federato inviante; coincide con il valore dell’elemento <Issuer>:
aud — valorizzato con l’entityId (URL con schema HTTPS) dell’ente federato destinatario; coincide con il valore dell’attributo Destination, rispettivamente, dell’elemento SAML:
<AuthnRequest> per il pacchetto di andata (flusso A), ovvero
<Response> per il pacchetto di ritorno (flusso B).
iat — valorizzato con l’orario in cui il messaggio è generato e inviato (rispetto al fuso orario italiano), codificato come campo di tipo NumericDate;
sessionID — valorizzato con il session ID, così come dichiarato nella richiesta di autenticazione per firma SPID – coincide con il valore che, nei pacchetti di andata e di ritorno, si trova rispettivamente nell’attributo:
ID dell’elemento SAML <AuthnRequest> per il flusso A (andata), ovvero
InResponseTo dell’elemento SAML <Response> per il flusso B (ritorno).
filename — valorizzato con il nome del file del documento inviato; coincide con il valore dell’elemento <Filename> come specificato nel §4.2;
cty — valorizzato con la tipologia MIME del documento di cui al punto precedente (quindi come “pdf”, come da normativa RFC 7515);
payload — valorizzato con l’evidenza del documento informatico da trasferire, codificato in Base64 (cfr. RFC 6848);
hash — valorizzato con una struttura JSON così costituita:
method — valorizzato con la codifica W3C della funzione di hash utilizzata per il calcolo delle impronte dei documenti e coincidente con il valore dell’emento SAML <DigestMethod>,
digest — valorizzato con l’impronta del documento trasferito e coincidente con il valore dell’elemento SAML <DigestValue>.
Nel pacchetto di andata:
signatures — valorizzato con un array JSON contenente tanti elementi quante sono le sottoscrizioni richieste; ciascun elemento dell’array è una struttura JSON contenente:
id — valorizzato con un identificativo univoco della firma nell’ambito del processo di firma, cioè una stringa alfanumerica di massimo 40 caratteri;
pag — valorizzato con il numero della pagina del documento ove è richiesto che l’IdP apponga la componente grafica di cui al §4.4;
pos — contenente un array JSON con quattro elementi di tipo number – llx, lly, urx e ury - valorizzati rispettivamente con l’ascissa e l’ordinata del vertice inferiore sinistro, l’ascissa e l’ordinata del vertice superiore destro di un’area rettangolare definita al §4.4, per il posizionamento della componente grafica del QSeal all’interno della pagina stessa, secondo quanto previsto tecnicamente per la rappresentazione di oggetti PDF Rectangles, §4.40 dello standard ISO/IEC 32000-1;
ref —booleano per indicare se la firma è facoltativa (false) ovvero obbligatoria (true) per il SP richiedente. Se il firmatario non accetta di apporre anche solo una firma obbligatoria, l’intero processo di sottoscrizione termina senza successo (cfr. §7)e l’IdP non restituisce il documento al SP, informandolo della mancanza di volontà del firmatario.
Nel pacchetto di ritorno:
sub — valorizzato con la stringa %firmatario% identificativa del firmatario, come definita nel §4.4;
signatures — valorizzato con un array JSON contenente tanti elementi quante sono le firme richieste nel pacchetto di andata; ciascun elemento dell’array è una struttura JSON contenente:
id — l’identificativo univoco della firma contenuto nel pacchetto di andata;
signed — il booleano che conferma l’apposizione (true) o meno (false) della firma.
I pacchetti sono validi se conformi al presente provvedimento e a eventuali successive indicazioni dell’Agenzia.
Seguono un esempio del pacchetto di andata e del relativo pacchetto di ritorno per la sottoscrizione di un documento per il quale sono richieste due firme: la prima, a pagina 3, obbligatoria; la seconda, a pagina 7, facoltativa. Nella risposta, l’IdP informa il SP che l’utente ha apposto solo la firma obbligatoria.
Esempio di pacchetto di andata JSON:
"jti" : "uuid1",
"iss" : "https://entityId-SP-inviante",
"aud" : "https://entityId-IdP-ricevente",
"iat" : 1563235200,
"sessionID": "sig-sessionID",
"filename" : "AgID_20190321T083410.tmp.pdf",
"cty" : "pdf",
"method" : "schema://funzione_hash",
"value" : "ImprontaDocumento1"
"id"  : "sig1",
"pag" : 3,
"llx":89.9446,
"lly":719.976,
"urx":239.978,
"ury":751.299
"req" : true
"id"  : "sig2",
"pag" : 7,
"llx":240.734,
"lly":686.297,
"urx":390.768,
"ury":718.421
"req" : false
"payload" : "BlobDocumento1 + [...] + codificatoBase64"
Esempio di pacchetto di ritorno JSON:
"jti" : "uuid2",
"iss" : "https://entityId-IdP-inviante",
"aud" : "https://entityId-SP-ricevente",
"sub" : "Mario Rossi/CF:IT-RSSMR064T30H501H",
"iat" : 1563235220,
"filename" : "AgID_20190321T083410.pdf",
"method" : "http://funzione_hash",
"value" : "ImprontaDocumento2"
"signed" : true
"signed" : false
"payload" : "BlobDocumento2 + [...] + codificatoBase64"

References: §4
 §5
 §4
 §4
 §4
 §6
 §5
 §6
 §4
 §4
 §4
 §4
 §4
 §7
 §4