OhMyKeymint (OMK) uses two active configuration files:
/data/misc/keystore/omk/config.tomlcontrols the KeyMint service, the identity it reports, and the secrets used for OMK-created keys./data/misc/keystore/omk/injector.tomlselects which apps use OMK and which KeyStore requests are routed to it.
This guide describes the active configuration used by the current build. The examples are followed by a separate field-by-field reference so that the short comments in the examples are not the only explanation.
Jump to: config.toml | injector.toml
For ordinary use, the only setting that normally needs changing is scoop in
injector.toml. Keep the safety filters, all [intercept] switches, and the
generated [crypto] values unchanged.
Before making a change:
- Make a private backup of both active files.
- Edit the files under
/data/misc/keystore/omk/, not copies in the module ZIP. - Keep ordinary strings inside quotes and booleans as
trueorfalse. Keep thescoop = [and]lines, then add one bare package name per line; those entries omit both quotes and commas. - Change one thing at a time, save the complete file, and check the matching log after the change.
Never publish [crypto] values, IMEI, IMEI2, MEID, serial numbers, or an
unredacted copy of either active file.
Both components watch their active file for valid changes. Their behavior is not identical:
- A valid
injector.tomlis applied to new requests without a reboot. - A valid
config.tomlis read automatically. The four patch-level fields, biometric compatibility switch, and three TA delay ranges can take full effect without restarting keymint. The field reference below states when a restart is required. - A malformed file saved while its component is running is rejected and the last valid in-memory configuration remains active.
- A malformed
config.tomlpresent when keymint starts prevents keymint from starting. Fix the file and restart keymint. - A malformed
injector.tomlpresent when the injector starts leaves OMK request routing disabled. Saving a valid file lets the watcher restore routing automatically; restart the injector only if it does not recover. - If either file is missing when its component starts, OMK creates a new file with generated defaults. This is not a safe way to reset a working setup: regenerated secrets do not restore keys protected by the previous secrets. The restart commands are documented in Restarting keymint and injector. After changing app routing, close and reopen the affected app to avoid mixing an already-open operation with the new route. If a process restart is needed for a clean boundary, restart the injector only. An injector-only setting change does not require a keymint restart.
The module includes a WebUI for selecting packages in scoop, installing a
local keybox, managing the Android security patch level, and applying a Pixel
PIF fingerprint through OMK's own Zygisk payload. Open it from the Oh My Keymint module page in
KernelSU. With Magisk, open an installed KSUWebUIStandalone or WebUI X host and
select Oh My Keymint; the module does not install either host.
The main package picker shows user applications only. System applications, including Android overlays, are managed through More > Add system apps. Classification uses Android's package-manager list even when the WebUI host cannot provide an application's label or metadata. Hiding system applications from the main list does not remove their saved routing selections.
The Settings page keeps the selected language, theme mode, accent, and visual effects in the WebUI's local storage. Language selection opens a height-limited MIUIX bottom sheet with single-choice rows, including the system-language option. The list scrolls inside the sheet; dismissing it or navigating back leaves the current selection unchanged. When Monet is enabled, Default reads the current Android user's resolved dynamic primary colors from system resources, including wallpaper overlays, for both light and dark mode. Colors refresh on opening the WebUI, returning to the foreground, and system theme changes. Android 14 and newer use named primary roles; Android 12-13 use the equivalent accent palette tones. A fixed accent supplies a custom seed instead. The selected palette style and color standard generate the full MIUIX palette using Material Color Utilities and MIUIX's role mapping, including neutral unchecked controls and themed surfaces. Rainbow and FruitSalad use SPEC_2021, as SPEC_2025 does not define those styles. If system colors cannot be read, the current session retains its last resolved colors, or uses the static MIUIX palette when none are available. No wallpaper data or new persistent cache is created. Turning Monet off restores the static MIUIX light/dark palette while remembering the selected accent for the next time Monet is enabled. Bar blur, floating navigation, and liquid glass are optional and remain disabled until selected; liquid glass uses the floating navigation layout automatically. The bottom navigation stays anchored above the host's bottom safe area while pages switch and restore their own scroll positions. Interface scaling changes the bar's size without scaling the host's safe-area spacing. Top and side safe areas also retain their physical size at every interface scale. Scroll clearance follows the actual navigation height and bottom offset, so the last item can be scrolled fully above the bar.
Native status and navigation bar icons are controlled by the WebUI host.
The WebUI enables edge-to-edge layout and extends its surface behind the system
bars when the host and content use matching light/dark modes. When the modes
differ, only the system safe areas use the host surface from
/internal/colors.css to preserve icon contrast. Hosts without this endpoint
use the WebView's system color preference for this fallback. System bars remain
visible; this does not change the host or Android theme settings.
The Home page reads each identity item independently. The Keybox card parses
the installed XML and checks the private key against its leaf certificate
without rewriting the file. Source classification also verifies every
leaf-to-issuer signature link in leaf-to-root order. A chain is recognized as a
Google key only when that verification reaches a final certificate with one
of Google's pinned attestation-root public keys. The supported RSA root and
the newer EC attestation root are pinned separately. A verified chain ending
in one of these roots is shown as a Google hardware key when its root-adjacent
certificate Subject contains the factory serialNumber attribute. It is shown
as a Google remote key when it carries the RKP ProvisioningInfo extension or
its root-adjacent certificate identifies CN=Droid CA2, O=Google LLC. A chain
without either verified provisioning marker is shown as unknown. The root's key
algorithm and certificate name are not used to infer the provisioning source.
When a Keybox contains multiple algorithm chains, every chain must resolve to
the same known source; an unknown or conflicting chain makes the Keybox source
unknown. The Home page shows only this source classification. The hardware
level is read from the leaf certificate Subject organization (O=TEE or
O=StrongBox) and shown separately as Security Level. Older factory
keyboxes that use the X.520 title attribute (T=TEE or
T=StrongBox) are supported as a compatibility fallback. Valid chains that
do not match either source or level are shown as unknown. The
security-patch card reads the current
ro.build.version.security_patch runtime property. TEE: Normal is shown
only after the injector reaches OMK and obtains the Trusted Environment
security level. The spoofed-device value is the Pixel model in OMK's active PIF
profile; it describes the configured target and is not a separate live check of
a Google Play services process.
The Keybox card checks every certificate serial number from both presented
algorithm chains against Google's attestation status list at
https://android.googleapis.com/attestation/status. A validated local cache
is used for up to 12 hours after its last successful refresh; the next status
check after that interval performs an online lookup. A successful online
lookup is atomically cached at
/data/misc/keystore/omk/data/google_attestation_status.json. If the endpoint
cannot be reached, the WebUI uses that locally validated cache; a first install
is seeded from the validated snapshot shipped in the module. A lookup is shown
as Not revoked when no serial is present. If any serial has a Google status
of SUSPENDED or REVOKED, the card shows Revoked. A network, HTTP,
certificate-parsing, or response-parsing failure is never treated as
Not revoked when neither local source is valid. The cache and bundled
snapshot contain public Google data and can become stale, so Not revoked
does not prove that Play Integrity will accept the Keybox. When a refresh is
due, an unavailable endpoint falls back to the last validated cache and then
the bundled snapshot.
The Home page also keeps the 30 most recent successful WebUI changes in
/data/misc/keystore/omk/data/webui_activity.json. The list covers saved app
targets, Keybox changes, security-patch synchronization
and restore, and PIF enable or disable actions. It stores only the action type,
a short non-secret result such as an entry count, patch date, or Pixel model,
and the completion time. It never stores package-name lists, Keybox contents or
filenames, downloaded response bodies, or a PIF
fingerprint. The Home page initially shows the newest four entries, can expand
the complete retained list, and provides controls to copy an entry or clear the
activity file. Activity recording is supplementary: failure to update this file
does not change the result of a completed WebUI operation.
The WebUI can read and replace the scoop package list and can install a local
keybox selected through Android's system document picker. The picker can use
any installed storage provider, including MT Manager, and requests all MIME
types so providers that label XML as text/plain or application/octet-stream
remain available; the WebUI still requires an .xml filename. If the system
picker cannot be opened, the WebUI falls back to its shared-storage browser.
Its Sync security
patch action uses the root WebUI bridge to make an HTTPS request to the
official https://source.android.com/docs/security/bulletin/asb-overview page,
falling back to Google's official Chinese mirror when the primary host is
unavailable. It extracts the newest published security-patch level and uses
that level's year and month. When the saved default
ro.build.version.security_patch has day 01, the synchronized date also has
day 01; otherwise it keeps the published Google date. The saved system date
is authoritative if it differs from the saved vendor date. The action updates
the four [trust] patch-level fields and uses resetprop to set both
ro.build.version.security_patch and ro.vendor.build.security_patch to that
date. Before the first sync, the native helper saves the current values of both
properties to
/data/misc/keystore/omk/data/security_patch_defaults.toml. A later sync keeps
the existing snapshot instead of replacing the saved defaults.
The action uses the module's native HTTPS client with embedded WebPKI roots;
the device does not need to provide curl or wget. HTTPS redirects are
accepted only when the final URL remains the official bulletin page. A failed
request, unrecognized page, invalid date, or snapshot write leaves the
configuration and properties unchanged. The native helper verifies both
property writes and rolls them back when the paired update or subsequent
configuration write fails. Restore default security patch makes no network
request. It first restores both properties from the snapshot, then sets
security_patch, os_patchlevel, vendor_patchlevel, and boot_patchlevel to
"auto". It deletes the snapshot only after both property restores and the
configuration update succeed; a failed restore retains it for another attempt.
The two properties are global Android runtime state for the current boot, so
every process that reads them can observe the synchronized or restored values.
When Oh My Keymint is uninstalled from KernelSU, the bundled uninstaller removes
exactly /data/adb/omk and /data/misc/keystore/omk. This includes the active
configuration, keybox, logs, and OMK-created key data and cannot be undone. A
module disable does not remove these directories; reboot after an uninstall.
The Spoof PIF fingerprint action is a separate OMK Zygisk integration. It
downloads a Pixel device list from
KOWX712/PlayIntegrityFix's bot/device_list.json, then downloads the selected
bot/device_prop/<product>.prop. The upstream bot refreshes these records
daily from Google's Android preview pages, Android Flash Tool Canary metadata,
and Pixel security bulletin. The helper first tries the exact GitHub Raw path
and then the exact jsDelivr path. It does not run the upstream Autopif shell
script and does not require a device-provided curl, wget, or shell download
tool.
The native helper accepts only the fixed feed paths, validates every catalog
entry, requires exactly FINGERPRINT, MANUFACTURER, MODEL, and
SECURITY_PATCH in a profile, and splits the fingerprint into its eight Build
components. It writes the following LF-delimited values only after they agree
with one another and satisfy TrickyStore's value limits:
MANUFACTURER=Google
MODEL=Pixel ...
FINGERPRINT=google/.../...:.../.../...:user/release-keys
BRAND=google
PRODUCT=...
DEVICE=...
RELEASE=...
ID=...
INCREMENTAL=...
TYPE=user
TAGS=release-keys
SECURITY_PATCH=YYYY-MM-DD
The complete candidate is atomically stored at
/data/misc/keystore/omk/data/pif_fingerprint.json; an invalid download or
failed write leaves the previous profile unchanged. This state file is not
part of either OMK TOML schema. OMK packages its own Zygisk library, which reads
the validated profile through its root companion when a new
com.google.android.gms.unstable or com.android.vending process (including a
named :... child process) is specialized by the Zygisk Next loader. During
pre-app specialization the payload installs available PLT hooks. On AArch64 it
also attempts a process-wide bionic callback hook only after validating the
wrapper semantics, memory mappings, and BTI/MTE permissions. A rejected
callback hook leaves libc unchanged, records the reason, and continues with
the available PLT and Java paths. After specialization the payload updates Java
Build fields and records a property probe. Zygisk Next must already be
installed and enabled by the user; OMK does
not bundle, install, or implement that loader. The helper ends both target
process families after a successful change so a later process receives the
selected values. Disabling spoofing removes the profile and repeats the same
process refresh. The spoof is process-local: it does not call resetprop,
change global Android properties, or change values under OMK's [device]
section.
Soter HAL is a separate Qualcomm integration for
vendor.qti.hardware.soter.ISoter/default. Its WebUI panel exposes only an
enable switch and the Cancel and Save actions. Server URL, B-device ID, token,
UID mapping, and the self-signed-TLS option are not shown. Built-in relay defaults
fill each missing URL, B-device ID, or token field, including when no
configuration has been saved. Existing nonempty custom relay values are
preserved. Enabled configurations with missing fields are also resolved by the
native relay when read.
The switch is disabled by default, TLS certificate
validation remains enabled, and the default UID map is empty. Toggling the
switch changes only the enabled state and preserves the other configuration
fields. Opening or cancelling the panel does not write configuration.
Saving atomically writes
/data/misc/keystore/omk/data/soterta/remote.conf with mode 0600. Built-in
credentials are part of the module and are not secret storage; hiding the
fields in the WebUI does not make them confidential. Custom saved configuration
is device-local. When disabled, the software TA uses its local ledger; when
enabled, supported operations use the configured relay. Relay failures return
the stock dead-TA reply and never fall back to the local ledger. The service is
independent of KeyMint routing, and saved settings survive reboot.
The WebUI sends configuration as one bounded Base64-encoded UTF-8 JSON argument
to --webui-set-soter-hal-base64, then reads --webui-get-soter-hal and checks
every field before reporting a successful save. The raw JSON command
--webui-set-soter-hal remains available for correctly quoted direct CLI calls.
All other WebUI assets are bundled and no network request is made for normal
local operations. None of the WebUI network paths requires a device-provided
curl or wget.
The WebUI does not parse or rewrite injector.toml itself. It sends the package
list to the native inject helper. The helper first parses the current complete
file, normalizes duplicate and surrounding whitespace, rejects invalid package
names and TrickyStore-style ! or ? suffixes, then renders and atomically
replaces the complete file while preserving its ownership and mode. A read,
parse, validation, or write failure is returned to the WebUI and leaves the
existing file unchanged. Saving remains disabled when the current list could
not be loaded.
A successful save triggers the same injector hot-reload path as a valid manual edit. It applies to new requests without restarting keymint. Close and reopen the affected app when a clean routing boundary is required.
For a keybox installation, the native keymint helper enforces the input size
limit, decodes the selected file as UTF-8, and runs the complete in-memory
KeyBox validation, including private-key and certificate-chain matching. Only
then does it atomically replace the canonical lowercase
/data/misc/keystore/omk/keybox.xml. A read, size, UTF-8, validation, or write
failure leaves the active keybox unchanged. The keybox watcher loads a
successful replacement automatically, so a restart is normally unnecessary.
RSA-only, EC-only, and combined keyboxes are supported. When only one algorithm
is present, its key signs attestation leaves for both RSA and EC subject keys.
RSA private keys accept unencrypted PKCS#1 or PKCS#8 PEM encoding and normalize
to PKCS#1 for identity hashing and XML export.
EC private keys accept unencrypted SEC1 or PKCS#8 PEM encoding and normalize
to SEC1 for identity hashing and XML export. Adding or removing only the
PKCS#8 wrapper preserves the keybox identity when the inner SEC1 fields and
certificate chain are unchanged. A named curve carried only in the PKCS#8
algorithm identifier is restored into the SEC1 parameters.
The reload preserves ordinary application signing keys, including passkey
credentials. Only dedicated ATTEST_KEY entries tied to the previous keybox
are retired.
The values under [crypto] below are deliberately non-working redaction
placeholders. A real active file contains unique generated hexadecimal values.
Never paste the placeholder values into a device and never replace the values
already present in a working file. The [trust] and [device] values are also
examples; keep the values from the active file unless you intend to change the
reported identity.
# Configuration format. Keep this at 2.
version = 2
[main]
# The supported service connection. Keep this value unchanged.
backend = "injector"
# KeyMint log detail: off, error, warn, info, debug, or trace.
log_level = "debug"
# Insecure biometric compatibility switch. Keep false for normal use.
force_skip_system_biometric_hat_verification = false
# Extra random wait per software TA call: inclusive [minimum, maximum] in ms.
# These defaults also apply when fields are absent; [0, 0] disables a category.
ta_operation_delay_ms = [9, 21]
ta_generation_delay_ms = [6, 16]
ta_control_delay_ms = [1, 4]
[crypto]
# Redacted placeholders only. Keep the generated 64-character values.
root_kek_seed = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
kak_seed = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
shared_secret_seed = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
shared_secret_nonce = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
# Optional expert override. Normally leave this line absent.
# auth_token_hmac_key = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
[trust]
# Detect the Android major at each keymint start; use an integer to fix it.
os_version = "auto"
# Use auto, latest, or an exact YYYY-MM-DD date; boot also accepts decimal u32.
security_patch = "auto"
os_patchlevel = "auto"
vendor_patchlevel = "auto"
boot_patchlevel = "auto"
# Use auto, random, or exactly 64 hexadecimal characters.
vb_key = "auto"
vb_hash = "auto"
# Report verified boot and a locked bootloader when true.
verified_boot_state = true
device_locked = true
[device]
# Device identity strings reported when an app requests attestation IDs.
brand = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
device = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
product = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
manufacturer = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
model = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
serial = "KEEP_THE_VALUE_FROM_THE_ACTIVE_FILE"
# false fills only empty telephony fields from the device when available.
overrideTelephonyProperties = false
# Empty optional identifiers are valid; do not invent missing values.
meid = ""
imei = ""
imei2 = ""This identifies the configuration format. The supported value is the integer
2. It is not an Android version or an OMK release number. Do not increment it;
the current file should keep this value unchanged. Live reload rejects other
values and keeps the last valid runtime configuration.
At keymint startup, a missing version is treated as 0. Versions 0 and 1
are migrated in place to 2 before the service starts, and os_version is set
to "auto" so later Android upgrades are detected on the next keymint start.
Startup also removes the obsolete trust_record. For version 0, missing
patch-level fields inherit the configured security_patch. Other configured
and unknown values are preserved. Migration is not performed during live
reload, so restart keymint to migrate an older file. An unsupported future
version is never overwritten.
Use "injector". It is the only supported user choice and there is no
alternative runtime backend to select, so this field should be left unchanged.
This controls messages written by keymint. Use one of "off", "error",
"warn", "info", "debug", or "trace". "debug" is the default and is
the most useful level for a bug report. "trace" is more verbose; "off"
suppresses normal logging.
Changing this field requires a keymint restart. An unrecognized value falls
back to debug, but relying on that fallback can hide a spelling mistake.
This is an insecure compatibility switch for a device whose System KeyMint
cannot verify biometric authentication tokens correctly. When true, OMK
accepts a token whose structure is valid without asking System KeyMint to
verify its authentication code.
Keep it false unless a maintainer is diagnosing a confirmed device-specific
problem. It does not hide root and is not a general fix for fingerprint or
lock-screen failures. A valid save applies to new checks without restarting
keymint.
These three [main] fields configure extra random waits before OMK dispatches
calls to its software TA:
| Field | Default range (ms) | Covered TA calls |
|---|---|---|
ta_operation_delay_ms |
[9, 21] |
begin, updateAad, update, finish, abort, getKeyCharacteristics |
ta_generation_delay_ms |
[6, 16] |
generateKey, importKey, importWrappedKey, upgradeKey, convertStorageKeyToEphemeral |
ta_control_delay_ms |
[1, 4] |
getHardwareInfo, addRngEntropy, deleteKey, deleteAllKeys, destroyAttestationIds, earlyBootEnded, getRootOfTrustChallenge, getRootOfTrust, sendRootOfTrust, setAdditionalAttestationInfo |
Each value must be an array of exactly two integers, [minimum, maximum],
with 0 <= minimum <= maximum <= 250. Both endpoints are milliseconds and
are inclusive. [0, 0] disables that category; equal nonzero endpoints request
a fixed wait. Omitting a field enables its default range from the table.
For every covered TA invocation, OMK samples a new wait uniformly at microsecond granularity between the configured endpoints. Calls in a category share the same range, but do not reuse one sample for the category or thread. The wait is added to processing time; it is neither a target total duration nor a cap. Scheduling can extend the wait beyond the selected value, and one app request that makes several covered TA calls accumulates their waits.
The wait occurs before TA dispatch and before acquiring the TA mutex, with the configuration read guard released. The caller's Binder worker, RPC connection, per-operation concurrency guard, or database guard can remain occupied during the wait. Concurrent requests can therefore delay one another. A dispatched call receives its wait even if the TA returns an error; validation failures that return before TA dispatch do not. Raw TA initialization, local cache and authentication helpers, and calls routed to System are excluded.
Valid changes apply to new TA calls without restarting keymint. A malformed
array, non-integer value, out-of-range endpoint, or reversed range rejects the
configuration; live reload keeps the previous valid configuration. Edit these
fields in the existing active file while preserving its other values. OMK
generates config.toml on the device; the module does not ship a reusable main
configuration template.
These waits are independent of the fixed
attestation_generation_delay_ms and
operation_start_delay_ms settings in
injector.toml. An applicable nonzero injector delay is added as well. For
example, operation_start_delay_ms = 12 plus the default TA operation range
adds a 12 ms wait before the RPC and a separately sampled 9-21 ms wait before
the TA begin call. Set both injector delays to 0 if only the TA ranges are
wanted. Changing software timing does not provide hardware security, constrain
total calls to a hardware timing interval, or guarantee a detector result.
Every value in this section is private. Each value is exactly 32 bytes written
as 64 hexadecimal characters using 0-9 and a-f. OMK generates these values
when it creates a new configuration.
Keep all four generated seed and nonce fields present and stable, and back them up privately with the OMK data. Changing or removing any of them requires a keymint restart and can make existing keys or authentication-bound operations unusable. Values from another device and the redacted placeholders in this guide are not replacements for the active values.
If shared_secret_seed or shared_secret_nonce is missing, OMK generates a
new random replacement when it reads the file. That is not a stable active
configuration, so make sure both generated values remain present.
This seed is used to derive key material that protects OMK key blobs. If it changes, OMK may no longer be able to open keys created with the previous value. It must be present and must remain unchanged.
This seed is used for OMK's key-agreement protection. It belongs to the same
device-specific secret set as root_kek_seed. It must be present and must
remain unchanged.
This is the seed half of the shared-secret parameters used for authentication
token verification. Preserve it together with shared_secret_nonce; changing
only one side still changes the resulting secret.
This is the nonce half of the shared-secret parameters. It is also a full 64-character hexadecimal value, not a short counter or a value to regenerate manually.
This optional field supplies an explicit authentication-token HMAC key.
When it is absent, OMK derives the required key through
shared_secret_seed and shared_secret_nonce. Ordinary users should leave the
field absent. If it is explicitly present, it must also contain exactly 64
hexadecimal characters and must be kept private and stable.
These fields control values reported through key attestation. They do not repair hardware, renew a certificate, remove a keybox revocation, or hide root.
Use "auto" to detect the current Android major each time the keymint process
starts, or use an integer from 0 through 99 to keep a fixed major such as
12, 16, or 17. Do not write a dotted release, SDK number, or security
patch date here. KeyMint encodes the resolved major with the AOSP MMmmss
formula, so fixed 16 is reported as 160000. Changing this field requires a
keymint restart.
This controls ro.build.version.security_patch. It accepts:
"auto": use the currentro.build.version.security_patchvalue without writing it;"latest": use the fifth day of the current calendar month when the value is resolved; or- an actual date written as
"YYYY-MM-DD", including leading zeroes.
The WebUI Sync security patch action is separate from the "latest" mode.
It reads the main table on Google's Android Security Bulletin overview,
selects the greatest published security-patch date that is not in the future,
and uses its year and month as the newest published patch month. The day is
selected from the saved default ro.build.version.security_patch: day 01
uses day 01 in that newest month, while day 05 uses the Google bulletin
date unchanged. Any other saved day also keeps the Google bulletin date. If
the saved ro.build.version.security_patch and
ro.vendor.build.security_patch dates differ, the system value determines
the day behavior. For example, when the newest Google date is 2026-08-05, a
saved system default of 2025-06-01 synchronizes 2026-08-01, while
2025-06-05 synchronizes 2026-08-05. This does not change the separate
"latest" mode described above. The action never guesses an unpublished
current-month patch month. It requires network access to Google's official
bulletin host or mirror; if access or parsing fails, no file or property is
changed. The native helper validates the selected date again and preserves all
unrelated configuration values. After a successful sync or restore, the WebUI
shows a completion message asking you to reboot the device; it does not reboot
automatically.
Before changing runtime properties for the first sync, the helper atomically
saves both default properties to
/data/misc/keystore/omk/data/security_patch_defaults.toml. When all four
[trust] patch-level fields are auto, those defaults are read from the
current runtime properties; for an explicit date or a mixed configuration, they
are read from the trusted build.prop sources. An existing valid snapshot for
the same build fingerprint is retained across repeated syncs. The helper then
sets both properties to the selected date with resetprop and verifies the
results. After that, it writes the date to security_patch, os_patchlevel,
vendor_patchlevel, and boot_patchlevel. These are global Android properties
for the current boot, not values visible only to OMK.
While a valid defaults snapshot exists and all four configuration fields still contain the same exact date, the module's early boot hook reapplies that date to both properties before Android framework values are cached. Keymint also reapplies the pair at startup. The snapshot is the persistent marker for a WebUI synchronization: a manually authored exact-date configuration without a snapshot follows the normal patch-level path and does not cause an extra vendor-property write. If the optional snapshot cannot be read or validated, both paths skip this paired reapply and keymint continues its normal initialization.
The WebUI Restore default security patch action uses the saved snapshot and
does not access the network. If the snapshot is absent, the helper records the
current runtime properties as the restore values. It restores both properties
first, writes "auto" to security_patch, os_patchlevel,
vendor_patchlevel, and boot_patchlevel, and deletes the snapshot only when
every step succeeds. It preserves every other configuration value. A malformed
or unverifiable snapshot stops the operation before either property or the
configuration changes. A failed paired property update is rolled back. If the
configuration write fails, the helper attempts to roll back both properties;
any incomplete restore retains the snapshot so the action can be retried. The
helper serializes these actions with startup and live configuration reloads so
an older pending reload cannot overwrite a completed restore.
"auto" first uses a nonempty runtime property, then the exact key from the
standard build.prop locations, and finally 2025-06-05 if neither source is
available. A present runtime value is used as-is rather than replaced by a
build.prop value. "latest" and an exact date intentionally overwrite an
existing runtime property, but OMK never creates or deletes it. "auto" never
writes the property. After an explicit or "latest" override, manually
switching back to "auto" in the same boot keeps the current runtime value;
reboot to restore the system-provided value. The WebUI restore action instead
restores the saved system and vendor runtime properties before writing "auto".
This controls the KeyMint OS patch level. "auto" follows the effective
security_patch; "latest" and an exact "YYYY-MM-DD" date override it for
KeyMint without writing another property. The final value is parsed with the
AOSP YYYY-MM-DD parser and encoded as YYYYMM.
This controls the KeyMint vendor patch level. "auto" first reads the nonempty
runtime ro.vendor.build.security_patch, then the exact key from the standard
build.prop locations, and finally falls back to the effective
os_patchlevel. "latest" and an exact "YYYY-MM-DD" date are also accepted.
The final value is parsed with the AOSP YYYY-MM-DD parser and encoded as
YYYYMMDD. A present nonempty source is not replaced by a lower-priority source
merely because parsing later fails. Normal patch-level resolution does not write
the vendor property; the WebUI sync and restore actions explicitly update it as
described above.
This controls the KeyMint boot patch level. "auto" first reads
com.android.build.boot.security_patch from the active top-level vbmeta image.
If the property is absent, OMK reads the same property from the active boot
image's standalone or AVB-footer embedded vbmeta, then falls back to the boot
header. The legacy header field stores a year and month but no day, so its wire
value ends in 00; an all-zero field therefore becomes 20000000, but only
after neither vbmeta location supplied the property. If boot-metadata resolution
fails, OMK uses this fallback order: nonempty runtime
ro.vendor.boot_security_patch, the exact key from the standard build.prop
locations, then the effective os_patchlevel.
"latest", an exact "YYYY-MM-DD" date, and a decimal u32 wire value are
also accepted. The decimal form preserves bootloader wire values such as
"20000000" without interpreting them as dates. These explicit modes do not
read boot metadata. Boot patch-level resolution does not read the system TEE or
write the boot property. During hot reload, an unchanged "auto" keeps the
value resolved before keymint dropped privileges; switching from an override
back to "auto" takes effect after keymint restarts. Explicit dates are encoded
as YYYYMMDD.
If the selected value cannot be converted, startup fails; a failed hot update
keeps the previous runtime configuration.
The four patch-level fields are resolved and applied together while keymint is
running when no other [trust] field changes in the same save. Existing TAs are
updated in place so in-flight operations and per-boot counters remain intact;
equivalent boot representations do not trigger an update. If the matching log
reports that the live update failed, restart keymint.
This controls the 32-byte verified-boot public-key digest:
"auto"first readsro.boot.vbmeta.public_key_digest, then tries to calculate the top-level vbmeta key digest, and uses a random fallback only if neither source is available;"random"generates a new value whenever keymint starts; or- a 64-character hexadecimal string pins an exact value.
Keep "auto" unless you understand the attestation profile being configured.
Changing this field requires a keymint restart. If "random" was active and
you change it back to "auto", reboot the whole device so Android restores the
original boot property before "auto" reads it.
This controls the 32-byte verified-boot hash:
"auto"first readsro.boot.vbmeta.digest, then tries the original System attestation hash, and uses a random fallback only if neither source is available;"random"generates a new value whenever keymint starts; or- a 64-character hexadecimal string pins an exact value.
The same restart rule applies as for vb_key: restart keymint after a normal
change, and reboot the whole device when returning from "random" to
"auto".
true reports the verified boot state as verified; false reports it as
unverified. This is independent of the device_locked switch. Changing it
requires a keymint restart.
true reports that the device boot state is locked; false reports it as
unlocked. This does not actually lock or unlock the bootloader. Changing it
requires a keymint restart.
This section supplies device identity strings when an app explicitly requests attestation IDs. These values are personal data. Use the values already generated for the device, and restart keymint after changing this section so the one-shot attestation-ID snapshot is rebuilt.
The product brand reported in an attestation ID request, normally based on
ro.product.brand when a new configuration is created.
The device code name reported in an attestation ID request, normally based on
ro.product.device.
The product name reported in an attestation ID request, normally based on
ro.product.name.
The manufacturer name reported in an attestation ID request, normally based on
ro.product.manufacturer.
The model name reported in an attestation ID request, normally based on
ro.product.model.
The device serial reported in an attestation ID request, normally based on
ro.serialno. Treat it as private information and redact it from reports.
With the recommended value false, OMK tries to fill only empty imei,
imei2, and meid fields from the device's telephony services and property
fallbacks. A configured non-empty value is preserved, and OMK attempts to write
each successfully discovered value back to the active config.toml.
With true, OMK skips telephony discovery and uses the three configured fields
exactly as written, including empty strings. Use this only when intentionally
pinning the values.
The primary IMEI. Leave it empty when the device has no IMEI or when automatic discovery should fill it. Do not invent a value to satisfy an app.
The second IMEI. Single-SIM and some dual-SIM devices can legitimately leave it
empty. Its absence does not invalidate imei or the non-telephony device
fields.
The MEID used by devices that provide one. Many devices have no MEID, so an empty value is valid. Its absence does not invalidate an available IMEI.
| Fields | Required action |
|---|---|
[main].log_level |
Restart keymint. |
[main].force_skip_system_biometric_hat_verification |
Applies to new checks after a valid save. |
[main].ta_operation_delay_ms, ta_generation_delay_ms, ta_control_delay_ms |
Apply to new TA calls after a valid save; invalid ranges retain the previous configuration. |
All [crypto] fields |
Restart keymint; changing values can make keys unusable. |
[trust].security_patch, os_patchlevel, vendor_patchlevel, boot_patchlevel |
Hot-apply as a group when no other [trust] field changes; otherwise restart keymint. |
[trust].os_version |
Restart keymint. |
Other [trust] fields |
Restart keymint. |
All [device] fields |
Restart keymint to rebuild the cached ID snapshot. |
vb_key or vb_hash from "random" to "auto" |
Reboot the whole device. |
# Configuration format. Keep this at 1.
version = 1
# Add one exact package name per line. Blank lines and lines whose first non-space character is # are ignored.
# Bare entries omit quotes and commas; keep the surrounding scoop = [ ... ] lines.
scoop = [
io.github.vvb2060.keyattestation
com.google.android.gsf
com.google.android.gms
com.android.vending
com.eltavine.duckdetector
]
[main]
# Master switch for request routing. Keep true for normal use.
enabled = true
# Injector log detail: off, error, warn, info, debug, or trace.
log_level = "debug"
# Optional delay before challenged OMK generation, 0..250 ms.
attestation_generation_delay_ms = 0
# Optional delay before two-way OMK createOperation calls, 0..250 ms.
operation_start_delay_ms = 0
[filter]
# Enforce scoop and the safety rules below.
enabled = true
# Packages that must never use OMK, even if another shared package is in scoop.
deny_packages = []
# Block core Android and system identities. Keep true.
block_android_package = true
# Reject callers whose package name cannot be found. Keep false.
allow_unknown_package = false
[intercept]
# Route each named KeyStore operation to OMK for an allowed caller.
get_security_level = true
get_key_entry = true
update_subcomponent = true
list_entries = true
delete_key = true
grant = true
ungrant = true
get_number_of_entries = true
list_entries_batched = true
get_supplementary_attestation_info = trueThis identifies the injector configuration format. Keep the integer value 1.
It is not an Android version or an OMK release number. Live reload rejects
other values and keeps the last valid runtime configuration.
At injector startup, a missing version is treated as 0, and version 0 is
migrated in place to 1 while preserving the rest of the file. Version 0 is
not migrated during live reload, so restart the injector to migrate such a
file. An unsupported future version is never overwritten.
If a documented injector field is omitted, its default value is used. Unknown fields in the documented top-level and named sections are rejected, so do not add names that are not described in this guide.
This array contains exact Android package names that may use OMK. Keep the
surrounding scoop = [ and ] lines and add one bare package name per line,
matching the line-oriented package list used by TrickyStore. Bare entries omit
both quotes and commas. Empty lines and lines whose first non-space character
is # are ignored, and surrounding spaces are trimmed. The traditional
quoted, comma-separated TOML array form is also accepted. Empty entries are
removed and duplicate entries are reduced to one when the file is loaded. App
labels, partial names, and wildcards are not accepted. TrickyStore's !
generate suffix is not interpreted; enter the exact package name only.
The embedded WebUI presents installed package names and saves the selected
ones through the native helper described above. A WebUI save replaces only the
normalized scoop list; [main], [filter], [intercept], and preserved
per-package tables retain their current values. Opening the package selector,
returning to it from another app, or using its refresh action reloads installed
packages without discarding selections that have not yet been saved.
Android can assign several packages the same identity. In that case, listing any one of those packages allows the shared identity, unless a filter rule rejects one of the packages in the group. Adding or removing a package does not move or convert keys between System and OMK; an app may lose access to keys it created through the other route.
There is one narrow granted-key exception. An app outside scoop, or one whose
package name cannot be resolved, can still use a key-access grant that OMK
confirms belongs to an OMK key. This keeps a key deliberately shared by another
app usable without giving the receiving app general OMK access. Android-blocked
and deny-listed callers do not receive this exception.
This is the injector's master routing switch. true lets the filter and
[intercept] settings decide each new request. false stops new OMK routing so
normal requests continue to System. Keep it true for normal OMK use.
Avoid changing this switch while an app has a key operation open. Save the change, restart the injector, and reopen the app when deliberately switching routes.
This controls injector messages. Accepted values are "off", "error",
"warn", "warning", "info", "debug", and "trace"; "warning" is an
alias for "warn". Matching is case-insensitive, but lowercase values are
recommended. "debug" is the default and the normal choice for a bug report.
A valid file change updates the level without restarting the injector. An
unrecognized string does not make the TOML file invalid; the injector uses
debug instead.
Optional timing workaround, an integer from 0 to 250 milliseconds. The
default 0 disables it. A nonzero value delays OMK generateKey requests
containing ATTESTATION_CHALLENGE before the generation RPC starts. Both
two-way and one-way requests receive this delay, including calls that return
OMK business errors. Plain generation, imports, operations, System requests,
and failures before generation dispatch do not receive this delay.
This can mitigate clients that classify software KeyMint by generation
timing. It does not provide hardware security or guarantee a detector result.
For example, 25 adds at least 25 ms before each affected generation;
scheduling can add more. The wait occurs before creating or storing the new
key, without holding the RPC connection or KeyMint/database locks. The Binder
worker stays occupied, so concurrent requests can delay unrelated callers.
Key storage and reply delivery remain separate steps; this setting does not
promise that a concurrent reader cannot observe a key before the generation
reply arrives. Leave it at 0 unless needed.
This fixed wait adds to any applicable config.toml TA waits.
Valid changes apply without a restart. Out-of-range or non-integer values reject the configuration; on reload, the previous valid settings remain active.
Optional timing workaround, an integer from 0 to 250 milliseconds. The
default 0 disables it. A nonzero value delays two-way OMK createOperation
requests before the operation RPC starts. Both successful calls and calls that
return OMK business errors receive this delay. One-way calls, System requests,
and other methods do not receive this delay.
For example, 12 adds at least 12 ms to each affected operation start;
scheduling can add more. The waiting Binder worker stays occupied, so many
concurrent calls can delay unrelated callers. Waiting occurs before creating
the operation, without holding the RPC connection or KeyMint/database locks,
and does not allocate an operation slot during the wait. Existing operations
remain subject to their normal lifecycle and pruning rules.
This option can mitigate clients that classify software KeyMint by operation
timing. It does not alter permission checks, key metadata, routing, or reported
security levels, provide hardware security, or guarantee a detector result.
Leave it at 0 unless needed. Valid changes apply without a restart.
Out-of-range or non-integer values reject the configuration; on reload, the
previous valid settings remain active.
This fixed wait adds to any applicable config.toml TA waits.
With the filter enabled, OMK evaluates a caller in this order:
- Reject a core Android or system identity when
block_android_package = true. - If its package names cannot be resolved, follow
allow_unknown_package. - Reject the whole identity if any resolved package is in
deny_packages. - Reject it if none of its resolved packages is in
scoop. - Otherwise allow it to use the enabled
[intercept]routes.
This order matters for packages that share an Android identity: a deny rule
wins over a matching entry in scoop.
After this normal filter decision, the narrow OMK-owned grant exception
described under scoop can preserve access for an unknown or out-of-scope app.
It does not override the Android-package block or deny_packages.
true enforces scoop, the deny list, the Android-package block, and the
unknown-package policy. false bypasses all four checks and allows every
caller to reach any operation enabled under [intercept].
Disabling the filter can route Android services and unrelated apps to OMK and
can break unlocking, app storage, or the user interface. Keep it true.
This is an array of exact package names that must not use OMK. It is useful
when a selected package shares its Android identity with another package that
must stay on System. If any package resolved for the identity is denied, the
entire identity is rejected even when another package is listed in scoop.
An empty array, [], is the default. This list uses the standard quoted,
comma-separated TOML array format; the line-based shorthand is specific to
scoop.
true rejects core Android and system identities before scoop is considered.
It also rejects resolved package names equal to android or beginning with
android.. It does not mean that every ordinary app whose name begins with
com.android. is automatically blocked.
Keep this setting true. Setting it to false only removes this safety check;
the remaining filter rules still apply.
This controls a caller whose Android package name cannot be resolved. false
rejects that caller, which is the safe default. true allows an unresolved app
identity without requiring a match in scoop; core Android identities are
still rejected when block_android_package = true.
This setting is not an "all apps" switch. Keep it false unless a maintainer
has confirmed that a supported app cannot be resolved normally.
Each switch controls one Android KeyStore service operation. For a caller
allowed by the filter, true routes that operation to OMK and false leaves
that operation on System. These switches do not migrate existing keys or make
System-created key references usable by OMK.
Service, maintenance, and authorization requests must match the actual Binder
object registered for their interface before OMK dispatch or state mirroring.
An interface token naming a different Binder service is left to the system
interface check and does not trigger OMK work. Registered Binder identities
are resolved independently on a dedicated thread. If an identity is not yet
available, calls requiring OMK execution or mandatory state mirroring return
SYSTEM_ERROR without executing a backend; calls configured for System stay
on System. Best-effort authentication-token updates also stay on System while
their service identity is unavailable. Missing service identities are retried
automatically.
Isolated Android service callers use the system ActivityManager process record for package attribution when ordinary UID package lookup has no result. The privileged helper matches the Binder caller PID and checks its kernel UID and process start time before and after the lookup. Only the process package list affects the existing package filter; dependency packages are excluded. Null package-list entries are ignored; present package names must pass validation. The original isolated UID, PID, and SELinux identity remain authoritative for key permissions. Failed or unsupported lookups retain unknown-package behavior. The ActivityManager transaction number is read from the installed system framework's AIDL Stub constant, allowing vendor method-number changes without probing unknown transactions. The constant is cached only in memory; process ownership is queried and checked for each unresolved isolated caller request. This attribution has no key-descriptor or backend-origin dependency and does not override deny lists or per-method interception settings.
The OMK-owned grant exception is separate from ordinary package routing. A
request carrying a confirmed OMK grant may return to OMK even when the
receiving app is outside scoop, so the granted key remains usable.
Keep all switches true for normal use. Mixing System and OMK operations for
the same app can cause missing-key errors, inconsistent lists, or failed
follow-up operations.
Calls on an OMK operation handle follow the Keystore2 concurrency contract.
Overlapping updateAad, update, finish, or abort calls on the same handle
return OPERATION_BUSY (19) while another call is in progress. A busy response
leaves that operation usable. Each operation has its own concurrency guard,
so calls on different handles do not contend on this guard.
The software TA allocates 32 concurrent operation slots for an AIDL KeyMint
TEE profile and 16 for a legacy Keymaster TEE profile. StrongBox profiles
retain four slots. A full TA table returns TOO_MANY_OPERATIONS to the
existing Keystore2 pruning path; finish and abort release their slots.
These limits do not change request routing or provide hardware isolation.
Controls the request for a TEE or StrongBox KeyStore security-level handle. Apps use this handle for later operations such as creating, importing, and using keys.
Controls retrieval of an existing key entry, including its metadata and the handle used for later key operations.
Controls replacement of an existing key entry's certificate or certificate chain components.
Controls listing key aliases in a requested namespace.
Controls deletion of a named key. The selected backend is authoritative; OMK does not delete a matching System key as a substitute.
Controls granting another app access to a key.
Controls removal of a previously granted key permission.
Controls counting the key entries in a namespace.
Controls paged or batched listing of key entries.
Controls retrieval of supplementary information used by supported attestation requests.
Per-package tables such as [scoop.com.example.app] and values such as
mode = "strict" are not supported routing options. They may be preserved when
the file is parsed, but they do not change which backend handles a request. Do
not add them; use scoop, [filter], and [intercept] instead.
Every valid documented field change is loaded for new requests without a
device reboot. For scoop, [main].enabled, [filter], or [intercept]
changes, restart the injector and reopen the affected app when you need a clean
boundary after a route change. A syntax error, an unknown field, or an
unsupported future version leaves the last valid runtime configuration
active; if present at injector startup, it leaves OMK request routing disabled
until the file is corrected.
The embedded WebUI can change scoop, install a locally selected keybox,
synchronize the four [trust] patch-level fields from the official Android
Security Bulletin, restore those fields to "auto", manage the validated PIF
profile, and configure the independent Qualcomm Soter
HAL relay used by the WeChat payment fingerprint path. Security-patch sync and restore also manage
the two global runtime properties and the defaults snapshot described above.
Persistent native save paths validate the complete candidate before writing and
use atomic replacement. Successful saves enter the applicable watcher hot-reload
path.