WUA spiegata: come un wallet dimostra la propria autenticità a un emittente
Una Wallet Unit Attestation, WUA, è ciò che un EUDI Wallet mostra a un PID Provider o a un Attestation Provider durante l'emissione per dimostrare di essere autentico. Non è un solo documento ma due, entrambi firmati dal fornitore di wallet: una Wallet Instance Attestation (WIA) sull'app del wallet e una Key Attestation (KA) sull'archiviazione sicura delle chiavi a cui verrà legata una credenziale.
Il problema che una WUA risolve
Un emittente che sta per consegnare a un wallet un PID o una credenziale di registrazione aziendale non ha un modo integrato per distinguere un EUDI Wallet certificato da un'app modificata o da uno script che ripete un flusso di autorizzazione. Né può vedere se la chiave a cui verrà legata la credenziale risiede in hardware sicuro certificato o in una normale memoria da cui potrebbe essere copiata.
La WUA colma entrambe le lacune. Il fornitore di wallet garantisce per l'app tramite la WIA e per l'archiviazione delle chiavi tramite la Key Attestation. L'emittente controlla entrambe prima di emettere e continua a verificarne lo stato di revoca anche dopo, così può revocare ciò che ha emesso se in seguito il wallet o la sua archiviazione delle chiavi risultano compromessi.
Una WUA si usa solo durante l'emissione. L'ARF vieta a un'unità di wallet di presentare una WIA o una Key Attestation a una relying party, il che tiene i dettagli del wallet fuori da ogni presentazione.
Gli attori e chi si fida di chi
Sono coinvolti cinque ruoli, e solo quattro di essi gestiscono mai una WUA. Il WSCD (Wallet Secure Cryptographic Device) o un keystore genera e custodisce le chiavi, il fornitore di wallet garantisce per l'app e per le chiavi, e l'emittente si affida a questa garanzia invece di valutare direttamente il wallet.
Fornitore di wallet
Firma WIA e Key Attestation dopo aver verificato l'app e l'archiviazione delle chiavi, e gestisce le Status List di entrambe
Unità di wallet
Invia una WIA e una Key Attestation all'emittente durante l'emissione, e usa ciascuna per una sola emissione
WSCD o keystore
Genera e conserva le chiavi private descritte da una Key Attestation
PID Provider o Attestation Provider
Verifica la WIA e la Key Attestation, lega la credenziale a una chiave attestata e continua a controllare la revoca di entrambe
Relying party
Non riceve mai una WUA. Controlla invece la credenziale, il suo legame al dispositivo e il suo stato di revoca
Gli emittenti si fidano di una WUA perché il certificato di firma del fornitore di wallet, inviato nell'header x5c, risale a un'ancora di fiducia presente nella Trusted List dei fornitori di wallet. La Wallet Solution stessa è certificata da un organismo di valutazione della conformità, e la WIA riporta queste informazioni di certificazione.
Due attestazioni sotto un unico nome
TS3, la specifica tecnica EUDI per le WUA, divide l'attestazione in due perché l'app e l'archiviazione delle chiavi sono cose diverse, controllate su endpoint diversi e revocate per motivi diversi.
Wallet Instance Attestation (WIA)
- Attesta
- L'integrità della Wallet Instance, cioè l'app
- Inviata a
- L'Authorization Server, nella Pushed Authorization Request e nella Token Request
- Durata
- Meno di 24 ore
- Revoca
- client_status: lo stato di revoca di questa Wallet Instance
- Necessaria per
- Ogni emissione, con o senza legame al dispositivo
Key Attestation (KA)
- Attesta
- Che una o più chiavi sono state generate in un WSCD o keystore specifico e sono conservate lì, e quanto quell'archiviazione resiste agli attacchi
- Inviata a
- Il Credential Issuer, all'interno dei proofs della Credential Request
- Durata
- Scelta dal fornitore di wallet, e può essere più lunga di quella di una WIA
- Revoca
- key_storage_status: lo stato di revoca del WSCD o keystore
- Necessaria per
- Solo credenziali legate al dispositivo, incluso ogni PID
Entrambe sono JWT firmati dal fornitore di wallet con ES256, ES384 o ES512. Una Key Attestation si usa per una sola emissione e una WIA non viene mai riutilizzata verso un emittente diverso, così gli emittenti non possono collegare tra loro le richieste dello stesso wallet.
Come un'unità di wallet ottiene le sue WIA e Key Attestation
TS3 lascia questo passaggio a ciascun fornitore di wallet, poiché avviene all'interno di un singolo prodotto wallet. L'ARF richiede soltanto che il fornitore di wallet verifichi l'integrità dell'app prima di firmare una WIA, e che verifichi che le chiavi private attestate si trovino davvero nel WSCD o keystore indicato prima di firmare una Key Attestation. Un flusso tipico, che usa come prova attestazioni di piattaforma come Google Play Integrity o Apple DeviceCheck, si presenta così.
1. Unità di wallet
Chiede al WSCD o keystore di generare coppie di chiavi
2. WSCD o keystore
Restituisce le chiavi pubbliche, con le prove della piattaforma su dove sono state generate
3. Fornitore di wallet
Verifica l'integrità dell'app e le prove sulle chiavi, poi firma WIA e Key Attestation
4. Unità di wallet
Mantiene una scorta di WIA e Key Attestation nuove, e ne usa una nuova per ogni emissione
Cosa contengono una WIA e una Key Attestation
Nessuna delle due contiene un claim iss: l'emittente identifica il fornitore di wallet dal certificato di firma nell'header x5c. Gli esempi seguenti sono decodificati, con header e payload separati da un punto.
Wallet Instance Attestation
{
"typ": "oauth-client-attestation+jwt",
"alg": "ES256",
"x5c": ["MIIC..."]
}.{
"sub": "https://wallet.example.eu",
"wallet_name": "ExampleWallet-mobile",
"wallet_version": "2.3.0",
"wallet_link": "https://wallet.example.eu/about",
"wallet_solution_certification_information": "https://wallet.example.eu/certification/2-3-0",
"exp": 1789329600,
"client_status": {
"status": {
"status_list": { "idx": 48213, "uri": "https://wallet.example.eu/status/wia/17" }
},
"exp": 1791936000
},
"cnf": {
"jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
}
}| Campo | Cosa comunica all'emittente |
|---|---|
| typ / x5c | Che si tratta di un'attestazione del client, e la catena di certificati del fornitore di wallet da verificare rispetto alla Trusted List |
| sub | Il tipo di wallet, uguale per ogni installazione, quindi non può essere usato per tracciare un utente |
| wallet_name / wallet_version | La Wallet Solution come indicata nella Trusted List, e la sua versione |
| wallet_solution_certification_information | Chi ha certificato la Wallet Solution; il contenuto esatto deve ancora essere definito |
| exp | Scadenza tecnica, meno di 24 ore dopo il controllo di integrità |
| client_status | Una voce di Status List per questa Wallet Instance, e la data fino alla quale il fornitore di wallet la mantiene aggiornata |
| cnf | La chiave che firma la prova di possesso inviata insieme alla WIA |
Key Attestation
{
"typ": "key-attestation+jwt",
"alg": "ES256",
"x5c": ["MIIC..."]
}.{
"iat": 1789257600,
"exp": 1791936000,
"certification": "https://wallet.example.eu/certification/wscd/secure-element",
"key_storage": ["iso_18045_high"],
"user_authentication": ["iso_18045_high"],
"attested_keys": [
{ "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
{ "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
],
"key_storage_status": {
"status": {
"status_list": { "idx": 3, "uri": "https://wallet.example.eu/status/ka/1" }
},
"exp": 1794614400
}
}| Campo | Cosa comunica all'emittente |
|---|---|
| typ / x5c | Che si tratta di un'attestazione di chiave, e la catena di certificati del fornitore di wallet da verificare rispetto alla Trusted List |
| iat / exp | Quando è stata emessa e quando scade tecnicamente |
| attested_keys | Chiavi pubbliche le cui chiavi private sono state generate e sono conservate dal WSCD o keystore; più chiavi consentono l'emissione in batch |
| key_storage / user_authentication | Quanto resistono agli attacchi l'archiviazione e l'autenticazione dell'utente che sblocca le chiavi; un WSCD è sempre iso_18045_high per entrambe |
| certification | La certificazione del WSCD o keystore, da cui l'emittente capisce se si tratta di un WSCD |
| key_storage_status | Una voce di Status List per il WSCD o keystore, e la data fino alla quale il fornitore di wallet la mantiene aggiornata |
| nonce | Il c_nonce dell'emittente, presente solo quando la Key Attestation viene inviata come proof di tipo attestation |
Dove viaggia una WUA durante l'emissione OpenID4VCI
Le due attestazioni vanno in posti diversi. La WIA autentica il wallet come client OAuth presso l'Authorization Server. La Key Attestation va al Credential Issuer insieme alla richiesta della credenziale vera e propria.
L'Authorization Server riceve la WIA
- La firma della WIA risale alla Trusted List dei fornitori di wallet
- La WIA non è scaduta e la Wallet Instance non è revocata
- La prova di possesso è firmata con la chiave presente nel claim cnf della WIA
Il Credential Issuer riceve la Key Attestation
- La firma della Key Attestation risale alla Trusted List dei fornitori di wallet
- Il nuovo c_nonce dell'emittente è presente nella proof jwt o nella Key Attestation stessa
- Il WSCD o keystore non è revocato, e la credenziale è legata a una delle attested_keys
Pushed Authorization Request con la WIA
POST /par HTTP/1.1 Host: issuer.example.eu Content-Type: application/x-www-form-urlencoded OAuth-Client-Attestation: <WIA JWT> OAuth-Client-Attestation-PoP: <PoP JWT signed with the WIA cnf key> response_type=code &client_id=https%3A%2F%2Fwallet.example.eu &scope=company_registration &code_challenge=<S256 challenge> &code_challenge_method=S256 &redirect_uri=<wallet redirect URI>
Il client_id corrisponde al sub della WIA. La Token Request riporta gli stessi due header. Poiché il Credential Issuer non vede mai la WIA, l'Authorization Server deve trasmettergli il suo client_status, ad esempio all'interno dell'access token.
Credential Request con la Key Attestation
POST /credential HTTP/1.1
Host: issuer.example.eu
Authorization: DPoP <access_token>
DPoP: <DPoP proof JWT>
Content-Type: application/json
{
"credential_configuration_id": "company_registration",
"proofs": {
"jwt": ["<proof JWT: Key Attestation in its key_attestation header, signed with attested_keys[0]>"]
}
}Con il tipo di proof attestation, la richiesta contiene invece "proofs": { "attestation": ["<Key Attestation JWT>"] }. In quel caso non c'è alcuna prova di possesso: l'unità di wallet passa il c_nonce dell'emittente al fornitore di wallet, che lo inserisce in una Key Attestation appena firmata.
Il ciclo di vita di una WUA
Una WUA è di breve durata e monouso per scelta, ma le informazioni di revoca che la accompagnano sopravvivono al token stesso. Le prime tre fasi sono di routine; la quarta si verifica solo quando qualcosa va storto.
1. Emissione
Il fornitore di wallet firma WIA e Key Attestation dopo i propri controlli di integrità e di archiviazione delle chiavi
2. Monouso
Ognuna serve una sola emissione, quindi l'unità di wallet continua a ottenerne di nuove
3. Revoca a catena
Un PID Provider ricontrolla lo stato della WIA e della Key Attestation almeno ogni 24 ore, e revoca il PID se una delle due è revocata
4. Revoca
Il fornitore di wallet revoca una Wallet Instance, ad esempio dopo smarrimento o furto, oppure un WSCD o keystore con una vulnerabilità di sicurezza
Al di fuori dell'ecosistema EUDI Wallet, alcuni fornitori di wallet emettono attestazioni del wallet con una durata molto breve e senza alcun riferimento di stato, affidandosi alla scadenza anziché alla revoca; OpenID4VCI rende facoltativo il claim di stato. TS3 non lo consente per gli EUDI Wallet. La WIA dura già meno di 24 ore, eppure sia la WIA sia la Key Attestation devono contenere un riferimento di stato che il fornitore di wallet mantiene per almeno 31 giorni, perché i PID Provider lo usano per revocare i PID molto tempo dopo l'emissione.
WUA, WIA e KA: cosa significa ciascun termine
La terminologia è cambiata man mano che le specifiche maturavano. TS3 chiamava la WIA Wallet App Attestation fino alla versione 1.1, e usava WUA per l'attuale Key Attestation fino alla versione 1.5. Gli articoli meno recenti e le bozze dell'ARF usano quindi i termini in modo diverso.
| Termine | Cosa copre | Chi la riceve |
|---|---|---|
| WUA | Termine generale per le due attestazioni seguenti | PID Provider e Attestation Provider, solo durante l'emissione |
| WIA | La Wallet Instance, cioè l'app | L'Authorization Server, nella Pushed Authorization Request e nella Token Request |
| KA | Un WSCD o keystore e le chiavi che conserva | Il Credential Issuer, nei proofs della Credential Request |
Termini correlati
Domande frequenti
Una WUA è la stessa cosa di una Wallet Instance Attestation?
No. Dalla versione 1.5 di TS3, WUA è il termine generale per due attestazioni: la Wallet Instance Attestation (WIA), che copre l'app, e la Key Attestation (KA), che copre il WSCD o keystore in cui sono conservate le chiavi. I documenti meno recenti usano WUA per quella che oggi si chiama Key Attestation, ed è per questo che i termini vengono spesso confusi.
Un verificatore vede mai la WUA?
No. I requisiti ARF WUA_07 e WUA_24 consentono a un'unità di wallet di presentare una WIA o una Key Attestation solo a un PID Provider o a un Attestation Provider durante l'emissione, mai a una relying party. Un verificatore controlla invece la credenziale: la sua firma, il suo legame al dispositivo e il suo stato di revoca. Se il wallet dietro un PID viene revocato, il PID Provider revoca il PID entro il suo ciclo di controllo di 24 ore, e il verificatore lo vede attraverso lo stato del PID stesso.
Per quanto tempo è valida una WUA?
Una WIA scade meno di 24 ore dopo che il fornitore di wallet ha verificato l'integrità dell'app. Una Key Attestation può restare valida più a lungo, a discrezione del fornitore di wallet. Inoltre ciascuna riporta una data di mantenimento dello stato, client_status.exp o key_storage_status.exp, fino alla quale il fornitore di wallet mantiene aggiornato lo stato di revoca. L'unità di wallet deve sempre poterne presentare una la cui data sia ad almeno 31 giorni di distanza, e un PID deve scadere prima di quella data.
Cosa succede se un'unità di wallet viene compromessa prima che la sua WUA scada?
Il fornitore di wallet revoca la Wallet Instance nella Status List delle WIA oppure, in caso di vulnerabilità in un tipo di WSCD o keystore, la voce della Status List relativa a quell'archiviazione. Un PID Provider controlla almeno una volta ogni 24 ore lo stato della WIA e della Key Attestation dietro ogni PID che ha emesso, e revoca il PID quando una delle due è revocata. Gli Attestation Provider possono fare lo stesso. Non è la scadenza della WUA stessa a escludere il wallet, ma la revoca delle credenziali emesse a suo favore.
Una Key Attestation può coprire più di una chiave?
Sì. attested_keys può elencare diverse chiavi pubbliche dello stesso WSCD o keystore, ed è così che funziona l'emissione in batch: l'emittente lega ogni credenziale del batch a una chiave diversa, e una sola firma del fornitore di wallet le copre tutte. Quando la Key Attestation viaggia in una proof jwt, l'unità di wallet firma quella proof solo con la prima chiave dell'elenco.
Fonti
Questa pagina ha scopo informativo e non costituisce una consulenza legale. Per indicazioni autorevoli consultare direttamente la Commissione Europea e la OpenID Foundation.