# Native OMAPI service This is an implementation of the [Android binding](https://globalplatform.org/specs-library/open-mobile-api-omapi-android-binding-v1-0-for-omapi-v3-3/) for the [Global Platform OMAPI specification](https://globalplatform.org/specs-library/open-mobile-api-specification-v3-3/) used to provide the backend of the Android [SEService API](https://developer.android.com/reference/android/se/omapi/SEService). OMAPI specifies an interface for device applications and system components to communicate with a set of [ISO 7816-4](https://en.wikipedia.org/wiki/ISO/IEC_7816) secure elements (SEs), multiplexing access to the SEs so that multiple apps can communicate with one secure element, and controlling which apps are allowed to communicate with which SE applets. This implementation is modeled on and intended to replace the Java APK-based implementation that was contributed by partners in Android 10. That implementation cannot start in early boot, but because the platform needs to be able to communicate with StrongBox and perform SE updates during early boot, we need an OMAPI service that run and be used earlier. This implementation also optimizes early accesses by providing a mechanism to avoid reading the access control rules from the SE for system components whose access is statically authorized by the platform. ## Terminals An Android device can have any number of secure element terminals, divided into two categories, SIMs and ESEs. SIMs are typically, but not always, removable smart card chips. ESEs are typically discrete secure element chips soldered into the mainboard, but may also be integrated into the system on a chip. There is no significant diffence in the way the OMAPI service treats SIMs and ESEs, but they're divided into separate namespaces by the underlying service naming conventions. The OMAPI service finds available terminals by enumerating the available `ISecureElement` HAL service names. Only AIDL services are supported (the Java implementation also supports HIDL services, but those have been deprecated for several Android releases). The service names all follow the pattern `android.hardware.secure_element.ISecureElement/{name}`, where `{name}` is replaced by a string of the form `SIM#` or `ESE#`, with the `#` replaced by a terminal number. Terminal numbers must be consecutive and start with 1, so a device with two SIM slots and one embedded SE would have services with terminal names "SIM1", "SIM2", and "ESE1". The service will block on the availability of SIM1 and ESE1, if their HALs are registered. This mirrors the behavior of the Java implementation but may not be correct for a service that starts early in boot. See the section "Unsupported features" below. ## Access control Five access control mechanisms are supported, two relying on rules provided by the SE and three relying on configuration provided by the host Android platform: - ARA-M rules provided by SE; - ARA-M rules provided by the platform; - ARA-D rules provided by SE; - Android permission `SECURE_ELEMENT_PRIVILEGED_OPERATION`; and - Platform security profile (applicable only to debug builds). ### ARA-M rules provided by the SE [ARA-M](https://globalplatform.org/specs-library/secure-element-access-control_gpd_spe_013/) specifies an APDU-based API for retrieving access control rules from the secure element and an encoding for the rule data. ARA-M rules consist of two parts: matching criteria and an action. The matching criteria specify a host (the Android device) application or system component and an SE applet. Host applications are identified by SHA-1 or SHA-256 hashes of the application signing certificate. Host system components are identified by UUID. Because Android system components do not have UUIDs the platform must provide an XML file specifying how to map platform uids to UUIDs. See the "UUID mapping" section below. Applets are identified by AID. Wildcards are supported for both host application/component and applet. The specification includes rules for handling conflicting ARA-M rules. The action part of a rule specifies whether the access is allowed and, if so, may optionally specify a filter that defines the set of APDUs the application is allowed to send to the applet. Note that although ARA-M rules can also specify whether NFC event messages should be sent to the specified host application, this OMAPI implemntation does not do anything with that information. The Java implementation does support notifying clients of NFC events by sending intents, but the framework API does not expose this functionality so apps shouldn't be able to use it. ### ARA-M rules provided by the platform The platform can specify rules in the style of ARA-M by placing them in an XML file. These rules are appended to the list of rules retrieved from the SE and handled the same as the SE-provided ARA-M rules, except in one respect: If a client makes an OMAPI request before the SE rules have been read and if the platform-specified rules authorize the request, the request is carried out without first retrieving rules from the applet. This reduces latency for early requests from platform components. The first access request that is not authorized by platform rules (or [Android permission](#android-permission)) will trigger the ARA-M rules to be read. The platform-provided rules are defined in an XML format that mirrors the ARA-M TLV structure used to encode the SE-provided rules. For example: ```xml

A00000015141434C00

00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF

``` To specify rules for a given SE, create an XML file named `se_access_rules_NAME.xml`, replacing `NAME` with the relevant SE name (e.g. SIM2, ESE6, etc.), and place it in any of the following locations on the device: - /etc/ - /vendor/etc - /odm/etc ### ARA-D rules provided by the SE [ARA-D](https://globalplatform.org/specs-library/globalplatform-device-technology-device-api-access-control-v1/) specifies an APDU-based API for retrieving acess control rules from the secure element and an encoding for the rule data. ARA-D is similar to ARA-M, but allows host applications to be specified by package name in addition to certificate hash, and applies to all "sensitive APIs", rather than specifying allowed applets and APDUs. Android mostly doesn't know what APIs may be sensitive, so this implementation interprets ARA-D rules as allowing matching applications full access to all applets on the SE plus permission to execute privileged ISO commands (MANAGE CHANNEL and SELECT by DF name). ARA-D rules do not grant permission to reset the SE. ### Android permission Android apps with the `SECURE_ELEMENT_PRIVILEGED_OPERATION` permission are allowed full access to all applets on the SE, and allowed to reset the SE. ### Platform security profile (applicable only to debug builds) For debuggable builds (userdebug or eng), there are two system properties that affect access control: 1. security.seek 2. persist.security.seek The service checks the properties in order, using the first available. The properties contain a string which can contain one or more of the substrings: - "useara". If present, the service uses ARA-M and ARA-D rules from the SE. If not present, the SE will not use the SE ARA rules. - "usearf". This is not supported and has no effect. - "fullaccess". If present the service will bypass all access control checks. On production builds the system properties have no effect, ARA rules are always used, and access control is always enforced. ## UUID mapping System components in Android do not have UUIDs or signing certificates, but are identified by their Linux uids, specified in [android_filesystem_config.h](https://cs.android.com/android/platform/superproject/main/+/main:system/core/libcutils/include/private/android_filesystem_config.h) Since ARA-M and ARA-D rules need UUIDs as identifiers it's necessary to provide a mapping from uid to UUID. This is done with an XML file named `hal_uuid_map_NAME.xml`, with "NAME" replaced with an appropriate SE name, e.g. SIM3 or ESE6, which must be placed in any of the following directories on the device: - `/etc` - `/vendor/etc` - `/odm/etc` The format is simple and self-explanatory, easily understood with an example: ```xml 0 9f36407ead0639fc966f14dde7970f68 2901 2902 2903 636F6D2E6E78702E7365637572697479 ``` The specified UUID values must be 32-digit hexadecimal numbers, providing 16 bytes. The OMAPI implementation will prefix them with 0xFFFFFFFF to produce a 20-byte value. ## Unsupported features This implementation does not support: - Access Rule Files. Both the ARA-M and ARA-D specifications provide an alternative mechanism for secure elements to provide rules, Access Rule Files (ARF). - NFC event control. The ARA-M specification provides a way for rules to specify that a host application can be authorized to receive NFC events related to a particular applet. The prior Java implementation did not support this, and neither does this one. If ARA-M rules contain NFC even authorization it is silently ignored. Should this feature be needed at some point, much of the necessary infrastructure is in place. - Dynamic addition or removal of terminals. Note that this is addition or removal of terminals, not SEs. SIMs can be inserted and removed from SIM slot terminals and the service handles this correctly. The Java implementation also supported dynamically adding and removing terminals to support devices with dynamic numbers of SIM slots, but it appears that this feature was used on only one device which is long out of support -- and which didn't actually have a dynamic number of SIM slots but could dynamically update the number of SIM slots that were active and usable for some reason. If it becomes necessary, this feature is non-trivial to add because it requires the OMAPI service to be able to receive and react to a broadcast intent, which is something that native services can't really do. - Blocking on availability of all registered secure element HAL services. Like the Java implementation, this implemention will wait only on ESE1 and SIM1. Any other registered ISecureElement HAL services that are unavailable at the time the OMAPI service starts will be ignored. This seems incorrect but is left as-is pending feedback from partners. ## Code structure overview The code is divided into two distinct layers, AIDL and implementation. There is also a main function, `secure_element_service_main::main` which is responsible for setting up logging, creating an `android_system_services::AndroidSystemServices` instance and the `omapi::SecureElementService` instance and starting the threadpool. ### Implementation layer `terminal::Terminal` is the struct that provides communication with the `ISecureElement` HAL service and handles the low-level details of APDU validation and error handling. It also tracks the "channels" opened with the SE, which allow "concurrent" access to multiple SE applets. SEs are single-threaded and can only handle one APDU at a time, but this allows apps to take turns sending commands. The channels are SE-level virtual constructs. `reader::Reader` is the struct that owns the `Terminal`. It's responsible for host-side functionality related to the owned terminal, particularly access control. It has an `access_enforcer::AccessEnforcer` instance which is responsible for managing access control rules and determining whether a given access is allowed. `AccessEnforcer` uses the ARA rule parser and engine found in the `ara` module. `Reader` also tracks the "sessions" opened with the SE, each of which represents an app that has an open communication session with the SE. To do its work, `Reader` needs access to various system functions, which it gets through a reference to a `system_services::SystemServices` instance. `SystemServices` provides methods that allow the caller to retrieve a HAL service by name, get information about binder cliets (the apps using OMAPI) and get system configuration information. `SystemServices` is implemented as a trait mostly to make it easy to mock it for unit testing. The "real" implementation is found in `android_system_services::AndroidSystemServices`. ### AIDL layer The AIDL layer provides the binder interfaces used by the framework (or perhaps by apps directly). - `omapi::SecureElementService` provides the [`ISecureElementService`](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/omapi/aidl/android/se/omapi/ISecureElementService.aidl) binder interface. It is also responsible for enumerating the availalbe readers during startup and managing the set of available `Reader` instances. - `aidl_reader::AidlReader` provides the [`ISecureElementReader`](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/omapi/aidl/android/se/omapi/ISecureElementReader.aidl) binder interface which is handed to clients when they ask `ISecureElementService` for a specific reader. `AidlReader` contains a reference to the underlying `Mutex`-wrapped `Reader`. This mutex is the point of synchronization that protects concurrent access to the underlying `Reader` and everything it contains. - `aidl_session::AidlSession` provides the [`ISecureElementSession`](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/omapi/aidl/android/se/omapi/ISecureElementSession.aidl) binder interface which is handed to clients when they ask `ISecureElementReader` for a new session. Like `AidlReader`, `AidlSession` also contains a reference to the underlying `Mutex`-wrapped `Reader`, which it uses to communicate with the reader to create channels. - `aidl_channel::AidlChannel` provides the [`ISecureElementChannel`](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/omapi/aidl/android/se/omapi/ISecureElementChannel.aidl) binder interface which is handed to clients when they ask `ISecureElementSession` for a new channel. Like `AidlReader` and `AidlSession`, `AidlChannel` also contains reference to the underlying `Mutex`-wrapped `Reader`, which it uses to transmit APDUs. In addition, `AidlChannel` sets up a death listener for the client, so it can automatically close the underlying SE channel when the client dies. The death listener holds a weak reference to the `Mutex`-wrapped `Reader`. ### Logging On production builds, log level is set to `log::LevelFilter::Info`, so messages logged with `info!`, `warn!` and `error!` are written to logcat. On debug builds, log level is set to `log::LevelFilter::Debug`, so messages logged with `debug!`, `info!`, `warn!` and `error!` are written to logcat. If the `log_sensitive_data` feature is enabled in `Android.bp`, log level is set to `log::LevelFilter::Trace`, so all messages are written to logcat, including those logged with the `utils::sensitive!` macro. *This will log sensitive information*, like APDU contents. Take care to log potentially-sensitive information with the `sensitive!` macro.

c	File Name	Size	files	T	Date
zip	src/	351216	25	---	2026-10-26 17:19:18
-	Android.bp	2370		bp	2026-10-26 17:19:18
-	README.md	16357		md	2026-10-26 17:19:18
-	omapi.rc	68		rc	2026-10-26 17:19:18
-	omapi.xml	253		xml	2026-10-26 17:19:18
-	rustfmt.toml	93		toml	2026-10-26 16:41:57

🌲 / android-build build yaap system secure_element omapi

control-panel