51学通信

深度解析 3GPP TS 29.501：6 Requirements for secure API design (为你的API穿上“金钟罩”)

22分钟阅读

深度解析 3GPP TS 29.501：6 Requirements for secure API design (为你的API穿上“金钟罩”)

本文技术原理深度参考了3GPP TS 29.501 V18.7.0 (2024-12) Release 18规范中，关于“Chapter 6 Requirements for secure API design”的核心章节。本文将深入探讨3GPP为所有服务化接口（SBI）设下的“安全红线”，指导开发者如何构建一个不仅功能强大，而且坚不可摧的API。

在前几期的深度解析中，我们的主角——API设计师小王，已经为他的NIAF（网络智能分析功能）服务Nniaf_Analytics完成了从宏伟蓝图到精细施工图的全部设计工作。他精心雕琢的nniaf-analytics.yaml文件，遵循了统一的命名约定和交互模式，堪称一份优雅的API契约。

然而，在将这份设计交付开发之前，还有一个至关重要的环节——安全审查。小王将他的设计文档提交给了公司里经验最丰富的安全架构师，老李。老李是3GPP SA3（安全组）的专家，他打开了TS 29.501的第6章，开始逐条对小王的设计进行“灵魂拷问”。

老李语重心长地对小王说：“小王，你的API设计得非常漂亮，但在我们通信网络里，‘漂亮’远没有‘安全’重要。一个微小的API漏洞，都可能成为攻击者攻破整个5G核心网的突破口。第6章的内容，就是SA3为所有API设计师划定的‘生命线’，它不是建议，而是必须遵循的铁律。现在，让我们一起看看，你的API是否穿上了刀枪不入的‘金钟罩’。”

1. 解读 6.1 & 6.2 General - 安全设计的“五大铁律”

第6章开篇明义，指出本章内容由SA3提供，是所有Stage 3规范制定者都必须遵守的通用指南。老李将6.2节的核心内容，总结为“五大安全铁律”，这是构建一个健壮API的基石。

老李说：“这五条铁律的核心思想可以概括为一句话：对任何来自外部的输入，都不要有丝毫的信任 (Zero Trust Input)。你必须像边防哨兵一样，对每一个进入你系统的‘数据包’进行严格的盘查。”

1.1 铁律一：严格输入校验 (“严防死守，绝不信任”)

规范原文引用 (Clause 6.2): The valid format and range of values (when applicable) for each IE shall be defined unambiguously.

NOTE 1: Explicitly defining format and range of values not only helps to improve the security of a certain implementation, but also allows for reliable interoperability… Example: Defining a “lowercase string variable of length 10 and range [a..z]” is much more explicit that just defining a “string of length 10”.

深度解析： 这是所有安全设计的第一道，也是最重要的一道防线。任何模糊不清的输入定义，都可能成为漏洞的温床。例如，如果一个字段只定义为“字符串”，攻击者可能会传入一个超长的字符串导致缓冲区溢出，或者传入一段SQL注入、命令注入的恶意脚本。

“明确定义”意味着：

  • 类型 (Type): string, integer, boolean, object, array。
  • 格式 (Format): 对于字符串，要明确其格式，如date-time, uri, ipv4, ipv6。
  • 模式 (Pattern): 使用正则表达式来约束字符串的内容，例如，只允许包含特定的字符。
  • 范围 (Range): 对于数字，要明确其最大值和最小值。
  • 长度 (Length): 对于字符串和数组，要明确其最小和最大长度。

老李的审查与小王的设计： 老李首先检查了AnalyticsJobCreateData这个数据模型。

  • 审查 ueId 字段:
    • 小王的初始设计 (YAML): 
      ueId:
  type: string
  description: "Identifier of the UE."
    • 老李的反馈: “太模糊了！‘字符串’是什么字符串？SUPI？GPSI？IMSI？长度是多少？有什么字符限制？这样的定义，等于把大门敞开。”
    • 小王的修改后设计: 
      ueId:
  $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
  description: "The SUPI of the UE as defined in TS 29.571."
      在TS29571_CommonData.yaml中，Supi类型被严格定义为： 
      Supi:
  type: string
  pattern: '^(imsi-[0-9]{5,15}|nai-.+|gci-.+|gli-.+)$'
  • 审查 analysisDuration 字段:
    • 小王的初始设计: analysisDuration: type: integer
    • 老李的反馈: “这个整数的单位是什么？秒？毫秒？它的取值范围是多少？能是负数吗？能是几百万吗？”
    • 小王的修改后设计: 
      analysisDuration:
  type: integer
  format: int32
  description: "Analysis duration in seconds."
  minimum: 60       # 至少分析1分钟
  maximum: 86400    # 最多分析24小时

老李点头称赞：“很好，现在对于每一个输入，我们都有了一把精确的‘卡尺’。任何不符合尺寸的输入，都应该在API的入口处被直接拒绝，并返回400 Bad Request。”

1.2 铁律二 & 三：资源限制 (“拒绝饕餮，防止撑死”)

这两条铁律旨在防止**拒绝服务 (Denial of Service, DoS)**攻击。攻击者可能通过发送一个结构极其复杂或体积异常庞大的请求，耗尽服务器的CPU或内存资源，导致服务崩溃。

规范原文引用 (Clause 6.2):

  • For each message the number of leaf IEs shall not exceed 2048K (2,097,152).
  • The maximum size of the JSON body of any HTTP request/response shall not exceed 16 million octets (16MB) before compression is applied, if any.
  • The maximum nesting depth of leaves shall not exceed 32.

深度解析： 规范设定了三个清晰的物理限制：

  1. 最大叶子信息元数量 (Max Leaf IEs): JSON对象中所有“终极”数据项的总数不能超过约210万。一个简单的值（字符串、数字）是一个叶子，一个简单类型的数组算一个叶子，但对象（{}）是“树枝”，它的属性才是叶子。这个限制防止了包含海量字段的“巨型”JSON对象。
  2. 最大消息体大小 (Max Body Size): 原始（未压缩）的JSON消息体不能超过16MB。这是一个简单直接的体积限制。
  3. 最大嵌套深度 (Max Nesting Depth): JSON对象的嵌套层级不能超过32层。这个限制主要是为了防止因无限递归解析而导致的“栈溢出”错误。

老李的审查与小王的设计： 老李提出了一个场景：“假设OAM系统可以批量创建分析任务，一次POST一个包含任务数组的请求。如果这个数组有几百万个元素，你的NIAF不就内存溢出了吗？”

小王根据这些铁律，在他的设计和实现中加入了相应的防御措施：

  1. 配置API网关/SCP: 在NIAF服务的前端（如SCP或API网关）上，配置请求体大小上限为16MB。超过此大小的请求，连NIAF的门都摸不到，直接被前端拒绝。
  2. 配置JSON解析器: 在NIAF的应用代码中，使用的JSON解析库被配置了最大允许的元素数量和嵌套深度。一旦解析过程中超过这些阈值，就立即抛出异常并返回413 Payload Too Large或400 Bad Request。
  3. 在API契约中明确: 对于批量创建的接口，小王在OpenAPI文档中明确了数组的最大长度。 
    requestBody:
  content:
    application/json:
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AnalyticsJobCreateData'
        maxItems: 1000 # 一次最多创建1000个任务

老李补充道：“记住，这些限制不仅要对请求生效，对响应也要生效。你的NIAF不能因为一次查询就返回一个超过16MB的响应体。对于可能返回大量数据的查询接口，必须实现分页机制（Pagination），这我们在4.9节已经讨论过了。”

1.3 铁律四：键名唯一 (“名正言顺，杜绝分身”)

规范原文引用 (Clause 6.2): For data structures where values are accessible using names (sometimes referred to as keys), e.g. a JSON object, the name shall be unique. The occurrence of the same name (or key) twice within such a structure shall be an error and the message shall be rejected.

深度解析： RFC 8259（JSON规范）虽然建议JSON对象的键名应该是唯一的，但并未强制。这就导致了不同JSON解析器的行为不一致：有些会取第一个值，有些会取最后一个值，有些会报错。攻击者可以利用这种模糊性，构造一个包含重复键的恶意JSON，来绕过安全检查。

老李的审查与小王的设计： 老李画出了一个攻击示例： 假设一个简化的计费系统，有一个字段isInternalUser用于判断是否是内部测试用户（免计费）。

// 恶意请求
{
  "ueId": "imsi-12345",
  "isInternalUser": true,  // 第一次出现，用于绕过WAF/API网关的简单规则检查
  "dataUsage": 1024,
  ...
  "isInternalUser": false  // 第二次出现，希望后端的业务逻辑（如果取最后一个值）采纳此值
}

如果API网关的解析器取第一个值，认为这是一个内部用户请求，就放行了。而后端业务逻辑的解析器取最后一个值，认为这是一个外部用户，就进行了计费。如果反过来，就可能造成“免费午餐”的漏洞。

为了杜绝这种风险，规范强制要求：包含重复键的JSON对象必须被视为错误并拒绝。

小王立即在他的团队规范中增加了这一条，并确认他们使用的JSON解析库默认就启用了严格的重复键检查。

1.4 铁律五：SBA特定要求 - OpenAPI契约与跨域安全

第6.3节将安全要求从通用层面提升到了SBA的特定场景。

规范原文引用 (Clause 6.3): OpenAPI specifications are machine-readable JSON objects and can be used as the basis for re-configuring an NFs action … Therefore, each OpenAPI specifications shall contain all necessary information to correctly and unambiguously parse the contents of the message body.

深度解析： 这句话强调了OpenAPI文件本身就是一个安全工具。一个定义严格、无歧义的OpenAPI契约，是实现自动化安全策略的基础。API网关或SCP可以加载所有NF的OpenAPI文件，并基于这些“法律文书”，自动生成一套严格的校验规则，对流经它的所有HTTP流量进行实时校验。任何不符合契约的请求（无论是URI路径、参数、还是消息体结构）都会在第一时间被拦截。这构成了SBA的“边界防御体系”。

规范原文引用 (Clause 6.3): 3GPP TS 33.501 documents which type of information shall be confidentiality protected on the N32 interface. … the mechanism specified in clause 5.2.3.3 of 3GPP TS 29.573 shall clearly identify the type of information carried in each IE and which information types shall be confidentiality protected.

深度解析： 这是SBA中一个非常高级且重要的安全概念，主要针对**跨运营商（Inter-PLMN）**的通信。

  • N32接口：是两个不同运营商核心网之间通信的接口，其流量必须经过一个名为**SEPP（安全边缘保护代理）**的网关。
  • SEPP的职责：SEPP需要对出入境的API流量进行安全检查和处理，其中最重要的一项就是保护敏感信息，如用户的永久身份标识SUPI。根据运营商之间的协议，SEPP可能需要对SUPI进行加密，或者将其替换为一个假名（Pseudonym）。
  • 面临的挑战：SEPP是一个通用的网关，它如何知道在一个千差万别的JSON对象中，哪个字段（可能是ueId，也可能是subscriberId，或者是imsi）包含了需要被保护的SUPI呢？
  • 解决方案 (TS 29.573)：在OpenAPI定义中，为这些敏感字段增加一个特殊的元数据标签，明确指出这个字段所承载的“信息类型”。例如（这是一个简化的示意）： 
    ueId:
  type: string
  pattern: '...'
  x-3gpp-info-type: SUPI # 一个自定义的扩展标签
    SEPP在加载了NIAF的OpenAPI文件后，就知道所有x-3gpp-info-type: SUPI的字段都需要按预设策略进行保护。

老李的审查与小王的设计： 老李问小王：“如果你的Nniaf_Analytics服务未来需要被漫游伙伴的OAM系统调用，你如何确保UE的SUPI在跨越N32接口时是受保护的？” 小王恍然大悟，他意识到他的设计中缺少了这一环。他立即查阅了TS 29.573，学习了如何在OpenAPI中为敏感信息打上标准标签，并更新了他的nniaf-analytics.yaml文件，为所有包含SUPI、GPSI等敏感信息的字段都添加了相应的信息类型标识。

总结：安全，API设计的底色

经过老李一番严格的“拷问”，小王对API设计的理解又上了一个台阶。他深刻地认识到，安全不是API设计完成后附加的“补丁”，而是必须从第一行设计稿开始就贯穿始终的“底色”。

第6章为所有5G API设计师提供了一份简洁而强大的安全设计清单：

安全要求核心思想关键措施
严格输入校验零信任输入在OpenAPI中明确定义类型、格式、模式、范围、长度。
资源限制防御DoS攻击限制消息体大小（16MB）、叶子IE数量（2M）、嵌套深度（32）。
键名唯一消除解析歧义强制要求JSON对象的键名唯一，拒绝含重复键的请求。
OpenAPI即安全契约自动化边界防御编写无歧义的OpenAPI文件，供API网关/SCP进行自动化流量校验。
敏感信息标识保障跨域机密性为SUPI等敏感字段添加标准元数据标签，以便SEPP等网关实施保护策略。

小王拿着老李签字通过的设计文档，信心满满地走向了开发团队。他知道，他即将构建的Nniaf_Analytics服务，不仅功能先进，而且身披“金钟罩”，足以抵御来自内外部的各种已知威胁，能够成为5G核心网中一个值得信赖的、坚如磐石的节点。

FAQ

Q1：这些物理限制（16MB, 32层嵌套）在网络中是如何被强制执行的？ A1：通常是通过分层防御来执行的。第一层是在网络流量的入口处，即API网关或SCP（服务通信代理）。这些网关作为所有API请求的必经之路，会配置全局的或API级别的策略，对所有流经它的请求进行检查，超限的请求会被直接拒绝。第二层是在NF自身，作为最后的防线，NF的应用服务器（如Nginx）和内置的JSON解析库也应该配置相应的限制，实现纵深防御。

Q2：对于“叶子IE”的计算，一个包含100个字符串的数组，是算1个叶子还是100个叶子？ A2：根据规范的定义，“If a leaf IE is an array of a simple data type, then the whole array shall count as one leaf.”，即一个简单数据类型（如string, integer）的数组，无论包含多少个元素，都只算作1个叶子IE。这个规定是为了简化计算。但是，如果是一个对象数组，[{"a":1}, {"b":2}]，这个数组本身是“树枝”，它里面的每个对象又包含叶子，所以这个例子总共算2个叶子IE（a和b）。

Q3：在实际编码中，我应该如何确保“键名唯一”？ A3：幸运的是，绝大多数现代、高质量的JSON解析库，都提供了“严格模式”或默认就禁止重复键。例如，Java的Jackson库、Python的json库（在使用object_pairs_hook时）都可以配置为在遇到重复键时抛出异常。作为开发者，你需要确保你所使用的库开启了这一检查功能，而不是静默地覆盖或忽略重复键。

Q4：TS 29.573中定义的敏感信息标签，具体是什么样的？ A4：TS 29.573（Common Data Types for Service Based Interfaces）中定义了一系列通用数据类型。对于需要特殊保护的敏感信息，它不仅定义了数据类型（如Supi），还在其OpenAPI描述中，通过description字段或使用自定义扩展（vendor extensions, 如 x-3gpp-前缀的字段）来明确其信息类型。这使得SEPP等中间节点可以通过解析这些标准化的OpenAPI文件，自动识别出需要保护的数据，而无需硬编码每个API的私有字段名。

Q5：遵循了第6章的所有要求，是否就意味着我的NF是绝对安全的？ A5：不是。第6章规定的是API设计层面的安全要求，它能极大地提升API接口的健壮性，防御大量针对接口本身的攻击。但一个完整的NF安全，是一个系统工程，还包括：

  • 应用层安全：安全的编码实践（如防止业务逻辑漏洞）、依赖库的安全管理等。
  • 基础设施安全：操作系统加固、容器安全、网络隔离等。
  • 认证与授权：严格的NF间认证和基于OAuth2.0的授权。
  • 传输层安全：强制使用TLS进行通信加密。 这些更广泛的安全要求，由3GPP SA3的其他规范（如TS 33.501）进行定义。第6章只是整个安全体系中，面向API设计师的关键一环。

关系图谱