pysim-4-1.1.17 eUICC ISD-R commands

1.1.17 eUICC ISD-R 命令

这些命令用于执行针对 GSMA 消费者 eSIM 的 eUICC 的各种操作。它们实现了所谓的 ES10a、ES10b 和 ES10c 接口。基本上，它们执行了通常由 UE 中的 LPAd 完成的任务。

要使用这些命令，您需要按照 GSMA SGP.22 文档中指定的步骤进行操作：

• 打开一个新的逻辑通道（并开始使用它）
• 选择 ISD-R 应用程序

1.1.18 cmd2 可设置参数

cmd2 拥有可设置参数的概念，这些参数类似于操作系统级 shell 中的环境变量：它们可以被读取和设置，并且会在某种程度上影响行为。

• conserve_write
  如果启用，pySim 在被要求写入卡时，总是会先读取相应的文件/记录，并验证待写入的值是否与卡上当前的值不同。如果相同，则跳过写入操作。只有当新值与卡上当前值不同时，才会执行写入操作。
  如果禁用，pySim 将总是写入，不管当前/新值如何。
• json_pretty_print
  此参数决定生成的 JSON 输出是否（默认情况下）应该进行美化打印（多行输出，缩进级别为 4 个空格）。
  此参数的默认值为 'true'。
• debug
  如果启用，在出现异常时将显示完整的 Python 回溯信息。
• apdu_trace
  布尔变量，用于决定是否打印命令 + 响应 APDU 的十六进制转储。
• numeric_path
  布尔变量，用于决定路径（例如，在提示符中）是否以数字 FID 或字符串名称显示。

1.2 pySim-trace

pySim-trace 是一个用于高级解码 APDU 协议跟踪的工具，例如通过 Osmocom SIMtrace2 或 osmo-qcdiag 获得的跟踪。

pySim-trace 利用 pySim-shell 对 SIM 卡相关知识的现有了解，包括 SIM/USIM/ISIM/HPSIM 卡上各种文件的结构/编码，并将其应用于解码协议跟踪。这意味着它不仅能显示命令的名称（如 READ BINARY），还能理解当前选定的文件是什么，以及如何解码该文件的内容。

pySim-trace 还能理解传递给命令的参数以及如何解码它们，例如 USIM/ISIM/HPSIM 应用程序中的 AUTHENTICATE 命令。

1.2.1 演示

要了解 pySim-trace 的使用方式，您可以观看 2022 年 11 月 SIMtrace2 教程的相关部分，其录像是公开可访问的。

1.2.2 运行 pySim-trace

运行 pySim-trace 需要您指定待解码 APDUs 的来源。有几个支持的选项，每个都有自己的相应参数（如 PCAP 解码的文件名）。

详细命令行参考请参见下文。

一个典型的 pySim-trace 执行，用于实时解码 GSMTAP（SIM APDU）例如来自 SIMtrace2 或 osmo-qcdiag 的数据，看起来像这样：

取消自动换行

复制

./pySim-trace.py gsmtap-udp

这将绑定到本地主机（127.0.0.1）的默认 UDP 端口 4729（GSMTAP），并解码在那里接收到的任何 APDUs。

1.2.4 约束

• 为了正确跟踪文件系统树中的当前位置和其他状态，重要的是您正在解码的跟踪包括与 SIM 卡的所有通信，理想情况下从一开始（开机）。
• pySim-trace 目前仅支持 ETSI UICC（USIM/ISIM/HPSIM），尚未支持传统的 GSM SIM 卡。这不是一个基本的技术限制，只是目前还没有人开发和测试这部分。非常欢迎贡献。

1.3 传统工具

传统工具是 pySim-shell 出现之前就存在的经典 pySim-prog 和 pySim-read 程序。

现在，强烈推荐使用 pySim-shell 而不是这些传统工具。

1.3.1 pySim-prog

pySim-prog 是 pySim 软件套件的第一个部分。它最初是作为一个工具，用于向非常简单的 SIM 卡写入 ICCID、IMSI、MSISDN 和 Ki，后来扩展到支持多种其他类型的卡。随着支持的功能数量变得无法仅用命令行参数来表达，于是创建了 pySim-shell。

基本用例仍然可以使用 pySim-prog。

可编程 SIM 卡

有两种模式是可能的：

• 用户手动指定每个参数：
  这是使用 pySim-prog 的最常见方式。用户将通过命令行直接指定所有相关参数。一个典型的命令行可能如下所示：

取消自动换行

复制

pySim-prog.py -p <pcsc_reader> --ki <ki_value> --opc <opc_value> --mcc <mcc_value> --mnc <mnc_value> --country <country_code> --imsi <imsi_value> --iccid <iccid_value> --pin-adm <adm_pin>

请注意，即使这个已经很长的命令行也只包含了最常见的卡参数。要获取所有可能参数的完整列表，请使用 pySim-prog 的 --help 选项。还需要注意的是，并非所有参数都为所有卡类型所支持。特别是非常简单的可编程 SIM 卡只支持非常基础的参数集，如 MCC、MNC、IMSI 和 Ki 值。

• 从最小集生成参数：
  也可以将某些参数的生成留给 pySim-prog。当需要初始化大量卡片并使用随机生成的密钥材料时，这特别有帮助。

取消自动换行

复制

pySim-prog.py -p <pcsc_reader> --mcc <mcc_value> --mnc <mnc_value> --secret <random_secret> --num <card_number> --pin-adm <adm_pin>

参数 --secret 指定一个随机种子，用于生成卡片特定的参数（IMSI）。种子应包含足够的随机性以避免冲突。建议安全地存储种子，以防需要重新生成卡片或稍后扩展当前批次的卡片。出于安全原因，密钥材料（也是卡片特定的）不会从随机种子派生。相反，在每次编程周期中都会生成一组新的 Ki 和 OPc。这意味着即使 --num 保持不变，也会生成新的密钥。

参数 --num 指定一个卡片特定的数字。这个数字将被管理到随机种子中，作为一组特定随机生成参数的标识符。

在上面的例子中，还指定了参数 --mcc 和 --mnc，因为它们标识了卡片应该操作的 GSM 网络，绝对需要保持静态。pySim-prog 将使用这些参数生成一个有效的 IMSI，该 IMSI 以指定的 MCC/MNC 开头，并有一个随机的尾部。

指定卡类型：

pySim-prog 通常会自动检测卡类型。如果自动检测不起作用，可以指定参数 --type。支持以下卡类型：

• Fairwaves-SIM
• fakemagicsim
• gialersim
• grcardsim
• magicsim
• OpenCells-SIM
• supersim
• sysmoISIM-SJA2
• sysmoISIM-SJA5
• sysmosim-gr1
• sysmoSIM-GR2
• sysmoUSIM-SJS1
• Wavemobile-SIM

指定卡读取器：

通常与 PCSC 读取器一起使用 pySim-prog。PCSC 读取器编号通过 --pcsc-device 或 -p 选项指定。然而，也支持其他类型的读取器（如串行读取器和调制解调器）。有关更多信息，请使用 pySim-prog 的 --help 选项。

使用 CSV 文件进行卡编程

为了简化卡编程过程，pySim-prog 还允许从 CSV 文件中读取卡参数。当使用 CSV 文件作为输入时，用户不必为每张卡单独构造命令行。相反，所有与卡相关的参数都会自动从 CSV 文件中提取。

CSV 文件可以包含多行（数百甚至数千张卡）。pySim-prog 能够通过 ICCID（推荐使用，因为 ICCIDs 通常不会更改）或 IMSI 来识别行。

CSV 文件格式具有灵活的格式，包含强制性和可选列，这里适用与命令行参数相同的规则。列名与命令行选项相匹配。CSV 文件还可以包含 pySim-prog 不了解的列，如库存编号、昵称或与卡编程过程无关的参数。pySim-prog 将静默忽略所有未知列。

CSV 文件可以包含以下列：

• 名称
• iccid（通常用作键）
• mcc
• mnc
• imsi（可以作为键，但不推荐）
• smsp
• ki
• opc
• acc
• pin_adm, adm1 或 pin_adm_hex（必须存在）
• msisdn
• epdgid
• epdgSelection
• pcscf
• ims_hdomain
• impi
• impu
• opmode
• fplmn

由于历史原因，并为了保持与多种不同 CSV 文件格式的兼容性，ADM pin 可以存储在三个不同的列中。只需要其中一个列可用。

• adm1：此列包含以数字 ASCII 字符格式表示的 ADM pin。这是最常见的格式。
• pin_adm：与 adm1 相同，只是列名不同。
• pin_adm_hex：如果 ADM pin 由原始 HEX 字符组成，而不是数字 ASCII 字符，则可以使用此列以 HEX 字符串的形式提供 ADM pin。

以下是一个典型的最小示例：

取消自动换行

复制

"imsi","iccid","acc","ki","opc","adm1"
"999700000053010","8988211000000530108","0001","51ACE8BD6313C230F0BFE1A458928DF0","E5A00E8DE427E21B206526B5D1B902DF","65942330"
"999700000053011","8988211000000530116","0002","746AAFD7F13CFED3AE626B770E53E860","38F7CE8322D2A7417E0BBD1D7B1190EC","13445792"
...

以下命令行将指示 pySim-prog 使用提供的 CSV 文件作为参数源，并使用在编程前从卡中读取的 ICCID 作为识别卡的键。要使用 IMSI 作为键，可以使用参数 --read-imsi 而不是 --read-iccid。然而，这个选项只推荐在非常特定的情况下使用。

取消自动换行

复制

pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --read-iccid

也可以通过手动提供 ICCID（选项 --iccid）或 IMSI（选项 --imsi），然后用它作为键在 CSV 文件中找到匹配的行。

取消自动换行

复制

pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --iccid <iccid_value>

写入 CSV 文件

pySim-prog 还能够生成包含它已生成或从其他来源（命令行、CSV 文件）接收的参数子集的 CSV 文件。生成的文件将不包含标题，并将包含以下列：

• 名称
• iccid
• mcc
• mnc
• imsi
• smsp
• ki
• opc

使用 CSV 写入功能的命令行示例如下：

取消自动换行

复制

pySim-prog.py -p <pcsc_reader> --read-csv <path_to_input_csv_file> --read-iccid --source csv --write-csv <path_to_output_csv_file>

批量编程

如果需要编程较大的卡批次，可以使用 --batch 参数来以批处理模式运行 pySim-prog。

批处理模式将提示用户插入一张卡。一旦在读卡器中检测到卡，就会执行编程。然后用户可以再次移除卡，然后该过程重新开始。这允许快速且高效地进行卡编程，无需永久的命令行交互。

1.3.2 pySim-read

pySim-read 允许从 SIM 卡中读取一些最重要的数据项。这意味着它只会读取卡上的一些文件，并且只会读取普通用户（无需任何特殊认证）可访问的文件。

如今，建议使用 pySim-shell 的 export 命令来代替。它能够对卡上所有可找到的标准文件进行更全面的导出。要获取人类可读的解码而非原始的十六进制导出，您可以使用 export --json。

具体来说，pySim-read 将转储以下内容：

• MF（主文件）
• EF.ICCID（ICCID 入口文件）
• DF.GSM（GSM 专用文件）
• EF.IMSI（IMSI 入口文件）
• EF.GID1（GID1 入口文件）
• EF.GID2（GID2 入口文件）
• EF.SMSP（短信服务提供商名称文件）
• EF.SPN（服务提供商名称文件）
• EF.PLMNsel（已选择的 PLMN 文件）

• EF.PLMNwAcT（已激活的 PLMN 文件）

• EF.OPLMNwAcT（已激活的其他 PLMN 文件）

• EF.HPLMNAcT（已激活的 HPLMN 文件）

• EF.ACC（访问条件文件）

• EF.MSISDN（移动台国际 ISDN 号码文件）

• EF.AD（附加数据文件）

• EF.SST（服务表单文件）

• ADF.USIM（USIM 应用专用文件）

• EF.EHPLMN（等效 HPLMN 文件）

• EF.UST（USIM 工具集文件）

• EF.ePDGId（ePDG 标识符文件）

• EF.ePDGSelection（ePDG 选择文件）

• ADF.ISIM（ISIM 应用专用文件）

• EF.PCSCF（代理呼叫状态功能文件）

• EF.DOMAIN（域文件）

• EF.IMPI（IP 多媒体私有标识符文件）

• EF.IMPU（IP 多媒体公有标识符文件）

• EF.UICCIARI（UICC 应用资源标识符文件）

• EF.IST（ISIM 工具集文件）

串行读卡器

使用一个简单/超低成本的串行读卡器，它连接到一个（物理或USB/虚拟）RS232端口。这种读卡器只适用于遵循古老Phoenix或Smart Mouse设计的非常基础的读卡器，并不适用于所有RS232连接的智能卡读卡器。

• -d, --device SIM卡访问的串行设备
  默认值：'/dev/ttyUSB0'
• -b, --baud 用于SIM卡访问的波特率
  默认值：9600

PC/SC读卡器

使用PC/SC卡读卡器与SIM卡通信。PC/SC是应用程序访问智能卡读卡器的标准API，适用于多种操作系统，如Microsoft Windows、MacOS X和Linux。大多数智能卡读卡器供应商提供驱动程序，这些驱动程序提供PC/SC接口，甚至使用通用USB CCID驱动程序。您可以使用类似pcsc_scan -r的工具来获取系统上可用的读卡器列表。

• --pcsc-shared 以共享访问模式打开PC/SC读卡器（默认：独占访问）
  默认值：False
• -p, --pcsc-device 用于SIM卡访问的PC/SC读卡器编号
• --pcsc-regex 用于SIM卡访问的匹配PC/SC读卡器的正则表达式

AT命令调制解调器读卡器

与连接到此计算机的移动电话或蜂窝调制解调器中的SIM卡通信，该调制解调器提供AT命令接口，包括用于通用SIM卡访问的AT+CSIM接口，如3GPP TS 27.007所指定。

• --modem-device 用于通用SIM卡访问的调制解调器串行端口（3GPP TS 27.007）
• --modem-baud 用于调制解调器端口的波特率
  默认值：115200

OsmocomBB读卡器

使用兼容OsmocomBB的手机访问插入手机SIM卡槽的SIM卡。这需要在手机内运行OsmocomBB固件（可以是内存加载）。它还要求您运行osmocon程序，该程序提供一个unix域套接字，该读卡器驱动程序可以附加到该套接字。

• --osmocon 用于基于Calypso（例如Motorola C1XX）的读卡器的socket路径（通过OsmocomBB）