Biometric Lock

ZestSSH supports biometric authentication to protect the app from unauthorized access. This is a free feature — security is not paywalled.

Supported Biometrics

Platform	Methods
iOS	Face ID, Touch ID
Android	Fingerprint, face unlock, iris scan (device-dependent)
macOS	Touch ID (on supported hardware)
Windows	Windows Hello: the Hello PIN, face or fingerprint, whichever you set up in Windows (see Windows Hello unlock on the Windows desktop app below)
Linux	Not available. The app lock is PIN only.

Biometric support is provided by the local_auth Flutter package, which delegates to the platform’s native biometric APIs:

• iOS: LocalAuthentication framework
• Android: BiometricPrompt API
• macOS: LocalAuthentication framework
• Windows: Windows Hello (UserConsentVerifier)

On every platform the device factor is an addition to the ZestSSH PIN, never a replacement: the setup flow always stores a PIN, and the biometric or Windows Hello check is a faster way to pass it.

How It Works

Availability Check

Before offering biometric lock, ZestSSH checks two conditions:

1. canCheckBiometrics — The device has biometric hardware.
2. isDeviceSupported — The device supports the platform’s authentication mechanism.

On Android and iOS both must be true for biometric lock to be available. On Windows and macOS only isDeviceSupported is required, because Windows Hello is a valid unlock with just a Hello PIN, and canCheckBiometrics is false on a PC without a face or fingerprint sensor. If the check fails (or throws a PlatformException), the option is hidden in settings.

Authentication Flow

When the app is locked and biometric authentication is configured:

1. The system biometric dialog appears with the prompt: “Authenticate to unlock ZestSSH”.
2. The user authenticates with their face, fingerprint, or other enrolled biometric.
3. On success, the app unlocks.
4. On failure, the user can retry or fall back to PIN.

Authentication options:

• stickyAuth: true — The authentication dialog persists until the user explicitly cancels. It does not dismiss on app switch.
• biometricOnly: On Android and iOS only biometric methods are accepted (no device passcode fallback at the system level). On Windows and macOS the app requests the standard OS prompt instead, so Windows Hello can answer with its PIN, face or fingerprint, and Touch ID shows its normal macOS dialog.
• Timeout: A prompt that has not answered after 20 seconds is treated as unavailable and the lock screen falls back to the PIN, so a prompt that never surfaces cannot leave the app stuck on “Authenticating”.

Lock Methods

ZestSSH supports four lock method configurations:

Method	Behavior
none	No lock (default)
biometric	Biometric only
pin	PIN only (see PIN Lock)
both	Biometric with PIN fallback

The setup flow only ever stores pin or both: a PIN is always set, and the “Also enable …” switch during PIN setup decides whether the device factor is added on top. There is no way to enable a biometric-only lock without a PIN.

When set to both, the phone app prompts for biometric authentication first; if it fails or is cancelled, the PIN entry appears as a fallback. The desktop app shows the PIN field straight away and offers the device factor through a Use Biometrics button (see the Windows Hello section below).

Auto-Lock Timeout

Configure how quickly the app locks after you leave it:

• Immediately (0 minutes): Locks as soon as the app is backgrounded.
• 1 minute: The default on Android and iOS.
• 10 minutes: The default on Windows, macOS and Linux (desktop sessions are long-lived and already sit behind an OS login).
• Other choices: 5, 15 and 30 minutes, or Never.

The timeout is stored in secure storage under the key security_auto_lock_timeout.

Setup

1. Go to Settings > Security (mobile: App Lock & Encryption; desktop: the App Lock section) and turn on App Lock.
2. The PIN setup opens. Enter a PIN of 4 to 32 digits.
3. On the same step, if your device offers a factor, a switch reads Also enable biometrics (mobile), Also enable Windows Hello (Windows) or Also enable Touch ID (macOS). It is on by default when the factor is available. Leave it on to use it, or turn it off for a PIN-only lock.
4. Confirm the PIN. The lock is active immediately.

To add or remove the device factor later, open the PIN setup again (Change PIN, or turn App Lock off and on again), enter your current PIN, and set the switch.

Windows Hello unlock on the Windows desktop app

The Windows app can unlock with Windows Hello: your Hello PIN, face or fingerprint, whichever you have set up in Windows. It always sits on top of the ZestSSH PIN. The PIN is the lock; Hello is the faster way to pass it.

Requirements

• Windows Hello must be set up in Windows first: Windows Settings > Accounts > Sign-in options. A Hello PIN is enough; face or fingerprint are optional extras. If Windows reports that Hello is not available, ZestSSH does not show the option.
• An App Lock PIN in ZestSSH (4 to 32 digits).

How to enable it

1. Open Settings > Security > App Lock and turn on App lock.
2. The PIN setup opens. Enter your new PIN. On the same step a switch reads Also enable Windows Hello (“Unlock the app with Windows Hello”); it is on by default when Hello is available. Leave it on and confirm the PIN.
3. To add Hello to an existing PIN lock, open the PIN setup again (Change PIN, or turn App lock off and on again), enter your current PIN, and turn the switch on.

Unlocking

• On the lock screen the PIN field is shown right away. Click Use Biometrics to bring up the Windows Hello prompt; a successful Hello check unlocks the app. Unlike the phone app, the desktop app does not fire the prompt on its own, so a Hello dialog that fails to appear cannot leave you stuck.
• If the prompt fails or is cancelled, the button changes to Try Biometrics Again. After five failed attempts, or if Windows has locked Hello out after too many failures, the app falls back to the PIN. Use PIN instead is always available.
• A Hello prompt that does not answer within 20 seconds is treated as unavailable and the PIN takes over.

When Hello is not offered

• Encrypt data at rest is on. With that setting only the PIN can unwrap the encryption key, so the lock screen shows the PIN alone and no Hello button.
• Windows Hello is not set up in Windows, or the app is running on Linux (no equivalent, PIN only). On macOS the same option appears as Also enable Touch ID.

Version note: on Windows PCs without a face or fingerprint sensor, versions before 1.9.7 never showed the Hello prompt (the app asked Windows for a biometric-only check, which excludes the Hello PIN). Since 1.9.7 the app requests the standard Hello prompt, the same one other apps use, and treats Hello as available whenever Windows supports it. If you are on an older version, update.

Platform Notes

iOS

• Face ID requires the NSFaceIDUsageDescription key in Info.plist.
• Touch ID works on iPhone SE, iPhone 8, and iPads with a Home button.
• If the user has not enrolled any biometrics, the option is unavailable.

Android

• Requires android.permission.USE_BIOMETRIC in the manifest.
• The system BiometricPrompt handles all UI rendering — ZestSSH does not draw its own biometric dialog.
• On Android 9 and below, falls back to the legacy fingerprint API.

macOS

• Touch ID is available on MacBook Pro (2016+) and MacBook Air (2018+) with the Touch Bar or power button sensor.
• Does not need the com.apple.security.keychain-access-groups entitlement: the macOS app is not sandboxed, so Keychain Services scopes items to ZestSSH’s bundle identifier automatically (see the macOS Keychain page).
• Like Windows, the desktop lock screen shows the PIN first and offers Touch ID through the Use Biometrics button.

Windows

• Uses Windows Hello. See Windows Hello unlock on the Windows desktop app above for setup, requirements and behaviour.

Linux

• No device factor is available; the app lock is PIN only.

Security Considerations

• Biometric data never leaves the device — ZestSSH does not access or store biometric templates.
• The local_auth package uses the OS-level biometric APIs, which are backed by the Secure Enclave (iOS/macOS) or TEE/StrongBox (Android).
• The lock method is stored in Flutter Secure Storage (encrypted by the platform keystore), not in plaintext SharedPreferences.
• Biometric authentication state is not persisted — the app always re-authenticates after the auto-lock timeout expires.