eSIM-Android-LPA基于 Android 13的实现

国际对ESIM相关所有规范定义在：GSMA Spec (SGP) - eSIM Consumer and IoT Specifications

国内对EID相关规定在：电信终端产业协会-EID管理实施规定

Android 官方文档在：eSIM实现

开发前知

什么是 eSIM

嵌入式SIM（又称 eSIM 或 eUICC）技术，移动用户可以在没有实体 SIM 卡的情况下，下载运营商配置文件并激活运营商服务。该技术是由 GSMA 推动的全球规范，支持在任何移动设备上进行远程 SIM 配置 (RSP)。从 Android9 开始，Android 框架为访问 eSIM 和管理 eSIM 上的订阅配置文件提供了标准 API。借助这些 eUICC API，第三方可以在支持 eSIM 的 Android 设备上开发自己的运营商应用和 Local Profile Assistant (LPA)。

1. 为访问系统隐藏API，首先需编译相应 compileSdkVersion 的 framework.jar 和 telephony-common.jar，供 LPA 打包时编译检查使用

2. 其次，应用需要作为系统应用存在，自签名后在使用系统应用签名，然后安装在 system/priv-app/ 下，且需要在 etc/permissions/privapp-permissions-platform.xml 文件里配置应用所必须的特殊权限，例如：

3. 同样，在系统使用到 Euicc 这种特殊硬件功能，需要在 etc/permissions/android.hardware.telephony.euicc.xml 文件里配置需要启用的硬件特性

4. 最后使用 EuiccManager.isEnabled 检查得到结果 true ，表明可以 正常使用 eSIM相关API进行开发

系统应用安装流程：

1. adb root
2. adb remount
3. adb push lpa.apk system/priv-app/lpa/lpa.apk 推送apk到系统目录
4. adb shell am restart/ adb shell reboot 重启am或者系统，让系统自动检查并安装

涉及名词

id类

• AID 32位十六进制

  com.android.internal.telephony.uicc.euicc.EuiccCard

  样例：A0000005591010FFFFFFFF8900000100

• eid 32位十进制

  样例：89033023001211360000000007226088

• cardId 20位十六进制

  eSIM卡中是 eid，普通SIM卡中是 iccid

• ICCID 20位十六进制

Integrate circuit card identity 集成电路卡识别码（固化在手机SIM卡中） ICCID为IC卡的唯一识别号码，共有20位数字组成

样例1：898602F30918A0009913
样例2：89860922780011058162

• slotId/SlotIndex 卡槽ID

  0(卡槽1)、1(卡槽2)

其他类

• APDU

  APDU 是 ISO/IEC 7816-4 规范中定义的，用于和SIM卡交互（发送/响应）的 协议，具体呈现为一串 16进制的编码指令。

样例：

80E2910006BF3E035C015A（发送）、BF3E125A10890860302022000000220000153565489000（响应）

Android 13 中的 Euicc

从 Android 9 后就开始有 Euicc 的相关API，10、11、12、13新增了一些扩展或者标记了一些过时，比如新增了多卡功能、支持和运营商APP交互…

涉及关键入口类：

• android.service.euicc.EuiccService -> EuiccServiceImpl 需要我们自己实现
• android.telephony.euicc.EuiccManager -> EuiccController -> EuiccConnector

EuiccManager中保存的重要变量

private final EuiccConnector mConnector;
private final SubscriptionManager mSubscriptionManager;
private final TelephonyManager mTelephonyManager;
private final AppOpsManager mAppOpsManager;
private final PackageManager mPackageManager;

• android.telephony.euicc.EuiccCardManager -> EuiccCardController -> EuiccCard/UiccController/SubscriptionController

• android.telephony.TelephonyManager -> SubscriptionManager

• android.telephony.SubscriptionManager -> SubscriptionController

涉及关键底层类：

com.android.internal.telephony.euicc.EuiccConnector（连接 EuiccManager 和 EuiccService）

com.android.internal.telephony.uicc包下：

UiccController（直接操作卡槽）
euicc.EuiccCard（EuiccController 中部分Card方法的实现）
euicc.apdu.ApduSender（EuiccCard 中进行 APDU 命令发送）ApduSender错误举例：android.telephony.IccOpenLogicalChannelResponse（Response to the TelephonyManager.iccOpenLogicalChannel command.）
euicc.Tags（EuiccCard 中使用于 APDU 命令发送的 ASN.1 tag 定义）
euicc.EuiccCardErrorException（Card相关方法产生的异常定义）
euicc.apdu.ApduException（APDU 命令产生的异常定义）

总结一下：

EuiccManager 类中的方法，一部分通过各种 xxxManager 实现(最后发送APDU命令)，一部分通过 EuiccConnector 类调用到 EuiccService 中需要开发者自行实现。

大致调用栈：

xxxManager -> xxxController -> (EuiccConnector -> EuiccService/ EuiccCard -> ApduSender)

EuiccService的实现

从 Lui 层面来看，主要需要实现其中的5个方法：

1. onDownloadSubcription（下载订阅文件）
2. onGetEuiccProfileInfoList（获取所有 Profile 信息）
3. onSwitchToSubscription（切换 Profile）
4. onUpdateSubscriptionNickname（编辑某 Profile 的昵称字段）
5. onDeleteSubscription（删除某 Profile）

但其实内部还需实现最基础的方法： onGetEid（获取 eid），这一个跟上面5个方法不一样，需区分开来，下面方法未按照顺序排列，除了 getEid 都是由易入难

前提：

入口类：EuiccCardManager
除了 getEid 每个方法均回调为：EuiccCardManager.ResultCallback(resultCode, result)
resultCode：响应码，0为成功（EuiccService.RESULT_OK），其他负数值为失败，失败需处理返回异常
result：APDU响应指令

onGetEid 实现：

入口函数：

public String EuiccManager.getEid() {return getIEuiccController().getEid(...)
}

EuiccController 层通过 EuiccConnector ，最终调用到 EuiccService.onGetEid 方法里实现，这里一不小心就会进到死循环的坑！

实现很简单，Android 10 及以上版本使用新增方法 getUiccCardsInfo ，以下版本使用旧 getUiccSlotsInfo，获取所有卡的信息列表，因为同时只能启用一个卡槽功能，所以直接找不为空的就行了。其实在 EuiccCard 类中有 getEid() 的公开实现，但系统没有提供上层入口方法。

override fun onGetEid(slotId: Int): String {val eid =if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Qtm.uiccCardsInfo.find {it.isEuicc && !it.eid.isNullOrEmpty()}?.eid ?: ""} else {tm.uiccSlotsInfo.find {it.isEuicc && !it.cardId.isNullOrEmpty()}?.cardId ?: ""}
XLog.d("Service onGetEid slotId: $slotId, eid:$eid")
return eid
}

双卡槽下插入单eSIM卡，对比一下两个Info

TelephonyManager.getUiccSlotInfo()：

UiccSlotInfo (mIsActive=true, mIsEuicc=true, mCardId=89033023001211360000000007226088, cardState=2, phoneId=0, mIsExtendedApduSupported=false, mIsRemovable=true)

UiccSlotInfo (mIsActive=true, mIsEuicc=false, mCardId=, cardState=1, phoneId=1, mIsExtendedApduSupported=false, mIsRemovable=true)

TelephonyManager.getUiccCardInfo()：

UiccCardInfo (mIsEuicc=true, mCardId=5, mEid=89033023001211360000000007226088, mIccId=89861000000000000022, mSlotIndex=0, mIsRemovable=true)

UiccCardInfo (mIsEuicc=false, mCardId=-2, mEid=null, mIccId=, mSlotIndex=1, mIsRemovable=true)

onGetEuiccProfileInfoList 实现

调用函数：

public void EuiccCardManager.requestAllProfiles(String cardId, @CallbackExecutor Executor executor, ResultCallback callback
) {getIEuiccCardController().getAllProfiles(...)...
}

ProfileInfoList样例： 最后需展示在 Lui 上供用户操作

[{"iccid": "898602F30918A0009911","nickname": "CM","profileName": "","providerName": "","state": 1},{"iccid": "89860922780011058161","nickname": "CU","profileName": "","providerName": "","state": 0},{"iccid": "89861122215036305451","nickname": "CT","profileName": "","providerName": "","state": 0}
]

onSwitchToSubscription 实现

调用函数：

public void EuiccCardManager.switchToProfile(String cardId, String iccid, boolean refresh,@CallbackExecutor Executor executor, ResultCallback callback
) {getIEuiccCardController().switchToProfile(...)...
}

遇到的错误 1：

逻辑通道被占用
switchToProfile callback onException: com.android.internal.telephony.uicc.euicc.EuiccCardException: Cannot send APDU.ApduException: The logical channel is in use. (apduStatus=0)

出现原因：

1. 在下载订阅后立即进行切换操作
2. 多线程并发调用了底层 EuiccCard 的同一个接口（一个逻辑通道启用并占用时需要释放后才能被重新使用）

如何排查或解决：

1. 在下载后进行延时几秒，再调用切换
2. 检查 Lui 内有没有并发调用同一接口

onUpdateSubscriptionNickname 实现

调用函数：

public void EuiccCardManager.setNickname(String cardId, String iccid, String nickname,@CallbackExecutor Executor executor, ResultCallback callback
) {getIEuiccCardController().setNickname(...)...
}

onDeleteSubscription 实现

调用函数：

public void EuiccCardManager.deleteProfile(String cardId, String iccid,@CallbackExecutor Executor executor, ResultCallback callback
) {getIEuiccCardController().deleteProfile(...)...
}

DownloadSubscription 实现：

一、下载流程

下载流程较为复杂

由 运营商APP 拉起 LPA 发起下载并携带 ActivationCode（激活码通常是扫描二维码得到），Lui 上的 EuiccManager.downloadSubscription 为入口函数，参数 PendingIntent 包含 action：ACTION_DOWNLOAD ，同时注册 BroadcastReceiver 接收下载结果。下载途中可能需要到运营商APP端进行下载码的确认。

最终需实现方法 EuiccService.onDownloadSubscription：

override fun onDownloadSubscription(slotId: Int,subscription: DownloadableSubscription?,switchAfterDownload: Boolean,forceDeactivateSim: Boolean,resolvedBundle: Bundle?,
): DownloadSubscriptionResult {return null
}

二、下载实现步骤

所有接口调用，header 里是状态字段，response 里是验证信息。

header样例：

{"header": {"functionExecutionStatus": {"status": "Executed-Success"}},"transactionId": "FD913D91F79702FBF27DE2B4ABBD468A"
}

response样例：

{"pendingNotification":"vzeBrr8naIAQzS/mWM/RNgcHY2VAyc6yGr8vJoABB4ECB4AMEWRwcGx1cy5jY3NtZWMuY29tWgqYaAEAAAAAAAAzBgorBgEEAYOOA2UCoh+gHU8QoAAABVkQEP+JAAARAAQJMAegBTADgAEAXzdA0iN1N/yZEKdsbUub2PXOW9eT5NJi97ajNnu44rMTVimQnDzwvk4+hvsQFHH293xn7SUnfZM6gJswqaiF9gpONB=="}

1. getEid 是前提，操作卡时使用

val cardId = onGetEid(slotId)

2. 解析并验证激活码

获取激活码，为空或非法需中断操作返回错误：

val activationCode = subscription?.encodedActivationCode
// 激活码样例：1$dpplus.xxx.com:8445/xxfreexx-dp-service$2TSU5-NKVPM-MIS64-9CLYD-KD411val args = ac.split('$')
val smdpAddress = "https://${args[1]}/"
val matchingId = args[2] // 服务端验证使用

3. 初始化、双向验证，使用激活码到 SM-DP+ 拉取订阅信息

接口调用流程：

1. initiateAuthentication
2. authenticateClient
3. getBoundProfilePackage
4. handleNotification

接口响应重要标记：

1. euiccChallenge 字段
2. authenticateServerResponse 字段
3. prepareDownloadResponse 字段
4. pendingNotification 字段

如果顺利且成功，上面的每一次调用和一次响应是对应的，表明下载流程完整。

下面是完整的、带前因后果的 API 流程：

• API：EuiccCardManager.onGetEuiccChallenge
• API：EuiccCardManager.onGetEuiccInfo1

1. initiateAuthentication 接口调用

euiccChallenge 响应，返回（euiccChallenge，euiccInfo1，SM-DP+服务器地址）

// SM-DP+服务连接，初始化验证
val initAuthResp = es9.initiateAuthentication(InitiateAuthentication.Request(euiccChallenge.toBase64(),euiccInfo1.toBase64(),smdpAddress)
).execute().body()

• API：EuiccCardManager.onAuthenticateServer

val serverSigned1 = initAuthResp.serverSigned1.base64ToBytes()
val serverSignature1 = initAuthResp.serverSignature1.base64ToBytes()
val ciPkIdToBeUsed = initAuthResp.euiccCiPKIdToBeUsed.base64ToBytes()
val serverCertificate = initAuthResp.serverCertificate.base64ToBytes()euiccCardManager.authenticateServer(cardId,matchingId,serverSigned1,serverSignature1,ciPkIdToBeUsed,serverCertificate,AsyncTask.THREAD_POOL_EXECUTOR
) { resultCode, result ->...
}

2. authenticateClient 接口调用

authenticateServerResponse 响应，返回 functionExecutionStatus.status=Executed-Success 继续

val authClientResp =es9.authenticateClient(AuthenticateClient.Request(initAuthResp.transactionId, authServerResp.toBase64())).execute().body()

• API：EuiccCardManager.onPrepareDownload

euiccCardManager.prepareDownload(cardId,if (subscription.getEncodedActivationCode().endsWith("\$1")) {sha256(sha256(subscription.confirmationCode.toByteArray()) + authClientResp.transactionId.hexStringToBytes())} else {null},authClientResp.smdpSigned2.base64ToBytes(),authClientResp.smdpSignature2.base64ToBytes(),authClientResp.smdpCertificate.base64ToBytes(),AsyncTask.THREAD_POOL_EXECUTOR
) { resultCode, result ->...
}

3. getBoundProfilePackage 接口调用

prepareDownloadResponse 响应

 val getBoundProfilePackageResp = es9.getBoundProfilePackage(GetBoundProfilePackage.Request(authClientResp.transactionId,prepareDownloadResp.toBase64())).execute().body()

• API：EuiccCardManager.onLoadBoundProfilePackage

euiccCardManager.loadBoundProfilePackage(cardId, bpp, AsyncTask.THREAD_POOL_EXECUTOR) { resultCode, result ->...
}

4. handleNotification 接口调用

pendingNotification 响应

es9.handleNotification(HandleNotification.Request(installationResult.toBase64())).execute().body()

4. 判断是否需要下载后切换Profile，需要的话执行

遇到的错误1：多线程并发调用 或 下载后立即切换 Profile 产生，检查调用链，对下载后切换中间延时

E  getProfile in switchToProfile callback onException: com.android.internal.telephony.uicc.euicc.EuiccCardException: Cannot parse response: BF2D03810101at com.android.internal.telephony.uicc.euicc.EuiccCard$2.onResult(EuiccCard.java:1251)at com.android.internal.telephony.uicc.euicc.EuiccCard$2.onResult(EuiccCard.java:1242)at com.android.internal.telephony.uicc.euicc.apdu.ApduSender$4.onResult(ApduSender.java:275)at com.android.internal.telephony.uicc.euicc.apdu.ApduSender$4.onResult(ApduSender.java:266)at com.android.internal.telephony.uicc.euicc.async.AsyncMessageInvocation.handleMessage(AsyncMessageInvocation.java:57)at android.os.Handler.dispatchMessage(Handler.java:102)at android.os.Looper.loop(Looper.java:223)at android.app.ActivityThread.main(ActivityThread.java:7822)at java.lang.reflect.Method.invoke(Native Method)at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:592)at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:952)Caused by: com.android.internal.telephony.uicc.asn1.TagNotFoundException: null (tag=160)at com.android.internal.telephony.uicc.asn1.Asn1Node.getChild(Asn1Node.java:330)at com.android.internal.telephony.uicc.euicc.EuiccCard.lambda$getProfile$5(EuiccCard.java:288)at com.android.internal.telephony.uicc.euicc.-$$Lambda$EuiccCard$TTvsStUIyUFrPpvGTlsjBCy3NyM.handleResult(Unknown Source:0)at com.android.internal.telephony.uicc.euicc.EuiccCard$2.onResult(EuiccCard.java:1246)at com.android.internal.telephony.uicc.euicc.EuiccCard$2.onResult(EuiccCard.java:1242) at com.android.internal.telephony.uicc.euicc.apdu.ApduSender$4.onResult(ApduSender.java:275) at com.android.internal.telephony.uicc.euicc.apdu.ApduSender$4.onResult(ApduSender.java:266) at com.android.internal.telephony.uicc.euicc.async.AsyncMessageInvocation.handleMessage(AsyncMessageInvocation.java:57) ...at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:952) 

遇到的错误 2：
由于 eid 过长，在 onDownloadSubscription 返回实体类中传入 cardId: Int 字段过长（这个字段可不传，内部未使用）

java.lang.NumberFormatException: For input string: "89033023001211360000000007226077"at java.lang.Integer.parseInt(Integer.java:618)at java.lang.Integer.parseInt(Integer.java:650)at com.xxx.lpa.service.EuiccService.onDownloadSubscription(EuiccService.kt:193)at android.service.euicc.EuiccService$IEuiccServiceWrapper$1.run(EuiccService.java:669)at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1167)at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:641)at java.lang.Thread.run(Thread.java:923)

下载流程结束