HTTP 客户端 Crypto API 参考

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

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

哈希方法

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

HMAC 方法

crypto.hmac 对象使您能够使用 HMAC 对 HTTP 请求进行签名。它可以访问所有 hash 方法来生成哈希，并且还有方法可以获取令牌的秘密部分。

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

方法

形参

描述

withTextSecret

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 ，其提供标准加密功能，例如密钥生成、加密、解密、数字签名、签名验证等。

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