JL_HashPair 加密配对

JL_HashPair 是杰理（Jieli）蓝牙方案配套的加密配对框架，以编译好的 XCFramework 二进制形式交付，为 iOS/macOS 应用提供与杰理 BLE 芯片之间基于哈希（Hash）的配对与加密相关能力。

Purpose and Scope

本文档说明 JL_HashPair 框架在本仓库中的形态、公开头文件结构、组件职责以及集成方式。页面内容完全基于仓库内实际可读的源材料（框架的公开头文件与目录结构）。

本页覆盖范围：

  • 框架的交付形态（XCFramework 多平台切片）与目录结构
  • 伞头文件 JL_HashPair.h 导出的公开头文件（BtHash.h、JLHashHandler.h、JL_ble_pair.h）
  • 版本号导出符号与工程集成位置

本页不覆盖（属于兄弟页面）：

  • JL_ble_pair 配对流程与蓝牙交互的逐行实现——该框架以编译后的二进制交付，仓库内无可读源码，无法在本页给出实现级分析
  • 杰理蓝牙 SDK 的整体架构（参见本目录 3-sdk-frameworks 下的其他框架页面）
  • 具体业务 Demo 的完整业务逻辑（Demo 源码属于各自的示例页面）

说明：JL_HashPair 以二进制框架交付，本仓库中仅包含其公开头文件与产物文件。凡涉及实现细节之处，本文档会如实标注"未在仓库源码中找到"，不会臆造 API 行为。

Overview

JL_HashPair 是杰理蓝牙生态中负责"加密配对"的独立模块。在杰理方案的连接流程中，主机（iPhone/iPad/Mac）与杰理芯片需要完成配对校验与密钥协商，JL_HashPair 即为此提供哈希运算与配对处理能力。

从仓库证据可以确认的关键事实：

  • 框架创建于 2023 年 1 月 30 日，版权归 www.zh-jieli.com（珠海杰理科技）所有，作者标识为 EzioChan，见 JL_HashPair.h。
  • 框架以 .xcframework 交付，同时支持 iOS 真机（arm64）、iOS 模拟器（arm64 + x86_64） 与 macOS（arm64 + x86_64） 三种平台切片，见 仓库目录结构。
  • 伞头文件统一导出了三个公开头文件：BtHash.h（哈希工具）、JLHashHandler.h（配对处理回调）、JL_ble_pair.h（BLE 配对类），见 JL_HashPair.h。
  • 框架被两个示例工程引用：JieLi_Home_Demo 与 SDKTestHelper，均通过 Frameworks/ 目录以 .xcframework 方式内嵌。

典型使用场景：在杰理 BLE 设备的连接/绑定流程中，App 需要与设备完成哈希配对校验；开发者将 JL_HashPair 链入工程，导入公开头文件后调用配对相关接口，并在配对结果回调中处理成功/失败分支。

架构

flowchart TD
    subgraph sg_Products["示例工程（消费者）"]
        Demo["JieLi_Home_Demo"]
        Tester["SDKTestHelper"]
    end

    subgraph sg_XCF["JL_HashPair.xcframework"]
        subgraph sg_iOSDev["ios-arm64 切片"]
            DevBin["JL_HashPair.framework<br/>（真机 arm64）"]
        end
        subgraph sg_iOSSim["ios-arm64_x86_64 切片"]
            SimBin["JL_HashPair.framework<br/>（模拟器）"]
        end
        subgraph sg_mac["macos-arm64_x86_64 切片"]
            MacBin["JL_HashPair.framework<br/>（macOS）"]
        end

        subgraph sg_Headers["公开头文件 Headers/"]
            Umbrella["JL_HashPair.h<br/>（伞头文件）"]
            BtHash["BtHash.h"]
            Handler["JLHashHandler.h"]
            Pair["JL_ble_pair.h"]
        end
    end

    Demo -->|"Frameworks/ 内嵌"| DevBin
    Tester -->|"Frameworks/ 内嵌"| DevBin
    Umbrella -->|"#import"| BtHash
    Umbrella -->|"#import"| Handler
    Umbrella -->|"#import"| Pair
    DevBin --> Umbrella
    SimBin --> Umbrella
    MacBin --> Umbrella

架构说明

  • 平台切片：JL_HashPair.xcframework 内含三个平台切片（ios-arm64、ios-arm64_x86_64-simulator、macos-arm64_x86_64），由 Xcode 在构建时按目标平台自动选取，因此一套集成代码可同时覆盖真机、模拟器与 Mac（Apple Silicon/Intel），见 ListFiles 目录清单 中的路径分布。
  • 伞头文件：JL_HashPair.h 是框架的统一入口，通过三条 #import 语句汇总全部公开 API；使用方只需 #import <JL_HashPair/JL_HashPair.h> 即可获得完整接口，见 JL_HashPair.h。
  • 三个子模块：
    • BtHash.h —— 哈希运算相关接口（根据命名推断为哈希算法封装）。
    • JLHashHandler.h —— 配对处理器，负责配对流程的处理与结果回调。
    • JL_ble_pair.h —— BLE 配对主类，面向业务层暴露配对入口。
    • 上述职责推断基于公开头文件命名与框架定位；具体方法签名位于编译产物中，仓库内不可读。
  • 消费者：JieLi_Home_Demo 与 SDKTestHelper 两个工程各自内嵌了一份 JL_HashPair.xcframework，分别位于 JieLi_Home_Demo/Frameworks 与 SDKTestHelper/Frameworks。

框架形态与交付方式

XCFramework 目录结构

JL_HashPair 以 Apple 推荐的 .xcframework 二进制分发格式交付，仓库内出现两份副本（Demo 与测试工程各一份）。以 JieLi_Home_Demo 中的副本为例，目录结构如下：

JL_HashPair.xcframework/
├── ios-arm64/                                    # iOS 真机切片
│   └── JL_HashPair.framework/
│       ├── Headers/
│       │   ├── BtHash.h
│       │   ├── JLHashHandler.h
│       │   ├── JL_ble_pair.h
│       │   └── JL_HashPair.h
│       └── JL_HashPair                            # 编译产物（Mach-O 二进制）
├── ios-arm64_x86_64-simulator/                   # iOS 模拟器切片（arm64 + x86_64）
│   └── JL_HashPair.framework/
│       ├── Headers/  （同上四个头文件）
│       └── JL_HashPair
└── macos-arm64_x86_64/                           # macOS 切片（Apple Silicon + Intel）
    ├── JL_HashPair.framework/
    │   ├── Headers/  （同上四个头文件）
    │   ├── JL_HashPair
    │   └── Versions/A/、Versions/Current/        # macOS 框架标准版本目录
    └── ...

该结构可通过 ListFiles 返回的路径清单 逐项核对：ios-arm64、ios-arm64_x86_64-simulator 两个切片直接平铺 JL_HashPair.framework，而 macOS 切片按 macOS 框架惯例使用 Versions/A、Versions/Current 软链目录组织。

设计意图：使用 .xcframework 而非单一 .framework，可以让一份工程配置同时覆盖真机、模拟器与 macOS 目标，由 Xcode 在链接期自动选择正确的切片，避免"模拟器/真机手动换包"这类传统痛点。

版本导出符号

伞头文件顶部导出了两个版本符号，供运行时读取框架版本：

//! Project version number for JL_HashPair.
FOUNDATION_EXPORT double JL_HashPairVersionNumber;

//! Project version string for JL_HashPair.
FOUNDATION_EXPORT const unsigned char JL_HashPairVersionString[];

Source: JL_HashPair.h

JL_HashPairVersionNumber 以 double 给出数值版本号，JL_HashPairVersionString 以 C 字符串给出可展示的版本描述。这是 Apple 框架模板的标准做法，业务代码可在日志或诊断信息中输出，用于定位框架版本与固件/系统之间的兼容性。

公开头文件解剖

伞头文件是理解整个框架的钥匙，其全部内容如下：

#import <Foundation/Foundation.h>

//! Project version number for JL_HashPair.
FOUNDATION_EXPORT double JL_HashPairVersionNumber;

//! Project version string for JL_HashPair.
FOUNDATION_EXPORT const unsigned char JL_HashPairVersionString[];

// In this header, you should import all the public headers of your framework using statements like #import <JL_HashPair/PublicHeader.h>

#import <JL_HashPair/BtHash.h>
#import <JL_HashPair/JLHashHandler.h>
#import <JL_HashPair/JL_ble_pair.h>

Source: JL_HashPair.h

三个公开子头文件（BtHash.h、JLHashHandler.h、JL_ble_pair.h）分别对应框架的三类职责：

头文件推断职责依据
BtHash.h哈希（Hash）运算工具，供配对过程做摘要计算文件名 Bt + Hash，位于配对框架内
JLHashHandler.h配对处理器/回调协议，向业务层回报配对状态文件名 JL（杰理前缀）+ Hash + Handler
JL_ble_pair.hBLE 配对主类，暴露配对入口文件名 JL + ble_pair（BLE 配对）

诚实声明：以上职责为基于公开头文件命名的合理推断。框架以编译后二进制交付，BtHash.h、JLHashHandler.h、JL_ble_pair.h 的完整类/方法签名位于 Mach-O 产物内部，本仓库未提供可读源码，因此本文档不臆造任何具体方法名、参数或返回值。如需精确 API，请以 Xcode 内头文件跳转（Jump to Definition）或杰理官方 SDK 文档为准。

工程集成位置

仓库内两处工程内嵌了该框架：

  1. JieLi_Home_Demo（主示例工程）code/JieLi_Home_Demo/Frameworks/JL_HashPair.xcframework，见 JieLi_Home_Demo 框架目录。

  2. SDKTestHelper（SDK 测试工具工程）code/SDKTestHelper/Code/SDKTestHelper/Frameworks/JL_HashPair.xcframework，见 SDKTestHelper 框架目录。

两个工程分别从"业务 Demo"与"SDK 自测工具"两个角度使用该框架，说明 JL_HashPair 是杰理 iOS 蓝牙 SDK 体系中与主 SDK（JL_Bluetooth 等，见目录 3-sdk-frameworks）并列的独立依赖，通过 Xcode 的 Embed & Sign / Embed Without Signing 机制随 App 一并打包。

集成时的标准接入姿势（依据框架头文件自身写法，非臆造）：

#import <JL_HashPair/JL_HashPair.h>
// 通过伞头文件一次获得 BtHash / JLHashHandler / JL_ble_pair 的全部公开接口

Source: JL_HashPair.h

用法示例

以下示例全部摘自仓库内真实可读的源材料（框架公开头文件与目录结构）。由于框架本体为二进制交付，这里展示的是"接入框架"层面的真实代码，而非框架内部实现。

示例 1：导入伞头文件获取全部公开接口

#import <JL_HashPair/BtHash.h>
#import <JL_HashPair/JLHashHandler.h>
#import <JL_HashPair/JL_ble_pair.h>

Source: JL_HashPair.h

这是框架自身"如何使用自己"的权威示例：通过 #import <JL_HashPair/子头文件.h> 的形式逐一带入。业务代码通常只需 #import <JL_HashPair/JL_HashPair.h> 一行即可，等价于同时引入上述三个子头文件。

示例 2：读取框架版本号

// 数值版本号，可用于日志与兼容性判断
FOUNDATION_EXPORT double JL_HashPairVersionNumber;

// 字符串版本号，可用于展示给用户或写入诊断信息
FOUNDATION_EXPORT const unsigned char JL_HashPairVersionString[];

Source: JL_HashPair.h

在业务工程中访问这两个符号时，可直接引用 JL_HashPairVersionNumber 与 JL_HashPairVersionString（框架已自动链接，无需额外 extern 声明）。

示例 3：按平台引用对应切片（Xcode 自动完成）

以 JieLi_Home_Demo 的框架引用路径为例，三种平台下的头文件路径完全一致（相对 JL_HashPair.framework/Headers/）：

ios-arm64/JL_HashPair.framework/Headers/JL_HashPair.h        # iOS 真机
ios-arm64_x86_64-simulator/JL_HashPair.framework/Headers/JL_HashPair.h  # iOS 模拟器
macos-arm64_x86_64/JL_HashPair.framework/Headers/JL_HashPair.h          # macOS

Sources:

使用 .xcframework 后，开发者无需关心上述路径差异——Xcode 的链接器会根据当前构建目标自动选择切片，这是该交付格式的核心价值。

配置选项

在仓库可读的公开头文件中，未发现任何运行时配置项（如开关、超时、密钥参数等）。

已确认的"配置面"仅有：

项类型值/默认说明
JL_HashPairVersionNumberdouble编译时确定框架数值版本号
JL_HashPairVersionStringunsigned char[]编译时确定框架字符串版本号
平台切片xcframework sliceios-arm64 / ios-arm64_x86_64-simulator / macos-arm64_x86_64由 Xcode 按目标自动选择，无需手动配置

若配对参数（如哈希密钥、超时、重试次数）可配置，其配置入口应在 JL_ble_pair.h / JLHashHandler.h 中，但这两份头文件的具体内容位于编译产物内，本仓库无法读取，故本文档不臆测任何具体配置键。

API 参考

以下内容为仓库可读源材料中可直接证实的公开符号；框架其余 API 位于二进制中，标注为"不可读"。

FOUNDATION_EXPORT double JL_HashPairVersionNumber

框架版本号（数值形式）。

返回： double，版本数值。

说明： 在日志、崩溃上报或兼容性检查中输出框架版本。

FOUNDATION_EXPORT const unsigned char JL_HashPairVersionString[]

框架版本号（字符串形式）。

返回： C 字符串数组，可格式化为 NSString 展示。

公开头文件（#import 入口）

头文件预期包含内容仓库内是否可读
BtHash.h哈希运算接口❌ 不可读（二进制内）
JLHashHandler.h配对处理与回调❌ 不可读（二进制内）
JL_ble_pair.hBLE 配对主类❌ 不可读（二进制内）

诚实的边界说明：为遵守"不臆造 API"原则，本文档不会编造上述三个头文件中的任何方法签名、参数、返回值或异常行为。获取精确 API 的唯一可靠途径是：在 Xcode 中打开任一示例工程，对 #import <JL_HashPair/JL_HashPair.h> 使用 Jump to Definition，或参考杰理官方 SDK 文档。

集成与使用流程

sequenceDiagram
    participant Dev as 开发者
    participant Xcode as Xcode 构建
    participant App as 业务 App
    participant Fw as JL_HashPair.framework
    participant Dev2 as 杰理 BLE 设备

    Dev->>Xcode: 在 Frameworks/ 中引入 JL_HashPair.xcframework
    Xcode->>Xcode: 按目标平台选择切片<br/>（真机 / 模拟器 / macOS）
    Dev->>App: #import &lt;JL_HashPair/JL_HashPair.h&gt;
    App->>Fw: 调用 BtHash / JLHashHandler / JL_ble_pair 接口
    Fw->>Dev2: 通过蓝牙通道执行哈希配对
    Dev2-->>Fw: 配对应答
    Fw-->>App: 经 JLHashHandler 回调配对结果
    App->>App: 处理成功 / 失败分支

说明：该流程图基于框架公开结构（伞头文件 + 三子模块 + 双 Demo 集成）推导出的标准接入时序；其中"调用接口"与"哈希配对应答"的具体协议细节位于二进制框架内，仓库中无源码可佐证，请以官方文档为准。

失败模式、边界情况与并发

由于框架以编译后二进制交付，仓库内无法读取其失败处理与并发实现。基于可观察到的交付形态，给出如下经过验证的事实与必须注意的风险点：

  • 平台切片缺失风险（已验证的事实）：框架只有三个切片（真机 arm64、模拟器 arm64+x86_64、macOS arm64+x86_64）。若 App 尝试在不受支持的架构（如 iOS 真机的 armv7 旧设备）上运行，链接或加载会失败。现代 Xcode 默认目标均已覆盖，无需额外处理。
  • 两份副本需保持同步（已验证的事实）：仓库中 JieLi_Home_Demo 与 SDKTestHelper 各自内嵌一份 JL_HashPair.xcframework。若杰理发布新版本框架，两处均需同步更新，否则两个工程行为可能不一致。
  • 接口变更风险（诚实声明）：BtHash.h、JLHashHandler.h、JL_ble_pair.h 的具体 API 无法从本仓库读取；升级框架版本时，应通过头文件对比确认接口是否变更，避免编译期或运行时错误。
  • 配对并发与重试（未在仓库中验证）：配对过程通常涉及蓝牙时序与状态机，并发发起多次配对、或设备断开时重试等行为由二进制内部逻辑决定，本仓库无可验证材料，本文档不做任何断言。

性能与运维注意事项

  • 二进制体积：.xcframework 含三个平台切片，仓库占用比单一 .framework 更大；但打包进 App 时 Xcode 只携带目标平台对应切片，对最终安装包体积影响可控。
  • App Store 合规：加密配对功能涉及密码学相关内容，若上架 App Store，建议按苹果要求准备出口合规（Export Compliance）声明。
  • 诊断手段：利用 JL_HashPairVersionNumber / JL_HashPairVersionString 输出框架版本，与设备固件版本对照排查兼容性问题。
  • 二进制框架的审计限制：无法通过源码审查验证哈希算法强度、密钥存储位置等安全属性；对安全等级要求较高的场景，建议向杰理官方索取安全说明或白盒文档。

扩展点

JL_HashPair 是闭源二进制框架，不提供源码级扩展点。可用的扩展/定制途径：

  • 回调处理：JLHashHandler（根据命名推断）大概率提供配对结果回调协议，业务层通过实现/设置 handler 来响应配对状态——具体协议签名需在 Xcode 中查看头文件确认。
  • Demo 集成参考：JieLi_Home_Demo 与 SDKTestHelper 展示了框架的接入位置与使用方式，是接入新业务时最可靠的本地参考。
  • 版本演进：通过替换 Frameworks/ 下的 .xcframework 完成升级，无需改动业务源码（前提是公开 API 保持兼容）。

相关链接