HTTP 客户端加密 API 参考

crypto 对象提供对 HTTP 客户端加密 API 的访问权限，可让您使用加密哈希函数、RSA 和 HMAC 来生成 HTTP 签名。然后，您可以在请求前脚本中将这些签名用作变量，以对 HTTP 请求进行签名。

crypto 接受的方法可以是哈希函数（sha1、 sha256、 sha512、 md5 ）之一、 HMAC 或 RSA。

哈希方法

方法	参数	描述
`updateWithText`	`textInput` （字符串） `encoding` （字符串）： `textInput` 的编码方式。默认为 `UTF8`。	更新字符串以转换为哈希值。
`updateWithHex`	`hexInput` （字符串）	更新十六进制字符串以转换为哈希值。
`updateWithBase64`	`base64Input` （字符串） `urlSafe` （布尔值）：如果字符串使用 Base64 的 URL 安全变体编码，请输入 `true`。	更新 Base64 字符串以转换为哈希值。
`digest().toHex()`	—	生成哈希值并将其转换为十六进制格式。
`digest().toBase64()`	`urlSafe` （布尔值）：如果要使用 Base64 的 URL 安全变体，请输入 `true`	生成哈希值并将其转换为 Base64 格式。

HMAC 方法

crypto.hmac 对象使您能够使用 HMAC 对 HTTP 请求进行签名。它可以访问所有哈希方法以生成哈希值，同时也有方法获取令牌的密钥部分。

方法	参数	描述
`withTextSecret`	`textSecret` （字符串） `encoding` （字符串）： `textSecret` 的编码方式。默认为 `UTF8`。	设置用于 HMAC 的密钥。
`withHexSecret`	`hexSecret` （字符串）	设置十六进制格式的密钥。
`withBase64Secret`	`base64Input` （字符串） `urlSafe` （布尔值）：如果字符串使用 Base64 的 URL 安全变体编码，请输入 `true`。	设置 Base64 格式的密钥。

方法

参数

描述

withTextSecret

textSecret （字符串）

encoding （字符串）： textSecret 的编码方式。默认为 UTF8。

设置用于 HMAC 的密钥。

withHexSecret

hexSecret （字符串）

设置十六进制格式的密钥。

withBase64Secret

base64Input （字符串）

urlSafe （布尔值）：如果字符串使用 Base64 的 URL 安全变体编码，请输入 true。

设置 Base64 格式的密钥。

示例：

            < {%
                const signature = crypto.hmac.sha256()
                    .withTextSecret(request.environment.get("secret")) // get variable from http-client.private.env.json
                    .updateWithText(request.body.tryGetSubstituted())
                    .digest().toHex();
                request.variables.set("signature", signature)

                const hash = crypto.sha256()
                    .updateWithText(request.body.tryGetSubstituted())
                    .digest().toHex();
                request.variables.set("hash", hash)
            %}
            POST https://httpbin.org/post
            X-My-Signature: {{signature}}
            X-My-Hash: {{hash}}
            Content-Type: application/json

            {
            "prop": "value"
            }
        
  

RSA 方法

crypto.subtle 对象使您能够在请求前脚本中使用 RSA 加密。 HTTP 客户端支持 Web Crypto API ，该 API 提供标准加密功能，例如密钥生成、加密、解密、数字签名、签名验证等。

方法	参数	描述
`加密`	`算法` （对象）：指定加密算法及其参数。具体对象结构取决于所使用的算法。 `密钥` （对象）：指定包含用于加密的密钥的 `CryptoKey`。 `数据` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥对提供的数据进行加密。
`解密`	`算法` （对象）：指定解密算法及其参数。具体对象结构取决于所使用的算法。 `密钥` （对象）：指定包含用于解密的密钥的 `CryptoKey`。 `数据` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥对加密数据进行解密。
`签名`	`算法` （对象）：指定用于生成数字签名的算法。具体对象结构取决于所使用的算法。 `密钥` （对象）：指定包含用于签名的密钥的 `CryptoKey`。如果 `算法` 表示公钥加密系统，则该密钥为私钥。 `数据` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥生成数字签名。
`验证`	`算法` （对象）：指定用于验证签名的算法。具体对象结构取决于所使用的算法。 `密钥` （对象）：指定包含用于验证签名的密钥的 `CryptoKey`。对称算法使用密钥，非对称算法使用公钥。 `签名` （`ArrayBuffer`） `数据` （`ArrayBuffer`）	使用指定算法和密钥验证数字签名。
`摘要`	`算法` （object 或 string）：指定要使用的算法或哈希函数。 `数据` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的哈希函数（例如 SHA-256）生成固定大小的数据摘要。
`生成密钥`	`算法` （object）：指定定义要生成的密钥类型的算法。 `可导出` （boolean）：输入 `true` 以允许使用 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定与密钥可能的操作列表。	生成新密钥（用于对称算法）或密钥对（用于公钥算法）。
`派生密钥`	`算法` （object）：指定派生算法及其参数。确切的对象结构取决于所使用的算法。 `baseKey` （object）：指定要用作派生算法输入的 `CryptoKey`。 `derivedKeyAlgorithm` （object）：指定用于从派生数据中创建密钥的算法。 `可导出` （boolean）：输入 `true` 以允许使用 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定与密钥可能的操作列表。	从基础密钥派生密钥。
`派生位`	`算法` （object）：指定派生算法及其参数。确切的对象结构取决于所使用的算法。 `baseKey` （object）：指定用作派生算法输入的 `CryptoKey`。 `length` （number）：指定要派生的比特数。	从基础密钥派生出比特数组。
`导入密钥`	`format` （string）：指定要导入密钥的数据格式。可能的取值： `pkcs8`、 `spki`。 `keyData` （`ArrayBuffer`、 `TypedArray`、 `DataView` 或 `JSONWebKey`） `算法` （object）：指定导入密钥类型的算法并提供特定算法的参数。 `可导出` （boolean）：输入 `true` 以允许使用 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定与密钥可能的操作列表。	以外部可移植格式导入密钥并返回一个 `CryptoKey` 对象。
`导出密钥`	`format` （string）：指定用于导出密钥的数据格式。可能的取值： `pkcs8`、 `spki`。 `密钥` （object）：指定要导出的 `CryptoKey`。	导出一个 `CryptoKey` 并返回以外部可移植格式表示的密钥。
`封装密钥`	`format` （string）：指定在加密之前导出密钥时使用的数据格式。可能的取值： `pkcs8`、 `spki`。 `密钥` （object）：指定要包裹的 `CryptoKey`。 `wrappingKey` （object）：指定用于加密已导出密钥的 `CryptoKey`。 `wrapAlgo` （object）：指定用于加密导出密钥的算法。确切的对象结构取决于所使用的算法。	以外部可移植格式导出密钥并进行加密。
`解封密钥`	`format` （string）：指定要解包密钥的数据格式。可能的取值： `pkcs8`、 `spki`。 `wrappedKey` （`ArrayBuffer`） `unwrappingKey` （object）：指定用于解密包裹密钥的 `CryptoKey`。 `unwrapAlgo` （object）：指定用于解密包裹密钥的算法。确切的对象结构取决于所使用的算法。 `unwrapedKeyAlgo` （object）：指定解包密钥类型的算法并提供特定算法的参数。 `可导出` （boolean）：输入 `true` 以允许使用 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定与密钥可能的操作列表。	导入并解密已包裹的密钥，返回一个 `CryptoKey` 对象。

示例：

             < {%
                 const keyPair = crypto.subtle.generateKey({
                             name: "RSA-PSS",
                             modulusLength: 2048,
                             publicExponent: new Uint8Array([1, 0, 1]),
                             hash: "SHA-256"
                         },
                         true,
                         ["sign", "verify"])
                 const text = "Hello, HTTP Client Pre Script!!!";
                 const data = string2byteArray(text);
                 const signature = crypto.subtle.sign(
                         {
                             name: "RSA-PSS",
                         },
                         keyPair.privateKey,
                         data
                 );
                 const verified = crypto.subtle.verify(
                         {
                             name: "RSA-PSS",
                         },
                         keyPair.publicKey,
                         signature,
                         data);

                 client.log(`${text}, verified: ${verified}`);
             %}

             GET https://example.com/api/path
        
  

示例：生成 JWT

以下是如何创建一个 JSON Web Token (JWT) 的示例，该令牌由三个部分组成：base64url 编码的头部、base64url 编码的负载（声明）以及使用 SHA-256 算法生成的加密签名。随后，此令牌将被保存为一个 jwt_token 请求前变量，并可用于验证请求身份。

            < {%
                const CLIENT_ID = request.environment.get("client_id"); // get variable from http-client.private.env.json
                const SECRET = request.environment.get("secret"); // get variable from http-client.private.env.json

                function base64UrlEncode(input) {
                    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
                    let binary = "";
                    for (let i = 0; i < input.length; i++) {
                        binary += input.charCodeAt(i).toString(2).padStart(8, "0");
                    }
                    let base64 = "";
                    for (let i = 0; i < binary.length; i += 6) {
                        const chunk = binary.substring(i, i + 6);
                        const index = parseInt(chunk.padEnd(6, "0"), 2);
                        base64 += chars[index];
                    }
                    return base64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
                }

                const header = {
                    alg: "HS256",
                    typ: "JWT"
                };
                const payload = {
                    iat: Math.floor(Date.now() / 1000),
                    client_id: CLIENT_ID,
                    iss: CLIENT_ID,
                    user_id: "dev-user",
                    user_representation: "dev user"
                };
                const encodedHeader = base64UrlEncode(JSON.stringify(header));
                const encodedPayload = base64UrlEncode(JSON.stringify(payload));
                const unsignedToken = `${encodedHeader}.${encodedPayload}`;

                const signature = crypto.hmac.sha256()
                    .withTextSecret(SECRET)
                    .updateWithText(unsignedToken)
                    .digest().toBase64(true);

                const token = `${unsignedToken}.${signature}`;
                request.variables.set("jwt_token", token);
            %}

            GET https://example.com/api/path
            Authorization: Bearer {{jwt_token}}
        
  

最后修改日期： 2025年 9月 26日