HTTP 客户端加密 API 参考

crypto 对象提供对 HTTP Client Crypto 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 请求。它可以访问所有 hash methods 来生成哈希，同时还具有获取令牌密钥部分的方法。

方法	参数	说明
`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 Client 支持 Web Crypto API ，提供诸如密钥生成、加密、解密、数字签名、签名验证等标准加密功能。

方法	参数	说明
`encrypt`	`algorithm` （对象）：指定加密算法及其参数。具体对象结构取决于所使用的算法。 `key` （对象）：指定包含加密密钥的 `CryptoKey`。 `data` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥加密提供的数据。
`decrypt`	`algorithm` （对象）：指定解密算法及其参数。具体对象结构取决于所使用的算法。 `key` （对象）：指定包含解密密钥的 `CryptoKey`。 `data` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥解密加密数据。
`sign`	`algorithm` （对象）：指定用于生成数字签名的算法。具体对象结构取决于所使用的算法。 `key` （对象）：指定包含签名密钥的 `CryptoKey`。如果 `algorithm` 标识一个公钥密码系统，则密钥为私钥。 `data` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的算法和密钥生成数字签名。
`verify`	`algorithm` （对象）：指定用于验证签名的算法。具体对象结构取决于所使用的算法。 `key` （object）：指定包含用于验证签名的 `CryptoKey`。对于对称算法，请使用密钥；对于公钥算法，请使用公钥。 `signature` （`ArrayBuffer`） `data` （`ArrayBuffer`）	使用指定的算法和密钥验证数字签名。
`digest`	`algorithm` （object 或 string）：指定要使用的算法或哈希函数。 `data` （`ArrayBuffer`、 `TypedArray` 或 `DataView`）	使用指定的哈希函数（例如 SHA-256）生成固定大小的数据摘要。
`generateKey`	`algorithm` （object）：指定将定义要生成的密钥类型的算法。 `extractable` （boolean）：输入 `true` 以允许通过 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定密钥可能的操作列表。	生成一个新密钥（用于对称算法）或密钥对（用于公钥算法）。
`deriveKey`	`algorithm` （object）：指定派生算法及其参数。具体的对象结构取决于所使用的算法。 `baseKey` （object）：指定将用作派生算法输入的 `CryptoKey`。 `derivedKeyAlgorithm` （object）：指定从派生数据中生成的密钥类型的算法。 `extractable` （boolean）：输入 `true` 以允许通过 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定密钥可能的操作列表。	从基础密钥派生一个密钥。
`deriveBits`	`algorithm` （object）：指定派生算法及其参数。具体的对象结构取决于所使用的算法。 `baseKey` （object）：指定用作派生算法输入的 `CryptoKey`。 `length` （number）：指定要派生的比特数。	从基础密钥派生一组比特数组。
`importKey`	`format` （字符串）：指定要导入的密钥的数据格式。可能的值： `pkcs8`、 `spki`。 `keyData` （`ArrayBuffer`、 `TypedArray`、 `DataView` 或 `JSONWebKey`） `algorithm` （object）：指定定义导入密钥类型的算法并提供特定算法的参数。 `extractable` （boolean）：输入 `true` 以允许通过 `crypto.subtle.exportKey()` 或 `crypto.subtle.wrapKey()` 导出密钥。 `keyUsages` （字符串数组）：指定密钥可能的操作列表。	以外部可移植格式导入密钥并返回一个 `CryptoKey` 对象。
`exportKey`	`format` （字符串）：指定用于导出密钥的数据格式。可能的值： `pkcs8`、 `spki`。 `key` （object）：指定要导出的 `CryptoKey`。	导出一个 `CryptoKey` 并返回一个外部可移植格式的密钥。
`wrapKey`	`format` （字符串）：指定密钥在加密前将被导出的数据格式。可能的值： `pkcs8`、 `spki`。 `key` （object）：指定要封装的 `CryptoKey`。 `wrappingKey` （object）：指定用于加密导出密钥的 `CryptoKey`。 `wrapAlgo` （object）：指定用于加密导出密钥的算法。具体的对象结构取决于所使用的算法。具体的对象结构取决于所使用的算法。	将密钥导出为外部可移植格式并进行加密。
`unwrapKey`	`format` （字符串）：指定要解封装的密钥的数据格式。可能的值： `pkcs8`、 `spki`。 `wrappedKey` （`ArrayBuffer`） `unwrappingKey` （object）：指定用于解密封装密钥的 `CryptoKey`。 `unwrapAlgo` （object）：指定用于解密封装密钥的算法。具体的对象结构取决于所使用的算法。具体的对象结构取决于所使用的算法。 `unwrapedKeyAlgo` （object）：指定定义要解封装密钥的类型的算法并提供特定算法的参数。 `extractable` （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日