LPAC

English

lpac 是一个跨平台的本地 Profile 代理程序。致力于成为兼容性最好，功能最强大，代码最简洁的 LPA 程序。

下载地址: Github Release

关于 Release 的预构建分发：

macOS 理论上需要 12 以后版本，无法运行请自行编译
Linux 基于 Ubuntu 22.04 构建，需要安装 pcscd libpcsclite 依赖。无法运行请自行编译

加入我们的 Telegram 群组进行讨论！

特性：

支持激活码(Activate Code)和确认码(Confirm Code)
支持自定义请求用的 IMEI
Profile 管理 -- 启用，禁用，删除，设置昵称等
Discovery 功能(Push Model) -- 查询下载电信业者推送的配置文件
Notification 管理 -- 查询，发送，删除
查看 eUICC 元数据 -- 查询 eUICC 的 eID，根 SM-DP+ 服务器和 SM-DS 服务器地址
etc

编译

Linux

Debian/Ubuntu

sudo apt install build-essential cmake git g++ libpcsclite-dev libcurl4-openssl-dev
git clone --depth=1 https://github.com/estkme-group/lpac
cd lpac && mkdir build && cd build 
cmake .. 
make

编译后的二进制在 output 目录内.

macOS

您需要先安装 Homebrew.
依赖安装--WIP

git clone --depth=1 https://github.com/estkme-group/lpac
cd lpac && mkdir build && cd build 
cmake .. 
make

编译后的二进制在 output 目录内.

Windows

使用 MinGW 编译的 lpac 存在无法发送通知的 bug，如果不需要用到该功能可以忽略。如有需要可尝试使用 Cygwin 编译

在 Linux 上编译

sudo apt install build-essential cmake git g++ libpcsclite-dev libcurl4-openssl-dev gcc-mingw-w64 g++-mingw-w64
git clone --depth=1 https://github.com/estkme-group/lpac
cd lpac && mkdir build && cd build
cmake -DLINUX_MINGW32=ON .. && make
# 下载 libcurl
wget https://curl.se/windows/dl-8.4.0_6/curl-8.4.0_6-win64-mingw.zip -O curl.zip && unzip curl.zip && mv curl-8.4.0_6-win64-mingw/bin/libcurl-x64.dll output/libcurl.dll

编译后的二进制在 output 目录内.

在 Windows 上编译(MSYS2)

# MSYS2 MINGW64 环境
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-gcc
git clone --depth=1 https://github.com/estkme-group/lpac
cd lpac && mkdir build && cd build
cmake -DLINUX_MINGW32=ON .. && ninja
# 下载 libcurl
wget https://curl.se/windows/dl-8.4.0_6/curl-8.4.0_6-win64-mingw.zip -O curl.zip && unzip curl.zip && mv curl-8.4.0_6-win64-mingw/bin/libcurl-x64.dll output/libcurl.dll

编译后的二进制在 output 目录内.

在 Windows 上编译(Cygwin)

安装好 gcc-core gcc-g++ make cmake unzip wget

git clone --depth=1 https://github.com/estkme-group/lpac
cd lpac && mkdir build && cd build
cmake -DCYGWIN=ON .. && make
# 下载 libcurl
wget https://curl.se/windows/dl-8.4.0_6/curl-8.4.0_6-win64-mingw.zip -O curl.zip && unzip curl.zip && mv curl-8.4.0_6-win64-mingw/bin/libcurl-x64.dll output/libcurl.dll

编译后的二进制在 output 目录内.

在 Cygwin shell 外运行程序需要把 cygwin1.dll 放置一份于程序目录下。对于默认路径安装的 Cygwin 这个文件应该位于 C:\cygwin64\bin\cygwin1.dll

使用

Linux 依赖

在 Linux 下访问 PCSC 读卡器需要安装 pcscd 并启动。

sudo apt install pcscd
sudo systemctl start pcscd

libpcsclite 也需要安装

库说明

默认会使用 libapduinterface APDU 库和 libhttpinterface HTTP 库，请提前重命名以选择需要使用的库。或者通过 APDU_INTERFACE 和 HTTP_INTERFACE 环境变量告诉 lpac 使用的 APDU 库和 HTTP 库。库文件在 lpac 程序目录下，根据系统不同，后缀为 dll, so, dylib

APDU:

libapduinterface_at 适用于 LTE 模块的 /dev/ttyUSB0 的 AT 指令接口
libapduinterface_pcsc PCSC 读卡器接口
libapduinterface_stdio 标准输入输出

温馨提示：libapduinterface_at 适用于 LTE 模块的 AT 指令接口，通常为 /dev/ttyUSBx，需要自行确认具体的 AT 指令接口，操作 /dev/USBx 通常需要程序使用 root 用户运行。

HTTP:

libhttpinterface_curl curl http库
libhttpinterface_stdio 使用标准输入输出的 HTTP 接口，开发中

下面以使用 PCSC 读卡器和 cURL 库下载 profile 的典型使用场景为例定义环境变量：

Windows(使用PowerShell)

$env:APDU_INTERFACE=".\libapduinterface_pcsc.dll"
$env:HTTP_INTERFACE=".\libhttpinterface_curl.dll"

Linux

export APDU_INTERFACE=./libapduinterface_pcsc.so
export HTTP_INTERFACE=./libhttpinterface_curl.so

macOS

export APDU_INTERFACE=./libapduinterface_pcsc.dylib
export HTTP_INTERFACE=./libhttpinterface_curl.dylib

CLI

lpac 的命令格式如下

lpac <选项1> [选项2] [参数]
  选项1:
    chip		查看与管理您的 eUICC 卡片本身的信息
    profile		管理您的 eUICC 卡片的配置文件
    notification	管理您的 eUICC 卡片内的通知
  选项2:
    请参考下面详细的指令介绍

返回值

lpac 的指令返回内容均为 json 格式，所有指令的返回都遵守下面的格式。

{
   "type":"lpa",
   "payload":{
      "code":0,
      "message":"success",
      "data":{[]}
   }
}

说明：

"type":"lpa" 固定内容
code为 0 表示成功执行，其它为错误码
message 操作成功为 success，出现错误则返回错误类型
data 操作成功时返回需要的内容，错误时则为空（但不是 NULL）

命令选项

chip

查看 eUICC 卡的 EID，默认 SM-DP+ 服务器和 SM-DS 服务器.目前已支持 euicc_info2.

lpac chip <选项> [参数]
	选项:
		info				查看您的 eUICC 卡片本身的信息
		defaultsmdp			修改您的 eUICC 卡片的缺省 SM-DP+ 服务器地址
		示例: lpac chip defaultsmdp <您想要修改的 SM-DP+ 服务器的地址>
		purge				用于使 eUICC 恢复出厂状态，会清空所有 Profile。慎用！

以下是一个返回示例

{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": {
      "eid": " EID  ",
      "default_smds": "testrootsmds.gsma.com",
      "default_smdp": "",
      "euicc_info2": {
        "profile_version": "2.1.0",
        "sgp22_version": "2.2.0",
        "euicc_firmware_version": "4.6.0",
        "uicc_firmware_version": "9.2.0",
        "global_platform_version": "2.3.0",
        "protection_profile_version": "0.0.1",
        "sas_accreditation_number": "GI-BA-UP-0419",
        "free_nvram": 295424,
        "free_ram": 295424
      }
    }
  }
}

profile

Profile 管理，您可以枚举(list)，设置别名(nickname)，启用(enable)，禁用(disable)，删除(delete)，Pull 式下载(download)和 Push 式下载(discovery)配置文件.

lpac profile <选项> [参数]
	选项:
		list			枚举出您的 eUICC Profile
		nickname		给指定的 Profile 设置别名
		示例: lpac profile nickname [Profile 的 ICCID] [别名]
		enable			启用指定的 Profile，括号内为 RefreshFlag 状态，默认启用，可省略
		示例: lpac profile enable [Profile 的 ICCID/AID] (1/0)
		disable			禁用指定的 Profile，括号内为 RefreshFlag 状态，默认启用，可省略
		示例: lpac profile disable [Profile 的 ICCID/AID] (1/0)
		delete			删除指定的 Profile
		示例: lpac profile delete [Profile 的 ICCID/AID]
		download		Pull 式下载新的 Profile
		discovery		Push 式检查可下载的新 Profile

删除 Profile 操作无二次确认，请谨慎执行( 提示:本功能仅会删除 Profile 并签发 Notification，但是不会自动发送，您需要手动发送之. )

Pull 式下载需要连接 SM-DP+ 服务器以及需要以下额外的参数才能完成：

-s SM-DP+服务器：可选，若不提供则会尝试读取defaultsmdp属性。
-m Matching ID：激活码。可选。
-c Confirmation Code：确认码。可选。
-i IMEI: 欲下载Profile的设备的IMEI。可选。

这里用 BetterRoaming 的公共 Profile 举例：

./lpac profile download -s rsp.truphone.com -m "QR-G-5C-1LS-1W1Z9P7"

Push 式下载需要连接 SM-DS 服务器完成 Profile 的推送查询

可以设置以下参数以自定义IMEI和SM-DS服务器：

-s SM-DS服务器：不提交则为 gsma 官方服务器"lpa.ds.gsma.com"
-i IMEI: 欲下载Profile的设备的IMEI,可选

示例：./lpac profile discovery -s lpa.ds.gsma.com -i ""

以下为 lpac profile list 的返回示例

{
   "type":"lpa", 
   "payload":{
      "code":0, 
      "message":"success", 
      "data":[
         {
            "iccid":"8999990000... ",
            "isdpAid":"A0000005591010...",
            "profileState":1,
            "profileNickname":"tel-u",
            "serviceProviderName":"eSIM",
            "profileName":"NEWARE_CUG_V001",
            "profileClass":2
         }, 
         {
            "iccid":"894447860000...", 
            "isdpAid":"A0000005591011...", 
            "profileState":0,
            "serviceProviderName":"BetterRoaming", 
            "profileName":"BetterRoaming", 
            "profileClass":2
         }
      ]
   }
}

其中：

iccid: Profile 的 ICCID
isdpAid: Profile 的 Aid
profileState: Profile 的状态，1 为启用，仅在设备支持 MEP(Multiple Enabled Profiles) 时才能启用多个 Profile
profileNickname: Profile 的别名
serviceProviderName: Profile 的电信业者名字
profileName: Profile 的名字
profileClass: Profile 版本

notification

用于 Notification 的管理，Notification 是在对 Profile 的操作过程中由电信业者发送的。您可以枚举(list)，发送(process)，移除(remove) Notification.

lpac notification <选项> [参数]
	选项:
		list                枚举出您的 eUICC 待发 Notification 列表
		process             发送 Notification 报告
		示例: lpac notification process <序列ID>
		remove              移除 Notification 报告
		示例: lpac notification remove <序列ID>

注意: 下游开发或者最终用户应该在存在 Notification 报告时尽快处理，以遵守 GSMA 规范。lpac 发送 Notification 后不会自动删除 Notification，需要手动进行删除操作。

以下为 lpac notification list 的返回示例

{
   "type":"lpa", 
   "payload":{
      "code":0, 
      "message":"success", 
      "data":[
         {
            "seqNumber":7,
            "profileManagementOperation":32,
            "notificationAddress":"rsp-eu.simlessly.com",
            "iccid":"8999990000"
         }, 
         {
            "seqNumber":8, 
            "profileManagementOperation":64, 
            "notificationAddress":"rsp.truphone.com", 
            "iccid":"894447860000"
         }
      ]
   }
}

其中：

seqNumber: 序列 ID
profileManagementOperation: Profile 状态标识
notificationAddress: Profile 的通知报告服务器地址

FAQ

Q: 执行 lpac 任意指令都返回类似 "SCardListReaders() failed:" 加8位的错误码，例如 80100069, 80100066, 8010002E, 8010000F等

A:80100069 意味你没插好你的 UICC;
   80100066 意味你的卡并未响应请求，请取下来擦拭触点再次尝试插入;
   8010002E 意味通信错误;
   8010000F 意味您插入的卡并非 eUICC 芯片;
   其他错误码请善用搜索引擎，或者加群询问

Q: xxx (电信业者)的卡下不了啊?

A: 电信业者的 SM-DP+ 服务器的验证是多种多样的，请检查您输入的参数是否与电信业者提供给您的相符，部分电信业者以推送形式下发 profile，可能需要用到 lpac 的 discovery 和自定义 IMEI 功能

贡献

欢迎 PR。如果遇到问题，可以提 issue 报告。在提问前请先搜索类似的问题和 issue。也可前往 TG 群组讨论

TODO 列表

优化代码
继续完善文档
stdio 文档待更新
etc

bigikoccc / lpac Goto Github PK

lpac's Introduction

LPAC

目录

编译

使用

Linux 依赖

库说明

CLI

返回值

命令选项

chip

profile

Pull 式下载需要连接 SM-DP+ 服务器以及需要以下额外的参数才能完成：

Push 式下载需要连接 SM-DS 服务器完成 Profile 的推送查询

notification

FAQ

贡献

TODO 列表

致谢

许可

lpac's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org

Jobs