What this app does with an IKE pre-shared key and a PPP password, what actually protects them, and — the part most documents skip — what does not.
The short version: the encryption protects the credentials at rest against a copy of the data directory, and against nothing else. That is worth having and it is not a vault. Everything below either supports that sentence or qualifies it.
See also: android.md for the storage layout and the migration, configuration.md for the fields, architecture.md for where the types live.
- What is stored, and where
- What actually encrypts what
- Threat model
- The never-reveal guarantee
- Where a secret can still leak
- Redaction
- Backup and device transfer
- Known weaknesses and deliberate decisions
- The recommendation on the table: a Secret value class
- What is not claimed
Two secrets per profile, and nothing else in the app is treated as one.
| Secret | SecretKind |
Where it comes from | Where it goes |
|---|---|---|---|
| IKE pre-shared key | PRESHARED_KEY |
the profile form | the ISAKMP key schedule (SKEYID) |
| PPP password | PASSWORD |
the profile form | PAP / CHAP-MD5 / MS-CHAPv2 |
Everything else — server address, user name, algorithm choices, MTU, DNS list — is not a secret
and lives in VpnProfile, which has no secret-shaped field at all. VpnProfileTest enumerates the
class and fails the build if one appears.
Both files are in the app's private directory (/data/data/<package>/shared_prefs/), which no other
app can read whatever the encryption does.
| File | Contents |
|---|---|
vpn-profile-encrypted.xml |
the profile rows and both credentials, all encrypted; also the two wrapped Tink keysets |
vpn-profile.xml |
written only by builds before the fallback was removed. It is read once, its contents are moved into the encrypted store, and it is then deleted |
Credentials are keyed by profile id and kind:
secret.<profile-id>.psk
secret.<profile-id>.password
The profile id is a random UUID, never a list index — recycling one would hand a newly created
profile the deleted tenant's credentials. Deleting a profile calls SecretVault.clearAll, and it
does so before the profile row is removed, so a store that dies halfway leaves an orphan row
rather than an orphan credential.
Three layers, and only the innermost key is in hardware. The reasoning is written up in
data/EncryptedPreferences.kt; this is the summary.
AndroidKeyStore MasterKey, AES-256-GCM, alias _androidx_security_master_key_
│ wraps (android-keystore:// KMS URI)
├─ Tink keyset, AES256-SIV ──► encrypts preference NAMES (deterministically)
└─ Tink keyset, AES256-GCM ──► encrypts preference VALUES (name as associated data)
│
└─ the pre-shared key and the PPP password
- The master key.
MasterKey.Builder(...).setKeyScheme(AES256_GCM).build()asksAndroidKeyStorefor a 256-bit AES-GCM key, created on first use. Its material never leaves the keystore; the app only ever holds a handle. The generated spec does not require user authentication, and that is deliberate: the tunnel has to be able to reconnect while the screen is locked, and a key gated on unlock would make always-on VPN and background reconnects impossible. - Two Tink keysets.
EncryptedSharedPreferencesdoes not use the master key on the data. It generates one AES256-SIV keyset for names and one AES256-GCM keyset for values, wraps both with the master key, and stores them inside the same XML file under the reserved keys__androidx_security_crypto_encrypted_prefs_key_keyset__and…_value_keyset__. A copy of the file therefore contains the wrapped keysets; what it does not contain is the master key that unwraps them. - The entries. Names deterministically (that is what makes a lookup by name possible at all), values with AES-256-GCM.
Is it hardware-backed? The master key is, on every device this app realistically runs on: a
TEE-backed keymaster has been required for new devices since Android 7 and minSdk here is 26. Where
it is not — an emulator, a device with a software keymaster — the key silently degrades to software
and MasterKey.isKeyStoreBacked() still reports true. There is no promise to be had, so none is
made here.
| Attacker | What they get | Why |
|---|---|---|
| Another app on the device | Nothing | The file is in this app's private directory. UID separation is what stops them, not the encryption. |
An offline copy of the data directory — a stolen flash image, an adb backup, a forensic dump of an unlocked-but-not-rooted handset |
Ciphertext plus two wrapped keysets | The master key is not in the copy and cannot be extracted from the handset it came from. This is where the encryption earns its place: the credentials are not recoverable offline. |
| Root on the running device, or a compromised app process (a malicious dependency, a debugger on a debuggable build) | Everything | Keystore keys are non-exportable but they are usable by whoever can act as this app's UID, and root can. The heap is readable too, and the live VpnConfig holds both credentials as String. No storage scheme fixes this — not a hand-rolled AES-GCM store, not StrongBox, not CharArray secrets. |
| Someone holding the phone | Nothing from storage | Userdata is encrypted at rest by file-based encryption, and an idle handset's keys are not available before first unlock. The exposure was always the app's own screens, which is exactly what the vault design closes. |
Read the third row before deciding any of the improvements below are urgent. It is the row that decides what the others are worth.
A credential that has been saved can never be displayed again. This is enforced by the type system, not by a UI convention.
┌──────────────────────────────────────────┐
ui/ ──────────►│ SecretVault │ no getter exists
│ isSet store clear clearAll │
└──────────────────────────────────────────┘
▲
one and the same object
▼
┌──────────────────────────────────────────┐
tunnel worker ─►│ SecretReader │ the only read path
│ read │
└──────────────────────────────────────────┘
SecretVault— what the UI is handed — can answer whether a secret exists and can replace or delete one. It has no method that returns one. A screen cannot pre-fill a password field "just this once", a log line cannot interpolate a key, and a contributor cannot add either without changing the interface and being asked why in review.SecretReader— onereadmethod — is handed only to the tunnel worker, throughVpnStorage.secretReaderandAppComponents.secrets. Nothing underui/imports the type.- Both are views of the same
PreferenceSecretVaultinstance, so there is one copy of the data and one cache. The separation that matters is at the hand-out point, not two stores. - Consequently the form shows a fixed
••••••••placeholder with Replace and Clear for a saved secret. There is no reveal toggle there, because there is nothing in the process to reveal. The reveal toggle exists only on a field the user is currently typing into, and it resets on focus loss. - Validation asks
isSet, never a value. "A pre-shared key is required" is satisfied by a secret the UI cannot see. ProfileFormStatecarries atypedLength: Intfor each secret, not the characters — the reducer and the validator do their work without ever being handed a value, andremember(neverrememberSaveable) keeps the typed characters out of the saved-instance-state bundle the system writes to disk.- Duplicating a profile copies no secrets, and cannot: they are filed under the original's id in a store the UI cannot read. The snackbar says so rather than letting the user discover it when authentication fails.
Being honest about the edges of the guarantee above:
VpnConfigholdsStringsecrets. From the momentprepareConnectbuilds one, the pre-shared key and the password are immutable heap objects that cannot be wiped and that live as long as the tunnel does. TheCharArrays the vault returns are wiped, in afinally, as soon as the config is built — but theStrings they became survive. Narrowing this is what theSecretproposal is about.- Compose text fields produce an unwipeable
Stringper keystroke.OutlinedTextFieldisString-valued; typing an eight-character key allocates eight strings, all of which stay on the heap until a garbage collector that has no reason to hurry gets to them.CharArray.wipe()is applied to everything the app can wipe, and it cannot touch these. - Screenshots and the recents thumbnail.
FLAG_SECUREis not set on the Activity. A screenshot taken while a secret field is revealed captures it, and so may the recents thumbnail. Setting the flag would also make the in-app log screen unscreenshottable, which is the one screen users are asked to capture for bug reports; the trade has not been made either way yet, and it is a one-line change if it should be. - IME learning dictionaries. Secret fields declare
KeyboardType.Password, which asks the IME not to learn from them. Honouring that is the IME's choice, and a third-party keyboard is outside this app's control entirely. - A device the user has already lost control of. See the third row of the threat model.
Nothing that reaches a VpnLogger is private. The app writes every record to logcat and to an
in-memory ring buffer behind a screen with copy and share buttons, so a log line is a
publication channel rather than a private debugging aid.
redacted(secret) in core/util/Logging.kt returns <unset> or <redacted> — and nothing else.
The length is withheld on purpose. Printing it is tempting: it looks harmless and it catches a
stray trailing space in a pasted pre-shared key. But the length is exactly the parameter that sets
the cost of guessing the key, and a trace pasted into a support ticket should not narrow that search.
RedactionTest pins the property that the output does not vary with the input at all.
Four toString()s are written out by hand rather than generated, each because the generated one
would publish something:
| Type | What the generated one would print |
|---|---|
VpnConfig |
the pre-shared key and the PPP password, in full |
VpnProfile |
nothing secret today — kept explicit so that adding a secret cannot leak it by default |
L2tpAvp |
an AVP body, which for a Challenge Response is authentication material and for a parsed hidden AVP is recovered cleartext |
PppControlPacket / PppOption |
a control-packet body, which for a PAP Authenticate-Request is literally the cleartext password |
Nothing logs an L2tpAvp or a PppControlPacket today. CredentialSecrecyTest and
VpnConfigSecrecyTest pin the property anyway, because a $packet in a future diagnostic is one
edit away and is exactly the kind of change nobody re-audits.
Both are needed, and they cover different Android versions:
| Mechanism | What it does | Applies to |
|---|---|---|
android:allowBackup="false" |
clears FLAG_ALLOW_BACKUP, so the backup manager skips the app entirely |
API 26–30 it is the whole story; from Android 12 it covers cloud backup only |
res/xml/data_extraction_rules.xml |
excludes every domain from both <cloud-backup> and <device-transfer> |
Android 12+ |
From Android 12, device-to-device transfer is governed solely by dataExtractionRules, so without
the rules file a new handset would receive the pre-shared key and the PPP password during setup.
Below Android 12 the rules file does not exist and allowBackup="false" is what stops it. Neither
attribute is redundant.
The exclusions are spelled out one domain at a time rather than left as an empty element, because an
empty <cloud-backup> means "take everything". The device_* domains — direct-boot / device-
protected storage — are excluded too, so moving credentials there later cannot silently opt them back
into a backup.
Note the tools:ignore="DataExtractionRules" on <application>: lint asks for a
fullBackupContent file alongside, which on API 26–30 would never be consulted because
allowBackup="false" already skips the app.
Each of these is a decision, not an oversight. The reasoning is what makes it reviewable.
The library is deprecated in full and gets no fixes. It also carries a failure mode this project has
already been bitten by: once the keyset no longer matches the data — a restore onto another handset,
some OS upgrades — every getter throws SecurityException. That is why every read and write in
data/ is wrapped and why ProfileStoreState.UNREADABLE exists.
The replacement Google points at is a hand-rolled store: one AndroidKeyStore AES-256-GCM key, an
explicit 12-byte IV per record, ciphertext in a file or a DataStore. The crypto is about eighty
lines. The cost is elsewhere:
- The migration — reading the old store to write the new one, on devices whose old store may be exactly the one that throws, with a user's working VPN credentials as the thing being moved.
- The testing —
AndroidKeyStoredoes not exist on a plain JVM.KeyStore.getInstance("AndroidKeyStore")throwsNoSuchProviderExceptionin this module's unit tests, so a hand-rolled store could only be covered behind an interface with a fake, plus instrumented tests on a device. This module has noandroidTestsource set at all today.
So the move is warranted eventually and was declined for now: shipping a credential store whose only real exercise is manual is a worse defect than the deprecation. When it happens it should be its own change, with device tests, not folded into a persistence rewrite.
The suppression is confined to data/EncryptedPreferences.kt, which contains nothing else, so it can
never quietly hide an unrelated deprecation.
An earlier version dropped to plain private SharedPreferences when the keystore refused, with the
pre-shared key and the password unencrypted in the app's data directory, and rendered a red banner
saying so. That has been removed.
The reasoning for keeping it was that the only screen able to fix a broken keystore is the one that would fail to open, and that forcing a user to retype a pre-shared key ends with the key written down somewhere worse. The reasoning against it won: a banner does not make cleartext credentials acceptable, and the offline-copy row of the threat model above is the one case the encryption exists for — a fallback silently deletes that protection precisely when something has already gone wrong with the device.
So VpnStorage.open has no catch. If the keystore-backed store cannot be opened, ProfileStore
reports UNREADABLE, the home screen replaces the whole interface with an explanation, and the
service refuses to connect: there is no pre-shared key it is willing to have read. The state is
terminal rather than degraded, and a test pins that a store which fails to open does not come back
READY.
Reinstalling normally clears it, since a fresh install generates a fresh master key.
MasterKey.Builder.setRequestStrongBoxBacked(true) is one call, and 1.1.0 gates it behind
PackageManager.hasSystemFeature(...) so asking is safe. It is not asked because:
- it would only apply to installs created after the change — the builder reuses an existing key under the same alias untouched — so devices that already have one would not benefit;
- it cannot be tested from here;
- it buys nothing against the attacker who actually matters (root / compromised process), and the attacker it does help against (offline copy) is already defeated by a TEE-backed key.
AES256-SIV over preference names is what makes a lookup by name possible at all, and the price is
that an observer of the file can see how many entries exist, that two entries have the same name, and
that a given entry changed. Nothing here puts anything sensitive in a name: the credential keys are
secret.<uuid>.psk and secret.<uuid>.password, so what leaks is "this install has N profiles, each
with up to two credentials" — which the file size leaks anyway.
SharedPreferences.getAll() on an encrypted store decrypts every value as it goes. Asking "does
a password exist for this profile?" through getAll would therefore pull every profile's credentials
into the heap. PreferenceSecretVault.seedPresence probes with contains per key instead, and
writeProfiles derives the rows to drop from the previously stored order rather than from getAll.
Both are correctness-neutral and exist only to keep plaintext out of the heap.
If the store refuses a write, the queued credential is kept in PreferenceSecretVault.pending for
the life of the process and an error is logged. The tunnel therefore works for this session and stops
working after a restart. Failing the save instead would leave the user with a profile that cannot
connect and no way to understand why.
The obvious "fix" for VpnConfig holding String secrets is to change them to CharArray. The
recommendation is not that — it is a @JvmInline value class Secret, and the argument deserves to
be presented fairly because the CharArray case is not stupid.
The case for CharArray: a String cannot be wiped, so the credentials are readable in a heap
dump for as long as the tunnel lives. A CharArray can be zeroed the moment it has been consumed.
Why the win is largely illusory here:
CharArrayripples through everything —VpnConfig, the IKE key schedule, the PPP authenticators, and the Compose text fields — turning a data-shape change into a wide refactor of code that is currently correct.- Android hands you
Strings upstream regardless. The user typed into anOutlinedTextField, which isString-valued; those copies exist before any of this code runs and survive whatever the tunnel layer does. Wiping the last copy while the first eight are still on the heap is theatre. - The attacker who can read the heap is the attacker who can also use the keystore key as our UID. See the third row of the threat model.
What a value class buys instead:
@JvmInline
value class Secret(private val value: String) {
override fun toString(): String = "<redacted>"
internal fun expose(): String = value
}- It redacts by design, at compile time, everywhere — no hand-written
toString()to keep in sync, no secrecy test needed to catch the next field somebody adds. - It makes "this is a credential" a property of the type, so
expose()is a grep-able, review-able act rather than an ordinary field read. - It costs nothing at runtime (it erases to the underlying reference).
- And it is exactly the right place to put a
CharArraylater, behind an unchanged public surface, if heap residency ever becomes a real requirement rather than a theoretical one.
That last point is the whole argument: the value class is the cheap move that keeps the expensive move available.
Stated plainly, because the rest of this document reads more confidently than the evidence supports:
- None of this has been verified on a device by execution. What exists is a read-only review of
the code plus plain-JVM unit tests against a fake
SharedPreferences—FakePreferences, which can be made to throwSecurityExceptionthe way the encrypted store does. Those tests cover the store's ordering guarantees, the schema-1 migration (including that the credentials are durable before the old plaintext keys are dropped), the delete-wipes-secrets rule, and the "editing a profile must never destroy a secret the user did not touch" rule. AndroidKeyStoreis unavailable off-device, so nothing here exercises the realEncryptedSharedPreferences, the real master key, or the real wrapping. The claim "the master key is not in an offline copy" rests on the library's documented behaviour, not on an experiment run from this repository.- There is no instrumented test suite.
testInstrumentationRunneris configured inapp/build.gradle.ktsbut noandroidTestsource set exists. - No penetration test, no heap-dump inspection, no forensic extraction has been attempted against a built APK.
- No third-party review. This document is the author's own account of the design.
If any of that changes, this section is the first thing to update.