App Password & Vault Security
This content is for the 1.0.0 version. Switch to the latest version for up-to-date documentation.
PocketCmd seals every stored credential with a vault key that needs two things to open: a key held by the device and your app password. The app lock is mandatory. There is no way to use PocketCmd without an app password.
The app lock and the personal vault are part of Free. Adding a second device to your vault requires PocketCmd Pro, because it runs through device approval and sync on a paired server.
How the vault key is protected
Section titled “How the vault key is protected”- The device key. Each device generates its own vault key pair. Where the hardware supports it, the key is created inside the security chip and cannot be exported: the Secure Enclave on iPhone, iPad and Mac, StrongBox or the TEE on Android, and a TPM 2.0 on Windows and Linux. A device without one uses a software key sealed under the app password.
- The password factor. The app password is stretched with Argon2id and mixed into the key derivation for every vault key wrap this device addresses to itself.
A wrong password does not fail a comparison. It derives a different wrapping key, and AES-GCM refuses to decrypt.
| Property | Value |
|---|---|
| Password stretching | Argon2id |
| Memory cost | 64 MiB |
| Passes | 3 |
| Parallelism | 1 lane |
| Record encryption | AES-256-GCM under per-vault keys |
| Device key | Non-exportable where a security chip is available |
The same Argon2id parameters protect encrypted backup exports.
The app password
Section titled “The app password”You create the app password on first launch. The dialog checks the rules as you type and won’t accept a password until all of them pass:
| Rule | Requirement |
|---|---|
| Length | At least 12 characters |
| Lowercase | At least one a–z |
| Uppercase | At least one A–Z |
| Number | At least one 0–9 |
| Symbol | At least one character that is not a letter or digit |
The password belongs to the device you set it on. Each of your devices has its own, and changing it in Settings › Security › Change App Password affects only that device. A password change is staged, so an interrupted change cannot leave the vault unreadable.
Biometric unlock
Section titled “Biometric unlock”On Android, iPhone and iPad, Settings › Security › Biometric Unlock lets a fingerprint or face stand in for typing the password. The switch appears only when the device has a fingerprint or face enrolled. On Android that biometric has to be a strong (Class 3) one; face unlock that Android rates as weak does not qualify. On a Mac with Touch ID there is no switch: after you unlock once with the password, the lock screen offers Touch ID. On Windows and Linux you unlock with the password.
Biometric unlock is a shortcut to the same factor. The password-derived factor is held by a biometric-gated hardware key, and the biometric check releases it. When the device’s biometric enrollment changes, for example a new fingerprint is added, the stored factor is invalidated. The lock screen then reads “Biometric unlock was reset because this device’s biometric enrollment changed” and you unlock with the password once to turn it back on.
Lock after leaving the app
Section titled “Lock after leaving the app”Settings › Security › Lock after leaving the app sets how long PocketCmd may stay in the background before it locks. Locking wipes the vault keys from memory.
| Option | Behavior |
|---|---|
| Immediately | Locks as soon as the app leaves the foreground |
| 30 seconds, 5 minutes, 15 minutes, 1 hour | Locks after that long in the background |
| 2 minutes | Default |
| Never | Keys stay in memory while the app runs; only the device’s own lock screen protects the vault |
A new value applies from the next time the app goes to the background. If the system clock moves backwards while the app is in the background, the app locks regardless of the setting. Quick links always open behind the lock screen.
Check the key protection
Section titled “Check the key protection”Settings › Security › Key Protection reports what this device could actually prove about its vault key:
| Result | Meaning |
|---|---|
| Proven | The chip vendor certified that the key was created in secure hardware and cannot leave it. |
| Verified on this device | The device showed that the key lives in secure hardware and refuses export. This relies on the operating system being honest. |
| Claimed only | The platform reports secure hardware but offered nothing that could be checked. |
| Software key | The private key is stored on disk, encrypted with your app password. |
These checks are made by the device about itself. When another device approves this one, it treats a hardware claim as unproven unless it can verify the evidence.
This Device’s Fingerprint identifies the device’s vault key once the device is paired with a server. When you approve a device or grant a teammate access to a team vault, compare the fingerprint shown there with the one on the other device. A mismatch means the server is misreporting the key; do not continue.
Add another device
Section titled “Add another device”Your vault key exists only on your devices; the server never holds a password-wrapped copy. A new device gets access only when a device that already holds the vault approves it:
- Install PocketCmd on the new device, set its app password and pair it with the same PocketCmd Server.
- The new device asks to join your vault. On the device that already has it, a Let this device in? prompt appears. Check the device name and fingerprint, then tap Approve.
- The approving device shows a six-digit code. Type it into the new device and tap Join vault.
Read the code out in person, not over chat or email. After a few wrong entries the code expires and the approval has to be started again.
If you lose a device
Section titled “If you lose a device”- Losing every device that holds the vault means the vault is gone. While only one device holds it, the vault shows a reminder to add a second one.
- Revoking a device from the team screen cuts its server access immediately. Removing a member also rotates the keys of the team vaults they could read. See Teams.
- If the operating system destroys this device’s key, for example after its secure storage is reset, the app says so. The vault itself is untouched, and the device can rejoin only through approval from another device that holds it.
- Settings › Security › Reset Vault creates a new vault key on this device and re-encrypts its data. Your other devices lose access until this device approves them again. Anything that existed only under the old key is lost.
What is sealed with the vault key
Section titled “What is sealed with the vault key”Before anything below reaches the system keychain or keystore, it is encrypted with the vault key:
- SSH passwords, private keys and key passphrases, including jump-host credentials
- Vault items, personal and team
- The state used to resume Mosh and Eternal Terminal sessions, which contains their session keys
The app’s database is encrypted separately (SQLCipher on mobile, SQLite3 Multiple Ciphers on desktop). Its key is stored in the system’s secure storage and is not sealed with the vault key, because the database has to open before you unlock. Credentials are never written to the app’s logs.
Clipboard
Section titled “Clipboard”When you copy a password, a one-time code or an invite link, PocketCmd clears it from the clipboard after 45 seconds if it is still there. On Android 13 and later the copy is marked sensitive, which keeps it out of the clipboard preview and history. On iOS it stays off Universal Clipboard and expires even if PocketCmd is closed first.
Threat model
Section titled “Threat model”| Scenario | Protected |
|---|---|
| Someone has your unlocked device | No |
| Someone has your locked device | Yes: they need the device key and the password |
| The device’s storage is copied | Yes on hardware-backed devices, where the key cannot be copied with the files. With a software key, the attacker has to guess the password at Argon2id cost. |
| The sync server’s database is stolen | Yes: it holds no password-wrapped key to guess against |
| An encrypted export file is stolen | Cost-bounded: every guess costs 64 MiB of Argon2id |
| The sync server is compromised | Record contents and vault items stay encrypted. Metadata and the plaintext monitoring configuration are exposed. |
| You are phished for your password | No |
Frequently asked questions
Section titled “Frequently asked questions”Can I recover a forgotten app password?
Section titled “Can I recover a forgotten app password?”No. The password is never stored or transmitted. It is stretched with Argon2id and mixed into the key that unwraps your vault, so there is no reset and no support channel that can open it. If another device still holds your vault, unlock there and approve this device again. If no device holds it, the vault cannot be recovered.
Does biometric unlock make PocketCmd less secure?
Section titled “Does biometric unlock make PocketCmd less secure?”No. The biometric releases the same password-derived factor from a biometric-gated hardware key, so the key that unwraps the vault is identical either way. Enrolling a new fingerprint or face invalidates the stored factor, and you unlock with the password once to re-enable it.
Can the sync server read my data?
Section titled “Can the sync server read my data?”It cannot read the contents of synced records or vault items. Records are encrypted with AES-256-GCM on the device before upload. The server does see metadata such as record types, IDs, sizes and timestamps, and the team’s monitoring configuration is stored in plaintext because the server has to run it. See Self-Hosted Sync.