pysim-1
pySim 简介
pySim 是一个 Python 实现的软件套件，旨在帮助您管理蜂窝网络的用户身份卡，即 SIM 卡。许多 Osmocom（开源移动通信）项目都与运行私有/定制蜂窝网络有关，为这些网络提供 SIM 卡是运营这些网络的常见要求。要充分利用 pySim 的大多数功能，您需要一个可编程的 SIM 卡，即您是卡的所有者/运营商，并且拥有足够的凭证（如 ADM PIN）来写入卡上的许多文件。
sysmocom 是 pySim 的主要贡献者之一，提供了可编程 SIM 卡。更多详情请访问 sysmocom 产品页面。
pySim 支持经典 GSM SIM 卡以及符合 ETSI UICC 标准的 3GPP USIM 和 ISIM 应用。它易于扩展，因此任何 Python 开发者都可以轻松添加对额外文件、卡应用程序等的支持。我们鼓励您提交贡献以帮助这个协作开发项目。
pySim 包括以下几个部分：
- 一个包含大量对象和方法的 Python 库，可用于编写与 SIM 卡交互的自定义程序。
- 新的交互式命令行程序 pySim-shell。
- 新的 pySim-trace APDU 跟踪解码器。
- 传统的 pySim-prog 和 pySim-read 工具。
pySim-shell
pySim-shell 是一个用于与 SIM 卡进行各种交互的交互式命令行界面，包括经典 GSM SIM、GSM-R SIM、UICC、USIM、ISIM、HPSIM 以及最近的 eUICC。
如果您熟悉 Unix/Linux shell：想象一下它就像是 SIM 卡的 bash。
pySim-shell 交互式 shell 提供了以下命令：
- 导航卡上的文件系统层次结构。
- 使用 PIN（如 ADM1）进行认证。
- CHV/PIN 管理（验证、启用、禁用、解锁）。
- 解码 SELECT 响应（文件控制参数）。
- 以原始、十六进制编码的二进制格式读写文件和记录。
- 对于大多数文件（已开发相关文件特定的编码器/解码器类）：读取和写入文件和记录。
pySim-shell 通过使用 Python cmd2 模块，提供了各种有用的功能以提高可用性，例如命令历史（跨重启持久化）、输出重定向到计算机上的文件、通过外部工具（如 grep）进行输出管道、命令和可选择的文件/目录的 tab 完成、所有命令的交互式帮助等。
典型的工作流程可能如下：
1.启动程序并指定用于与卡通信的智能卡接口。
2.验证 PIN（如果需要）或 ADM1 PIN（如果您想要写入/修改卡）。
3.选择卡上的应用程序专用文件，如 ADF.USIM，并导航 DF 树。
4.读取并可能修改文件内容，在原始二进制（十六进制）或解码的 JSON 格式中。
pySim-shell 还支持视频演示、运行示例、高级主题、cmd2 基础知识、pySim 命令、ISO7816 命令、TS 102 221 命令、线性固定 EF 命令、透明 EF 命令、BER-TLV EF 命令、USIM 命令、文件特定命令、UICC 行政命令、ARA-M 命令、GlobalPlatform 命令、eUICC ISD-R 命令、cmd2 可设置参数等详细内容。
sysmocom 介绍
sysmocom 专注于为移动通信网络和协议提供定制解决方案，包括从无线接入网（RAN）到核心网络的各个方面。他们提供从 SIM 卡、核心网络元素到无线接入网（RAN）的设备，涵盖从微微小区到小型小区再到宏小区的范围。sysmocom 还提供咨询和培训服务，专注于 GSM/UMTS/LTE/5G 协议和接口的渗透测试的安全审计，以及协议跟踪器、分析器和转换器的开发。他们还开发了后向haul协议优化、小型蜂窝网络/网络模拟、负载测试和漫游测试、使用 GSM/GPRS/UMTS/LTE/5G 调制解调器模块（如 Wavecom、Cinterion、Option、Simcom、u-blox、Quectel）、GPS/GNSS 接收器等的 M2M 设备的电路设计和软件/固件开发，以及为各种其他无线电技术（如 AIS 和 ADS-B）的接收器和模拟器。
sysmocom 致力于为小型移动网络运营商（MNOs）和移动虚拟网络运营商（MVNOs）提供量身定制的产品和服务，同时也为大型运营商提供独立于供应商偏见的技术和经济解决方案。
1.1.2 运行 pySim-shell
pySim-shell 有多种命令行参数来控制：
- 使用哪种传输方式（如何使用读卡器与 SIM 卡通信）
- 是否自动验证 ADM pin（以及以何种格式）
- 是否执行启动脚本
- 交互式 SIM 卡壳；OsmocomBB 读卡器
使用兼容 OsmocomBB 的手机访问插入手机 SIM 卡槽的 SIM 卡。这将需要你在手机内运行 OsmocomBB 固件（可以是内存加载）。它还要求你运行 osmocon 程序，该程序提供一个 unix 域套接字，这个读卡器驱动程序可以附加到该套接字上。
--osmocon Socket 路径用于基于 Calypso（例如 Motorola C1XX）的读卡器（通过 OsmocomBB） - 通用选项
--script 在启动时自动执行的包含 pySim-shell 命令的脚本
--csv 从 CSV 文件读取卡数据
--csv-column-key 每个 CSV 列的 AES 传输密钥
默认值：[]
--card_handler 使用自动卡处理机
--noprompt 以非交互模式运行
默认值：False
-a, --pin-adm 用于配置的 ADM PIN（覆盖默认值）
-A, --pin-adm-hex 用于配置的 ADM PIN，以十六进制字符串形式（16个字符长）
1.1.3 使用示例
指南：启用 5G SUCI
SUPI/SUCI 隐藏是 5G 独立组网（SA）的一个特性，用于使用网络运营商的公钥加密 IMSI/SUPI。3GPP 规定了两种不同的变体：
- 在 UE 中进行 SUCI 计算，使用 SIM 中的密钥数据。
- 在卡上进行 SUCI 计算。
pySim 支持在 USIM 卡上为 UE 中的 SUCI 计算写入 5G 特定文件，假设您的卡包含所需的文件，并且您拥有写入它们的权限/凭证。使用 sysmocom sysmoISIM-SJA2 或任何 sysmoISIM-SJA5 的变体时都是这种情况。
目前没有 3GPP/ETSI 标准方法来配置卡上的 SUCI 计算；pySim 目前支持 sysmoISIM-SJA5-S17 的特定于供应商的方法。
此文档描述了这两种方法。
技术参考
本指南涵盖了使用 5G SUCI 功能配置 SIM 卡的基本工作流程。有关 SUCI 功能和文件内容的详细信息，请参考以下文档： - USIM 文件和结构：3GPP TS 31.102
- USIM 测试（包括文件内容示例）：3GPP TS 31.121
- SUCI 计算的测试密钥：3GPP TS 33.501
有关 sysmocom SIM 卡的具体信息，请参考： - 当前 sysmoISIM-SJA5 产品的 sysmoISIM-SJA5 用户手册
- 较旧的 sysmoISIM-SJA2 产品的 sysmoISIM-SJA2 用户手册
启用 UE 中的 5G SUCI 计算
简而言之，您可以按照以下步骤启用 UE 中的 SUCI 计算：
- 激活 USIM 服务 124
- 确保 USIM 服务 125 被禁用
- 在 EF.SUCI_Calc_Info 中存储公钥
- 设置路由指示器（必需）
如果您想禁用此功能，只需在 EF.UST 中禁用 USIM 服务 124（和 125）即可。
管理员 PIN
作为移动运营商向卡进行身份验证的通常方式是验证所谓的 ADM1（管理员）PIN。这可能因卡型号/供应商而异。
启动 pySIM-shell 并输入您的卡的管理员 PIN。如果您从您的网络运营商那里购买了 SIM 卡，但没有管理员 PIN，您将无法更改 SIM 内容！
启动 pySIM
以下 JSON 配置定义了来自 3GPP TS 31.121 第 4.9.4 节的测试文件，以及来自 3GPP TS 33.501 附录 C.4 的测试密钥。最高优先级（0）在密钥槽 1 中有一个 Profile-B（标识符：2）密钥，这意味着密钥标识符为 27 的密钥位于 hnet_pubkey_identifier 中。
警告：这些是带有公开知晓/指定私钥的测试密钥，因此对于实时/安全部署是不安全的！在生产网络中使用时，您需要生成自己的密钥集。
路由指示器
对于 SUCI 功能，必须存在路由指示器。默认情况下，文件内容无效（ffffffff）：
路由指示器是一个四字节文件，但实际的路由指示器位于字节 0 和 1 中（其他字节保留）。要将路由指示器设置为 0x71：
您也可以将路由指示器设置为 0x0，这是有效的，并意味着“未指定路由指示器”，将此留给调制解调器处理。
SUCI
（Subscription Concealed Identifier）是 5G 独立组网（SA）中的一个特性，用于保护用户的隐私。它允许网络运营商使用公钥加密用户的 IMSI（国际移动用户身份）或 SUPI（Subscription Permanent Identifier），从而在无线网络中传输时隐藏用户的实际身份信息。这样做的目的是为了防止 IMSI 捕获攻击，即攻击者通过监听无线网络中的 IMSI 信息来追踪或识别用户。
SUCI 的工作原理是将用户的 IMSI 或 SUPI 通过特定的算法转换成一个加密的标识符，这个过程通常在用户的设备（UE）上完成，或者在 SIM 卡上完成。加密后的 SUCI 信息随后在无线网络中传输，到达网络运营商的网络后，运营商可以使用相应的私钥对 SUCI 进行解密，以识别用户并提供服务。
SUCI 的使用可以增强用户隐私保护，减少用户身份信息被非法获取的风险。它在 3GPP 标准中被定义，并且是 5G 网络安全架构的一个重要组成部分。需要注意的是，SUCI 的实现和配置需要遵循相应的安全标准和最佳实践，以确保其安全性和有效性。
Routing Indicator
（路由指示器）在 5G 网络中用于指示用户数据应该被路由到哪个网络或服务提供商。它是一个关键的参数，用于网络中的网络选择和路由决策。在 5G 网络中，特别是在支持网络切片和多归属（multi-homing）的场景中，路由指示器变得尤为重要。
路由指示器通常包含在 SUCI（Subscription Concealed Identifier）中，SUCI 是一种用于保护用户身份隐私的机制，它通过加密用户的 IMSI（国际移动用户身份）或 SUPI（Subscription Permanent Identifier）来隐藏用户的真实身份。在 SUCI 中包含路由指示器可以确保即使 IMSI 被加密，网络仍然能够根据路由指示器将用户数据正确地路由到相应的网络切片或服务提供商。
在 5G 网络中，路由指示器的具体作用可能包括：
1.网络选择：允许用户选择特定的网络切片或服务提供商，即使他们当前连接到的网络可能不提供该服务。
2.漫游管理：在用户漫游到另一个网络时，路由指示器可以指示数据应该被路由到用户归属网络的哪个部分。
3.负载均衡和优化：网络运营商可以使用路由指示器来优化网络流量，确保数据被路由到负载较低或性能较好的网络部分。
路由指示器通常是一个四字节的字段，其中实际的路由指示器位于字节 0 和 1 中，其他字节保留供将来使用或特定实现细节。在配置 SUCI 时，需要正确设置路由指示器，以确保用户数据能够被正确路由。
UST Service
在这种情况下，UST Service 124 已经启用，您可以继续进行。sysmoISIM-SJA2 不支持在 SIM 卡上进行计算，因此必须禁用服务 125。
与 5G 和 sysmoISIM 相关的 USIM 错误
sysmoISIM-SJA2 支持 5G。然而，默认情况下，存储在卡文件系统中的配置对于 5G 网络是无效的：虽然启用了服务 124，但 EF.SUCI_Calc_Info 和 EF.Routing_Indicator 文件为空（因此不包含有效数据）。
至少对于 Qualcomm 的 X55 调制解调器，这会导致 USIM 错误，并且整个调制解调器会关闭 5G 功能。如果您不需要 SUCI 隐藏功能，但智能手机拒绝连接到任何 5G 网络，尝试禁用 UST 服务 124。
通过 USIM 进行 SUCI 计算
SUCI 计算也可以由 UICC 上的 USIM 应用程序直接执行。然后，UE 使用 GET IDENTITY 命令（也见 3GPP TS 31.102，第 7.5 节）来检索 SUCI 值。
sysmoISIM-SJA5-S17 支持 USIM 执行的 SUCI 计算。配置与上述 UE 中 SUCI 计算的配置没有太大区别。
主要区别在于密钥供应的方式。当 SUCI 计算由 USIM 完成时，那么密钥材料不会被 UE 访问。规范（也见 3GPP TS 31.102，第 7.5.1.1 节）也没有指定任何文件或文件格式来存储密钥材料。这意味着执行密钥供应的确切方式是 USIM 卡应用程序的实现细节。
在 sysmoISIM-SJA5-S17 的情况下，用于 USIM 执行 SUCI 计算的密钥材料存储在 ADF.USIM/DF.SAIP/EF.SUCI_Calc_Info 中（而不是在 ADF.USIM/DF.5GS/EF.SUCI_Calc_Info 中！）。
文件格式与 3GPP TS 31.102 第 4.4.11.8 节中指定的完全相同。这意味着上述描述的密钥供应程序可以无需任何更改地应用，除了文件位置不同。
为了向用户设备（UE）表明 USIM 已经设置为进行 SUCI 计算，除了服务 124 之外，还必须启用服务 125（也见 3GPP TS 31.102 第 5.3.48 节）。
为了验证 SUCI 计算是否按预期工作，可以使用 pySim-shell 发出 GET IDENTITY 命令。