From 3bd81251eff194b36a5d3118e7870926947c8100 Mon Sep 17 00:00:00 2001 From: sudoHG Date: Tue, 10 Nov 2026 15:38:02 +0800 Subject: [PATCH] Record the Mac's device key item layout in ADR 0013 #287 authenticates each Secure Enclave key item with an HMAC tag under a key derived from the vault key, so blobs another process planted before the first pairing are refused. ADR 0013 described the paired-device list tag but not the key items; record the layout next to the key storage. --- docs/adr/0013-device-identity-and-pairing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/adr/0013-device-identity-and-pairing.md b/docs/adr/0013-device-identity-and-pairing.md index 68b2ba6..1cd8356 100644 --- a/docs/adr/0013-device-identity-and-pairing.md +++ b/docs/adr/0013-device-identity-and-pairing.md @@ -61,6 +61,7 @@ The Mac bundle ID `com.sudohg.askkey.app` and the other product identifiers in ` - The Secure Enclave returns each key as a wrapped blob that any process on the same device can use once it has the blob. The blobs are stored like the vault key: - Mac: the login keychain, under the existing App service with the App-only access already used for the vault key, accounts `device-message-key`, `device-agreement-key` and `device-approval-key`. - iPhone: the data protection keychain, accessible after first unlock, this device only, in the access group above, so the stage 4 notification extension can read the message and key-agreement keys. + - On the Mac each key item holds the blob followed by a 32-byte HMAC-SHA256 tag over `AskKey device key blob v1` (with its NUL), the item's account name followed by a NUL, and the blob, under a key derived from the vault key with HKDF-SHA256, an empty salt and the info `AskKey device key blob key v1` (with its NUL). The tag is checked before the blob is used. Because any process on the Mac can use a blob it holds, this refuses an identity Ask Key did not write, such as blobs another App planted before the first pairing while keeping copies; the person is offered the reset. This layout was added after the cross review of #287. - Key access control: - Message and key-agreement keys, on both platforms: `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` with `privateKeyUsage` and no per-use authentication. Routine messages (requests, replies, unpair notices) are signed and decrypted without a prompt, including by a locked phone's notification extension and a Mac with a locked screen in stage 4. - iPhone approval key: `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` with `privateKeyUsage` and `biometryCurrentSet`. Each approval signature uses a new authentication context that is invalidated afterwards, whether it succeeded or was cancelled, so every signature asks for Face ID or Touch ID; an earlier authentication or the phone's unlock is never reused. Enrolling a new face or finger invalidates the key; the phone then has to pair again with each Mac. The prompt offers no passcode button (an empty fallback title); separately, the key's access control is what keeps a passcode from satisfying it. An enrollment change shows up the next time the approval key is used, which in stage 2 is the next pairing and in stage 4 the next approval; the key then fails and the identity is reported unusable. A phone without Face ID or Touch ID set up cannot pair.