Android eSIM-LPA基于Android13的实现

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

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

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

Android 官方文档在:eSIM实现

开发前知

什么是 eSIM

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

  1. 为访问系统隐藏API,首先需编译相应 compileSdkVersionframework.jartelephony-common.jar,供 LPA 打包时编译检查使用

  2. 其次,应用需要作为系统应用存在,自签名后在使用系统应用签名,然后安装在 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>
  1. 同样,在系统使用到 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>
  1. 最后使用 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

    APDUISO/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.Q
            tm.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)

出现原因:

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

如何排查或解决:

  1. 在下载后进行延时几秒,再调用切换
  2. 检查 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-KD411

val 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: BF2D03810101
 at 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)

下载流程结束

  • 8
    点赞
  • 28
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 23
    评论
eSIM模型代码实现主要涉及以下几个方面: 1. eSIM模块初始化:首先需要引入相应的库文件,包括与eSIM模块通信的串口库和其他所需的功能库。然后可以定义与eSIM模块通信的串口参数,例如波特率、数据位、停止位等。之后需要进行串口的打开和初始化操作,以保证与eSIM模块的正常通信。 2. eSIM命令交互:在与eSIM模块建立通信后,可以发送命令给eSIM模块,并接收其返回的响应。常见的eSIM命令包括SIM卡识别、获取IMSI号、发送短信等。通过串口通信,将命令以字符串的形式发送给eSIM模块,在获取响应后进行相应的处理。 3. eSIM状态监测:可以设置定时器或轮询机制,监测eSIM模块的状态,例如SIM卡是否插入、网络信号强度等。通过相应的命令和响应,可以实时监测并获取eSIM模块的状态信息。 4. eSIM错误处理:在eSIM模块通信的过程中,可能会出现各种错误情况,例如命令发送错误、响应超时等。针对这些错误,可以通过异常处理的方式进行相应的处理,例如重新发送命令或报错提示等。 5. eSIM模块的应用:在eSIM模块的基础上,可以进行相应的应用开发。例如通过HTTP协议与云平台进行通信,实现远程下发指令的功能,或者通过MQTT等协议实现数据上报和接收的功能。 需要注意的是,以上是一种简单的eSIM模型代码实现的基本思路,具体的代码实现可能因硬件和软件平台的差异而有所变化。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 23
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

柯基爱蹦跶

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值