0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

パスキーだけでログインし、中身は端末で暗号化する ― WebAuthn PRF+AES-256-GCM の実装

0
Last updated at Posted at 2026-11-19

📚 3記事シリーズ

パスワードを預からず、ユーザーの中身も運営が読めないWebサービスを、実装の手を動かして作ります。コードは読書メモアプリ「栞」から取り出した部品 pkvault より引用します(行番号は執筆時点)。


全体像

層 手段
認証 パスキー(WebAuthn PRF)。サーバは公開鍵のみ、秘密は無い
保管 レコード単位の端末暗号化(AES-256-GCM、WebCryptoのみ)
鍵の預け方 データ鍵をPRF由来の鍵で包んでサーバへ
同期 暗号文のまま。AADで取り替え・巻き戻しを検出

04_key_wrap.png


1. 暗号の土台:AADに文脈を焼き込む

肝は AAD(追加認証データ)に「誰の・何の・どの版か」を入れること(static/pkvault/pkvault-crypto.js)。

// seal: 版(1B)+ノンス(12B)+暗号文。aadも封に入れる  (:86)
async function seal(key, bytes, aad) {
  const iv = random(12);
  const ct = new Uint8Array(await subtle.encrypt(
    { name: 'AES-GCM', iv, additionalData: enc.encode(aad) }, key, bytes));
  const out = new Uint8Array(1 + 12 + ct.length);
  out[0] = VERSION; out.set(iv, 1); out.set(ct, 13);
  return b64u(out);
}
// open: 形・版・封(aad)のどれかが違えば失敗  (:96)
async function open(key, blob, aad) {
  const a = unb64u(blob);
  if (a.length < 1 + 12 + 16 || a[0] !== VERSION) throw new Error('bad blob');
  return new Uint8Array(await subtle.decrypt(
    { name: 'AES-GCM', iv: a.subarray(1, 13), additionalData: enc.encode(aad) }, key, a.subarray(13)));
}

GCMは認証付き暗号なので、AADが1文字違えば復号は必ず失敗します。


2. 鍵の設計:データ鍵を3通りに包む

唯一の鍵(データ鍵)を平文で保存せず、HKDFで用途別に鍵を導出して包みます。

// HKDF-SHA256で用途ごとに別鍵。作った鍵は取り出せない  (:76)
async function derive(ikm, label, usages = ['encrypt', 'decrypt']) {
  const base = await subtle.importKey('raw', ikm, 'HKDF', false, ['deriveKey', 'deriveBits']);
  return subtle.deriveKey(
    { name: 'HKDF', hash: 'SHA-256', salt: SALT, info: enc.encode(label) },
    base, { name: 'AES-GCM', length: 256 }, false, usages);
}

// パスキーのPRF出力でデータ鍵を包む  (:113)
const passkeyAad = (uid, credId) => `${prefix}/wrap/passkey|${uid}|${credId}`;
const wrapForPasskey = async (raw, prfOut, uid, credId) =>
  seal(await derive(prfOut, 'wrap/passkey'), raw, passkeyAad(uid, credId));
包み 鍵の由来 置き場所
パスキーの包み WebAuthn PRF 出力 サーバー
復旧キーの包み 復旧キー サーバー(復旧時のみ開く)
端末の控え 端末鍵(IndexedDB・取り出し不可)+サーバ割符 端末

サーバは包みを預かるが、開ける鍵は端末にしか無い。


3. サーバを信用しない

3.1 取り替え・ロールバック検出

const recordAad = (uid, kind, id, ver) => `${prefix}/rec|${uid}|${kind}|${id}|${ver}`;  // :162

AADに版番号まで入るので、サーバが暗号文を取り替え/古い版に巻き戻すと、復号時にAAD不一致で弾かれます。

06_rollback_detect.png

3.2 長さの秘匿(256Bパディング)

async function sealRecord(dataKey, obj, uid, kind, id, ver) {   // :163
  const body = enc.encode(JSON.stringify(obj));
  const size = Math.ceil((body.length + 4) / PAD) * PAD;  // PAD=256。先頭4Bに本当の長さ
  const buf = new Uint8Array(size);
  new DataView(buf.buffer).setUint32(0, body.length);
  buf.set(body, 4);
  return seal(dataKey, buf, recordAad(uid, kind, id, ver));
}

3.3 レコードIDもサーバから読めない

async function recordId(text) {   // :188
  const mac = new Uint8Array(await subtle.sign('HMAC', need().idKey, enc.encode(text)));
  return b64u(mac.subarray(0, 16));
}

3.4 CSRF

/api/ の変更系は X-PKV: 1 ヘッダを必須化。


4. 復旧:ユーザーID+復旧キー+総当たり対策

サーバは照合値しか持たず、「包みを開ける値」は端末から出しません。

// 送るのは確認用の値だけ。ここから復旧キーも開ける値も計算できない  (:129)
const recoveryAuth = async key => hex(await deriveBits(enc.encode(normRecovery(key)), 'recovery/auth'));
const wrapForRecovery = async (raw, key, uid) =>
  seal(await derive(enc.encode(normRecovery(key)), 'recovery/wrap'), raw, recoveryAad(uid));

総当たり対策は 作業証明(PoW) + IDごと・ネットワークごと・IPv6 /64 単位のレート制限。

方針:セキュリティを下げる復旧手段(メール/SMSリセット等)は入れない。復旧経路の強度=本当の強度。

03_recovery_key.png
※画像のユーザー名と復旧キーはダミー用です。


5. 検証:サーバは暗号文しか持たない

sample(sample/app.py, localhost:5180)で1件保存してDBを覗いた実測:

  • records 行:id は題名ではなく HMAC、blob は380Bの暗号文、size: 380
  • GET /api/usage → { "notes": 1, "bytes": 380 }(件数と大きさだけ)
  • users.name は平文(メタデータは見える)

07_ciphertext_proof.png


6. テスト(ここがいちばん効く)

ファイル 項目 主な検証
test_server.py 71 CSRF・チャレンジ使い回し・別サイトの答え・他人の記録・上限・版・本人確認・端末ログアウト・物理キー・復旧の総当たり対策(PoW・IDごと・網ごと・IPv6 /64)・送り元偽装・退会掃除・8台同時保存
test_e2e.mjs 40 本物のサーバに試験用パスキーの端末を複数接続。登録→同期→重なり→削除→送信前に閉じた変更→すり替え→復旧→退会。ランダム操作300回で全端末の収束(SEEDで再現)
test_crypto.mjs 15 改ざん検出ほか。+栞との相互復号5項目(crypto_prefix="shiori/v1")
.venv/Scripts/python tests/test_server.py
node tests/test_e2e.mjs
node tests/test_crypto.mjs

7. 守れること・守れないこと

09_protect_matrix.png

守れる:DB・バックアップ漏洩に強い/総当たり対象のパスワードが無い/フィッシング耐性(オリジン束縛)/取り替え・ロールバック検出。

守れない:配るスクリプトの改ざん(CSP等で軽減するが原理的限界)/セッションクッキー窃取・端末乗っ取り/メタデータ(名前・IP・件数・大きさ)/パスキーと復旧キーの両方紛失=復旧不能。

設計思想と脅威モデルの整理は → [Zenn版]、思想・運用の話は → [note版]。
行番号は pkvault(MIT)コミット 956cee8 の static/pkvault/pkvault-crypto.js と一致確認済み(2026-11-19)。リンクはこのコミットのGitHubパーマリンク(.../blob/956cee8/...#L86 形式)で貼ると、以後の更新でもズレません。

あわせて読む

  • 設計と脅威モデルの整理 → Zenn版
  • 思想・運用の話 → note版
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?