Lysann Tranvouez 4d564f570b plan updates

2026-03-12 22:51:28 +01:00

11 KiB

Raw Blame History

Multi-Recipient Encryption Plan

Concept

The pass password store format supports encrypting each password to multiple PGP keys via .gpg-id files (one key ID per line). This enables sharing a store with other users — each person imports the same git repository but decrypts with their own private key. When adding or editing a password, it must be encrypted to all key IDs listed in .gpg-id.

The app currently has a setting (isEnableGPGIDOn) that reads .gpg-id for per-directory key selection, but it only supports a single key ID. This plan fixes every layer to support multiple recipients.

This is standalone — it can be implemented before or after multi-store support.

Current State

The codebase does not support encrypting to multiple public keys. Every layer assumes a single recipient:

Layer	Current state	What needs to change
`.gpg-id` file format	Supports multiple key IDs (one per line)	No change needed
`findGPGID(from:)`	Returns the entire file as one trimmed string — does not split by newline	Split by newline, return `[String]`
`PGPInterface.encrypt()`	Signature: `encrypt(plainData:keyID:)` — singular `keyID: String?`	Add `encrypt(plainData:keyIDs:[String])` or change `keyID` to `keyIDs: [String]?`
`GopenPGPInterface`	Creates a `CryptoKeyRing` with one public key	Add all recipient public keys to the keyring before encrypting
`ObjectivePGPInterface`	Passes `keyring.keys` (all keys, including private) — accidentally multi-recipient but not intentionally	Filter to only the specified public keys, pass those to `ObjectivePGP.encrypt()`
`PGPAgent.encrypt()`	Routes to a single key via `keyID: String`	Accept `[String]` and pass through to the interface
`PasswordStore.encrypt()`	Calls `findGPGID()` for a single key ID string	Call the updated `findGPGID()`, pass the key ID array

Implementation

1. `findGPGID(from:) -> [String]`

Split file contents by newline, trim each line, filter empty lines. Return array of key IDs.

2. `PGPInterface` protocol

Change encrypt(plainData:keyID:) to encrypt(plainData:keyIDs:) where keyIDs: [String]?. When nil, encrypt to the first/default key (backward compatible).

3. `GopenPGPInterface.encrypt()`

Look up all keys matching the keyIDs array from publicKeys. Add each to the CryptoKeyRing (GopenPGP's CryptoKeyRing supports multiple keys via add()). Encrypt with the multi-key ring.

4. `ObjectivePGPInterface.encrypt()`

Filter keyring.keys to only the public keys matching the requested keyIDs. Pass the filtered array to ObjectivePGP.encrypt().

5. `PGPAgent.encrypt()`

Update both overloads to accept keyIDs: [String]? and pass through to the interface.

6. `PasswordStore.encrypt()`

Call updated findGPGID(), pass the array to PGPAgent.

Public Key Management

When a store lists multiple key IDs in .gpg-id, the user needs the public keys of all recipients. The user's own private key is sufficient for decryption (since the message is encrypted to all recipients), but all public keys are needed for re-encryption when editing.

Current state

The keychain holds one pgpPublicKey blob and one pgpPrivateKey blob, but each can contain multiple concatenated armored key blocks. Both interface implementations parse all keys from these blobs.
The import UI (armor paste, URL, file picker) has one public key field + one private key field. Importing replaces the set of keys entirely, there is no append mode for adding additional keys or managing existing keys.
There is no UI for viewing which key IDs are loaded or for importing additional recipient-only public keys, nor for viewing the key metadata.
There is no UI for viewing or editing .gpg-id files, which are the source of truth for which keys are used for encryption.

Key storage approach

Store all public keys as a single concatenated armored blob in the keychain (pgpPublicKey). Both interface implementations already parse multi-key blobs into dictionaries/keyrings. This avoids schema changes — we just need to append instead of replace when importing additional public keys.

The user's own private key stays as a separate single blob (pgpPrivateKey).

7. UI: Import additional recipient public keys

Add an "Import Recipient Key" action to the PGP key settings (alongside the existing import that sets the user's own key pair). This flow:

Imports a public-key-only armored blob
Appends it to the existing pgpPublicKey keychain entry (concatenating armored blocks)
Does not touch the private key
On success, shows the newly imported key ID(s)

The existing import flow ("Set PGP Keys") continues to replace the user's own key pair (public + private).

8. UI: View loaded key IDs and metadata

PGP keys carry a User ID field, typically in the format "Name <email@example.com>". Both GopenPGP (key.entity.PrimaryIdentity()) and ObjectivePGP (key.keyID + user ID packets) can access this. The app currently doesn't expose it.

Add key metadata to the PGPInterface protocol:

struct PGPKeyInfo {
    let fingerprint: String    // full fingerprint
    let shortKeyID: String     // last 8 hex chars
    let userID: String?        // "Name <email>" from the primary identity
    let isPrivate: Bool        // has a matching private key
    let isExpired: Bool
    let isRevoked: Bool
}
var keyInfo: [PGPKeyInfo] { get }

Both GopenPGPInterface and ObjectivePGPInterface should implement this by iterating their loaded keys.

Add a read-only section to the PGP key settings showing all loaded public keys. Each row shows:

User ID (e.g. "Alice <alice@example.com>") as the primary label — this is the human-readable identifier
Short key ID (e.g. ABCD1234) as the secondary label
Badge/icon if it's the user's own key (has matching private key) vs a recipient-only key
Badge/icon if expired or revoked
Swipe-to-delete to remove a recipient public key

This also informs the .gpg-id editing UI (§9) — when the user adds/removes recipients from .gpg-id, they see names and emails, not just opaque hex key IDs.

9. UI: View/edit `.gpg-id` files

When isEnableGPGIDOn is enabled, add visibility into .gpg-id:

In the password detail view, show which key IDs the password is encrypted to (from the nearest .gpg-id file)
In folder navigation, show an indicator on directories that have their own .gpg-id
Tapping the indicator shows the .gpg-id contents (list of key IDs) with an option to edit
Editing .gpg-id triggers re-encryption of all passwords in the directory (see §10)

Note: Viewing .gpg-id is low-effort and high-value. Editing is more complex due to re-encryption. These can be split into separate steps.

10. Re-encryption when `.gpg-id` changes

When the user edits a .gpg-id file (adding/removing a recipient), all .gpg files in that directory (and subdirectories without their own .gpg-id) must be re-encrypted to the new recipient list. This is equivalent to pass init -p subfolder KEY1 KEY2.

Steps:

Write the new .gpg-id file
For each .gpg file under the directory:
- Decrypt with the user's private key
- Re-encrypt to the new recipient list
- Overwrite the .gpg file
Git add all changed files + .gpg-id
Git commit

This can be expensive for large directories. Show progress and allow cancellation.

Implementation Order

Step	Description	Status	Depends On
1	`findGPGIDs` returns `[String]` + update callers	✅ Done	—
2	`PGPInterface` protocol change (`keyIDs: [String]`)	✅ Done	—
3	`GopenPGPInterface` multi-key encryption	✅ Done	Step 2
4	`ObjectivePGPInterface` multi-key encryption	✅ Done	Step 2
5	`PGPAgent` updated overloads	✅ Done	Steps 2-4
6	`PasswordStore.encrypt()` uses `[String]` from `findGPGIDs`	✅ Done	Steps 1+5
7	UI: import additional recipient public keys	Not started	Step 5
8	UI: view loaded key IDs and metadata	Not started	Step 5
9a	UI: view `.gpg-id` in password detail / folder view	Not started	Step 1
9b	UI: edit `.gpg-id`	Not started	Step 9a
10	Re-encryption when `.gpg-id` changes	Not started	Steps 6+9b

Testing

Pre-work: existing encryption tests

The PGPAgentTest already covers single-key encrypt/decrypt with multiple key types. These serve as the regression baseline.

Multi-recipient encryption tests

Test findGPGID with multi-line .gpg-id: File with two key IDs on separate lines → returns [String] with both.
Test findGPGID with single-line .gpg-id: Backward compatible → returns [String] with one element.
Test findGPGID with empty lines and whitespace: Trims and filters correctly.
Test GopenPGPInterface.encrypt with multiple keys: Encrypt with two public keys → decrypt succeeds with either private key.
Test ObjectivePGPInterface.encrypt with multiple keys: Same as above.
Test PGPAgent.encrypt with keyIDs array: Routes through correctly to the interface.
Test round-trip: Encrypt with key IDs [A, B] → user with private key A can decrypt, user with private key B can decrypt.
Test encrypt with single keyID still works: Backward compatibility — keyIDs: ["X"] behaves like the old keyID: "X".
Test encrypt with unknown keyID in list: If one of the key IDs is not in the keyring, appropriate error is thrown.
Test multi-key public key import: Import an armored blob containing multiple public keys → all are available for encryption.

Key management tests

Test appending recipient public key: Import user's key pair → append a second public key → both key IDs are available. Original private key still works for decryption.
Test removing a recipient public key: Remove one public key from the concatenated blob → only the remaining key IDs are available.
Test replacing key pair doesn't lose recipient keys: Import user's key pair → add recipient key → re-import user's key pair → recipient key is still present (or: design decision — should re-import clear everything?).

`.gpg-id` and re-encryption tests

Test re-encryption: Edit .gpg-id to add a recipient → all passwords in directory are re-encrypted → new recipient can decrypt.
Test re-encryption removes access: Edit .gpg-id to remove a recipient → re-encrypted passwords cannot be decrypted with the removed key.
Test .gpg-id directory scoping: Subdirectory .gpg-id overrides parent. Passwords in subdirectory use subdirectory's recipients.
Test multi-key public key import: Import an armored blob containing multiple public keys → all are available for encryption.

11 KiB Raw Blame History