13.1. Endpoint del Fornitore di Wallet¶

Il Fornitore di Wallet, responsabile della fornitura di una Soluzione Wallet, DEVE esporre gli endpoint per supportare l'instaurazione della fiducia e le funzionalità essenziali dell'Istanza di Wallet. Questi includono l'endpoint di Federazione /.well-known/openid-federation che DEVE aderire alla specifica OpenID Federation 1.0 per stabilire in modo affidabile la fiducia con il Fornitore di Wallet, nonché endpoint per la registrazione dell'Istanza di Wallet, la generazione di nonce (richiesta per la registrazione), l'emissione di attestati e la revoca. A parte l'endpoint di Federazione, i dettagli di implementazione degli altri sono lasciati alla discrezione del Fornitore di Wallet.

Nota

I test relativi all'uso degli endpoint del Wallet Provider sono definiti in Matrice di Test per Wallet Provider, in particolare in Casi di Test per Backend del Fornitore del Wallet, Casi di Test per Istanza del Wallet e Casi di Test Opzionali per Istanza del Wallet.

13.1.1. Endpoint di Federazione¶

L'endpoint /.well-known/openid-federation serve come meccanismo di discovery per l'instaurazione della fiducia recuperando la Entity Configuration del Fornitore di Wallet.

Vedere la Sezione Entity Configuration del Fornitore di Wallet per i dettagli tecnici (WP_001–004).

13.1.2. Endpoint Nonce della Soluzione Wallet¶

Questo è un endpoint API RESTful che consente all'Istanza di Wallet di richiedere un nonce crittografico dal Fornitore di Wallet. Il nonce serve come sfida imprevedibile, monouso per garantire la freschezza e prevenire attacchi di replay.

Vedere Richiesta di Nonce dell'Applicazione Mobile e Risposta di Nonce dell'Applicazione Mobile per i dettagli sulla Richiesta di Nonce e sulla Risposta di Nonce (WP_131).

13.1.3. Endpoint di Gestione dell'Istanza di Wallet¶

Questo è un endpoint API RESTful fornito dal Fornitore di Wallet che consente la gestione dell'Istanza di Wallet, inclusa la registrazione, il recupero dello stato, la revoca su richiesta (ad esempio, da parte dell'Utente) e l'eliminazione. Le seguenti sezioni descrivono le richieste di registrazione, recupero dello stato e revoca, insieme alle relative risposte, gestite da questo endpoint, che sono necessarie per le funzionalità di base dell'Funzionalità dell'Istanza del Wallet.

13.1.3.1. Richiesta di Registrazione dell'Istanza di Wallet¶

Per registrare un'Istanza di Wallet, la richiesta al Fornitore di Wallet DEVE utilizzare il metodo HTTP POST con Content-Type impostato su application/json. Il corpo della richiesta DEVE contenere i claim descritti in Richiesta di Inizializzazione dell'Istanza dell'Applicazione Mobile (WP_131–134).

13.1.3.2. Risposta alla Registrazione dell'Istanza di Wallet¶

Se una Richiesta di Registrazione dell'Istanza di Wallet viene convalidata con successo, il Fornitore di Wallet fornisce una Risposta HTTP con codice di stato 204 (No Content). Per i dettagli vedere Risposta di Inizializzazione dell'Istanza dell'Applicazione Mobile (WP_135–137).

13.1.3.3. Richiesta di Recupero dell'Istanza di Wallet¶

Per recuperare tutte le Istanze di Wallet associate a un Utente, una richiesta DEVE essere inviata utilizzando il metodo HTTP GET al Fornitore di Wallet (WP_145).

Nota

Per recuperare una specifica Istanza di Wallet, la richiesta DEVE includere l'ID dell'Istanza di Wallet come parametro di percorso.

13.1.3.4. Risposta al Recupero dell'Istanza di Wallet¶

Se una Richiesta di Recupero dell'Istanza di Wallet viene elaborata con successo, il Fornitore di Wallet DEVE restituire una Risposta HTTP con un codice di stato 200 (OK). Il corpo della risposta DEVE essere in formato JSON e includere le informazioni rilevanti dell'Istanza di Wallet, come il suo ID univoco, lo stato e la data di emissione. Quando si recuperano tutte le Istanze di Wallet, la risposta DEVE restituire un array contenente i dettagli di tutte le istanze associate (WP_146).

Se si verificano errori durante il processo di recupero, DEVE essere restituita una risposta di errore. Fare riferimento a Gestione degli Errori per la Gestione dell'Istanza di Wallet per i dettagli sui codici di errore e le descrizioni.

Di seguito è riportato un esempio non normativo di una risposta di errore:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "forbidden",
  "error_description": "User is not authorized to retrieve Wallet Instances."
}

13.1.3.5. Richiesta di Revoca dell'Istanza di Wallet¶

Per revocare un'Istanza di Wallet attiva, una richiesta di revoca DEVE essere inviata utilizzando il metodo HTTP PATCH con Content-Type impostato su application/json. Il corpo della richiesta DEVE contenere un parametro status impostato su REVOKED (WP_147).

Nota

Mentre PATCH è il metodo consigliato, la richiesta di revoca PUÒ anche essere inviata utilizzando il metodo POST, a seconda delle preferenze di implementazione.

13.1.3.6. Risposta alla Revoca dell'Istanza di Wallet¶

Se una Richiesta di Revoca dell'Istanza di Wallet viene elaborata con successo, il Fornitore di Wallet fornisce una Risposta HTTP con un codice di stato 204 (No Content) come specificato in WP_148.

Se si verificano errori durante la Revoca dell'Istanza di Wallet, DEVE essere restituita una risposta di errore. Fare riferimento a Gestione degli Errori per la Gestione dell'Istanza di Wallet per i dettagli sui codici di errore e le descrizioni (WP_035–039, WP_043–044).

Di seguito è riportato un esempio non normativo di una risposta di errore:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error": "bad_request",
  "error_description": "The request is missing status parameter."
}

13.1.3.7. Gestione degli Errori per la Gestione dell'Istanza di Wallet¶

Per garantire robustezza e sicurezza, il Fornitore di Wallet DEVE gestire gli errori in modo coerente in tutte le richieste di Gestione dell'Istanza di Wallet, incluse Registrazione, Recupero e Revoca (WP_035–044, e WP_150–155).

In caso di errore, il Fornitore di Wallet DEVE restituire una risposta di errore come definito in RFC 7231, con ulteriori dettagli disponibili in RFC 7807. La risposta DEVE utilizzare il Content-Type impostato su application/json e DEVE includere i seguenti parametri:

error. Il codice di errore.
error_description. Testo in forma leggibile dall'uomo che fornisce ulteriori dettagli per chiarire la natura dell'errore riscontrato.

Le seguenti sezioni classificano gli errori in errori comuni, che si applicano a tutte le richieste, ed errori specifici della richiesta, che sono rilevanti per operazioni particolari.

13.1.3.8. Risposte di Errore Comuni¶

I seguenti errori si applicano a tutte le operazioni di Gestione dell'Istanza di Wallet (Registrazione, Recupero e Revoca) e DEVONO essere supportati per la risposta di errore, se non diversamente specificato (WP_035–039):

Codice di Stato HTTP	Codice di Errore	Descrizione
`400 Bad Request`	`bad_request`	La richiesta è malformata, mancano parametri richiesti o include parametri non validi e sconosciuti.
`422 Unprocessable Content` [OPZIONALE]	`validation_error`	La richiesta non aderisce al formato richiesto.
`500 Internal Server Error`	`server_error`	Si è verificato un errore interno durante l'elaborazione della richiesta.
`503 Service Unavailable`	`temporarily_unavailable`	Il servizio non è disponibile. Si prega di riprovare più tardi.

13.1.3.9. Risposte di Errore Specifiche della Richiesta¶

Gli errori in Risposta di Errore di Inizializzazione dell'Istanza dell'Applicazione Mobile DEVONO essere supportati per le risposte di errore relative alla Registrazione dell'Istanza di Wallet.

I seguenti errori DEVONO essere supportati per le risposte di errore relative al Recupero dell'Istanza di Wallet (WP_041–042):

Codice di Stato HTTP	Codice di Errore	Descrizione
`403 Forbidden`	`forbidden`	L'Utente non ha il permesso di recuperare questa Istanza di Wallet.
`401 Unauthorized`	`unauthorized`	La richiesta manca di Credenziali di autenticazione valide.

I seguenti errori DEVONO essere supportati per le risposte di errore relative alla Revoca dell'Istanza di Wallet (WP_043–044):

Codice di Stato HTTP	Codice di Errore	Descrizione
`403 Forbidden`	`invalid_request`	L'Utente non ha il permesso di revocare questa Istanza di Wallet.
`401 Unauthorized`	`unauthorized`	La richiesta non può essere autenticata o autorizzata.

13.1.4. Endpoint di Emissione della Wallet App e Wallet Unit Attestation¶

Questo è un endpoint API RESTful fornito dal Fornitore di Wallet che consente all'Istanza di Wallet di ottenere una Wallet App Attestation e Wallet Unit Attestation, inviando una Richiesta di Emissione della Wallet App e Wallet Unit Attestation.

13.1.4.1. Richiesta di Emissione della Wallet App e Wallet Unit Attestation¶

La richiesta di emissione della Wallet App e la Wallet Unit Attestation utilizza il metodo HTTP POST con il Content-Type impostato su application/json (WP_026 e WP_140–142).

L'intestazione typ del JWT della richiesta di emissione della Wallet App e Wallet Unit Attestation assume il valore wp-war-wua+jwt.

Il body della richiesta di emissione della Wallet App e Wallet Unit Attestation contiene un parametro assertion il cui valore è un JWT firmato che include tutti i parametri di intestazione e le claim descritti di seguito.

Di seguito è riportato un esempio non normativo di una richiesta di emissione della Wallet App e Wallet Unit Attestation.

POST /wallet-attestation HTTP/1.1
Host: application-provider.example.org
Content-Type: application/json

{
  "assertion": "eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlc..."
}

In particolare, il JWT della richiesta di emissione della Wallet App e Wallet Unit Attestation include i seguenti parametri di intestazione HTTP:

Parametro	Descrizione	Riferimento
alg	Identificatore dell'algoritmo di firma digitale, come definito nel registro IANA "JSON Web Signature and Encryption Algorithms". DEVE essere uno degli algoritmi supportati elencati in algorithms:cryptographic algorithms e non DEVE essere impostato su `none` né su alcun identificatore di algoritmo simmetrico (MAC).	[RFC 7516#section-4.1.1]
kid	thumbprint della JWK dell'Istanza del Wallet contenuta nella dichiarazione `cnf`.	[RFC 7638#section_3]
typ	Il tipo del JWT, che DEVE essere impostato su `wp-war-wua+jwt`.

Il JWT della richiesta include le seguenti claim nel body:

Claim	Descrizione	Riferimento
iss	L'identificatore del Fornitore di Wallet concatenato con l'impronta digitale (thumbprint) della JWK nella dichiarazione `cnf`.	[RFC 9126], [RFC 7519].
aud	L'identificatore del Fornitore di Wallet.	[RFC 9126], [RFC 7519].
exp	UNIX timestamp che rappresenta il tempo di scadenza del JWT.	[RFC 9126], [RFC 7519].
iat	UNIX timestamp che rappresenta il tempo di emissione del JWT.	[RFC 9126], [RFC 7519].
nonce	Il `nonce` ottenuto dal Nonce Endpoint.
hardware_signature	la firma di `client_data_hash_waa` e `client_data_hash_wua` ottenuta utilizzando la Chiave Crittografica Hardware, codificata nel formato `base64url`.
integrity_assertion	L'Integrity Assertion per la Wallet App Attestation ottenuta dalle Device Integrity Service APIs con il binding di `client_data_hash_waa`.
attested_key	La key Attestation ottenuta per la chiave di credenziale proveniente dalle Key Attestation APIs con il binding di `client_data_hash_wua` oppure dalle Device Integrity Service APIs con il binding di `client_data_hash_wua`.
hardware_key_tag	Il valore del Tag della Chiave Crittografica Hardware.
cnf	Oggetto JSON contenente la parte pubblica di una coppia di chiavi asimmetriche posseduta dall'istanza del Wallet.	RFC 7800.

Di seguito è riportato un esempio non normativo dell'intestazione e del payload del JWT della Wallet App e Wallet Unit Attestation Request.

{
  "alg": "ES256",
  "kid": "OnsiandrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiL",
  "typ": "wp-war-wua+jwt"
}

{
  "iss": "https://wallet-provider.example.org/instance/OnsiandrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiL",
  "sub": "https://wallet-provider.example.org/",
  "nonce": "f3b29a81-45c7-4d12-b8b5-e1f6c9327aef",
  "hardware_signature": "KoZIhvcNAQcCoIAwgAIB...",
  "integrity_assertion": "o2NmbXRvYXBwbGUtYXBwYXNzZXJ0aW9uLXBheWxvYWQtYXBw...",
  "attested_key": "o2CFbXRvYXBwbGUtYXBwYXNzTYU0aW9uLXBheWxvYWQtZvRM..."
  "hardware_key_tag": "QW12DylRTmF89iGkpydNDWW7m8bVpa2Fn9KBeXGYtfX"
  "cnf": {
    "jwk": {
      "crv": "P-256",
      "kty": "EC",
      "x": "8FJtI-yr3pjyRKGMnz4WmdnQD_uJSq4R95Nj98b44",
      "y": "MKZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg"
    }
  }
}

13.1.4.2. Risposta all'Emissione della Wallet App e Wallet Unit Attestation¶

Se la Richiesta di Emissione della Wallet App e Wallet Unit Attestation viene convalidata con successo, il Fornitore di Wallet restituisce una risposta HTTP con un codice di stato 200 OK e Content-Type application/json. L'Oggetto JSON restituito DEVE possedere il parametro wallet_attestations che include gli elementi wallet_app_attestations e wallet_unit_attestation (vedi Emissione della Wallet App e Wallet Unit Attestation). wallet_app_attestations è un array che contiene le Wallet App Attestation nei formati JWT, SD-JWT e mdoc, mentre wallet_unit_attestation è un singolo oggetto che contiene la Wallet Unit Attestation. Entrambe le attestazioni sono firmate dal Fornitore di Wallet (WP_027–029 e WP_143–144). La Wallet App Attestation in formato JWT deve essere utilizzato per la fase di Emissione di un Attestato Elettronico, come OAuth Client Attestation, e sarà inviato al Fornitore di Attestati Elettronici come discusso in Emissione di Attestati Elettronici. La Wallet App Attestation in formato SD-JWT e mdoc sarà invece utilizzato durante la presentazione rispettivamente nei flussi remoto (Flusso Remoto) e di prossimità (Flusso di Prossimità). La Wallet Unit Attestation in formato JWT deve essere utilizzata nella fase di Emissione di un Attestato Elettronico, come intestazione JOSE key_attestation nel JWT di tipo proof, e verrà inviata al Fornitore di Attestati Elettronici come discusso in Emissione di Attestati Elettronici.

L'Oggetto JSON restituito nella risposta ha il seguente claim:

Parametro

Descrizione

Riferimento

wallet_attestations

OBBLIGATORIO. Un array JSON contenente una o più Wallet App Attestation e una Wallet Unit Attestation negli elementi wallet_app_attestations e wallet_unit_attestation, rispettivamente. Deve contenere le seguenti dichiarazioni obbligatorie:

wallet_app_attestation: un array JSON contenente una o più Wallet App Attestation emesse. Gli elementi dell'array DEVONO essere oggetti JSON. Devono essere presenti almeno due oggetti JSON.
wallet_unit_attestation: un oggetto JSON contenente la Wallet Unit Attestation emessa.

Questa specifica.

Ogni oggetto JSON contenuto nell'array wallet_app_attestations DEVE avere la seguente forma:

Parametro

Descrizione

Riferimento

format

Una stringa che identifica il Modello di Dati utilizzato per creare e rappresentare la Wallet App Attestation. DEVE essere jwt, dc+sd-jwt o mso_mdoc a seconda del formato della Credenziale.

Questa specifica.

wallet_app_attestation

Una stringa che rappresenta la Wallet App Attestation. Se

la Wallet App Attestation è in formato JWT, allora il valore del claim DEVE essere una stringa che è un JWT.
la Wallet App Attestation è in formato SD-JWT, allora il valore del claim DEVE essere una stringa che è un SD-JWT VC.
la Wallet App Attestation è in formato mdoc, allora il valore del claim è la rappresentazione codificata in base64url della struttura IssuerSigned codificata in CBOR, come definito in [ISO.18013-5]. Questa struttura DEVE contenere tutti i Namespace e gli IssuerSignedItems inclusi nel MobileSecurityObject.

Questa specifica.

Nel caso del parametro wallet_unit_attestation, il suo valore è una stringa che rappresenta la Wallet Unit Attestation in formato JWT.

Se si verifica un errore durante il processo, viene restituita una risposta di errore. La risposta utilizza application/json come Content-Type e include i seguenti parametri:

error: il codice di errore.

error_description: testo in formato leggibile dall'uomo che fornisce ulteriori dettagli per chiarire la natura dell'errore riscontrato (WP_035).

Di seguito è riportato un esempio non normativo di una Wallet App e Wallet Unit Attestation Issuance Response.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "invalid_request",
  "error_description": "The provided challenge is invalid, expired, or already used."
}

La seguente tabella elenca i codici di stato HTTP e i relativi codici di errore supportati per la risposta di errore, salvo diversa indicazione (WP_036–039 e WP_150–155):

HTTP Status Code	Error Code	Descrizione
`400 Bad Request`	`bad_request`	La richiesta è malformata, mancano parametri obbligatori (ad esempio parametri di intestazione, Integrity Assertion o `attested_key`), oppure include parametri non validi o sconosciuti.
`403 Forbidden`	`invalid_request`	L'istanza del Wallet è stata revocata.
`403 Forbidden`	`integrity_check_error`	Il dispositivo non soddisfa i requisiti minimi di sicurezza del Fornitore di Wallet.
`403 Forbidden`	`invalid_request`	La firma della Wallet App e della Wallet Unit Attestation Request non è valida oppure non corrisponde alla chiave pubblica (JWK) associata.
`403 Forbidden`	`invalid_request`	La validazione della Integrity Assertion o della Key Attestation (`attested_key`) non è riuscita; la Integrity Assertion o la Key Attestation (`attested_key`) è stata manomessa o firmata in modo non corretto.
`403 Forbidden`	`invalid_request`	Il `nonce` fornito non è valido, è scaduto oppure è già stato utilizzato.
`403 Forbidden`	`invalid_request`	La Proof of Possession (`hardware_signature`) non è valida.
`403 Forbidden`	`invalid_request`	Il parametro `iss` non corrisponde all'identificatore URL previsto dal Fornitore di Wallet.
`404 Not Found`	`not_found`	L'istanza del Wallet non è stata trovata.
`422 Unprocessable Content` [OPTIONAL]	`validation_error`	La richiesta non rispetta il formato richiesto.
`500 Internal Server Error`	`server_error`	Si è verificato un errore interno del server durante l'elaborazione della richiesta.
`503 Service Unavailable`	`temporarily_unavailable`	Il servizio non è disponibile. Si prega di riprovare più tardi.

13.1.4.3. JWT della Wallet App Attestation¶

L'header JOSE del JWT della Wallet App Attestation contiene i seguenti parametri:

Header JOSE	Descrizione	Riferimento
alg	OBBLIGATORIO. Un identificatore di algoritmo di firma digitale come da registro IANA "JSON Web Signature and Encryption Algorithms". DEVE essere uno degli algoritmi supportati elencati nella Sezione Algoritmi Crittografici e NON DEVE essere impostato su `none` o qualsiasi identificatore di algoritmo simmetrico (MAC).	RFC 7516#section-4.1.1.
kid	OBBLIGATORIO. Identificatore univoco della chiave pubblica associata alla chiave privata che il Fornitore di Wallet ha utilizzato per firmare la Wallet App Attestation.	RFC 7638#section_3.
typ	OBBLIGATORIO. DEVE essere impostato su `oauth-client-attestation+jwt`	OPENID4VC-HAIP.
trust_chain	OBBLIGATORIO. Sequenza di Entity Statement che compone la Catena di Fiducia relativa al Fornitore di Wallet.	OID-FED Sezione 4.3 Trust Chain Header Parameter.
x5c	OBBLIGATORIO. Contiene il certificato di chiave pubblica X.509 o la catena di certificati (RFC 5280) corrispondente alla chiave utilizzata per firmare digitalmente il JWT.	RFC 7515 Sezione 4.1.8 e SD-JWT-VC Sezione 3.5.

Il corpo del JWT della Wallet App Attestation contiene i seguenti claim:

Claim	Descrizione	Riferimento
iss	OBBLIGATORIO. Identificatore del Fornitore di Wallet.	RFC 9126 e RFC 7519.
exp	OBBLIGATORIO. Timestamp UNIX con il tempo di scadenza del JWT.	RFC 9126 e RFC 7519.
iat	OBBLIGATORIO. Timestamp UNIX con il tempo di emissione del JWT.	RFC 9126 e RFC 7519.
cnf	OBBLIGATORIO. Oggetto JSON, contenente la parte pubblica di una coppia di chiavi asimmetriche posseduta dall'Istanza di Wallet.	RFC 7800.
wallet_link	OPZIONALE. Stringa contenente un URL per ottenere ulteriori informazioni sul Wallet e sul Fornitore di Wallet.	OpenID4VCI.
wallet_name	OPZIONALE. Stringa contenente un nome leggibile dall'uomo del Wallet.	OpenID4VCI.
sub	OBBLIGATORIO. Identificatore dell'Istanza di Wallet che è l'impronta digitale della JWK della Wallet App Attestation.	RFC 9126 e RFC 7519.

Di seguito è riportato un esempio non normativo dell'header e del payload della Wallet App Attestation JWT senza codifica e firma applicata:

  {
    "alg": "ES256",
    "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY",
    "trust_chain": [
      "eyJhbGciOiJFUz...6S0A",
      "eyJhbGciOiJFUz...jJLA",
      "eyJhbGciOiJFUz...H9gw"
    ],
    "x5c": [
      "MIIDqjCCApKgAwIBAgIESLNEvDA ...",
      "MIICwzCCAasCCQCKVy9eKjvi+jA ...",
      "MIIDTDCCAjSgAwIBAgIJAPlnQYH..."
    ],
    "typ": "oauth-client-attestation+jwt"
  }

  {
    "iss": "https://wallet-provider.example.org",
    "cnf":
    {
      "jwk":
      {
        "crv": "P-256",
        "kty": "EC",
        "x": "4HNptI-xr2pjyRJKGMnz4WmdnQD_uJSq4R95Nj98b44",
        "y": "LIZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg"
      }
    },
    "iat": 1687281195,
    "exp": 1687288395,
    "sub": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
    "wallet_name": "Wallet_v1",
    "wallet_link": "https://example.com/wallet/detail_info.html"
  }

13.1.4.4. SD-JWT della Wallet App Attestation¶

L'header JOSE dell'SD-JWT della Wallet App Attestation DEVE contenere i seguenti parametri:

Header JOSE	Descrizione	Riferimento
alg	OBBLIGATORIO. Un identificatore di algoritmo di firma digitale come da registro IANA "JSON Web Signature and Encryption Algorithms". DEVE essere uno degli algoritmi supportati elencati in Algoritmi Crittografici e NON DEVE essere impostato su `none` o qualsiasi identificatore di algoritmo simmetrico (MAC).	RFC 7516#section-4.1.1.
kid	OBBLIGATORIO. Identificatore univoco della chiave pubblica associata alla chiave privata che il Fornitore di Wallet ha utilizzato per firmare la Wallet App Attestation.	RFC 7638#section_3.
typ	OBBLIGATORIO. DEVE essere impostato su `dc+sd-jwt`	OPENID4VC-HAIP.
trust_chain	OBBLIGATORIO. Sequenza di Entity Statement che compone la Catena di Fiducia relativa al Fornitore di Wallet.	OID-FED Sezione 4.3 Trust Chain Header Parameter.
x5c	OBBLIGATORIO. Contiene il certificato di chiave pubblica X.509 o la catena di certificati (RFC 5280) corrispondente alla chiave utilizzata per firmare digitalmente il JWT.	RFC 7515 Sezione 4.1.8 e SD-JWT-VC Sezione 3.5.

Il corpo dell'SD-JWT della Wallet App Attestation contiene i seguenti claim:

Claim	Descrizione	Riferimento
iss	OBBLIGATORIO. Identificatore del Fornitore di Wallet.	RFC 9126 e RFC 7519.
exp	OBBLIGATORIO. Timestamp UNIX con il tempo di scadenza del JWT.	RFC 9126 e RFC 7519.
iat	OBBLIGATORIO. Timestamp UNIX con il tempo di emissione del JWT.	RFC 9126 e RFC 7519.
cnf	OBBLIGATORIO. Oggetto JSON, contenente la parte pubblica di una coppia di chiavi asimmetriche posseduta dall'Istanza di Wallet.	RFC 7800.
vct	OBBLIGATORIO. Il valore del tipo di Credenziale DEVE essere una Stringa URL HTTPS e DEVE essere impostato come `urn:eudi:wallet_app_attestation:it:{version}`; si veda Struttura del Catalogo degli Attestati Elettronici per dettagli.	Sezione 3.2.2.2 SD-JWT-VC.
_sd	OBBLIGATORIO. Array JSON contenente un elenco di tutti i digest delle divulgazioni.	SD-JWT.
sd_alg	OBBLIGATORIO. Stringa contenente l'algoritmo di hash utilizzato dal Fornitore di Wallet per generare i digest delle divulgazioni.	SD-JWT.
sub	OPZIONALE. Identificatore dell'Istanza di Wallet che può essere l'impronta del JWK della Wallet App Attestation.	RFC 9126 e RFC 7519.

Le seguenti divulgazioni POSSONO essere presenti:

Divulgazione	Descrizione	Riferimento
wallet_link	OPZIONALE. Stringa contenente un URL per ottenere ulteriori informazioni sul Wallet e sul Fornitore di Wallet.	OpenID4VCI.
wallet_name	OPZIONALE. Stringa contenente un nome leggibile dall'uomo del Wallet.	OpenID4VCI.

Nota

Indipendentemente dal fatto che wallet_link e wallet_name siano divulgabili selettivamente, questi valori NON DEVONO essere mostrati all'Utente, in quanto non sono attributi dell'Utente.

Di seguito sono descritti esempi di valori per le divulgazioni:

Claim wallet_link:

Hash SHA-256: cD9/XC7t7QVHvmSiE1dGW0WYr0jcqm8n0GA6MGitaik=
Divulgazione: WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgIndhbGxldF9saW5rIiwgImh0dHBzOi8vZXhhbXBsZS5jb20vd2FsbGV0L2RldGFpbF9pbmZvLmh0bWwiXQ==
Contenuti: ["2GLC42sKQveCfGfryNRN9w", "wallet_link", "https://example.com/wallet/detail_info.html"]

Claim wallet_name:

Hash SHA-256: iQQhzf6+saYCzHH92N1QyJisKsZbApbTrJ1amHgLoOk=
Divulgazione:n``WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgIndhbGxldF9uYW1lIiwgIldhbGxldF9Ib2JiaXRvbl92MSJd``
Contenuti: ["2GLC42sKQveCfGfryNRN9w", "wallet_name", "Wallet_v1"]

Di seguito è riportato un esempio non normativo dell'header e del payload della Wallet App Attestation SD-JWT senza codifica e firma applicata:

  {
    "alg": "ES256",
    "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY",
    "typ": "dc+sd-jwt",
    "x5c": [
      "MIIDqjCCApKgAwIBAgIESLNEvDA ...",
      "MIICwzCCAasCCQCKVy9eKjvi+jA ...",
      "MIIDTDCCAjSgAwIBAgIJAPlnQYH..."
    ]
  }

  {
    "iss": "https://wallet-provider.example.org",
    "cnf": {
      "jwk":
      {
        "crv": "P-256",
        "kty": "EC",
        "x": "4HNptI-xr2pjyRJKGMnz4WmdnQD_uJSq4R95Nj98b44",
        "y": "LIZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg"
      }
    },
    "_sd": ["cD9/XC7t7QVHvmSiE1dGW0WYr0jcqm8n0GA6MGitaik=", "iQQhzf6+saYCzHH92N1QyJisKsZbApbTrJ1amHgLoOk="],
    "_sd_alg": "sha-256",
    "iat": 1687281195,
    "exp": 1687288395,
    "vct": "urn:eudi:wallet_app_attestation:it:1",
    "sub": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c"
  }

13.1.4.5. Wallet App Attestation mdoc¶

Questa descrizione specializza ulteriormente le linee guida fornite in ref:pid-eaa-data-model:MDOC-CBOR Credential Format per rappresentare la Wallet App Attestation in formato mdoc. Quest'ultimo DEVE avere il docType alorizzato come {Trust Anchor reverse domain}.{wallet_app_attestation}.{versione}; si veda Struttura del Catalogo degli Attestati Elettronici per dettagli.

I nameSpaces per gli Oggetti Json del nameSpace domestico sono definiti come segue:

Tabella 13.1 it.wallet.trust-registry.WalletAttestation.1¶
elementIdentifier	Descrizione	Riferimento
sub	OPZIONALE. Identificatore dell'Istanza di Wallet che è l'impronta digitale della Chiave COSE della Wallet App Attestation.	RFC 9126 e RFC 7519.
wallet_link	OPZIONALE. Stringa JSON contenente un URL per ottenere ulteriori informazioni sul Wallet e sul Fornitore di Wallet.	OpenID4VCI.
wallet_name	OPZIONALE. Stringa JSON, DEVE essere l'Identificatore del Fornitore di Wallet.	OpenID4VCI.

Di seguito è riportato un esempio non normativo della Wallet App Attestation mdoc in notazione diagnostica CBOR:

  {
    "nameSpaces": {
      "it.wallet.trust-registry.wallet_attestation": [
        24(<<
          {
            "digestID": 0,
            "elementIdentifier": "sub",
            "elementValue": "ec#1",
            "random": h'0117942b3ecdad65f226a668466fa175b72563a392598ad18fa6d359ea9b1b2d'
          }
        >>),
        24(<<
          {
            "digestID": 1,
            "elementIdentifier": "wallet_link",
            "elementValue": "https://wallet-provider.example.org",
            "random": h'dc9d032a64866e33d06f48a882989b5747da3638f0d216a2275191ed3395fdec'
          }
        >>),
        24(<<
          {
            "digestID": 2,
            "elementIdentifier": "wallet_name",
            "elementValue": "Wallet name",
            "random": h'd665c50c4364c7cbf4ab9461b9bbb228f37ad278b9fb61283550951624d4d9ae'
          }
        >>)
      ]
    },
    "issuerAuth": [
      << {1: -7} >>,
      {
        33: h'825903B0...'
      },
      <<
        24(<<
          {
            "version": "1.0",
            "digestAlgorithm": "SHA-256",
            "valueDigests": {
              "it.wallet.trust-registry.wallet_attestation": {
                0: h'2f89a12f690fe570b9b18d96acd231a70b5cb97cef5edad81973b99eeb145c2f',
                1: h'7541a38f61d686f72ca8fb9da87a3db9fc65d28caa4e0973b0a3d66181ff7997',
                2: h'7049c3bfcd96d62833f2fdb892b12cb6fd983b4c3bf40b0c39cb233bfeb5b75f',
                3: h'ce566344e76ff543c5084e7618bdb54223ff2750dbcb4a3c7c35fd56a47a1024'
              }
            },
            "deviceKeyInfo": {
              "deviceKey": {
                -1: 1,
                2: "ec#1",
                1: 2,
                -2: h'09a9028deb030705de45e4702d1ce6860e94c0e29f334359a476078c2d22b9c5',
                -3: h'6b972cd32c19cd5e8c19e051f1e207cabb3c2a802abf40ee5baaaa4a464508c3'
              }
            },
            "docType": "it.wallet.trust-registry.wallet_attestation",
            "validityInfo": {
              "signed": 0("2025-06-27T07:40:21Z"),
              "validFrom": 0("2025-06-27T07:40:21Z"),
              "validUntil": 0("2025-06-27T08:40:21Z")
            }
          }
        >>)
      >>
      h'97f223fd4c9c462454e4123df916dd0d672af14608727ce38470b8bd74fb496e11462113f0005d3e97bf6115074712991e1720eb085292edd894a116a305310c'
    ]
  }

Nota

Indipendentemente dal fatto che sub, wallet_link e wallet_name siano contenuti nel namespace, questi valori NON DEVONO essere mostrati all'Utente, in quanto non sono un attributo dell'Utente.

13.1.4.6. Wallet Unit Attestation JWT¶

L'intestazione JOSE del Wallet Unit Attestation JWT contiene i seguenti parametri:

JOSE header	Descrizione	Riferimento
alg	OBBLIGATORIO. Un identificatore di algoritmo di firma digitale come da registro IANA "JSON Web Signature and Encryption Algorithms". DEVE essere uno degli algoritmi supportati elencati in Algoritmi Crittografici e NON DEVE essere impostato su `none` o qualsiasi identificatore di algoritmo simmetrico (MAC).	RFC 7516#section-4.1.1.
kid	OBBLIGATORIO. Identificatore univoco della chiave pubblica associata alla chiave privata che il Fornitore di Wallet ha utilizzato per firmare la Wallet Unit Attestation.	RFC 7638#section_3.
typ	OBBLIGATORIO. Deve essere impostato su `key-attestation+jwt`	OPENID4VC-HAIP.
trust_chain	OBBLIGATORIO. Sequenza di Entity Statement che compone la Catena di Fiducia relativa al Fornitore di Wallet.	OID-FED Sezione 4.3 Trust Chain Header Parameter.
x5c	OPZIONALE. Contiene il certificato di chiave pubblica X.509 o la catena di certificati (RFC 5280) corrispondente alla chiave utilizzata per firmare digitalmente il JWT.	RFC 7515 Sezione 4.1.8 e SD-JWT-VC Sezione 3.5.

Il corpo del Wallet Unit Attestation JWT contiene le seguenti dichiarazioni (claims):

Claim	Descrizione	Riferimento
iss	OBBLIGATORIO. Identificatore del Fornitore di Wallet.	RFC 9126 e RFC 7519.
exp	OBBLIGATORIO. Timestamp UNIX con il tempo di scadenza del JWT.	RFC 9126 e RFC 7519.
iat	OBBLIGATORIO. Timestamp UNIX con il tempo di emissione del JWT.	RFC 9126 e RFC 7519.
attested_keys	OBBLIGATORIO. Un array non vuoto di chiavi attestate provenienti dallo stesso componente di archiviazione delle chiavi, utilizzando la sintassi JWK, contenente la parte pubblica di una coppia di chiavi asimmetriche posseduta dall'istanza del Wallet.	RFC 7517.
key_storage	OBBLIGATORIO. Un array non vuoto di stringhe sensibili alle maiuscole che dichiarano la resistenza al potenziale di attacco del componente di archiviazione delle chiavi e delle chiavi attestate nel parametro `attested_keys`. I seguenti valori sono definiti come possibili valori per questa dichiarazione claim: `iso_18045_high`: Deve essere utilizzato quando l'archiviazione delle chiavi è resistente ad attacchi con potenziale di attacco `High`. `iso_18045_moderate`: Deve essere utilizzato quando l'archiviazione delle chiavi è resistente ad attacchi con potenziale di attacco `Moderate`. `iso_18045_basic`: Deve essere utilizzato quando l'archiviazione delle chiavi è resistente ad attacchi con potenziale di attacco `Basic`.	OpenID4VCI.
user_authentication	OBBLIGATORIO. Un array non vuoto di stringhe sensibili alle maiuscole che dichiarano la resistenza al potenziale di attacco dei metodi di autenticazione utente autorizzati ad accedere alle chiavi private dal parametro attested_keys. I seguenti valori sono definiti come possibili valori per questa dichiarazione claim: `iso_18045_high`: Deve essere utilizzato quando l'autenticazione dell'utente è resistente ad attacchi con potenziale di attacco `High`. `iso_18045_moderate`: Deve essere utilizzato quando l'autenticazione dell'utente è resistente ad attacchi con potenziale di attacco `Moderate`. `iso_18045_basic`: Deve essere utilizzato quando l'autenticazione dell'utente è resistente ad attacchi con potenziale di attacco `Basic`.	OpenID4VCI.
status	OBBLIGATORIO. Oggetto JSON che rappresenta i meccanismi supportati per la verifica della revoca, come ad esempio OAuth Status List.	OpenID4VCI.
certification	OPZIONALE. Una stringa che contiene un URL che rimanda alla certificazione del componente di archiviazione delle chiavi.	OpenID4VCI.

Di seguito è riportato un esempio non normativo dell'intestazione e del payload del Wallet Unit Attestation JWT, senza codifica né firma applicata:

  {
    "alg": "ES256",
    "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY",
    "trust_chain": [
      "eyJhbGciOiJFUz...6S0A",
      "eyJhbGciOiJFUz...jJLA",
      "eyJhbGciOiJFUz...H9gw"
    ],
    "typ": "key-attestation+jwt"
  }

  {
    "iss": "https://wallet-provider.example.org",
    "attested_keys": [
      {
        "crv": "P-256",
        "kty": "EC",
        "x": "4HNptI-xr2pjyRJKGMnz4WmdnQD_uJSq4R95Nj98b44",
        "y": "LIZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg"
      }
    ],
    "status": { 
    "status_list": {
        "idx": 412,
        "uri": "https://revocation_url/statuslists/1"
      }
  },
    "iat": 1687281195,
    "exp": 1687288395,
    "key_storage": [ "iso_18045_moderate" ],
    "user_authentication": [ "iso_18045_moderate" ],
    "certification": "GP"
  }

13.1.5. Catalogo e-Service PDND del Fornitore di Wallet¶

La morte dell'Utente porta alla revoca delle Istanze di Wallet dell'Utente e all'eliminazione dell'account dell'Utente presso il Fornitore di Wallet. Per questo motivo, il Fornitore di Wallet fornisce il seguente e-service tramite PDND. Un Fornitore di Attestati Elettronici di Dati di Identificazione Personale che è stato notificato dalla Fonte Autentica del PID della morte dell'Utente DEVE inviare una notifica ai Fornitori di Wallet utilizzando questo endpoint.

Nota

Una Specifica OpenAPI completa è disponibile qui.

13.1.5.1. Notifica Morte Utente¶

Descrizione	Questo servizio viene utilizzato per notificare al Fornitore di Wallet la necessità di revocare l'Istanza di Wallet ed eliminare l'account dell'Utente a causa della morte dell'Utente.
Fornitore	Fornitore di Wallet
Consumatore	Fornitore di Attestati Elettronici di Dati di Identificazione Personale