Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Once the iPhone is paired, a read request that waits for you also goes to it: at

A request sent to the iPhone contains the agent's name and the purpose it states (both declared by the agent, not verified), the credential's name, the command line and working directory as the approval prompt shows them, the program's name, the names the credential is delivered as (environment variables and temporary files) with each part's name for a credential that has several, the deadline, the decisions offered with the length of a timed allowance, when Ask Key last started on the Mac, and a random ID and a digest that tie the answer to this one request. It never contains a credential's value or the content of any of its parts, file contents, the rest of the environment, the content of a write, the vault key, anything about Hidden credentials, or the Mac's name.

The iPhone's notification shows the request as one sentence, for example “Codex” on “MacBook Pro” wants to use “GitHub Token” to run deploy.sh, and only after Ask Key on the iPhone has fetched, decrypted and verified it as a request from a Mac you turned approval on for. Otherwise it says “A paired device sent a message.” A notification never shows a credential's value, the command's arguments, the folder or the variable names. The iPhone's Show Previews setting decides whether the details appear on the Lock Screen (by default only when the iPhone is unlocked), and delivered notifications stay in Notification Center until you clear them. Decide on the card in the Ask Key app, not on a notification's text: anyone who can write to your iCloud can make your devices show a notification with any text under Ask Key's name. The design is recorded in [ADR 0014](docs/adr/0014-remote-approval.md).
The iPhone's notification shows the request as one sentence, for example “Codex” on “MacBook Pro” wants to use “GitHub Token” to run deploy.sh, and only after Ask Key on the iPhone has fetched, decrypted and verified it as a request from a paired Mac whose requests this iPhone approves. Otherwise it says “A paired device sent a message.” A notification never shows a credential's value, the command's arguments, the folder or the variable names. The iPhone's Show Previews setting decides whether the details appear on the Lock Screen (by default only when the iPhone is unlocked), and delivered notifications stay in Notification Center until you clear them. Decide on the card in the Ask Key app, not on a notification's text: anyone who can write to your iCloud can make your devices show a notification with any text under Ask Key's name. The design is recorded in [ADR 0014](docs/adr/0014-remote-approval.md).

## Upgrade

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,17 @@ extension DeviceCoordinator {
/// its failure counts as "not applied".
static let applyAttempts = 3

/// The handler `AskKeyDevices` calls with every verified kind 10–14
/// The handler `AskKeyDevices` calls with every verified kind 10–13
/// message, after it checked the envelope, the payload, the pairing ID and
/// the approval-key signature (checks 1, 3 and 6). The Mac accepts only
/// a decision or a receipt; an approver confirmation, retired by #336,
/// is refused like any kind the Mac does not expect.
/// a decision or a receipt.
func handleApprovalMessage(_ message: VerifiedApprovalMessage) async -> ApprovalMessageHandling {
switch message.message {
case .decision(let decision):
return await handleRemoteDecision(message, decision)
case .receipt(let receipt):
return handleReceipt(message, receipt)
case .request, .closed, .confirmation:
case .request, .closed:
return .refused(.unexpectedKind)
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ extension BrokerApprovalStateMachine {
/// `revocationCount`. Refuses the whole addition if any removal or
/// emptying happened since. Every added entry gets a new generation from
/// a counter that only grows, also one already in the set, so neither a
/// reload nor turning approval off and on revives an earlier generation
/// (ADR 0014). After a flag write, add only the newly enabled device, so
/// other approvers keep theirs. Returns the generation of every given ID.
/// reload nor a repeated addition revives an earlier generation (ADR
/// 0014). After a pairing's add, or for a flagged entry the set is
/// missing, add only that pairing ID, so other approvers keep theirs.
/// Returns the generation of every given ID.
@discardableResult
package func addActiveApprovers(
_ pairingIDs: [Data], revocationCount: UInt64
Expand Down
47 changes: 0 additions & 47 deletions Sources/AskKeyDevices/Approval/ApprovalMessages.swift
Original file line number Diff line number Diff line change
Expand Up @@ -185,53 +185,6 @@ public struct ApprovalReceipt: Hashable, Sendable {
}
}

/// Kind 14, the iPhone's approver confirmation, 113 bytes:
///
/// pairing ID (16) ‖ layout version (1) ‖ code proof (32)
/// ‖ approval-key signature (64) over the confirmation statement
public struct ApproverConfirmation: Hashable, Sendable {
public static let byteCount = 113

public let pairingID: PairingID
/// The App compares it in constant time with its own (`ApproverCode`).
public let codeProof: Data
let signature: Data

/// `AskKey approver confirmation v1\0` ‖ iPhone's device ID ‖ Mac's
/// device ID ‖ pairing ID ‖ code proof.
public static func statement(phone: DeviceID, mac: DeviceID, pairingID: PairingID, codeProof: Data) -> Data {
var writer = ByteWriter()
writer.append(DomainLabel.approverConfirmation)
writer.append(phone.rawValue)
writer.append(mac.rawValue)
writer.append(pairingID.rawValue)
writer.append(codeProof)
return writer.data
}

static func encode(pairingID: PairingID, codeProof: Data, signature: Data) -> Data {
var writer = ByteWriter()
ApprovalLayout.writeHeader(pairingID, into: &writer)
writer.append(codeProof)
writer.append(signature)
return writer.data
}

init(decoding payload: Data) throws {
self = try MessagePayload.decode(payload) { reader in
ApproverConfirmation(pairingID: try ApprovalLayout.readHeader(&reader),
codeProof: try ApprovalLayout.readDigest(&reader),
signature: try reader.readBytes(ApprovalLayout.signatureByteCount))
}
}

private init(pairingID: PairingID, codeProof: Data, signature: Data) {
self.pairingID = pairingID
self.codeProof = codeProof
self.signature = signature
}
}

/// The binding digest (ADR 0014 → Encodings): SHA-256 over
/// `AskKey approval binding v1\0` and eight length-prefixed UTF-8 strings,
/// exactly as the Broker holds them, with no case folding or normalization.
Expand Down
4 changes: 2 additions & 2 deletions Sources/AskKeyDevices/Approval/ApprovalTypes.swift
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ public enum ApprovalClosedOutcome: UInt8, Hashable, Sendable, CaseIterable {
case decidedOnAnotherApprover = 3
case expired = 4
/// The agent cancelled, the credential changed, agent access was
/// paused, or this approver was turned off or removed.
/// paused, or this approver was removed or its pairing replaced.
case cancelled = 5
/// The Mac verified the decision but could not apply it as signed.
case notApplied = 6
Expand Down Expand Up @@ -111,7 +111,7 @@ public enum ApprovalMessageError: Error, Equatable, Sendable {
case invalidClosedOutcome
}

/// The rules shared by every kind 10–14 payload (ADR 0014 → Encodings):
/// The rules shared by every kind 10–13 payload (ADR 0014 → Encodings):
/// each starts with the pairing ID and the layout version, and text fields
/// are length-prefixed UTF-8 without control or line-break characters.
enum ApprovalLayout {
Expand Down
35 changes: 11 additions & 24 deletions Sources/AskKeyDevices/Approval/ApprovalVerification.swift
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
import CryptoKit
import Foundation

/// The content of a verified kind 10–14 message.
/// The content of a verified kind 10–13 message.
public enum ApprovalMessage: Hashable, Sendable {
case request(ApprovalRequest)
case decision(ApprovalDecision)
case closed(ApprovalClosed)
case receipt(ApprovalReceipt)
case confirmation(ApproverConfirmation)
}

/// A kind 10–14 message that passed every rule `AskKeyDevices` checks:
/// A kind 10–13 message that passed every rule `AskKeyDevices` checks:
/// ADR 0013's refusal rules, the payload layout, the pairing ID against the
/// sender's current entry, and the approval-key signature of decisions and
/// confirmations (ADR 0014 → Verifying and applying a decision, checks 1, 3
/// and 6). The App checks the rest against its own state.
/// sender's current entry, and the approval-key signature of decisions
/// (ADR 0014 → Verifying and applying a decision, checks 1, 3 and 6). The
/// App checks the rest against its own state.
public struct VerifiedApprovalMessage: Hashable, Sendable {
/// The sender's entry on this device's list when the message was verified.
public let sender: PairedDevice
Expand All @@ -34,15 +33,13 @@ public struct VerifiedApprovalMessage: Hashable, Sendable {

public var senderID: DeviceID { sender.deviceID }
/// The request this message is about: a request's own digest, or the
/// request digest a decision, closed message or receipt carries; nil
/// for a confirmation.
public var requestDigest: Data? {
/// request digest a decision, closed message or receipt carries.
public var requestDigest: Data {
switch message {
case .request: return digest
case .decision(let decision): return decision.requestDigest
case .closed(let closed): return closed.requestDigest
case .receipt(let receipt): return receipt.requestDigest
case .confirmation: return nil
}
}
/// The pairing ID the payload carries, which is the sender's current one.
Expand All @@ -61,19 +58,19 @@ public enum ApprovalMessageHandling: Hashable, Sendable {
case failed
}

/// Handles verified kind 10–14 messages for the App. Calls for one message
/// Handles verified kind 10–13 messages for the App. Calls for one message
/// ID never overlap; calls for different messages can, when the zone poll
/// and a named fetch run at the same time, so the handler keeps its own
/// state consistent.
public typealias ApprovalMessageHandler = @Sendable (VerifiedApprovalMessage) async -> ApprovalMessageHandling

enum ApprovalVerification {
/// The checks of a kind 10–14 message whose sender is `entry` and whose
/// The checks of a kind 10–13 message whose sender is `entry` and whose
/// message-key signature already verified: the payload layout
/// (`malformed`), the pairing ID against the entry (`bindingMismatch`),
/// a request's times against its inner message's, and the approval-key
/// signature of an Allow or a confirmation over the statement rebuilt
/// from the signed fields (`badSignature`).
/// signature of an Allow over the statement rebuilt from the signed
/// fields (`badSignature`).
static func verify(_ inner: InnerMessage, from entry: PairedDevice) -> Result<ApprovalMessage, DeviceMessageRefusal> {
let message: ApprovalMessage
let pairingID: PairingID
Expand All @@ -91,9 +88,6 @@ enum ApprovalVerification {
case .approvalReceipt:
let receipt = try ApprovalReceipt(decoding: inner.payload)
(message, pairingID) = (.receipt(receipt), receipt.pairingID)
case .approverConfirmation:
let confirmation = try ApproverConfirmation(decoding: inner.payload)
(message, pairingID) = (.confirmation(confirmation), confirmation.pairingID)
default:
return .failure(.unexpectedKind)
}
Expand All @@ -114,13 +108,6 @@ enum ApprovalVerification {
return .failure(.badSignature)
}
}
case .confirmation(let confirmation):
let statement = ApproverConfirmation.statement(phone: inner.sender, mac: inner.recipient,
pairingID: confirmation.pairingID,
codeProof: confirmation.codeProof)
guard isValid(confirmation.signature, over: statement, by: entry.card.approvalPublicKey) else {
return .failure(.badSignature)
}
case .closed, .receipt:
break
}
Expand Down
67 changes: 0 additions & 67 deletions Sources/AskKeyDevices/Approval/ApproverCode.swift

This file was deleted.

17 changes: 1 addition & 16 deletions Sources/AskKeyDevices/Approval/DeviceMessageSealer.swift
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ public struct SealedApprovalRequest: Hashable, Sendable {
public var requestDigest: Data { sealed.digest }
}

/// Seals kind 10–14 messages and delivery check replies without any state,
/// Seals kind 10–13 messages and delivery check replies without any state,
/// for a recipient entry the caller holds: the messenger's current list, or
/// the card the Mac held before a removal for a closing message. Every
/// message uses base-mode HPKE; its sent time is this sealer's clock when it
Expand Down Expand Up @@ -108,21 +108,6 @@ public struct DeviceMessageSealer: Sendable {
messageID: ApprovalReceipt.receiptID(for: content.responseID))
}

/// Kind 14 to the Mac `mac`: the code proof for the typed code, signed
/// with the approval key over the confirmation statement, which asks for
/// Face ID or Touch ID. Throws `DeviceIdentityError` from the prompt.
public func sealApproverConfirmation(_ code: ApproverCode, to mac: PairedDevice,
approvalReason: String) async throws -> SealedDeviceMessage {
let phone = identity.deviceID
let proof = code.proof(mac: mac.deviceID, phone: phone, pairingID: mac.pairingID)
let statement = ApproverConfirmation.statement(phone: phone, mac: mac.deviceID, pairingID: mac.pairingID,
codeProof: proof)
let signature = try await identity.signWithApprovalKey(statement, reason: approvalReason)
guard signature.count == ApprovalLayout.signatureByteCount else { throw DeviceIdentityError.authenticationFailed }
let payload = ApproverConfirmation.encode(pairingID: mac.pairingID, codeProof: proof, signature: signature)
return try sealApprovalKind(.approverConfirmation, payload, to: mac)
}

/// Kind 8 for a verified delivery check, signed with the message key, as
/// the notification extension answers on a locked phone.
public func sealDeliveryCheckReply(answering check: VerifiedDeliveryCheck) throws -> SealedDeviceMessage {
Expand Down
2 changes: 1 addition & 1 deletion Sources/AskKeyDevices/Approval/DeviceMessageVerifier.swift
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ public enum DeviceMessageVerdict: Hashable, Sendable {
/// Extension): against the list it is given, it applies the same envelope,
/// signature, payload, pairing-ID and approval-signature checks as
/// `DeviceMessenger`, in the same order, for delivery checks and kinds
/// 10–14. It does not check replay, does not hold a message from an open
/// 10–13. It does not check replay, does not hold a message from an open
/// pairing session's peer as the messenger does, and does not know the
/// caller's handler or state: `.approval` means only that the checks
/// `AskKeyDevices` owns passed. It deletes nothing, writes nothing and never
Expand Down
2 changes: 0 additions & 2 deletions Sources/AskKeyDevices/Encoding/ByteCoding.swift
Original file line number Diff line number Diff line change
Expand Up @@ -107,8 +107,6 @@ enum DomainLabel {
static let approvalBinding = label("AskKey approval binding v1")
static let approvalDecision = label("AskKey approval decision v1")
static let approvalReceiptID = label("AskKey approval receipt id v1")
static let approverConfirmation = label("AskKey approver confirmation v1")
static let approverCode = label("AskKey approver code v1")

private static func label(_ text: String) -> Data {
precondition(text.allSatisfy(\.isASCII))
Expand Down
Loading
Loading