# 双向 TLS 的助手方法
<a name="mtls-helper-methods"></a>

CloudFront 在 `cf.mtls` 命名空间中为查看器请求函数提供特定于 mTLS 的助手函数。这些函数在将请求转发到源之前，重命名、重新格式化或组合客户端证书标头。

```
import cf from "cloudfront";
```

## `cf.mtls.renameClientCertHeaders`
<a name="mtls-rename-client-cert-headers"></a>

将证书元数据标头重命名为自定义标头名称。

```
cf.mtls.renameClientCertHeaders({
    "CloudFront-Viewer-Cert-Pem": "X-Client-Cert",
    "CloudFront-Viewer-Cert-Serial-Number": "X-Client-Cert-Serial",
    "CloudFront-Viewer-Cert-Issuer": "X-Client-Cert-Issuer",
});
```

允许的源标头：
+ `CloudFront-Viewer-Cert-Pem`
+ `CloudFront-Viewer-Cert-Serial-Number`
+ `CloudFront-Viewer-Cert-Issuer`
+ `CloudFront-Viewer-Cert-Subject`
+ `CloudFront-Viewer-Cert-Validity`
+ `CloudFront-Viewer-Cert-Present`
+ `CloudFront-Viewer-Cert-Sha256`
+ `Client-Cert`
+ `Client-Cert-Chain`

## `cf.mtls.renamePemHeaders`
<a name="mtls-rename-pem-headers"></a>

重命名 PEM 证书标头，也可以选择重新格式化证书编码。

```
cf.mtls.renamePemHeaders({
    "Client-Cert": {
        "newHeaderName": "X-Leaf-Cert",
        "pemCertFormatInfo": {
            "certHeader": "-----CUSTOM HEADER-----",
            "certFooter": "-----CUSTOM FOOTER-----",
            "certEndMarker": "",
            "keepNewlinesInCertData": true
        }
    },
    "Client-Cert-Chain": {
        "newHeaderName": "X-Intermediate-Certs",
        "pemCertFormatInfo": {
            "certHeader": "-----CUSTOM HEADER-----",
            "certFooter": "-----CUSTOM FOOTER-----",
            "certEndMarker": "",
            "keepNewlinesInCertData": true
        }
    }
});
```

允许的源标头：
+ 在直通模式下：`Client-Cert`、`Client-Cert-Chain`
+ 在必需/可选模式下：`Cloudfront-Viewer-Cert-PEM`

**`pemCertFormatInfo` 字段：**

对于：`Cloudfront-Viewer-Cert-PEM`
+ `certHeader` 替换 `-----BEGIN CERTIFICATE-----`。
+ `certFooter` 替换 `-----END CERTIFICATE-----`。
+ `certEndMarker` 在 certFooter 之后设置一个自定义字符串。
+ `keepNewlinesInCertData`（默认：`true`）当为 true 时，保留 base64 数据中的换行符。

对于 `Client-Cert` 和 `Client-Cert-Chain`：
+ `certHeader` 替换 `:`。
+ `certFooter` 替换 `:`。
+ `certEndMarker` 在 certFooter 之后设置一个自定义字符串。
+ `keepNewlinesInCertData`（默认：`false`）当为 true 时，保留 base64 数据中的换行符。

## `cf.mtls.combinePemHeaders`
<a name="mtls-combine-pem-headers"></a>

将 `Client-Cert` 和 `Client-Cert-Chain` 组合成包含完整证书链的单个标头。

```
cf.mtls.combinePemHeaders({
    "newHeaderName": "X-Full-Chain",
    "pemCertFormatInfo": {
        "certHeader": "-----BEGIN CERTIFICATE-----",
        "certFooter": "-----END CERTIFICATE-----",
        "certEndMarker": "\n",
        "keepNewlinesInCertData": false
    }
});
```

`certEndMarker` 设置证书之间的分隔符。

**注意**  
这些助手函数可以在所有 mTLS 模式下使用（必需、可选和直通）。但是，`cf.mtls.combinePemHeaders` 仅在直通模式下有效，在必需模式和可选模式下，`Client-Cert` 和 `Client-Cert-Chain` 标头不存在，因此该函数是无操作的。
如果 `cf.mtls.*` 方法和具有 `customHeaders` 的 `cf.updateRequestOrigin()` 指向相同的标头名称，则 CloudFront 会返回 502 错误。
在直通模式下，CloudFront 会丢弃所有传入的 `Client-Cert` 或 `Client-Cert-Chain` 标头，并从实际客户端证书中重新添加它们。
CloudFront 不会在任何边缘函数中提供完整的原始 PEM 证书内容。