Introduction #

OMAPI (Open Mobile API) is an API by which android applications can access SE (Secure Elements), including SIM cards and eUICCS. It provides APDU level access and hence works at a similar level of abstraction to what PC/SC provides on Windows/OS-X/Linux.

This feature is available in Android 9 (API level 28) or later.

If you use org.simalliance.openmobileapi, then can downgrade to Android 5 (API level 21).

Checkpoints #

• PackageManager#FEATURE_SE_OMAPI_UICC
• Try open each slot ISD-R Application Applet ID, See Android Security feature
• If the Android system is eng or userdebug (ro.debuggable=1) then can modify any system properties service.seek or persist.service.seek, set as fullaccess bypass access limitation, see getprop and setprop shell commands.

Android Security feature #

SecurityException: If the calling application cannot be granted access to this AID or the default Applet on this session.

Compatibility can therefore be tested by turning on each ISD-R logical channel (eSIM.me and 5ber.eSIM app use this method)

See android.se.omapi.Session#openLogicalChannel (source code)
See org.simalliance.openmobileapi.Session#openLogicalChannel (source code)

Device-specific Caveats #

Mainland China Manufacturer #

China Mobile Super SIM card is also based on OMAPI to access SE

China Mobile considers SIM Slot 1 to be generally available, so it can be assumed that card slots in mobile phones manufactured in Mainland China are generally available.

see Sustainability Report (2022)
see mp.weixin.qq.com/s/jH_Gi82yHed22mY2XipUDw (Chinese)
see wap.js.10086.cn/vw/HK/pages/XLK (Chinese)

Xiaomi Manufacturer #

The MIUI (now HyperOS) on Snapdragon by Qualcomm, will seize ISD-R logical channel, resulting in unavailability.

There is no userspace solution to this problem, which requires the eUICC slave side to implement ISD-R non-exclusive access.

FOSS Applications #

• EasyEUICC (Mirror)
  Package Name: im.angry.easyeuicc
  ARA-M SHA-1: 2a2fa878bc7c3354c2cf82935a5945a3edae4afa (Release)
• Infineon LPA
  Package Name: com.infineon.esim.lpa
  ARA-M SHA-1: 6fb0729d5b19897c044078a0184b68647704fa99 (Release)
• OMAPI Bypass (Android 9+)
• Override OMAPI SE AccessControl (Android 6 to 8)
• eUICC Probe

Specifications #

• OMAPI v3.3
  • Android Binding v1.0
• SE Access Control v1.1

References #

• android.se.omapi (source code)
• org.simalliance.openmobileapi (source code)
• OMAPI Reader Support
• OMAPI Vendor Stable Interface
• UICC Carrier Privileges
• Using build variants
• 2016-01-06 Override SIM Secure Element Access Control
• 2016-01-12 OMAPI: Accessing the UICC on Android Devices
• 2018-08-06 Open Mobile API for NFC payments and secure transactions
• 2018-09-14 As easy as Pie: Google’s Android implementation of OMAPI
• 2018-11-06 google-cardlet.cap はロードできるのか (Japanese)
• 2018-11-10 OmapiTest.testTransmitApdu() が期待する SIM カードの振る舞い (1) (Japanese)
• 2018-11-14 OmapiTest.testTransmitApdu() が期待する SIM カードの振る舞い (2) (Japanese)
• 2018-11-18 OmapiTest.testLongSelectResponse()のサポート (Japanese)
• 2018-11-24 Case 2 コマンドや Case 4 コマンドへの長いデータの応答 (Japanese)
• 2018-11-27 各種警告系ステータスワードの返却 (Japanese)
• 2018-11-29 論理チャネルを開くときに P2 値を割愛するケース (Japanese)
• 2018-12-05 OMAPI/AC テスト用アプレットはこれで完成（のつもり） (Japanese)
• 2018-12-08 では ARA-M を作り始める準備を (Japanese)
• 2018-12-12 GET DATA [All] と GET DATA [Next] の実装 (Japanese)
• 2018-12-14 GET DATA [Refresh tag] の追加 (Japanese)
• 2018-12-22 Android Secure Element CTS の実行用 ARA-M できました (Japanese)
• 2019-07-15 Android は APDU の送受信を制限しなくていいのに (Japanese)
• 2022-03-04 eSIM.me は商用かつ汎用の Removable eUICC カード (Japanese)
• 2022-05-05 The ingenious product that brings eSIM to any Android phone
• 2022-06-26 ワイモバイルの eSIM カード (Removable eUICC) はいい感じです (Japanese)
• 2023-07-08 如何自己实现 eSIM.me app (思路) (Chinese)
• 2024-02-04 给想入坑的朋友再次提个醒， OpenEUICC 并不是所有手机都可以用 (Chinese)