51学通信

深度解析 3GPP TS 29.586：6. API定义与数据模型 (最终章)

15分钟阅读

好的，我们已经抵达了3GPP TS 29.586规范深度解读的最后一站。在前文中，我们已经全面掌握了SLPKMF的两大核心服务——Discovery和KeyRequest——的功能逻辑和API交互流程。现在，我们将深入到协议的最底层，对构成这些安全交互的“DNA”——数据模型（Data Model）——进行精细的解剖。

深度解析 3GPP TS 29.586：6. API定义与数据模型 (最终章)

本文技术原理深度参考了3GPP TS 29.586 V18.1.0 (2024-06) Release 18规范中，第六章“API Definitions”的全部核心内容。本文是TS 29.586解读的最终章，旨在为读者提供一份详尽的Nslpkmf API“精装修”施工图和“材料清单”，我们将剖析两大服务（Discovery和KeyRequest）的API资源和所有核心JSON对象的精确结构，揭示每个字段在Sidelink定位密钥管理中的具体作用。

引言：从“指令”到“密文”——API的微观构造

我们已经学会了如何向SLPKMF下达“作战指令”——我们知道了Discovery服务的三个授权操作和KeyRequest服务的一个密钥请求操作。我们理解了这些指令的战略意图。

现在，我们将进入“密码编译室”，学习如何将这些指令，编码成SLPKMF之间能够精确无误解析的“密文”——即具体的HTTP API和JSON数据体。第六章“API Definitions”正是这份规范的“密码本”。

  • 6.1 Nslpkmf_Discovery Service API: 定义了“准入安检”阶段所有授权请求的编码规则。
  • 6.2 Nslpkmf_SLPKMFKeyRequest Service API: 定义了“会话密钥”分发阶段密钥请求的编码规则。

对于负责开发V-SLPKMF和H-SLPKMF的工程师来说，这一章的内容将直接转化为他们代码中的API客户端、服务器路由和数据结构。让我们最后一次回到自动化仓库的场景，看看V-SLPKMF为“穿梭者-访客”机器人发起的每一个请求，其背后的JSON对象是如何被精确构造的。

1. 解读第6.1章 Nslpkmf_Discovery Service API - “发现授权”API详解

本节定义了与发现阶段相关的三个授权操作的API实现。

1.1 6.1.3 Resources (资源) - 授权即资源

Nslpkmf_Discovery API的资源模型非常独特，它没有/subscriptions这样的集合资源，而是直接定义了三个独立的、文档式的资源模板。

Figure 6.1.3.1-1: Resource URI structure of the Nslpkmf_Discovery API

URI结构清晰地展示了这三个资源：

  • /announcement-authorization/{userInfold}
  • /monitor-authorization/{userInfold}
  • /discovery-authorization/{userInfold}

这些资源都嵌套在/{ueId}之下，形成了/{ueId}/<authorization-type>/{userInfoId}的结构。这是一种非常直观的RESTful设计：授权被建模为隶属于特定用户和特定应用会话的文档资源。

Table 6.1.3.1-1 确认了这三个资源都只支持PUT方法，用于创建或更新授权。

1.2 AnnouncementAuthorization API 数据模型

  • 请求 (PUT):

    • Request Body (AnnounceAuthData):

      Table 6.1.6.2.2-1: Definition of type AnnounceAuthData

      • rangingSlAppId (M): ApplicationId，字符串类型，指明这是哪个Sidelink定位应用。
      • ueRole (M): UeRole，枚举类型，对于广播者，通常是"TARGET_UE"或"LOCATED_UE"。

  • 响应 (201 Created):

    • Response Body (AnnounceAuthData): 成功创建时，响应体中会包含H-SLPKMF生成的授权数据。规范虽然将请求和响应的数据类型都命名为AnnounceAuthData，但在OpenAPI定义中，响应体的内容会更丰富，包含了授权令牌等信息（具体格式可能在TS 33.533或TS 24.514中进一步定义）。

1.3 MonitorAuthorization API 数据模型

  • 请求 (PUT):

    • Request Body (MonitorAuthReqData):

      Table 6.1.6.2.3-1: Definition of type MonitorAuthReqData

      • rangingSlAppId (M): 应用ID。
      • ueRole (M): 监控者的角色，如"REFERENCE_UE"。
      • ueSecurityCapability (M): UeSecurityCapability，Bytes类型。这是一个关键字段，它是UE上报的、经过Base64编码的PC5安全能力信息，告知H-SLPKMF该UE支持哪些加密和完整性保护算法。

  • 响应 (201 Created):

    • Response Body (MonitorAuthRespData):

      Table 6.1.6.2.4-1: Definition of type MonitorAuthRespData

      • chosenPc5CipheringAlgorithm (M): integer类型。H-SLPKMF根据请求中的ueSecurityCapability，选择一个双方都支持的算法，并在此字段中告知V-SLPKMF。
      • discSecMaterials (M): DiscSecMaterials，这是核心的安全材料。

1.4 DiscSecMaterials (发现安全材料) 数据模型

这是监控者和发现者获取的“解码本”。

Table 6.1.6.2.7-1: Definition of type DiscSecMaterials

  • duik (O): Duik (Discovery User Integrity Key)，Bytes类型。用于验证广播消息完整性的用户级密钥。
  • duck (O): Duck (Discovery User Confidentiality Key)，Bytes类型。用于解密广播消息的用户级密钥。
  • dusk (O): Dusk (Discovery User Scrambling Key)，Bytes类型。用于加扰的密钥。

这些密钥都是Base64编码的字符串。

2. 解读第6.2章 Nslpkmf_SLPKMFKeyRequest Service API - “密钥请求”API详解

本节定义了为单播通信请求会话密钥的API实现。

2.1 6.2.3 Resources & 6.2.3.2.4 Custom Operations (资源与自定义操作)

Nslpkmf_SLPKMFKeyRequest API的资源模型更为特殊，它采用自定义操作 (Custom Operation) 的模式。

  • 资源集合: /ranging-keys
  • 自定义操作: 在这个集合上定义了一个名为request的动作。
  • API端点: POST /ranging-keys/request

这种设计清晰地表达了“我不是在管理一个资源，我是在请求执行一个动作”的意图。

2.2 UnicastKey API 数据模型

  • 请求 (POST .../request):

    • Request Body (UnicastKeyReqData):

      Table 6.2.6.2.2-1: Definition of type UnicastKeyReqData

      • rangingSlAppId (M): 应用ID。
      • kslpFreshness1 (M): KslpFreshnessParameter1，string类型。由请求方UE生成的随机数（Nonce），用于防止重放攻击。
      • slpkId (M): SlpkId，string类型。在发现阶段获取的密钥ID，用于关联授权上下文。

  • 响应 (200 OK):

    • Response Body (UnicastKeyRspData):

      Table 6.2.6.2.3-1: Definition of type UnicastKeyRspData

      • kslp (M): Kslp (Key for Sidelink Positioning)，string类型。这是H-SLPKMF为本次单播会话生成的会话密钥。
      • kslpFreshness2 (M): KslpFreshnessParameter2，string类型。由H-SLPKMF生成的Nonce，用于对请求方进行验证。

所有这些看似是string的密钥和新鲜度参数，在实际传输时都是Base64编码的二进制数据。

3. 全景复盘：一次完整的安全交互API之旅

让我们将所有API和数据模型串联起来，以API的视角，完整地走一遍“穿梭者-访客-007”（SUPI为supi-007，应用会话ID为info-xyz）在仓库中进行一次安全定位的生命周期：

  1. 广播授权阶段

    • V-SLPKMF → H-SLPKMF: PUT /nslpkmf-discovery/v1/supi-007/announcement-authorization/info-xyz
    • Request Body (AnnounceAuthData): {"rangingSlAppId": "warehouse-navi", "ueRole": "TARGET_UE"}
    • H-SLPKMF → V-SLPKMF: 201 Created，Body中包含授权令牌。

  2. 监控授权阶段 (为本地“观察员”获取密钥)

    • V-SLPKMF → H-SLPKMF: PUT /nslpkmf-discovery/v1/supi-observer-01/monitor-authorization/info-abc
    • Request Body (MonitorAuthReqData): {"rangingSlAppId": "warehouse-navi", "ueRole": "REFERENCE_UE", "ueSecurityCapability": "base64-encoded-caps"}
    • H-SLPKMF → V-SLPKMF: 201 Created
    • Response Body (MonitorAuthRespData): 包含chosenPc5CipheringAlgorithm和discSecMaterials（其中有duik, duck等密钥）。

  3. 单播密钥请求阶段

    • “观察员”与“访客-007”相互发现，准备测距。
    • V-SLPKMF → H-SLPKMF: POST /nslpkmf-keyrequest/v1/ranging-keys/request
    • Request Body (UnicastKeyReqData): {"rangingSlAppId": "warehouse-navi", "kslpFreshness1": "nonce-from-ue1", "slpkId": "id-from-discovery-phase"}
    • H-SLPKMF → V-SLPKMF: 200 OK
    • Response Body (UnicastKeyRspData): {"kslp": "base64-encoded-session-key", "kslpFreshness2": "nonce-from-hslpkmf"}

总结与宣告

通过对TS 29.586第六章API定义与数据模型的最终解剖，我们已经将SLPKMF这座“安全堡垒”的内部构造彻底摸清。

  1. 独特的API范式: SLPKMF的API设计展示了SBA框架的灵活性。它没有采用通用的订阅/通知模式，而是根据业务特性，分别采用了基于PUT的幂等资源管理模型（用于持久化的授权）和基于POST的自定义操作模型（用于一次性的密钥生成），两者都非常贴合其安全业务的本质。

  2. 以安全为核心的数据模型: 所有的数据对象都紧密围绕“授权”和“密钥”这两个核心来设计。ueSecurityCapability的传递、chosen...Algorithm的协商、...Freshness...参数的交换，都体现了设计者对安全流程的严谨考虑。

  3. 二进制数据的标准承载: 规范明确所有密钥、能力等二进制信息都使用Bytes类型（即Base64编码的字符串）在JSON中承载，为不同厂商的互通提供了统一的数据交换格式。

至此，我们对3GPP TS 29.586规范的系列深度解读已全部完成。 我们从Sidelink定位的安全挑战出发，深入到了SLPKMF两大核心服务的业务逻辑，最终抵达了构成其网间安全交互的每一个API和数据模型的细节。

这份看似小众的规范，实则为5G赋能垂直行业（如车联网、工业4.0）过程中的一个关键安全问题，提供了坚实、标准化的解决方案。理解它，就是理解5G如何将安全能力，从传统的网络覆盖，延伸到设备间直接通信的“最后一厘米”。

FAQ

Q1：Nslpkmf_Discovery服务的三个授权资源URI中，ueId和userInfoId是什么关系？为什么需要两个ID？ A1：ueId代表了UE本身的永久身份（如SUPI），是物理设备或SIM卡的标识。而userInfoId代表了UE在该Sidelink定位应用中的一次会话或角色的身份。一个UE可能同时参与多个不同的定位应用，或者在同一个应用中扮演不同的角色（例如，既是“搬运工”又是临时的“观察员”）。使用userInfoId，可以为UE的每一次不同的“任务”或“角色”创建独立的授权，使得授权管理更加精细化。

Q2：在MonitorAuthRespData中，为什么H-SLPKMF返回的是discSecMaterials，而不是一个单一的密钥？ A2：discSecMaterials是一个安全材料的集合，包含了用于完整性保护的duik、用于机密性保护的duck等。这是因为一个安全的通信过程，通常需要多种不同用途的密钥来协同工作，以抵御不同类型的攻击（如篡改、窃听）。将它们打包在一个结构体中，便于统一管理和分发。

Q3：UnicastKey操作返回的会话密钥kslp是一次性的吗？ A3：是的，kslp是为一次特定的单播通信会话生成的会话密钥，具有很短的生命周期。当这次测距通信结束后，这个密钥就应该被废弃。下次再需要进行单播测距时，UE需要重新发起请求，获取一个新的会た话密钥。这种“一次一密”的机制，极大地提升了通信的安全性。

Q4：为什么密钥、安全能力等二进制数据要用Base64编码放在JSON字符串里，而不是像TS 29.591那样使用multipart消息？ A4：这是一个API设计上的权衡。Sidelink定位密钥管理服务中，二进制数据的大小通常是固定的、且相对较小（几十到几百字节）。在这种情况下，使用Base64编码直接嵌入JSON，虽然会带来约33%的体积膨胀，但实现起来非常简单，无需处理复杂的多部分消息。而multipart消息的优势在于传输大块的、大小可变的二进制数据。对于密钥这样的小块数据，简单性带来的好处超过了体积膨胀的缺点。

Q5：整个流程中，密钥都是由H-SLPKMF生成的吗？V-SLPKMF的角色是什么？ A5：是的，核心的安全信任根和密钥生成能力都位于H-SLPKMF。这是“归属地控制”原则的体现。V-SLPKMF的角色更像是一个代理和转发器：它负责接收其网络内漫游UE的请求，验证其合法性，然后将请求“翻译”成Nslpkmf接口的调用，转发给H-SLPKMF。它从H-SLPKMF获取到加密的安全材料后，再将其安全地转发给UE。V-SLPKMF本身不参与密钥的生成。

关系图谱