Skip to content

Latest commit

 

History

History
1144 lines (929 loc) · 56.4 KB

CONFIGURATION.md

File metadata and controls

1144 lines (929 loc) · 56.4 KB

Configuration Guide

OhMyKeymint (OMK) uses two active configuration files:

  • /data/misc/keystore/omk/config.toml controls the KeyMint service, the identity it reports, and the secrets used for OMK-created keys.
  • /data/misc/keystore/omk/injector.toml selects 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

Before editing

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:

  1. Make a private backup of both active files.
  2. Edit the files under /data/misc/keystore/omk/, not copies in the module ZIP.
  3. Keep ordinary strings inside quotes and booleans as true or false. Keep the scoop = [ and ] lines, then add one bare package name per line; those entries omit both quotes and commas.
  4. 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.

How changes are loaded

Both components watch their active file for valid changes. Their behavior is not identical:

  • A valid injector.toml is applied to new requests without a reboot.
  • A valid config.toml is 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.toml present when keymint starts prevents keymint from starting. Fix the file and restart keymint.
  • A malformed injector.toml present 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.

Embedded WebUI

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.

config.toml

Complete annotated example

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 = ""

Top-level field

version

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.

[main]

backend

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.

log_level

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.

force_skip_system_biometric_hat_verification

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.

TA delay ranges

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.

[crypto]

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.

root_kek_seed

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.

kak_seed

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.

shared_secret_seed

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.

shared_secret_nonce

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.

auth_token_hmac_key

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.

[trust]

These fields control values reported through key attestation. They do not repair hardware, renew a certificate, remove a keybox revocation, or hide root.

os_version

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.

security_patch

This controls ro.build.version.security_patch. It accepts:

  • "auto": use the current ro.build.version.security_patch value 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".

os_patchlevel

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.

vendor_patchlevel

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.

boot_patchlevel

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.

vb_key

This controls the 32-byte verified-boot public-key digest:

  • "auto" first reads ro.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.

vb_hash

This controls the 32-byte verified-boot hash:

  • "auto" first reads ro.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".

verified_boot_state

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.

device_locked

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.

[device]

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.

brand

The product brand reported in an attestation ID request, normally based on ro.product.brand when a new configuration is created.

device

The device code name reported in an attestation ID request, normally based on ro.product.device.

product

The product name reported in an attestation ID request, normally based on ro.product.name.

manufacturer

The manufacturer name reported in an attestation ID request, normally based on ro.product.manufacturer.

model

The model name reported in an attestation ID request, normally based on ro.product.model.

serial

The device serial reported in an attestation ID request, normally based on ro.serialno. Treat it as private information and redact it from reports.

overrideTelephonyProperties

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.

imei

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.

imei2

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.

meid

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.

config.toml apply summary

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.

injector.toml

Complete annotated example

# 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 = true

Top-level fields

version

This 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.

scoop

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.

[main]

enabled

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.

log_level

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.

attestation_generation_delay_ms

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.

operation_start_delay_ms

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.

[filter]

With the filter enabled, OMK evaluates a caller in this order:

  1. Reject a core Android or system identity when block_android_package = true.
  2. If its package names cannot be resolved, follow allow_unknown_package.
  3. Reject the whole identity if any resolved package is in deny_packages.
  4. Reject it if none of its resolved packages is in scoop.
  5. 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.

enabled

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.

deny_packages

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.

block_android_package

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.

allow_unknown_package

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.

[intercept]

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.

get_security_level

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.

get_key_entry

Controls retrieval of an existing key entry, including its metadata and the handle used for later key operations.

update_subcomponent

Controls replacement of an existing key entry's certificate or certificate chain components.

list_entries

Controls listing key aliases in a requested namespace.

delete_key

Controls deletion of a named key. The selected backend is authoritative; OMK does not delete a matching System key as a substitute.

grant

Controls granting another app access to a key.

ungrant

Controls removal of a previously granted key permission.

get_number_of_entries

Controls counting the key entries in a namespace.

list_entries_batched

Controls paged or batched listing of key entries.

get_supplementary_attestation_info

Controls retrieval of supplementary information used by supported attestation requests.

Per-package subtables

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.

injector.toml apply summary

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.