📚 3記事シリーズ
- 設計・脅威モデル編(Zenn)
- 思想・運用編(note)
- 実装編(この記事)
- passkey-vault-kit(MIT)
- 基礎資料:パスキーとセキュリティシアター
パスワードを預からず、ユーザーの中身も運営が読めないWebサービスを、実装の手を動かして作ります。コードは読書メモアプリ「栞」から取り出した部品 pkvault より引用します(行番号は執筆時点)。
全体像
| 層 | 手段 |
|---|---|
| 認証 | パスキー(WebAuthn PRF)。サーバは公開鍵のみ、秘密は無い |
| 保管 | レコード単位の端末暗号化(AES-256-GCM、WebCryptoのみ) |
| 鍵の預け方 | データ鍵をPRF由来の鍵で包んでサーバへ |
| 同期 | 暗号文のまま。AADで取り替え・巻き戻しを検出 |
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不一致で弾かれます。
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リセット等)は入れない。復旧経路の強度=本当の強度。
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は平文(メタデータは見える)
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. 守れること・守れないこと
守れる:DB・バックアップ漏洩に強い/総当たり対象のパスワードが無い/フィッシング耐性(オリジン束縛)/取り替え・ロールバック検出。
守れない:配るスクリプトの改ざん(CSP等で軽減するが原理的限界)/セッションクッキー窃取・端末乗っ取り/メタデータ(名前・IP・件数・大きさ)/パスキーと復旧キーの両方紛失=復旧不能。
設計思想と脅威モデルの整理は → [Zenn版]、思想・運用の話は → [note版]。
行番号は pkvault(MIT)コミット956cee8のstatic/pkvault/pkvault-crypto.jsと一致確認済み(2026-11-19)。リンクはこのコミットのGitHubパーマリンク(.../blob/956cee8/...#L86形式)で貼ると、以後の更新でもズレません。




