Docs / Key Vault

Face ID lock & auto-relock

A second lock just for NetShell: even on an unlocked device, your keys, hosts, and live sessions stay sealed behind Face ID until you prove it's you.

What the lock protects

NetShell holds sensitive material — saved connections, snippets that may carry secrets, and a Key Vault of private keys and passphrases stored in the hardware-backed iOS Keychain. The app-level lock puts a biometric gate in front of all of it. When the gate is up, a full-screen overlay covers NetShell and nothing underneath is interactive: you can't open a connection, read the terminal scrollback, browse SFTP, or copy a key until you authenticate.

This is distinct from your device passcode. The device lock protects the whole phone; the NetShell lock protects NetShell specifically, so a borrowed-but-unlocked iPhone, iPad, or Mac still can't reach your servers.

Enabling Face ID lock

1. Open Settings → Security inside NetShell.
2. Turn on Require Face ID (or Touch ID / device passcode on hardware without Face ID).
3. Confirm with a biometric prompt so iOS grants NetShell access to authentication.

Once enabled, the gate appears automatically on cold launch and again after the app has been idle in the background. There's nothing to lock manually — it relocks itself.

Cold-launch vs background-resume

The gate fires in two situations, and they behave a little differently:

• Cold launch. When NetShell starts fresh — after a reboot, after being swiped away from the app switcher, or after iOS reclaimed its memory — the lock is up immediately. You authenticate before any screen content is shown.
• Background resume. When you switch away to another app and come back, NetShell checks how long it was backgrounded. If that exceeds your idle timeout, the gate returns. If you only glanced away for a moment, it stays unlocked so quick app-switching isn't punished.

Auto-relock idle timeout

Auto-relock is time-based. After NetShell goes to the background, a timer starts; when you return and the elapsed time is past the threshold, the biometric gate comes back up. The default idle window is sixty seconds, so brief context switches (checking a notification, pasting from another app) keep your session open while a longer absence reseals it.

Because the timer keys off background time rather than active use, an app left in the foreground untouched isn't relocked mid-task — relock happens on the next resume after a long enough gap.

Passcode fallback

NetShell uses the standard iOS authentication flow, which means if Face ID (or Touch ID) fails or is unavailable — a mask, poor lighting, or too many failed scans — iOS offers your device passcode as the fallback. You're never locked out of your own data by a finicky scan. On devices without biometric hardware, the passcode is the primary unlock method.

NetShell never stores or sees your biometric data or your passcode; it asks iOS to authenticate and only receives a yes/no result. The biometric template stays inside Apple's secure hardware.

How it works with your keys

The lock complements, rather than replaces, the Keychain protection on your Key Vault. Private keys and passphrases are individually protected by Face ID in the hardware-backed iOS Keychain regardless of the app-level gate. The app lock simply adds a single, fast checkpoint at the front door so you don't get a biometric prompt for every individual action while still keeping everything sealed when the app isn't actively in use.

Your keys sync only through Apple's end-to-end encrypted iCloud Keychain — never a NetShell server — so the same protection model travels with you across your iPhone, iPad, and Mac. See iCloud Keychain sync for how that works.

If Face ID isn't prompting

• Confirm Require Face ID is on in Settings → Security.
• Check iOS Settings → Face ID & Passcode and make sure NetShell is allowed to use Face ID.
• If you previously denied the permission, re-enable it for NetShell in iOS Settings, then relaunch.
• For deeper issues, see Troubleshooting.

Defense in depth

The lock is one layer in NetShell's security model. Host verification at handshake time fails closed so credentials are never sent to an unknown or changed server, and the destructive-command guard intercepts dangerous commands before they reach the wire. Together with the Key Vault, they're designed so a single lapse — a misplaced unlocked device — doesn't hand over your infrastructure.