WebAuthn & Passkeys Deep Dive — FIDO2, Attestation, Passkey Sync, 피싱 내성 인증 완전 정복 (2025)

┌──────────┐       ┌──────────┐       ┌──────────────┐
│   User   │◄─────►│  Browser │◄─────►│  RP (서버)    │
└─────┬────┘       │ (User    │       └──────────────┘
      │            │  Agent)  │
      │            └─────┬────┘
      │                  │
      │  (사용자 동의)    │  (WebAuthn)
      ▼                  ▼
┌──────────────────────────┐
│    Authenticator         │
│  (TouchID / YubiKey /    │
│   Windows Hello / ...)   │
└──────────────────────────┘

1. RP가 registration options 생성 → Browser에 JSON 전달
2. Browser가 navigator.credentials.create(options) 호출
3. Browser가 Authenticator에 요청 전달
4. Authenticator가 사용자 승인 요청 (UV)
5. Authenticator가 키 쌍 생성
6. Authenticator가 Attestation + 공개 키를 Browser에 반환
7. Browser가 RP에 전달
8. RP가 검증 후 공개 키 DB에 저장

// 서버 (RP)
const options = {
  challenge: crypto.randomBytes(32),  // 랜덤
  rp: {
    name: "Example Corp",
    id: "example.com",
  },
  user: {
    id: userIdBytes,  // 사용자 고유 ID (bytes)
    name: "alice@example.com",
    displayName: "Alice",
  },
  pubKeyCredParams: [
    { alg: -7, type: "public-key" },   // ES256 (ECDSA P-256)
    { alg: -257, type: "public-key" }, // RS256
  ],
  authenticatorSelection: {
    authenticatorAttachment: "platform",  // 또는 "cross-platform"
    residentKey: "preferred",
    userVerification: "preferred",
  },
  timeout: 60000,
  attestation: "none",
};

res.json({ options });

// 브라우저 (페이지 JavaScript)
const credential = await navigator.credentials.create({
  publicKey: options,  // 서버에서 받은 옵션
});

// credential.response.attestationObject
// credential.response.clientDataJSON
// credential.rawId

{
  "type": "webauthn.create",
  "challenge": "<base64url(random)>",
  "origin": "https://example.com",
  "crossOrigin": false
}

┌────────────────────────────────────────────┐
│ RP ID Hash (32 bytes, SHA-256 of RP ID)    │
├────────────────────────────────────────────┤
│ Flags (1 byte)                             │
│   - UP (User Present)                      │
│   - UV (User Verified)                     │
│   - AT (Attested credential data included) │
│   - ED (Extension data included)           │
├────────────────────────────────────────────┤
│ Sign Counter (4 bytes)                     │
├────────────────────────────────────────────┤
│ AAGUID (16 bytes) - 인증기 모델 ID           │
├────────────────────────────────────────────┤
│ Credential ID Length (2 bytes)             │
├────────────────────────────────────────────┤
│ Credential ID (variable)                   │
├────────────────────────────────────────────┤
│ Credential Public Key (CBOR)               │
├────────────────────────────────────────────┤
│ Extensions (optional, CBOR)                │
└────────────────────────────────────────────┘

// 서버
const { clientDataJSON, attestationObject } = credential.response;

// 1. Client data parse
const clientData = JSON.parse(Buffer.from(clientDataJSON).toString());

// 2. 검증
if (clientData.type !== 'webauthn.create') throw new Error('wrong type');
if (clientData.challenge !== expectedChallenge) throw new Error('bad challenge');
if (clientData.origin !== 'https://example.com') throw new Error('bad origin');

// 3. Attestation object parse (CBOR)
const attObj = CBOR.decode(attestationObject);
// attObj.fmt: "none" | "packed" | "fido-u2f" | "tpm" | "android-key" | "apple"
// attObj.authData: bytes
// attObj.attStmt: attestation statement (알고리즘별)

// 4. Auth data parse
const authData = parseAuthData(attObj.authData);
// rpIdHash, flags, signCount, aaguid, credId, publicKey

// 5. RP ID 해시 일치 확인
if (!authData.rpIdHash.equals(sha256('example.com'))) throw new Error('bad rpId');

// 6. Flags 확인
if (!authData.flags.UP) throw new Error('user not present');
if (requireUV && !authData.flags.UV) throw new Error('user not verified');

// 7. Attestation 검증 (fmt에 따라)
if (attObj.fmt === 'packed') {
    verifyPackedAttestation(attObj, clientDataJSON);
}

// 8. DB 저장
db.users.update(userId, {
    credentials: [{
        credId: authData.credId,
        publicKey: authData.publicKey,
        signCount: authData.signCount,
        aaguid: authData.aaguid,
    }]
});

1. RP가 assertion options 생성 → 브라우저에
2. Browser가 navigator.credentials.get(options) 호출
3. Browser가 Authenticator에 요청
4. Authenticator가 사용자 인증
5. Authenticator가 challenge를 private key로 서명
6. Browser가 서명 + 공개 키 정보를 RP에 전달
7. RP가 저장된 공개 키로 서명 검증

const options = {
  challenge: crypto.randomBytes(32),
  rpId: "example.com",
  timeout: 60000,
  allowCredentials: [
    {
      id: existingCredId,  // 사용자의 credId 바이트
      type: "public-key",
      transports: ["internal", "usb", "nfc", "ble"],
    }
  ],
  userVerification: "preferred",
};

const assertion = await navigator.credentials.get({
  publicKey: options,
});

// assertion.response.authenticatorData
// assertion.response.clientDataJSON
// assertion.response.signature
// assertion.response.userHandle (optional)

signature = sign(privateKey, authenticatorData || SHA256(clientDataJSON))

const { authenticatorData, clientDataJSON, signature } = assertion.response;

// 1. Client data 검증 (type, challenge, origin)
const clientData = JSON.parse(Buffer.from(clientDataJSON).toString());
if (clientData.type !== 'webauthn.get') throw new Error('wrong type');
// ... challenge/origin 검증

// 2. Authenticator data parse
const authData = parseAuthData(authenticatorData);
if (!authData.rpIdHash.equals(sha256('example.com'))) throw new Error('bad rpId');
if (!authData.flags.UP) throw new Error('user not present');

// 3. 서명 검증
const credId = assertion.rawId;
const credential = db.getCredential(credId);

const signedData = Buffer.concat([
    authenticatorData,
    sha256(clientDataJSON),
]);

const valid = verifySignature(
    credential.publicKey,
    signedData,
    signature,
    credential.alg  // ES256, etc
);

if (!valid) throw new Error('bad signature');

// 4. Sign counter 검증 (옵션, clone 감지)
if (authData.signCount !== 0 && authData.signCount <= credential.signCount) {
    console.warn('Possible credential clone!');
}

// 5. Update counter
db.updateCredential(credId, { signCount: authData.signCount });

// 6. 로그인 완료
session.userId = credential.userId;

JSON: {"a": 1, "b": "hello"}
     = 22 bytes

CBOR: a26161016162656865 6c6c6f
     = 9 bytes (59% 감소)

{
  "fmt": "packed",
  "authData": h'...',
  "attStmt": { ... }
}

ES256 public key in COSE format:
{
  1: 2,         // kty = EC2
  3: -7,        // alg = ES256
  -1: 1,        // crv = P-256
  -2: h'<x coordinate>',
  -3: h'<y coordinate>',
}

attStmt: {
  "alg": -7,
  "sig": <인증기 attestation key로 서명>,
  "x5c": [<attestation certificate chain>]
}

authenticatorData || clientDataHash

1. 사용자가 username 입력.
2. 서버가 allowCredentials를 user의 저장된 credential로 세팅.
3. 인증기가 그 credential로 서명.

1. 사용자가 아무것도 입력 안 함.
2. 서버가 allowCredentials = [] 로 요청.
3. 브라우저가 인증기들에 "discoverable credential 있어?" 물음.
4. 인증기가 "네, 이거 있어요" + 사용자 선택 UI.
5. 사용자 선택 + 지문 → 서명.
6. 서버가 `userHandle`로 사용자 식별.

1. 노트북이 브라우저에서 로그인 시작.
2. 브라우저가 QR 코드 표시.
3. 폰으로 QR 스캔.
4. 폰과 노트북이 BLE로 proximity 확인.
5. 폰이 서명 후 결과를 노트북에 전달 (암호화).
6. 노트북이 서버에 전달.

<input type="text" autocomplete="username webauthn">

navigator.credentials.get({
    publicKey: options,
    mediation: "conditional"
});

CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR UNIQUE NOT NULL,
    display_name VARCHAR,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE credentials (
    id BYTEA PRIMARY KEY,            -- credential ID (bytes)
    user_id UUID REFERENCES users(id),
    public_key BYTEA NOT NULL,       -- COSE 형식
    algorithm INT NOT NULL,
    counter BIGINT DEFAULT 0,
    transports VARCHAR[],
    aaguid UUID,
    backup_eligible BOOLEAN,
    backup_state BOOLEAN,
    name VARCHAR,                    -- "Alice's iPhone"
    created_at TIMESTAMP DEFAULT NOW(),
    last_used_at TIMESTAMP
);

CREATE INDEX idx_credentials_user ON credentials(user_id);

// POST /webauthn/register/begin
app.post('/webauthn/register/begin', async (req, res) => {
    const user = req.user;  // 로그인 또는 새 사용자
    const options = generateRegistrationOptions({
        rpName: "Example",
        rpID: "example.com",
        userID: user.id,
        userName: user.email,
        attestationType: "none",
        authenticatorSelection: {
            residentKey: "required",
            userVerification: "preferred",
        },
    });

    // challenge 세션에 저장
    req.session.currentChallenge = options.challenge;
    res.json(options);
});

// POST /webauthn/register/complete
app.post('/webauthn/register/complete', async (req, res) => {
    const { body } = req;
    const expectedChallenge = req.session.currentChallenge;

    const verification = await verifyRegistrationResponse({
        response: body,
        expectedChallenge,
        expectedOrigin: "https://example.com",
        expectedRPID: "example.com",
    });

    if (verification.verified) {
        const { credentialID, credentialPublicKey, counter } =
            verification.registrationInfo;
        await db.credentials.insert({
            id: credentialID,
            userId: req.user.id,
            publicKey: credentialPublicKey,
            counter,
        });
        res.json({ ok: true });
    } else {
        res.status(400).json({ ok: false });
    }
});

// POST /webauthn/login/begin
app.post('/webauthn/login/begin', async (req, res) => {
    const { email } = req.body;
    const options = generateAuthenticationOptions({
        rpID: "example.com",
        userVerification: "preferred",
        allowCredentials: email
            ? (await getCredsForEmail(email)).map(c => ({
                id: c.id,
                type: "public-key",
                transports: c.transports,
            }))
            : [],  // empty for discoverable
    });

    req.session.currentChallenge = options.challenge;
    res.json(options);
});

// POST /webauthn/login/complete
app.post('/webauthn/login/complete', async (req, res) => {
    const { body } = req;
    const credId = body.id;
    const credential = await db.credentials.findByCredId(credId);
    if (!credential) return res.status(404).json({});

    const verification = await verifyAuthenticationResponse({
        response: body,
        expectedChallenge: req.session.currentChallenge,
        expectedOrigin: "https://example.com",
        expectedRPID: "example.com",
        authenticator: {
            credentialID: credential.id,
            credentialPublicKey: credential.publicKey,
            counter: credential.counter,
        },
    });

    if (verification.verified) {
        await db.credentials.updateCounter(
            credential.id,
            verification.authenticationInfo.newCounter
        );
        req.session.userId = credential.userId;
        res.json({ ok: true });
    } else {
        res.status(400).json({});
    }
});

// Feature detection
if (window.PublicKeyCredential) {
    // WebAuthn 지원
}

// Conditional UI 지원 확인
if (await PublicKeyCredential.isConditionalMediationAvailable?.()) {
    // 자동완성 드롭다운 가능
}

// Platform authenticator 지원 확인
if (await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()) {
    // TouchID/Windows Hello 있음
}

<iframe allow="publickey-credentials-get"></iframe>

┌─────────────────────────────────────────────────────┐
│         WebAuthn / Passkeys Cheat Sheet              │
├─────────────────────────────────────────────────────┤
│ 4 Actors:                                             │
│   Relying Party (서버)                                │
│   User Agent (브라우저)                                │
│   Authenticator (TouchID/YubiKey)                    │
│   User                                                │
│                                                       │
│ 2 Ceremonies:                                         │
│   Registration: 키 쌍 생성 + 공개 키 등록              │
│   Authentication: challenge 서명 검증                 │
│                                                       │
│ 핵심 방어:                                             │
│   Origin 바인딩 (RP ID)                               │
│   브라우저가 강제                                      │
│   피싱 사이트에서 credential 사용 불가                  │
│                                                       │
│ Client Data:                                          │
│   type: "webauthn.create" or "webauthn.get"          │
│   challenge: 서버 생성 랜덤                            │
│   origin: 브라우저가 채움 (신뢰 가능)                   │
│                                                       │
│ Authenticator Data:                                   │
│   RP ID hash                                          │
│   Flags (UP, UV, AT, ED)                             │
│   Sign counter                                        │
│   AAGUID                                              │
│   Credential ID + Public Key (COSE)                  │
│                                                       │
│ 서명:                                                  │
│   sign(privKey, authData || sha256(clientData))      │
│   ES256 (기본), EdDSA, RS256                          │
│                                                       │
│ Attestation:                                          │
│   none (프라이버시)                                    │
│   packed/fido-u2f/tpm/apple                          │
│   FIDO Metadata Service로 검증                        │
│                                                       │
│ Credential 종류:                                      │
│   Server-side (non-resident)                          │
│   Discoverable (resident key)                         │
│                                                       │
│ Passkey = Discoverable credential + Sync:             │
│   iCloud Keychain / Google PM / MS Account           │
│   End-to-end encrypted                               │
│   Cross-device via caBLE/Hybrid (QR + BLE)           │
│                                                       │
│ Conditional UI:                                       │
│   autocomplete="username webauthn"                    │
│   자동완성 드롭다운                                    │
│                                                       │
│ 라이브러리:                                            │
│   @simplewebauthn/server (Node)                      │
│   py_webauthn (Python)                                │
│   webauthn4j (Java)                                  │
│   webauthn-rs (Rust)                                 │
│                                                       │
│ 검증 체크리스트:                                        │
│   ✓ clientData.type                                   │
│   ✓ clientData.challenge                              │
│   ✓ clientData.origin                                 │
│   ✓ authData.rpIdHash                                 │
│   ✓ authData.flags (UP, UV)                          │
│   ✓ 서명 (publicKey)                                  │
│   ✓ signCount (옵션)                                   │
└─────────────────────────────────────────────────────┘