Tutti gli articoli

WebAuthn e passkey sotto il cofano: messaggi reali, CTAP2, chiavette FIDO2 e telefono via BLE

Una passkey è una coppia di chiavi legata a un dominio: niente da ricordare, niente da rubare dal server, niente da digitare su un sito falso. Vediamo cosa succede davvero sotto: i messaggi WebAuthn in registrazione e login con dati reali, l'authenticatorData byte per byte, il protocollo CTAP2 con le chiavette FIDO2 su USB e NFC, e come un telefono fa da autenticatore per il PC via Bluetooth.

Pubblicato il 20 ottobre 2026 40 min di letturaWebAuthnPasskeyFIDO2CTAPBLESicurezza
01

Il problema dei segreti condivisi

Una password è un segreto condiviso: lo conoscono l'utente e il server, e per autenticarsi l'utente lo consegna. Tutto il resto deriva da qui. Lo si può riusare su altri siti, quindi un breach altrove diventa un accesso qui (credential stuffing). Lo si può consegnare alla persona sbagliata, quindi il phishing funziona. Il server ne conserva una forma derivata, quindi un database rubato diventa una lista da craccare.

L'MFA con codici OTP o notifiche push alza l'asticella ma non cambia la natura del problema: anche il codice è un segreto che l'utente consegna. Un proxy di phishing in tempo reale (adversary in the middle) si mette tra utente e sito, inoltra password e codice, e si tiene il cookie di sessione. L'utente non ha fatto niente di sbagliato, se non fidarsi di un dominio quasi uguale a quello vero.

PasswordOTP (SMS, TOTP)PushPasskey / FIDO2
Segreto sul serverHash della passwordSeed TOTPToken del dispositivoNessuno: solo una chiave pubblica
Riutilizzabile su altri sitiSì, spessoNoNoNo: una chiave per rpId
Phishing in tempo reale (AitM)VulnerabileVulnerabileVulnerabile (MFA fatigue)Resistente: firma legata all'origin
Data breach del serverHash da craccareSeed da rubareDipendeInutile per l'attaccante
Cosa digita l'utenteTuttoUn codiceNienteNiente (o un PIN locale)

L'idea chiave

Con la crittografia a chiave pubblica non si consegna più niente. Il server tiene la chiave pubblica, l'utente la privata, e per autenticarsi firma una challenge. E soprattutto: la firma contiene il dominio per cui è stata fatta, scritto dal browser e non dalla pagina. Un sito di phishing può ottenere solo firme per sé stesso, che al sito vero non servono.
02

FIDO2: WebAuthn + CTAP

FIDO2 è il nome ombrello di due specifiche che lavorano insieme. WebAuthn (W3C, oggi Level 3) è l'API JavaScript che un sito usa per creare e usare credenziali, e definisce i formati dei dati e le verifiche che il server deve fare. CTAP (Client to Authenticator Protocol, FIDO Alliance, oggi 2.2) è il protocollo con cui il browser o il sistema operativo parla con un autenticatore esterno: una chiavetta su USB o NFC, un telefono via Bluetooth.

Lo stack FIDO2Schema

Server del Relying Party

genera challenge, verifica firme, conserva chiavi pubbliche

HTTPS · JSON con base64urlapplicazione

JavaScript del sito

chiama navigator.credentials.create() / get()

WebAuthn APIW3C WebAuthn

Browser / sistema operativo

il client: verifica l'origin, scrive clientDataJSON, parla con gli autenticatori

CTAP2 su USB HID · NFC · BLE · hybrid, oppure API di piattaformaFIDO CTAP

Di piattaforma

Touch ID, Windows Hello, sblocco Android: chiave nel Secure Enclave, nel TPM, nel TEE

Gestore di passkey

Portachiavi iCloud, Google Password Manager, 1Password: passkey sincronizzate

Roaming

Chiavetta FIDO2 (USB, NFC, BLE) o telefono via hybrid

autenticatori

Il sito non parla mai direttamente con l'autenticatore. In mezzo c'è sempre il client, ed è il client a garantire l'origin.

Gli attori

Il Relying Party (RP) è il sito: un server che emette challenge e verifica firme, più il JavaScript che chiama l'API. Il client è il browser, spesso insieme al sistema operativo (su Windows le chiamate passano da webauthn.dll, su Android da Credential Manager). L'autenticatore genera e custodisce le chiavi private e firma. Può essere di piattaforma, integrato nel dispositivo (Touch ID, Windows Hello, il gestore di passkey del sistema), oppure roaming, staccabile e usabile su più dispositivi (una chiavetta, un telefono via hybrid). In WebAuthn si chiama authenticatorAttachment: platform o cross-platform.

CTAP esiste in tre generazioni. CTAP1 è il vecchio U2F: messaggi APDU binari, solo secondo fattore, nessuna credenziale salvata, nessun PIN. CTAP2.0 introduce CBOR, credenziali discoverable e PIN. CTAP2.1 aggiunge token PIN con permessi, gestione delle credenziali, biometria; la 2.2 standardizza il trasporto hybrid. Un autenticatore dichiara cosa parla nella risposta a getInfo.

03

Credenziali, rpId e passkey

Una credenziale WebAuthn è una coppia di chiavi creata per un solo rpId e un solo utente. Gli ingredienti che vedremo nei messaggi sono pochi, conviene fissarli subito.

  • rpId: un dominio, uguale all'host della pagina o un suo suffisso registrabile. Da https://login.example.com si può usare login.example.com o example.com, non com né example.org. Per più domini diversi esistono le Related Origin Requests: un file /.well-known/webauthn sull'rpId che elenca le origin ammesse.
  • credential ID: fino a 1023 byte scelti dall'autenticatore, che il server usa per ritrovare la chiave pubblica.
  • user handle (user.id): fino a 64 byte opachi scelti dal server. Dovrebbe essere un valore casuale, non l'email.
  • challenge: almeno 16 byte casuali, monouso, che rendono ogni firma impossibile da riutilizzare.
  • signCount: un contatore che l'autenticatore può incrementare a ogni firma.

Discoverable e non discoverable

Una credenziale non discoverable non esiste per l'autenticatore finché il server non gli passa il suo ID: molte chiavette cifrano la chiave privata con un segreto interno e la restituiscono come credential ID, così possono gestire infinite credenziali senza memoria. È il modello del secondo fattore: prima lo username, poi la chiavetta. Una credenziale discoverable (resident key) è salvata sull'autenticatore insieme a rpId e user handle, e si può trovare da sola: il server chiede «una qualunque credenziale per example.com» e l'autenticatore propone gli account.

Non discoverableDiscoverable (passkey)
Dove sta la chiave privataSpesso cifrata dentro il credential ID (key wrapping)Nella memoria dell'autenticatore o del gestore
Il server deve conoscere l'IDSì, in allowCredentialsNo: login senza username
Spazio sull'autenticatoreNessunoUno slot per credenziale
Parametro WebAuthnresidentKey: "discouraged"residentKey: "required" o "preferred"
Opzione CTAPrk: falserk: true

Cos'è, esattamente, una passkey

Passkey è il nome commerciale, adottato da FIDO Alliance, Apple, Google e Microsoft, per una credenziale FIDO discoverable. Può essere sincronizzata tra dispositivi (la maggior parte, oggi) o legata a un solo dispositivo (su una chiavetta). Il protocollo è lo stesso: cambiano dove vive la chiave privata e due flag nell'authenticatorData.
04

Registrazione, messaggio per messaggio

Seguiamo una registrazione reale. Tutti i valori che vedi, challenge, chiavi, hash, firme, sono stati generati con chiavi P-256 vere per l'rpId example.com e l'origin https://login.example.com: decodificano e si verificano, puoi controllarli nel laboratorio più avanti.

Registrazione di una passkeySequence
UtenteAutenticatorepasskey providerBrowserclient WebAuthnSitoJavaScript RPServer RPexample.com1POST /webauthn/register/options2PublicKeyCredentialCreationOptions3navigator.credentials.create()4controlla rp.id, crea clientDataJSON5authenticatorMakeCredential6«Creare una passkey per example.com?»7impronta / volto / PIN8genera chiavi, credential ID, authData9fmt, authData, attStmt10PublicKeyCredential11POST /webauthn/register/verify12verifica (§7.1), salva la chiave13201 Created
passo 1 / 13 · rete

1. Il sito chiede le opzioni

L'utente è già autenticato (o sta creando l'account): il frontend chiede al server di preparare una cerimonia di registrazione. Il server genera una challenge casuale di almeno 16 byte (qui 32), la lega alla sessione e la conserva per pochi minuti.
sul filo
POST /webauthn/register/options HTTP/1.1
Host: login.example.com
Cookie: session=…
Content-Type: application/json

{ "username": "gianni@example.com" }
Clicca su una freccia o usa i pulsanti. Linee piene: rete. Tratteggiate: dentro il dispositivo o interazione con l'utente. Il pannello «sul filo» mostra i dati scambiati in quel passo.

clientDataJSON

È il documento che il browser compone e che l'autenticatore firma (attraverso il suo hash). Il server lo riceve in chiaro, come byte UTF-8, e deve verificarlo prima di qualsiasi altra cosa.

clientDataJSON (registrazione)
{
  "type": "webauthn.create",
  "challenge": "COTwHfFRxa0Tm-d4bmst0mTUbp5GTy67g9Z0FM0kl4I",
  "origin": "https://login.example.com",
  "crossOrigin": false
}

type distingue registrazione (webauthn.create) e login (webauthn.get), così una firma non si può spacciare per l'altra. challenge è quella del server, in base64url. origin è l'origin completa della pagina che ha chiamato l'API: il server la confronta con l'elenco delle proprie. crossOrigin segnala una chiamata da un iframe di terze parti, con topOrigin che indica la pagina contenitore.

attestationObject

È una mappa CBOR (Concise Binary Object Representation, RFC 8949): JSON binario, compatto e senza ambiguità di parsing. Contiene il formato dell'attestation, lo statement e, soprattutto, l'authData. Clicca le righe per vedere quali byte codificano cosa.

Dentro l'attestationObjectInterattivo

browser → sito · response.attestationObject · 178 byte

a363666d74646e6f6e656761747453746d74a06861757468446174615894a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce19475d00000000ea9b8d664d011d213ce4b6b48cb575d40010f1054e25c2255a8178a9fdf607640906a501020326200121582039a446e6ade386699e298edc236b75ee27299e4ea473165f612d9737c284e3cd225820cf33a76a86572cb1d1e420875ab04e07a7fe3455c1043154ba751a146118c9b6

byte 0–177 · 178 B

messaggio

Una mappa CBOR con tre chiavi testuali. È lo stesso contenuto della risposta CTAP, con i nomi al posto degli interi.

Il primo byte a3 dice «mappa di 3 elementi». 63 666d74 è la stringa di 3 caratteri «fmt». 58 94 annuncia una byte string di 0x94 = 148 byte.
05

authenticatorData byte per byte

L'authenticatorData è la struttura binaria che l'autenticatore produce e firma, identica in registrazione e in login, con una parte opzionale in più quando nasce una credenziale. Non è CBOR: è un formato a campi fissi, con la chiave pubblica codificata in CBOR (COSE) in coda.

authenticatorDataInterattivo

byte 32–32 di 148

flags · 1 B

Una bitmask. Il server deve controllare almeno UP, e UV se la sua policy lo richiede.

0x5d = 01011101b

  • UPbit 0 · User Present: qualcuno ha toccato, cliccato, confermato
  • UVbit 2 · User Verified: PIN, biometria o sblocco del dispositivo
  • BEbit 3 · Backup Eligible: la credenziale può essere sincronizzata
  • BSbit 4 · Backup State: la credenziale è sincronizzata ora
  • ATbit 6 · Attested credential data presente (solo in registrazione)
  • EDbit 7 · Extension data presente
Registrazione: 148 byte con i dati della credenziale (flag AT). Login: 37 byte, solo rpIdHash, flag e contatore. L'hash dell'rpId è ricalcolato nel tuo browser.
layout (WebAuthn §6.1)
offset  len   campo
0       32    rpIdHash            SHA-256(rpId)
32      1     flags               UP(0) UV(2) BE(3) BS(4) AT(6) ED(7)
33      4     signCount           uint32 big endian
--- solo se AT = 1 (attestedCredentialData) ---
37      16    aaguid
53      2     credentialIdLength  uint16 big endian
55      L     credentialId
55+L    var   credentialPublicKey COSE_Key in CBOR
--- solo se ED = 1 ---
...     var   extensions          mappa CBOR

La chiave pubblica in COSE

COSE (RFC 9052 e 9053) è l'equivalente CBOR di JOSE: chiavi intere al posto dei nomi. Per una chiave EC2 su P-256 con ES256 servono cinque voci, 77 byte in tutto. Il server la può conservare così com'è o convertirla in JWK o SPKI.

COSE_Key → JWK
{ 1: 2,      kty: EC2               →  "kty": "EC"
  3: -7,     alg: ES256              →  "alg": "ES256"
 -1: 1,      crv: P-256              →  "crv": "P-256"
 -2: h'39a446e6…',  x (32 B)         →  "x": "OaRG5q3jhmmeKY7cI2t17icpnk6kcxZfYS2XN8KE480"
 -3: h'cf33a76a…',  y (32 B)         →  "y": "zzOnaoZXLLHR5CCHWrBOB6f-NFXBBDFUunUaFGEYybY" }

Gli altri algoritmi che incontrerai: -257 RS256 (Windows Hello lo usa ancora su alcuni TPM), -8 EdDSA (Ed25519, molte chiavette), -35 e -36 ES384 ed ES512. Un server dovrebbe offrire almeno -7 e -257.

06

Attestation: chi ha creato la chiave?

Un server può voler sapere non solo che una chiave esiste, ma dove è stata creata: un'azienda può accettare solo chiavette certificate FIDO L2, una banca può voler escludere autenticatori software. L'attestation serve a questo: un produttore installa in fabbrica una chiave di attestation, condivisa da un lotto di almeno 100 000 dispositivi per non renderli tracciabili, e l'autenticatore firma con quella la nuova credenziale. Il server verifica la catena fino a un certificato radice pubblicato nel FIDO Metadata Service (MDS3), cercato per AAGUID.

fmtChi lo usaCosa contiene
noneDefault, quasi tutte le passkey sincronizzateNiente: il sito non ha chiesto attestation
packedChiavette FIDO2, molti autenticatorialg, sig e x5c (certificato di batch) oppure self attestation
tpmWindows HelloStruttura TPMS_ATTEST firmata da una chiave AIK del TPM
android-keyAndroid, chiavi in hardwareCatena Android Key Attestation
appleDispositivi Apple (attestation anonima)Certificato con nonce = hash di authData e clientDataHash
fido-u2fVecchi token U2FFirma U2F e certificato di attestation

Il sito sceglie con attestation: none (default), indirect, direct o enterprise. Per un sito consumer la scelta giusta è quasi sempre none: le passkey sincronizzate non offrono attestation e chiederla aggiunge solo un prompt di privacy. In ambito aziendale, con enterprise una chiavetta configurata dall'organizzazione può includere il numero di serie, solo per gli rpId autorizzati.

attStmt packed con certificato (struttura)
{
  "fmt": "packed",
  "attStmt": {
    "alg": -7,
    "sig": h'3045…',              // firma con la chiave di attestation
    "x5c": [ h'3082…' ]           // certificato di batch: O=Yubico AB, OU=Authenticator Attestation
  },                              //   estensione 1.3.6.1.4.1.45724.1.1.4 = AAGUID
  "authData": h'a379a6f6…'
}
verifica: sig su authData ‖ clientDataHash con la chiave di x5c[0],
          catena fino alla radice del Metadata Statement dell'AAGUID
07

Autenticazione e verifica della firma

Il login è più semplice della registrazione: una challenge, una firma, una verifica. Le passkey rendono possibile il login senza username, con allowCredentials vuota, e la conditional UI le integra nel normale autocompletamento del browser.

Login con una passkeySequence
UtenteAutenticatorepasskey providerBrowserclient WebAuthnSitoJavaScript RPServer RPexample.com1POST /webauthn/login/options2PublicKeyCredentialRequestOptions3credentials.get({ mediation: "conditional" })4authenticatorGetAssertion5«Accedi a example.com come gianni@…»6impronta / volto / PIN7sig = Sign(authData ‖ clientDataHash)8credential, authData, signature, user9PublicKeyCredential10POST /webauthn/login/verify11verifica (§7.2)12Set-Cookie: session=…
passo 1 / 12 · rete

1. Una nuova challenge

Al caricamento della pagina di login, prima ancora che l'utente scriva qualcosa.
Il server non sa chi è l'utente fino al passo 10: lo scopre dallo userHandle e dal credential ID, e lo conferma con la firma.

Cosa si firma, esattamente

L'autenticatore firma authenticatorData ‖ SHA-256(clientDataJSON). Le firme ECDSA arrivano codificate in DER (una SEQUENCE ASN.1 di due INTEGER, r e s), non nel formato raw r‖s di JOSE: è un dettaglio che fa fallire molte implementazioni fatte a mano.

i byte firmati del nostro esempio
authenticatorData (37 B)
  a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce19471d00000000
clientDataHash = SHA-256(clientDataJSON) (32 B)
  bcf2fb4fe07c22c66fd69269411aa2d690fb027534318b856f22fa4f8763bf33

signature (DER, 71 B)
  30 45                     SEQUENCE, 69 B
     02 20 21c5603c12969d…   INTEGER r (32 B)
     02 21 00 ae6cebd1e2706d…   INTEGER s (33 B: 00 iniziale, bit alto a 1)

La checklist del server

  1. la credenziale con quell'id esiste e, se c'è lo userHandle, appartiene a quell'utente;
  2. clientDataJSON.type è webauthn.get, la challenge è quella emessa (e non ancora usata), l'origin è ammessa;
  3. rpIdHash è lo SHA-256 dell'rpId atteso;
  4. il flag UP è a 1, e UV se la policy lo richiede;
  5. la firma è valida con la chiave pubblica salvata;
  6. se signCount o il valore salvato sono diversi da zero, il nuovo valore è maggiore: altrimenti possibile clone;
  7. aggiornare signCount, il flag BS e la data di ultimo uso.
08

Laboratorio: una passkey vera

Basta teoria. Questo widget esegue cerimonie WebAuthn vere su questa pagina, con il tuo autenticatore (il gestore di passkey del sistema, una chiavetta, il telefono via QR), e poi fa nel browser tutte le verifiche che farebbe un server: challenge, origin, rpIdHash, flag e firma, con WebCrypto. Nessun dato lascia la pagina.

Crea e usa una passkeyLaboratorio
WebAuthn no
attestation:
La passkey demo resta nel tuo gestore con il nome «Demo articolo WebAuthn»: puoi cancellarla dalle impostazioni, o con il pulsante «Dimentica» se il browser supporta la Signal API. Il pulsante «Verifica l'esempio» controlla la firma dell'esempio di questo articolo, senza creare niente.

Prova con autenticatori diversi e confronta: un gestore di passkey avrà BE e BS a 1 e signCount 0, una chiavetta BE a 0 e un contatore che cresce; con attestation: direct e una chiavetta vedrai un fmt packed con il certificato del produttore in x5c.

09

CTAP2: il protocollo dell'autenticatore

Quando l'autenticatore è esterno, tra browser e dispositivo viaggia CTAP2. Il modello è semplice: richiesta e risposta. Una richiesta è un byte di comando seguito da una mappa CBOR con chiavi intere; una risposta è un byte di stato seguito, se lo stato è 0x00, da una mappa CBOR. Le chiavi intere al posto dei nomi servono a stare dentro dispositivi con pochi KB di RAM, e la codifica è canonica (chiavi ordinate, lunghezze minime) perché ogni byte deve essere deterministico.

ByteComandoA cosa serve
0x01authenticatorMakeCredentialCrea una credenziale (registrazione)
0x02authenticatorGetAssertionFirma una challenge (autenticazione)
0x04authenticatorGetInfoVersioni, estensioni, AAGUID, opzioni, limiti
0x06authenticatorClientPINGestione PIN e pinUvAuthToken (subCommand)
0x07authenticatorResetCancella tutto: credenziali, PIN. Solo entro 10 s dall'accensione
0x08authenticatorGetNextAssertionLe altre asserzioni, se le credenziali sono più di una
0x09authenticatorBioEnrollmentRegistrazione delle impronte (chiavette biometriche)
0x0AauthenticatorCredentialManagementElenca e cancella le passkey salvate
0x0BauthenticatorSelection«Tocca la chiavetta che vuoi usare»
0x0CauthenticatorLargeBlobsPiccoli blob cifrati associati alle credenziali
0x0DauthenticatorConfigenterprise attestation, alwaysUv, lunghezza minima PIN

Ecco i messaggi di una registrazione completa con una chiavetta con PIN, nell'ordine in cui la piattaforma li manda. Sono gli stessi byte che passano sul cavo, dentro i pacchetti USB che vedremo tra poco.

I messaggi CTAP2, decodificatiInterattivo

piattaforma → autenticatore · 0x01 authenticatorMakeCredential · 238 byte

01a801582003810f69dcb0fdcfe96cf36d66e81fc14478fc2414edd3b090b096cde2c19a2302a26269646b6578616d706c652e636f6d646e616d65674578616d706c6503a3626964508c1f4e2a9b7d4c03a6e5f2d1b0c9a877646e616d65726769616e6e69406578616d706c652e636f6d6b646973706c61794e616d65664769616e6e690482a263616c672664747970656a7075626c69632d6b6579a263616c6739010064747970656a7075626c69632d6b657906a16b6372656450726f746563740207a162726bf50858207c325a81762523bf696a88153c9e98d254b07f9ec4be7a4c75d648e39f979bc40902

byte 0–0 · 1 B

command

0x01 = authenticatorMakeCredential. Il byte di comando precede la mappa CBOR.

La freccia indica la direzione: → verso l'autenticatore, ← risposta. Il primo byte (in colore) è il comando o lo stato; il resto è CBOR.

Dalla chiamata WebAuthn al comando CTAP

Il client traduce: residentKey: "required" diventa options: { rk: true }, excludeCredentials diventa la excludeList (chiave 0x05), userVerification: "required" impone di ottenere un pinUvAuthToken prima del comando, le estensioni WebAuthn (prf, credProtect, largeBlob) diventano estensioni CTAP (hmac-secret, credProtect, largeBlobKey). E al ritorno riscrive la risposta con chiavi testuali. Se l'autenticatore risponde con un errore, il sito non vede il codice CTAP: vede un DOMException generico, quasi sempre NotAllowedError, per non rivelare informazioni sugli autenticatori presenti.

CodiceNomeQuando
0x00CTAP2_OKSuccesso
0x19CTAP2_ERR_CREDENTIAL_EXCLUDEDUna credenziale in excludeList esiste già: il browser restituisce InvalidStateError
0x27CTAP2_ERR_OPERATION_DENIEDL'utente ha rifiutato
0x28CTAP2_ERR_KEY_STORE_FULLNessuno slot libero per una resident key
0x2ECTAP2_ERR_NO_CREDENTIALSNessuna credenziale per l'rpId o nella allowList
0x2FCTAP2_ERR_USER_ACTION_TIMEOUTNessun tocco entro il timeout
0x31CTAP2_ERR_PIN_INVALIDPIN sbagliato
0x32CTAP2_ERR_PIN_BLOCKEDTentativi esauriti: serve un reset, che cancella tutto
0x33CTAP2_ERR_PIN_AUTH_INVALIDpinUvAuthParam non valido
0x35CTAP2_ERR_PIN_NOT_SETServe UV ma il PIN non è impostato
0x36CTAP2_ERR_PUAT_REQUIREDIl comando richiede un pinUvAuthToken
10

Chiavette FIDO2: USB HID e NFC

Una chiavetta FIDO2 su USB è un dispositivo HID (Human Interface Device), la stessa classe di tastiere e mouse: nessun driver, funziona ovunque. Si riconosce dalla usage page 0xF1D0 e scambia report di 64 byte. Il protocollo di trasporto, CTAPHID, aggiunge tre cose: canali (più applicazioni sullo stesso dispositivo), frammentazione (messaggi più lunghi di 64 byte) e keepalive (mentre la chiavetta aspetta il tocco).

Registrazione con una chiavetta FIDO2 via USB, con PINSequence
UtenteChiavetta FIDO2USB HIDBrowser / OSclient CTAP2Sitoexample.comScoperta e canalePIN · clientPIN protocollo 2Creazione della credenziale1credentials.create(...)2enumera HID, usage page 0xF1D03CTAPHID_INIT (CID ffffffff)4nonce, CID 1a2b3c4d, capabilities5CTAPHID_CBOR 0x04 getInfo600 + getInfo (268 B, 5 report)7«Inserisci il PIN della chiave»8PIN90x06 getKeyAgreement10keyAgreement (COSE, ECDH P-256)11ECDH → Z, HKDF → hmacKey, aesKey120x06 getPinUvAuthToken… (perm mc, rpId)13pinUvAuthToken (cifrato)140x01 makeCredential + pinUvAuthParam15CTAPHID_KEEPALIVE UPNEEDED16tocca il sensore17genera chiave, salva resident key1800 + fmt packed, authData, attStmt19PublicKeyCredential (usb)
passo 1 / 19 · locale

Scoperta e canale

1. La pagina chiede una credenziale

Le stesse opzioni di prima, con authenticatorAttachment: "cross-platform". Il browser apre la finestra «Usa la chiave di sicurezza».
Le bande separano le fasi. In ogni passo «sul filo» trovi i report HID o il CBOR decodificato. I dati sono gli stessi del widget dei messaggi CTAP.

Frame e pacchetti

Il pacchetto iniziale ha 4 byte di Channel ID, 1 di comando (con il bit alto a 1), 2 di lunghezza totale e 57 di dati. Quelli di continuazione hanno il CID, un numero di sequenza da 0 a 127 e 59 byte di dati. Il resto del report si riempie di zeri. Scegli un messaggio e un trasporto per vedere come viene tagliato.

Lo stesso messaggio su USB, BLE e NFCInterattivo

piattaforma → autenticatore · 0x01 authenticatorMakeCredential · messaggio 238 B → 5 frame, 320 B sul filo

init · 64 B · CID (4) · CMD 0x90 = CTAPHID_CBOR | 0x80 · BCNT (2) · dati (57)

1a2b3c4d9000ee01a801582003810f69dcb0fdcfe96cf36d66e81fc14478fc2414edd3b090b096cde2c19a2302a26269646b6578616d706c652e636f6d646e61

cont 0 · 64 B · CID (4) · SEQ 0x00 · dati (59)

1a2b3c4d006d65674578616d706c6503a3626964508c1f4e2a9b7d4c03a6e5f2d1b0c9a877646e616d65726769616e6e69406578616d706c652e636f6d6b6469

cont 1 · 64 B · CID (4) · SEQ 0x01 · dati (59)

1a2b3c4d0173706c61794e616d65664769616e6e690482a263616c672664747970656a7075626c69632d6b6579a263616c6739010064747970656a7075626c69

cont 2 · 64 B · CID (4) · SEQ 0x02 · dati (59)

1a2b3c4d02632d6b657906a16b6372656450726f746563740207a162726bf50858207c325a81762523bf696a88153c9e98d254b07f9ec4be7a4c75d648e39f97

cont 3 · 64 B · CID (4) · SEQ 0x03 · dati (59)

1a2b3c4d039bc4090200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
In colore gli header di trasporto, in grigio il padding. Su BLE la dimensione dei frammenti dipende dall'MTU negoziato (qui 20 byte, il minimo); su NFC i messaggi lunghi usano APDU chaining o extended length.
CMDNomeUso
0x83CTAPHID_MSGMessaggi CTAP1/U2F (APDU)
0x86CTAPHID_INITAllocare un Channel ID
0x81CTAPHID_PINGEco, per test
0x88CTAPHID_WINKFa lampeggiare il LED, per riconoscere la chiavetta
0x90CTAPHID_CBORMessaggi CTAP2: comando + CBOR
0x91CTAPHID_CANCELAnnulla l'operazione in corso
0xBBCTAPHID_KEEPALIVE«Sto lavorando» / «aspetto il tocco»
0xBFCTAPHID_ERRORErrore di trasporto (canale occupato, sequenza sbagliata…)

NFC

Su NFC la chiavetta è una smart card ISO 7816. La piattaforma seleziona l'applet FIDO con una SELECT sull'AID A0000006472F0001 (la risposta FIDO_2_0 o U2F_V2 dice cosa parla), poi incapsula ogni messaggio CTAP2 in un APDU con CLA 0x80 e INS 0x10 (NFCCTAP_MSG). Non ci sono keepalive asincroni: se l'operazione è lunga, la chiavetta risponde con lo status 9100 e la piattaforma interroga con NFCCTAP_GETRESPONSE. La user presence è implicita: avvicinare la chiavetta al lettore è il gesto.

USB HIDNFCBLE (GATT)Hybrid
Livello fisicoUSB, report da 64 BISO 14443, APDU ISO 7816-4GATT, service 0xFFFDAnnuncio BLE + WebSocket via internet
Frammentazioneinit 57 B, cont 59 BAPDU chaining o extended lengthframmenti di fidoControlPointLengthMessaggi interi nel tunnel
Cifratura del trasportoNo (cavo)No (pochi cm)Pairing BLE (LE Secure Connections)Noise end-to-end
User presenceTocco sul sensoreAvvicinare la chiavettaPulsanteUI del telefono
TipicoChiavette, desktopChiavette e telefoniPoche chiavette, ormai rareTelefono come autenticatore per il PC

Più chiavette collegate

Se ci sono due chiavette, il browser non sa quale vuoi usare. Manda a tutte un comando che richiede il tocco (authenticatorSelection, 0x0B, o un makeCredential fittizio sui dispositivi CTAP2.0), aspetta il primo tocco e cancella le altre con CTAPHID_CANCEL. Per questo lampeggiano tutte insieme.
11

PIN e pinUvAuthToken

Una chiavetta senza schermo né tastiera fa user verification con un PIN digitato sulla piattaforma. Il problema è ovvio: il PIN deve arrivare alla chiavetta senza viaggiare in chiaro e senza che un malware sul cavo possa riutilizzarlo. CTAP lo risolve con il protocollo clientPIN.

  1. Accordo di chiavi: la chiavetta espone una chiave ECDH P-256 effimera, la piattaforma ne genera una sua, entrambe calcolano Z. Con il protocollo 2, HKDF-SHA-256 ricava da Z una chiave HMAC e una AES-256.
  2. PIN cifrato: la piattaforma manda i primi 16 byte di SHA-256(PIN), cifrati in AES-CBC con IV casuale. La chiavetta confronta con l'hash salvato.
  3. Token: se il PIN è giusto, la chiavetta restituisce un pinUvAuthToken cifrato, con permessi (mc, ga, cm…) e legato a un rpId. Il token vive in RAM e scade.
  4. Autorizzazione dei comandi: ogni makeCredential o getAssertion porta pinUvAuthParam = HMAC-SHA-256(token, clientDataHash). La chiavetta lo ricalcola e imposta UV = 1.
pinUvAuthParam del makeCredential di esempio
token          = 32 byte casuali (decifrati da getPinUvAuthToken)
clientDataHash = 03810f69dcb0fdcfe96cf36d66e81fc14478fc2414edd3b090b096cde2c19a23
pinUvAuthParam = HMAC-SHA-256(token, clientDataHash)   // protocollo 2: 32 B
                                                       // protocollo 1: primi 16 B

Il PIN ha 8 tentativi in tutto; dopo 3 errori consecutivi la chiavetta pretende di essere scollegata e ricollegata, così un malware non può provarli tutti in un colpo. Esauriti i tentativi, l'unica strada è il reset, che cancella tutte le credenziali. Le chiavette con lettore di impronte usano lo stesso schema: getPinUvAuthTokenUsingUvWithPermissions (subCommand 0x06) ottiene il token con la biometria invece che con il PIN.

12

Il telefono come autenticatore: hybrid via BLE

Il caso più comune oggi: sei su un PC che non ha la tua passkey, che invece sta nel telefono. Il browser mostra un QR code, lo inquadri, confermi con l'impronta, e sul PC sei dentro. Il trasporto si chiama hybrid (CTAP 2.2; era caBLE v2, «cloud-assisted BLE») ed è un ibrido davvero: il Bluetooth serve solo a dimostrare la vicinanza, mentre i dati passano da internet, attraverso un tunnel server, cifrati end-to-end con Noise.

Perché non tutto in Bluetooth? Il vecchio trasporto BLE di CTAP richiede pairing, e il pairing tra un telefono e un PC qualunque è fragile e invasivo. Perché non tutto via internet? Perché un QR code si può fotografare e inoltrare: un sito di phishing potrebbe mostrare all'utente il QR generato dal PC dell'attaccante. Con hybrid il PC deve ricevere via radio un annuncio del telefono per poter aprire il tunnel: se il PC è dall'altra parte del mondo, non lo riceve.

Login dal PC con la passkey del telefono (hybrid)Sequence
UtenteTelefonoauthenticator appTunnel servercable.ua5v.comBrowser / OSPCSitoexample.com1 · QR code2 · Prossimità e tunnel3 · Handshake Noise4 · CTAP2 nel tunnel1credentials.get(...)2identity key + qrSecret → QR «FIDO:/…»3inquadra il QR con la fotocamera4HKDF: eidKey, tunnelId5WSS /cable/new/<tunnelId>6X-caBLE-Routing-ID7advert BLE: EID cifrato (20 B)8decifra EID, ricava psk9WSS /cable/connect/<routingId>/<tunnelId>10→ psk, e11← e, ee, se12post-handshake: getInfo (+ linking)130x02 getAssertion (cifrato)14«Accedi a example.com?»15impronta / volto16firma con la passkey sincronizzata1700 + assertion (cifrata)18PublicKeyCredential (hybrid)
passo 1 / 18 · locale

1 · QR code

1. Nessuna passkey su questo PC

Sul PC non c'è una passkey per example.com, oppure l'utente sceglie «Usa un telefono o un tablet». Il browser (o Windows, o macOS) avvia il trasporto hybrid, standardizzato in CTAP 2.2 e noto prima come caBLE v2.
Linea puntinata: annuncio Bluetooth LE. Linee in accento: messaggi cifrati Noise, che attraversano il tunnel server senza che possa leggerli. Il valore di QR, annuncio, routing ID e chiavi derivate è stato calcolato davvero.

Le chiavi in gioco

Tutto discende da due valori nel QR: la identity key pubblica del PC e un qrSecret di 16 byte. Da qrSecret, con HKDF, entrambi derivano la chiave dell'annuncio (EID key) e il tunnel ID. Dall'annuncio decifrato, insieme a qrSecret, derivano la psk dell'handshake. Nell'handshake Noise_KNpsk0_P256_AESGCM_SHA256 il telefono autentica il PC tramite la identity key letta nel QR, la psk lega la sessione al QR e al Bluetooth, le chiavi effimere danno forward secrecy. Il tunnel server vede due WebSocket e byte cifrati.

annuncio BLE (service data, UUID 0xFFF9)
┌──────────── AES-256(eidKey[0:32]) ────────────┐┌ HMAC[0:4] ┐
│ 00 │ nonce (10 B) │ routing ID (3 B) │ dom (2) ││  tag (4)  │
└────────────────────────────────────────────────┘└───────────┘
  20 byte in tutto: entrano in un singolo advertisement BLE legacy.
  Nessuna connessione GATT, nessun pairing.

Linking: la seconda volta senza QR

Dopo il primo uso il telefono può offrire al PC dei dati di linking: un identificativo per contattarlo con una notifica push e un segreto condiviso. La volta successiva il PC mostra il telefono nell'elenco, lo sveglia via push con i parametri del tunnel, e il resto è identico, annuncio BLE compreso: anche un dispositivo collegato deve essere vicino. È così che Chrome mostra «Usa il telefono di Gianni» senza QR.

E il vecchio CTAP su BLE?

Esiste ancora, per le chiavette Bluetooth: un servizio GATT FIDO (UUID 0xFFFD) con le caratteristiche fidoControlPoint (scrittura delle richieste), fidoStatus (notifiche con le risposte), fidoControlPointLength e fidoServiceRevisionBitfield. I frame hanno un byte di comando (0x83 MSG, 0x82 KEEPALIVE, 0xBF ERROR), due di lunghezza e frammenti con numero di sequenza, come nel widget sopra. Richiede pairing con LE Secure Connections. È poco diffuso: per i telefoni ha vinto hybrid.

13

Passkey sincronizzate e flag BE/BS

Per anni FIDO ha avuto un problema di adozione: se la chiave privata non esce mai dal dispositivo, perdere il dispositivo vuol dire perdere l'account. Le passkey sincronizzate cambiano il compromesso: la chiave privata viene cifrata end-to-end e copiata sui dispositivi dello stesso utente dal gestore di passkey (Portachiavi iCloud, Google Password Manager, gestori di password di terze parti). Il server lo sa grazie a due flag dell'authenticatorData.

Device-boundSincronizzata
FlagBE = 0, BS = 0BE = 1, BS = 1 (BS può cambiare nel tempo)
EsempiChiavetta FIDO2, chiave in un TPMPortachiavi iCloud, Google Password Manager, 1Password, Bitwarden
Chiave privataNon esportabile, in hardwareCifrata end-to-end e copiata sui dispositivi dell'utente
Se perdi il dispositivoPerdi la credenziale: registrane almeno dueLa recuperi dal gestore
signCountCresce a ogni usoDi solito 0
AttestationSì, verificabile con il Metadata ServiceDi norma none
Livello di assuranceAAL3 (NIST SP 800-63B-4)AAL2

BE (Backup Eligible) è fisso per tutta la vita della credenziale: dice se può essere sincronizzata. BS (Backup State) può cambiare: dice se è sincronizzata ora. Un uso pratico: se una credenziale è l'unico metodo di accesso e ha BS = 0, conviene suggerire all'utente di registrarne un'altra. Se invece la policy richiede chiavi non esportabili, il server rifiuta BE = 1 in registrazione.

Per spostare le passkey da un gestore all'altro, FIDO Alliance ha definito il Credential Exchange Protocol e Format (CXP/CXF). Per tenere allineati sito e gestore, WebAuthn Level 3 ha la Signal API: signalUnknownCredential (questa credenziale non esiste più sul server), signalAllAcceptedCredentials e signalCurrentUserDetails (l'utente ha cambiato email o nome).

14

Implementazione lato server

Il parsing di CBOR, COSE, attestation e firme DER non va scritto a mano in produzione. Ogni linguaggio ha una libreria matura: in Node.js SimpleWebAuthn, in Java webauthn4j o java-webauthn-server di Yubico, in Go go-webauthn, in Python py_webauthn, in .NET fido2-net-lib. Keycloak, Auth0, Entra ID e gli altri identity provider le integrano. Ecco i due endpoint con SimpleWebAuthn.

registrazione · @simplewebauthn/server
import { generateRegistrationOptions, verifyRegistrationResponse } from "@simplewebauthn/server";

const rpID = "example.com";
const expectedOrigin = ["https://login.example.com"];

// POST /webauthn/register/options
const options = await generateRegistrationOptions({
  rpName: "Example",
  rpID,
  userName: user.email,
  userID: user.webauthnHandle,              // 16-64 byte casuali, non l'email
  attestationType: "none",
  excludeCredentials: user.credentials.map((c) => ({ id: c.id, transports: c.transports })),
  authenticatorSelection: { residentKey: "required", userVerification: "preferred" },
});
session.challenge = options.challenge;      // monouso, scadenza breve
return options;

// POST /webauthn/register/verify
const { verified, registrationInfo } = await verifyRegistrationResponse({
  response: body,
  expectedChallenge: session.challenge,
  expectedOrigin,
  expectedRPID: rpID,
});
delete session.challenge;
if (verified) {
  const { credential, credentialDeviceType, credentialBackedUp, aaguid } = registrationInfo;
  await db.credentials.insert({
    id: credential.id,
    publicKey: credential.publicKey,        // COSE_Key, Uint8Array
    counter: credential.counter,
    transports: credential.transports,
    userId: user.id,
    deviceType: credentialDeviceType,       // "singleDevice" | "multiDevice" (BE)
    backedUp: credentialBackedUp,           // BS
    aaguid,
  });
}
autenticazione · @simplewebauthn/server
import { generateAuthenticationOptions, verifyAuthenticationResponse } from "@simplewebauthn/server";

// POST /webauthn/login/options
const options = await generateAuthenticationOptions({ rpID, userVerification: "preferred" });
session.challenge = options.challenge;

// POST /webauthn/login/verify
const cred = await db.credentials.findById(body.id);
if (!cred) throw new Unauthorized();
if (body.response.userHandle && body.response.userHandle !== cred.userHandle) throw new Unauthorized();

const { verified, authenticationInfo } = await verifyAuthenticationResponse({
  response: body,
  expectedChallenge: session.challenge,
  expectedOrigin,
  expectedRPID: rpID,
  credential: { id: cred.id, publicKey: cred.publicKey, counter: cred.counter, transports: cred.transports },
});
delete session.challenge;
if (!verified) throw new Unauthorized();

await db.credentials.update(cred.id, {
  counter: authenticationInfo.newCounter,
  backedUp: authenticationInfo.credentialBackedUp,
  lastUsedAt: new Date(),
});
startSession(cred.userId);

Errori classici

Challenge riutilizzabili o non legate alla sessione. Origin non verificata, o verificata con startsWith. rpId diverso tra registrazione e login (la credenziale «sparisce»). user handle uguale all'email. Nessuna excludeCredentials, e l'utente registra due volte la stessa chiavetta. Nessun modo per gestire le passkey: l'utente deve poterle vedere, rinominare e revocare.
15

Threat model: cosa protegge e cosa no

WebAuthn risolve molto bene un problema preciso: dimostrare che l'utente possiede una chiave legata a questo sito, senza segreti riutilizzabili. Tutto quello che sta intorno resta da progettare.

Phishing e AitM

Un proxy alla Evilginx inoltra password, OTP e push, ma non una firma WebAuthn: il browser scrive nel clientDataJSON l'origin del proxy, e l'rpIdHash sarebbe quello del dominio falso. Il punto debole diventa il fallback: se il login accetta ancora password + SMS, l'attaccante farà un downgrade.

Sottodomini

Una credenziale con rpId example.com è utilizzabile da qualunque sottodominio. Un sottodominio compromesso o preso con un DNS dimenticato (subdomain takeover) può chiedere asserzioni valide. Scegli l'rpId più stretto che ti serve e tieni l'inventario dei sottodomini.

XSS sull'origin del sito

WebAuthn lega la firma all'origin, non al codice: uno script iniettato nella tua pagina può chiamare credentials.get() e ottenere un'asserzione, se l'utente fa il gesto. Content Security Policy e igiene del frontend restano necessarie.

Furto della sessione

Dopo il login c'è un cookie. Un infostealer che lo copia salta l'autenticazione. Cookie brevi, rotazione, e per il futuro Device Bound Session Credentials, che legano la sessione a una chiave del dispositivo.

Recupero dell'account

Se perdere le passkey si risolve con «mandami un link via email», la sicurezza dell'account è quella dell'email. Offri più passkey, codici di recupero, verifiche di identità proporzionate al rischio.

Client compromesso

Browser e sistema operativo sono fidati per definizione: sono loro a scrivere l'origin. Un'estensione malevola con i permessi giusti o un malware con privilegi elevati possono chiedere firme per qualunque sito.

Account del gestore di passkey

Una passkey sincronizzata è sicura quanto l'account che la sincronizza (Apple, Google, gestore di password). I gestori cifrano end-to-end, ma proteggere quell'account diventa critico.

Privacy

Lo user handle non deve contenere email o nomi: alcuni autenticatori lo restituiscono senza UV. L'attestation diretta rivela il modello: chiedila solo se la usi davvero, e in ambito enterprise usa enterprise attestation.

16

In sintesi

  1. 1Le passkey sostituiscono un segreto condiviso con una coppia di chiavi per sito: il server conserva solo chiavi pubbliche.
  2. 2La resistenza al phishing nasce dal client: il browser scrive l'origin nel clientDataJSON e l'autenticatore firma l'hash dell'rpId.
  3. 3In registrazione il server verifica clientDataJSON, rpIdHash, flag e attestation, e salva la chiave COSE; in login verifica una firma su authenticatorData ‖ SHA-256(clientDataJSON).
  4. 4authenticatorData è un formato a campi fissi: rpIdHash, flag UP/UV/BE/BS/AT/ED, contatore e, alla creazione, AAGUID, credential ID e chiave pubblica.
  5. 5CTAP2 è il protocollo verso gli autenticatori esterni: comandi a un byte e mappe CBOR canoniche con chiavi intere.
  6. 6Su USB viaggia in report HID da 64 byte con canali, frammentazione e keepalive; su NFC in APDU; il PIN passa cifrato via ECDH e autorizza i comandi con un HMAC.
  7. 7Con hybrid il telefono fa da autenticatore per il PC: QR per le chiavi, Bluetooth solo per la prossimità, tunnel cifrato Noise per i messaggi CTAP.
  8. 8Passkey sincronizzate (BE/BS) per gli utenti consumer, chiavi device-bound con attestation dove serve l'assurance più alta. E nessun fallback debole.

Per approfondire: W3C Web Authentication Level 3, FIDO Client to Authenticator Protocol 2.2 (in particolare le sezioni su CTAPHID, NFC, BLE e hybrid), FIDO Metadata Service 3, RFC 8949 (CBOR), RFC 9052 e 9053 (COSE), il framework Noise, NIST SP 800-63B-4 e la documentazione di passkeys.dev.

GP

Lead | Solution Architect – CIAM & API Security

Fatto con da Gianni

© 2026 Tutti i diritti riservati

Costruito con Next.js & Tailwind CSS