# 头增强策略设计

## 预定义头增强插入清单规则

- header_enrichment_rule_name（String）：头增强规则唯一标识，作为 PFCP Active Header Enrichemt 的匹配字段。
- basic_extensions（Array of String）：基础扩展头清单，指定需要进行插入的增强头 keys。枚举：x-up-calling-line-id（手机号）、x-up-bear-type（RAT）、x-forwarded-for（UE IP）、IMSI、IMEI、ULI（User Location Information）、APN/DNN、UPFIP。
- custom_extensions（Map of String）：自定义扩展头清单，至少 4 对，指定需要进行插入的增强头 key/value pairs。

JSON Example:

```json
{
    "header_enrichment_rules":[
        {
            "rule_name":"0405ddf1-d9d3-4332-a56c-2b28b69c5ba2",
            "basic_extensions":[
                "x-up-calling-line-id",
                "x-up-bear-type",
                "x-forwarded-for",
                "SUPI",
                "PEI",
                "GPSI",
                "ULI",
                "DNN",
                "UPF-IP",
                "RAT"
            ],
            "custom_extensions":{
                "name":"fanguiju",
                "location":"beijing"
            }
        },
        {
            "rule_name":"6404c847-3ea7-4953-850c-726b9a44282e",
            "others":"others.."
        }
    ]
}
```



XML Example:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <header_enrichment_rules>
    <rule_name>0405ddf1-d9d3-4332-a56c-2b28b69c5ba2</rule_name>
    <basic_extensions>x-up-calling-line-id</basic_extensions>
    <basic_extensions>x-up-bear-type</basic_extensions>
    <basic_extensions>x-forwarded-for</basic_extensions>
    <basic_extensions>SUPI</basic_extensions>
    <basic_extensions>PEI</basic_extensions>
    <basic_extensions>GPSI</basic_extensions>
    <basic_extensions>ULI</basic_extensions>
    <basic_extensions>DNN</basic_extensions>
    <basic_extensions>UPF-IP</basic_extensions>
    <basic_extensions>RAT</basic_extensions>
    <custom_extensions>
      <name>fanguiju</name>
      <location>beijing</location>
    </custom_extensions>
  </header_enrichment_rules>
  <header_enrichment_rules>
    <rule_name>6404c847-3ea7-4953-850c-726b9a44282e</rule_name>
    <others>others..</others>
  </header_enrichment_rules>
</root>
```



## HTTP 头增强插入配置

- url_white_list（ Map of String)：指定白名单 URL 列表，对目的为白名单 URL 的 HTTP 做进行头增强，以及增强字段。
- ue_id_white_list（Array of String）：指定 UE 白名单，目前仅支持 IMSI 类型。
- custom_header_enrichment_list（ Map of String）：全局变量，自定义头增强字段，适配用例 11.9.1.1。

*为满足方便测试，本节默认 URL 和 HOST 匹配*

JSON Example:
```json
{
    "http_header_enrichment_config": {
        "url_white_list": {
            "http://www.99cloud.net/": {
                "header_enrichment_fields": [
                    "IMSI",
                    "x-up-bear-type",
                    "DNN"
                ]
            },
            "http://www.99.com/": {
                "header_enrichment_fields": [
                    "x-forwarded-for"
                ]
            }
        },
        "ue_id_white_list": [
            "imsi-466920100001101",
            "imsi-466920100001102",
            "imsi-8618867101077"
        ],
        "custom_header_enrichment_list": {
            "user1": "1",
            "user2": "abc"
        }
    }
}
```

XMl Example:
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<http_header_enrichment_config>
    <url_white_list>
        <url_header_enrichment url="http://www.99cloud.net/">
            <header_enrichment_fields>IMSI</header_enrichment_fields>
            <header_enrichment_fields>x-up-bear-type</header_enrichment_fields>
            <header_enrichment_fields>DNN</header_enrichment_fields>
        </url_header_enrichment>
        <url_header_enrichment url="http://www.99.com/">
            <header_enrichment_fields>x-forwarded-for</header_enrichment_fields>
        </url_header_enrichment>
    </url_white_list>
    <ue_id_white_list>imsi-466920100001101</ue_id_white_list>
    <ue_id_white_list>imsi-466920100001102</ue_id_white_list>
    <ue_id_white_list>imsi-8618867101077</ue_id_white_list>
    <custom_header_enrichment_list>
        <user1>1</user1>
        <user2>abc</user2>
    </custom_header_enrichment_list>
</http_header_enrichment_config>
```



## HTTPS 头增强插入配置

- extension_type（String）：指定 TLS extension 中的 extension_type。
- encryption_algorithm_and_key（Map of String）：指定 sub extension 是否加密、以及采用哪种加密算法、加密随机数。
- identify_dst_ip_white_list_only（Boolean）：指定是否仅仅识别目的 IP 地址白名单。
- dst_ip_white_list（Map of String）：指定目的 IP 地址白名单，支持精确 IP 地址、以及 CIDR，以及针对目的 IP 的 HTTPS 的头增强和加密信息。
- open_sni_cheat_proof（Boolean）：指定是否开启 SNI 域名防欺诈。若开启，则需要对 SNI 域名及其对应的业务平台目的 IP 地址进行匹配校验，若不匹配则不插入增强头， 适用于指定 ip + 域名 为白名单的用例。反之，则仅关心 SNI 白名单，适用于指定 域名 为白名单的用例。
- sni_white_list（Map of String）：指定 SNI 域名白名单，以及其对应的业务（托管）平台的 IP 地址，以及匹配后的头增强和加密字段。

JSON Example:
```json
{
    "https_header_enrichment_config": {
        "extension_type": 17516,
        "encryption_algorithm_and_key": {
            "RC4": "justfortest11"
    	},
        "identify_dst_ip_white_list_only": false,
        "dst_ip_white_list": {
            "192.168.6.0/24": {
                "header_enrichment_fields": [
                    "IMSI",
                    "x-up-bear-type"
                ],
                "encrypted_fields": [
                    "IMSI"
                ]
            }
        },
        "open_sni_cheat_proof": true,
        "sni_white_list": {
            "www.baidu.com": {
                "ipv4": "192.168.0.2",
                "header_enrichment_fields": [
                    "IMSI",
                    "x-up-bear-type"
                ],
                "encrypted_fields": [
                    "IMSI"
                ]
            },
            "www.99cloud.net": {
                "ipv4": "192.168.0.3",
                "header_enrichment_fields": [
                    "IMSI",
                    "x-up-bear-type"
                ],
                "encrypted_fields": [
                    "IMSI"
                ]
            }
        }
    }
}
```

XML Example:
```xml
<?xml version="1.0" encoding="UTF-8" ?>
    <https_header_enrichment_config>
        <extension_type>17516</extension_type>
        <encryption_algorithm_and_key>
            <RC4>justfortest11</RC4>
        </encryption_algorithm_and_key>
        <identify_dst_IP_white_list_only>false</identify_dst_IP_white_list_only>
        <dst_ip_white_list>
            <dst_ip_white dst_ip="192.168.6.0/24">
                <header_enrichment_fields>IMSI</header_enrichment_fields>
                <header_enrichment_fields>x-up-bear-type</header_enrichment_fields>
                <encrypted_fields>IMSI</encrypted_fields>
            </dst_ip_white>
        </dst_ip_white_list>
        <open_sni_cheat_proof>true</open_sni_cheat_proof>
        <sni_white_list>
            <www.baidu.com>
                <ip>192.168.0.2</ip>
                <header_enrichment_fields>IMSI</header_enrichment_fields>
                <header_enrichment_fields>x-up-bear-type</header_enrichment_fields>
                <encrypted_fields>IMSI</encrypted_fields>
            </www.baidu.com>
            <www.99cloud.net>
                <ip>192.168.0.3</ip>
                <header_enrichment_fields>IMSI</header_enrichment_fields>
                <header_enrichment_fields>x-up-bear-type</header_enrichment_fields>
                <encrypted_fields>IMSI</encrypted_fields>
            </www.99cloud.net>
        </sni_white_list>
    </https_header_enrichment_config>
```



## 程序逻辑 UML 图

![http_header_enrichment_UML.png](../../../_static/header_enrichment_UML.png)

```bash
@startuml
autonumber
entity gNB
entity SMF
entity UPF

== UPF VPP 初始化启动阶段 ==

UPF -> UPF: 加载预定义头增强插入清单规则
UPF -> UPF: 加载全局 HTTP 头增强插入配置
UPF -> UPF: 加载全局 HTTPS 头增强插入配置

== PDN Session 建立阶段 ==
SMF -> UPF: 建立 N4 Session 请求
UPF -> SMF: 建立 N4 Session 响应
gNB -> UPF: 建立 N3 GTP-U 隧道
UPF -> gNB: 建立 N3 GTP-U 隧道

== HTTP 业务访问阶段（UE 通过 URL 访问互联网 HTTP 业务） ==

"ip4-udp-lookup" -> "ip4-udp-lookup": 识别 GTP-U 报文
"ip4-udp-lookup" -> "gtpu4-input": 传递 GTP-U 报文


box "UPF plugin graph" #LightBlue
participant "gtpu4-input"
participant "upf-ip4-input"
participant "upf-pdr-detect"
participant "upf-ip4-process"
participant "upf4-encap"
participant "ip4-lookup"
end box

"gtpu4-input" -> "gtpu4-input": 识别 PDU 业务类型报文
"gtpu4-input" -> "upf-ip4-input": 传递 IPv4 PDU 报文

"upf-ip4-input" -> "upf-ip4-input": DPI 解析入口
"upf-ip4-input" -> "upf-pdr-detect": 传递 IPv4 PDU 报文

alt 场景1: 动态规则，插入清单由 HE IE 决定
SMF -> UPF: 下发 HE IE
note right: 包含了待插入的增强头 key/value pairs

"upf-pdr-detect" -> "upf-pdr-detect": PDR 信元解析，识别出内含 HE IE
"upf-pdr-detect" -> "upf-ip4-process": 传递匹配 PDR 的报文

"upf-ip4-process" -> "upf-ip4-process": FAR 信元解析
note left: 根据 HE IE 内含的增强头 key/value pairs 执行头增强插入。
"upf-ip4-process" -> "upf4-encap": 传递匹配 PDR 的报文


else 场景2: 静态规则，插入清单由 Predefined 决定

SMF -> UPF: 下发 Active Predefined Rule Name
note right: 指定了待激活的预定义头增强插入清单规则

"upf-pdr-detect" -> "upf-pdr-detect": PDR 信元解析，识别出 Active Predefined Rule Name
"upf-pdr-detect" -> "upf-ip4-process": 传递匹配 PDR 的报文

"upf-ip4-process" -> "upf-ip4-process": FAR 信元解析
note left: 根据预定义头增强插入清单规则的增强头 key 或 key/value pairs 执行头增强插入
"upf-ip4-process" -> "upf4-encap": 传递匹配 PDR 的报文

end

"upf4-encap" -> "upf4-encap": 根据 FAR 对报文进行重封装
"upf4-encap" -> "ip4-lookup": 重封装报文头部，决定下一跳
@enduml
```