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)。

为访问系统隐藏API，首先需编译相应 compileSdkVersion 的 framework.jar 和 telephony-common.jar，供 LPA 打包时编译检查使用
其次，应用需要作为系统应用存在，自签名后在使用系统应用签名，然后安装在 system/priv-app/ 下，且需要在 etc/permissions/privapp-permissions-platform.xml 文件里配置应用所必须的特殊权限，例如：

<privapp-permissions package="com.xxx.lpa"><permission name="android.permission.INTERNET"/><permission name="android.permission.READ_PHONE_STATE"/><permission name="android.permission.MODIFY_PHONE_STATE"/><permission name="android.permission.BIND_EUICC_SERVICE"/><permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/><permission name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/><permission name="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS"/>
</privapp-permissions>

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

<permissions><feature name="android.hardware.telephony.euicc" /><feature name="android.hardware.telephony.radio.access" /><feature name="android.hardware.telephony.subscription" />
</permissions>

最后使用 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个方法：

onDownloadSubcription（下载订阅文件）
onGetEuiccProfileInfoList（获取所有 Profile 信息）
onSwitchToSubscription（切换 Profile）
onUpdateSubscriptionNickname（编辑某 Profile 的昵称字段）
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<EuiccProfileInfo> 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<EuiccProfileInfo> 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)

出现原因：

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

如何排查或解决：

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

onUpdateSubscriptionNickname 实现

调用函数：

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

onDeleteSubscription 实现

调用函数：

public void EuiccCardManager.deleteProfile(String cardId, String iccid,@CallbackExecutor Executor executor, ResultCallback<EuiccProfileInfo> 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)

下载流程结束

Android eSIM-LPA基于Android13的实现相关推荐

基于Android13的系统启动流程分析（三）之FirstStageMain阶段
Android13系统启动阶段大致分为FirstStageMain阶段和SecondStageMain,此章主要讲FirstStageMain阶段 (若分析有误敬请指教) 本章讲解的方向和你将收获的知 ...
基于Android13的系统启动流程分析（六）之SystemServer内部逻辑分析
主要分析一下SystemServer启动过后的内部逻辑,特别说明一下AMS,WMS都属于SystemServer进程,属于同一个进程一. SystemServer进程启动流程基于Android13 ...
android全平台基于ffmpeg解码本地MP4视频推流到RTMP服务器
音视频实践学习 android全平台编译ffmpeg以及x264与fdk-aac实践 ubuntu下使用nginx和nginx-rtmp-module配置直播推流服务器 android全平台编译ffm ...
android 身份认证技术,Android平台上基于人脸识别的身份认证系统的设计与实现
摘要: 随着移动互联网与人工智能技术的发展,基于个人特征的生物识别技术代替传统的身份验证方式已经是大势所趋.而人脸识别是生物识别技术的一个重要组成部分,拥有其他生物识别技术没有的独特优势.本文主要针对 ...
android平台下基于ANativeWindow实现渲染bitmap图像
OpenGL ES 3.0学习实践 android平台下OpenGL ES 3.0从零开始 android平台下OpenGL ES 3.0绘制纯色背景 android平台下OpenGL ES 3.0绘 ...
Android 批量打包基于Walle的多渠道快速打包自动脚本
Android 批量打包基于Walle的多渠道快速打包自动脚本 Android Signature V2 Scheme签名下的新一代渠道包打包神器 github主页:https://github.c ...
android实习报告,基于Android的毕业实习报告.doc
基于Android的毕业实习报告成绩: 西安建筑科技大学毕业实习报告院 (系): 信息与控制工程学院专业班级: 计算机1201 实习单位: 计算机技术应用研究所实习时间: 2015.2.25 ...
一款提供 dota2 游戏相关资讯，视频，攻略，更新日志的 Android App，基于 RetrofitRxJavaMvpGreenDao
Dota2Helper 项目地址:uin3566/Dota2Helper 简介:一款提供 dota2 游戏相关资讯,视频,攻略,更新日志的 Android App,基于 Retrofit&Rx ...
android 智能设备管理,基于Android平台上BLE的智能家居控制系统设计与实现
摘要:基于智能家居无线控制的市场需求,以集成了CSR1010低功耗蓝牙芯片的智能插座为例,在Android平台上设计了一套基于蓝牙4.0通信协议的智能家居控制系统,实现了对此智能插座的无线通断电控制 ...
Android本科毕业设计基于Android的天气预报APP系统（附带源码）
Android本科毕业设计基于Android的天气预报开发APP系统源码.显示城市当前的实时天气状况,包括城市名称.城市名片.天气情况.温度高低.星期等信息.界面左边有一列城市列表,显示中国各个城市名 ...

Android eSIM-LPA基于Android13的实现

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

开发前知

什么是 eSIM

涉及名词

id类

其他类

Android 13 中的 Euicc

EuiccService的实现

onGetEid 实现：

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

onGetEuiccProfileInfoList 实现

onSwitchToSubscription 实现

onUpdateSubscriptionNickname 实现

onDeleteSubscription 实现

DownloadSubscription 实现：

一、下载流程

二、下载实现步骤

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

2. 解析并验证激活码

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

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

下载流程结束

Android eSIM-LPA基于Android13的实现相关推荐

最新文章

热门文章