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:

1. predisposizione di una struttura JSON contenente sia il dato (cioè il documento oggetto di sottoscrizione) che i suoi metadati, di seguito elencati:

   1. il nome del documento da inviare, predisposto come da §4.2,
   2. l’impronta del docuento da inviare sigillato elettronicamente,
   3. la funzione di hash impiegata al punto 1.b,
   4. la posizione ove collocare la/le componente/i grafica/he del QSeal (§4.4),
   5. l’eventuale obbligatorietà di ciascuna firma.

2. codifica del messaggio di cui al punto 1 in un pacchetto JWT;

3. 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",
    "digest" : {
        "method" : "schema://funzione_hash",
        "value" : "ImprontaDocumento1"
    },
    "signatures" : [
        {
            "id"  : "sig1",
            "pag" : 3,
            "pos" : {
                "llx":89.9446,
                "lly":719.976,
                "urx":239.978,
                "ury":751.299
            },
            "req" : true
        },
        {
            "id"  : "sig2",
            "pag" : 7,
            "pos" : {
                "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,
    "sessionID": "sig-sessionID",
    "filename" : "AgID_20190321T083410.pdf",
    "cty" : "pdf",
    "digest" : {
        "method" : "http://funzione_hash",
        "value" : "ImprontaDocumento2"
    },
    "ref" : [
        {
            "id"  : "sig1",
            "signed" : true
        },
        {
            "id"  : "sig2",
            "signed" : false
        }
    ],
    "payload" : "BlobDocumento2 + [...] + codificatoBase64"
}