OMAPI Vendor Stable Interface

Introduction

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.

Design architecture

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 property ro.boot.product.hardware.sku

    hal_uuid_map_value_of_ro.boot.product.hardware.sku.xml

OMAPI Vendor Stable service searches for this file under /odm/etc/, /vendor/etc/ and /etc/ folders. Detailed description on the vendor UUID mapping configuration file is available here.

Implementation

The following changes are required to enable the OMAPI Vendor Stable Service feature on a target build.

SecureElement

Enable the service flag secure_element_vintf_enabled using resource overlay under device specific folders.

    <bool name="secure_element_vintf_enabled">true</bool>

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 service label android.se.omapi.ISecureElementService/defaultandroid.se.omapi.ISecureElementService/default to connect to the service.

Validation

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