Docs Italia beta

Documenti pubblici, digitali.

4.3. Integrità

4.3.1. [IDAS03] Integrità della payload del messaggio SOAP

4.3.1.1. Scenario

Il presente profilo estende IDAS01 o IDAS02, aggiungendo alla comunicazione tra fruitore ed erogatore a livello di messaggio:

  • Integrità della payload del messaggio.

4.3.1.2. Descrizione

Il presente profilo specializza lo standard OASIS Web Services Security X.509 Certificate Token Profile Versione 1.1.1 [4].

Si assume l’esistenza di un trust tra fruitore ed erogatore, che permette il riconoscimento da parte dell’erogatore del certificato X.509, o la CA emittente.

Il meccanismo con cui è stabilito il trust non condiziona il presente profilo.

Il fruitore inoltra un messaggio all’interfaccia di servizio dell’erogatore includendo o referenziando il certificato X.509 e la firma della payload del messaggio.

L’erogatore, ricevuto il messaggio, verifica il certificato X.509 e valida l’integrità della payload del messaggio firmato. Se la verifica e la validazione sono superate, l’erogatore consuma la richiesta e produce la relativa risposta.

4.3.1.3. Dettaglio

sequenceDiagram participant F as Fruitore participant E as Erogatore activate F F->>E: 1. Request() activate E E-->>F: 2. Reply deactivate E deactivate F

Fig. 4.8 Integrità della payload del messaggio

4.3.1.3.1. Regole di processamento

A: Richiesta

  1. Il fruitore costruisce un messaggio SOAP per il servizio.
  2. Il fruitore calcola la firma della payload del messaggio usando l’XML Signature. Il digest è firmato usando la chiave privata associata al certificato X.509 del fruitore. L’elemento <Signature> è posizionato nell’header <Security> del messaggio.
  3. Il fruitore referenzia il certificato X.509 usando in maniera alternativa, nell’header <Security>, i seguenti elementi previsti nella specifica ws-security:
    1. <wsse:BinarySecurityToken>
    2. <wsse:KeyIdentifier>
    3. <wsse:SecurityTokenReference>
  4. Il fruitore spedisce il messaggio all’interfaccia di servizio dell’erogatore.

B: Risultato

  1. L’erogatore recupera il certificato X.509 referenziato nell’header <Security>.
  2. L’erogatore verifica il certificato secondo i criteri del trust.
  3. L’erogatore valida la firma verificando l’elemento <Signature> nell’header <Security>.
  4. Se il certificato è valido anche per identificare il soggetto fruitore, l’erogatore autentica lo stesso
  5. Se le azioni da 5 a 8 hanno avuto esito positivo, il messaggio viene elaborato e viene restituito il risultato del servizio richiamato.

Note:

  • Per quanto riguarda gli algoritmi da utilizzare nell’elemento <Signature> rispettivamente <DigestMethod> , <SignatureMethod> e <CanonicalizationMethod> si fa riferimento agli algoritmi indicati alla sezione Elenco degli algoritmi.
  • Un meccanismo simile può essere utilizzato per garantire l’integrità della payload del del messaggio risposta dell’erogatore al fruitore.

.._integrita-tracciato-4:

4.3.1.3.2. Tracciato

Di seguito è riportato un tracciato del messaggio inoltrato dal fruitore all’interfaccia di servizio dell’erogatore.

I namespace utilizzati nel tracciato sono riportati di seguito:

soap="http://schemas.xmlsoap.org/soap/envelope/"
wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
ds="http://www.w3.org/2000/09/xmldsig#"
ec="http://www.w3.org/2001/10/xml-exc-c14n#"
"http://www.w3.org/2005/08/addressing"
<soap:Envelope>
  <soap:Header>
    <wsse:Security soap:mustUnderstand="1">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"    ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"    wsu:Id="X509-44680ddc-e35a-4374-bcbf-2b6dcba722d7">MIICyzCCAbOgAwIBAgIECxY+9TAhkiG9w...
      </wsse:BinarySecurityToken>
      <ds:Signature Id="SIG-f58c789e-e3d3-4ec3-9ca7-d1e9a4a90f90">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces PrefixList="soap" />
          </ds:CanonicalizationMethod>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
            <ds:Reference URI="#bd-567d101-aed1-789e-81cb-5ae1c5dbef1a"> <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces PrefixList="soap" />
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
            <ds:DigestValue>0cJNCJ1W8Agu66fGTXlPRyy0EUNUQ9OViFlm8qf8Ysw=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>AIrDa7ukDfFJD867goC+c7K3UampxpX/Nj/...</ds:SignatureValue>
        <ds:KeyInfo Id="KI-cad9ee47-dec8-4340-8fa1-74805f7e26f8">
          <wsse:SecurityTokenReference wsu:Id="STR-e193f25f-9727-4197-b7aa-25b01c9f2ba3">
           <wsse:Reference URI="#X509-44680ddc-e35a-4374-bcbf-2b6dcba722d7" ValueType="http://docs.oasis-open.org/   wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
     </soap:Header>
  <soap:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"    wsu:id="bd-567d101-aed1-789e-81cb-5ae1c5dbef1a">
    <ns2:sayHi xmlns:ns2="http://example.profile.security.modi.agid.gov.it/">
      <arg0>Hello World!</arg0>
    </ns2:sayHi>
  </soap:Body>
</soap:Envelope>

Il codice rispecchia alcune scelte implementative esemplificative in merito:

  • riferimento al security token (BinarySecurityToken)
  • algoritmi di canonizzazione (CanonicalizationMethod)
  • algoritmi di firma (SignatureMethod)
  • algoritmo per il digest (DigestMethod)

Le parti, in base alle proprie esigenze, individuano gli specifici algoritmi secondo quanto indicato alla sezione Elenco degli algoritmi nonché la modalità di inclusione o referenziazione del certificato X.509.

4.3.2. [IDAR03] Integrità della payload messaggio REST

4.3.2.1. Scenario

Il presente profilo estende IDAR01 o IDAR02, aggiungendo alla comunicazione tra fruitore ed erogatore a livello di messaggio:

  • Integrità della payload del messaggio.

Si adottano le indicazione riportate in RFC 7231.

Considereremo sempre richieste e risposte complete, con i metodi standard definiti in RFC 7231#section-4.

Questo scenario non copre quindi Range Requests RFC 7233 o HTTP method PATCH che trasmette una rappresentazione parziale.

4.3.2.2. Descrizione

Il presente profilo propone l’utilizzo di:

  • semantica HTTP RFC 7231;
  • Digest HTTP header RFC 3230 per l’integrità della rappresentazione della risorsa;
  • JSON Web Token (JWT) definita dall’ RFC 7519;
  • JSON Web Signature (JWS) definita dall’ RFC 7515.

Si assume l’esistenza di un trust tra fruitore ed erogatore, che permette il riconoscimento da parte dell’erogatore del certificato X.509, o la CA emittente.

Il meccanismo con cui è stabilito il trust non condiziona il presente profilo.

4.3.2.3. Dettaglio

sequenceDiagram participant F as Fruitore participant E as Erogatore activate F F->>F: Calcola il Digest del messaggio F->>F: Crea la struttura da firmare F->>F: Firma la struttura F->>E: Richiesta activate E E->>E: Verifica claim JWT E->>E: Verifica firma JWT E->>E: Verifica header E->>E: Verifica digest E-->>F: Risposta deactivate E deactivate F

Fig. 4.9 Integrità del messaggio

4.3.2.4. Regole di processamento

A: Richiesta

  1. Il fruitore predispone il body del messaggio (ad esempio un oggetto JSON)

  2. Il fruitore calcola il valore del Digest header dei representation data secondo le indicazioni in RFC 3230

  3. Il fruitore individua l’elenco degli HTTP Header da firmare, inclusi Digest, HTTP header Content-Type e HTTP header Content-Encoding

  4. Il fruitore crea la struttura o la stringa da firmare in modo che includa gli http header da proteggere, i riferimenti temporali di validità della firma e degli estremi della comunicazione, ovvero:

    1. il Jose Header con almeno i parameter:

      • alg con l’algoritmo di firma

      • typ uguale a JWT

      • una o più delle seguenti opzioni per referenziare il certificato X.509:

        • x5u (X.509 URL)
        • x5c (X.509 Certificate Chain)
        • x5t#256 (X.509 Certificate SHA-256 Thumbprint)
    2. i seguenti claim obbligatori:

      • i riferimenti temporali di emissione e scadenza: iat , exp. Se il flusso richiede di verificare l’istante di prima validità del token, si può usare il claim nbf.
      • il riferimento dell’erogatore in aud;
    3. i seguenti claim, secondo la logica del servizio:

      • sub: oggetto (principal see RFC 3744#section-2) dei claim contenuti nel jwt
      • iss: identificativo del mittente
      • jti: identificativo del JWT, per evitare replay attack
    4. il claim signed_headers [1] con gli header http da proteggere ed i rispettivi valori, ovvero:

      • Digest
      • Content-Type
      • Content-Encoding
  1. il fruitore firma il token adottando la JWS Compact Serialization
  2. il fruitore posiziona il JWT nell’ Authorization header
  3. Il fruitore spedisce il messaggio all’erogatore.

B: Risultato

  1. L’erogatore decodifica il JWT presente in Authorization header e valida i claim contenuti nel Jose Header, in particolare verifica:
    • il contenuto dei claim iat ed exp;
    • la corrispondenza tra se stesso e il claim aud;
    • l’univocità del claim jti
  2. L’erogatore recupera il certificato X.509 referenziato nel Jose Header
  3. L’erogatore verifica il certificato secondo i criteri del trust
  4. L’erogatore valida la firma verificando l’elemento Signature del JWT
  5. L’erogatore verifica la corrispondenza tra i valori degli header passati nel messaggio e quelli presenti nel claim signed-header
  6. L’erogatore quindi verifica la corrispondenza tra Digest ed il payload body ricevuto
  7. Se le azioni da 6 a 11 hanno avuto esito positivo, il messaggio viene elaborato e viene restituito il risultato del servizio richiamato.

Note:

  • Per gli algoritmi da utilizzare in alg e Digest si veda Elenco degli algoritmi
  • Un meccanismo simile può essere utilizzato per garantire l’integrità della risposta da parte dell’erogatore al fruitore. In questo caso si ricorda che Digest fa” riferimento al checksum del payload body della selected representation. Per una richiesta con HTTP method HEAD il server deve ritornare il checksum dell’ipotetico payload body ritornato dalla corrispondente richiesta con HTTP method GET [2].

4.3.2.4.1. Tracciato

Di seguito è riportato un tracciato del messaggio inoltrato dal fruitore all’interfaccia di servizio dell’erogatore.

Listato 4.1 Richiesta HTTP con Digest e representation metadata
POST https://api.erogatore.org/rest/service/v1/hello/echo/ HTTP/1.1
Accept: application/json
Agid-JWT-Signature: eyJhbGciOiJSUzI1NiIsInR5c.vz8...
Digest: SHA-256=cFfTOCesrWTLVzxn8fmHl4AcrUs40Lv5D275FmAZ96E=
Content-Type: application/json
Content-Encoding: identity


{"testo": "Ciao mondo"}
Listato 4.2 Porzione JWT con campi protetti dalla firma
# header
{
  "alg": "ES256",
  "typ": "JWT",
  "x5c": [
    "MIICyzCCAbOgAwIBAgIEC..."
  ]
}
# payload
{
  "aud": "https://api.erogatore.org/rest/service/v1/hello/echo"
  "iat": 1516239022,
  "nbf": 1516239022,
  "exp": 1516239024,
  "signed_headers": [
      {"digest": "SHA-256=cFfTOCesrWTLVzxn8fmHl4AcrUs40Lv5D275FmAZ96E="},
      {"content-type": "application/json"},
      {"content-encoding": "identity"},
  ],
}

Il tracciato rispecchia alcune scelte implementative esemplificative in merito:

  • include tutti gli elementi del JWT utilizzati in IDAR02
  • mette in minuscolo i nomi degli header firmati
  • utilizza il claim custom signed_headers contenente una lista di json objects per supportare la firma di più header ed eventualmente verificare il loro ordinamento

Le parti, in base alle proprie esigenze, individuano gli specifici algoritmi secondo quanto indicato alla sezione Elenco degli algoritmi nonché la modalità di inclusione o referenziazione del certificato X.509.

[1]Il presente documento ha individuato il claim «signed_headers» per contenere l’elenco degli header firmati.
[2]Per coerenza con RFC 7231#section-3.1 «In a response to a HEAD request, the representation header fields describe the representation data that would have been enclosed in the payload body if the same request had been a GET.»