Open Mobile API (OMAPI) is a standard API used to communicate with a device's Secure Element. Before Android 13, only applications and framework modules had access to this interface. By converting it to a vendor stable interface, HAL modules are also capable of communicating with the secure elements through the OMAPI service.
A new access entry to OMAPI was added for the HAL modules without modifying any APIs in the current existing interface. There are no modifications required for existing application and framework modules using this interface.
As part of the Android Ready SE program we are making core Android security features like Keymaster, Keymint, Identity Credentials, and Remote Key Provisioning available on Secure Elements. Enabling these requires HALs (vendor components) of these features to communicate with the Secure Element via the OMAPI vendor stable interface.
OEMs integrating a Secure Element and Android Ready SE features into their devices need to enable this interface as it is disabled by default. Before this update Secure Element access rules were defined by package name or its signature hashes (device application reference) and AID (SE application reference). HAL modules didn’t have unique identifiers like package names or signature certificates. Now in Android 13, the OMAPI Vendor Stable Service allows HAL modules to access the Secure Element. SE vendors can define a unique identifier UUID of 16 bytes. To apply this access rule to HAL modules, SE vendors are required to map this 16 byte unique identifier UUID to HAL module UID in their vendor UUID mapping config XML.
The OMAPI Vendor Stable Service pads the UUID with FF if necessary to make it 20 bytes, as per section 6.1, DeviceAppID-REF-DO page: 66 and defines access rules in secure elements using this 20 byte UUID as device application reference.
The vendor UUID mapping file name is formed with the predefined prefix
hal_uuid_map_ and appended with the value of the system
OMAPI Vendor Stable service searches for this file under
folders. Detailed description on the vendor UUID mapping configuration
file is available
The following changes are required to enable the OMAPI Vendor Stable Service feature on a target build.
Enable the service flag
secure_element_vintf_enabled using resource overlay under
device specific folders.
Define the UID and UUID mapping xml for your service.
<ref_do> <uuid_ref_do> <uids> <uid>0</uid> </uids> <uuid>9f36407ead0639fc966f14dde7970f68</uuid> </uuid_ref_do> <uuid_ref_do> <uids> <uid>1096</uid> <uid>1097</uid> </uids> <uuid>a9b7ba70783b317e9998dc4dd82eb3c5</uuid> </uuid_ref_do> </ref_do>
Provision the Secure Element ARs for the HAL service using UUIDs as device application references. Add a mapping entry in the mapping config where you can map this UUID to HAL module UID(s). With this mapping vendors are allowing HAL modules to access Secure Element. OMAPI VTS tests can be used as reference implementations for enabling the OMAPI Vendor Stable Service in HAL modules.
Update HAL module sepolicy: Add sepolicy rule for HAL module to allow their domain to access the OMAPI vendor stable service.
allow hal_module_label secure_element_service:service_manager find
Connect to OMAPI vendor stable service: From HAL modules use OMAPI vendor
to connect to the service.
Validate that the OMAPI Vendor Stable Service has successfully been implemented by running OMAPI VTS tests.
run vts -m VtsHalOmapiSeServiceV1_TargetTest run vts -m VtsHalOmapiSeAccessControlTestCases