# HTTP クライアント暗号 API リファレンス

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/ja-jp/help/clion/llms.txt).

`crypto`  オブジェクトは、HTTP 署名生成のための暗号学的ハッシュ関数、HMAC、RSA、ECDSA をサポートする HTTP クライアント暗号化 API へのアクセスを提供します。 この機能は、便利なメソッド（  `crypto.hmac`  、ハッシュアルゴリズム）と  `crypto.subtle`  インターフェースの実装の両方を通じて利用できます。

> **Note:**
> HTTP クライアントでは、すべての  `crypto.subtle`  操作は同期的に実行され、結果が直接返されます。

HTTP クライアントは、  `jwt.*`  関数を使用して事前リクエストスクリプトで直接 JSON Web トークンを生成、インスペクション、検証するための JWT 操作もサポートしています。

## ハッシュ方法

|  メソッド  |  パラメーター  |  説明  |
| --- | --- | --- |
|   `updateWithText`   |      `textInput`  (文字列)        `encoding`  (文字列):  `textInput`  のエンコーディング。 デフォルトは  `UTF8`  です。     |  ハッシュに変換する文字列を更新します。  |
|   `updateWithHex`   |      `hexInput`  (文字列)     |  ハッシュに変換される 16 進文字列を更新します。  |
|   `updateWithBase64`   |      `base64Input`  (文字列)        `urlSafe`  (ブール値): 文字列が Base64 の URL セーフバリアントを使用してエンコードされている場合は、  `true`  を入力します。     |  ハッシュに変換される Base64 文字列を更新します。  |
|   `digest().toHex()`   |  —  |  ハッシュを生成し、16 進数形式に変換します。  |
|   `digest().toBase64()`   |   `urlSafe`  (boolean): Base64 の URL セーフバリアントを使用する場合は、  `true`  と入力します。  |  ハッシュを生成し、Base64 形式に変換します。  |

## HMAC メソッド。

`crypto.hmac`  オブジェクトを使用すると、HMAC を使用して HTTP 要求に署名できます。 ハッシュを生成するすべての [ハッシュメソッド](#hash_methods)にアクセスできますが、トークンの秘密部分を取得するメソッドもあります。

|  メソッド  |  パラメーター  |  説明  |
| --- | --- | --- |
|   `withTextSecret`   |      `textSecret`  (文字列)        `encoding`  (文字列):  `textSecret`  のエンコーディング。 デフォルトは  `UTF8`  です。     |  HMAC で使用する秘密鍵を配置します。  |
|   `withHexSecret`   |      `hexSecret`  (文字列)     |  秘密鍵を 16 進数形式にします。  |
|   `withBase64Secret`   |      `base64Input`  (文字列)        `urlSafe`  (ブール値): 文字列が Base64 の URL セーフバリアントを使用してエンコードされている場合は、  `true`  を入力します。     |  秘密鍵を Base64 形式にします。  |

HTTP クライアントは、SHA-2 および SHA-3 アルゴリズムファミリによる HMAC をサポートしています。 SHA-2 アルゴリズムを使用する場合は、  `crypto.hmac.sha256()`  や  `crypto.hmac.sha512()`  などの専用メソッドを呼び出すことができます。 SHA-3 アルゴリズムの場合はフォーマットが異なり、ビット長を指定するパラメーターを持つ単一のメソッド（例:  `crypto.hmac.sha3('512')`  や  `crypto.hmac.sha3('256')`  ）を使用します。

例：

SHA-2 を使った HMAC:

```JAVASCRIPT
< {%
    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"
}
                
```

SHA-3 を使った HMAC:

```JAVASCRIPT
< {%
    const signature = crypto.hmac.sha3('512')
            .withTextSecret('Secret')
            .updateWithText('Servus!')
            .digest().toHex();
    console.log(`signature: ${signature}`)
%}
POST https://examples.http-client.intellij.net/anything
                    
```

## RSA メソッド。

`crypto.subtle`  インターフェースを使用すると、事前リクエストスクリプトで RSA 暗号化を使用できます。 HTTP クライアントは、鍵生成、暗号化、復号化、デジタル署名、署名検証などの標準的な暗号化機能を提供する [Web 暗号 API(英語)](https://w3c.github.io/webcrypto/#algorithms) をサポートしています。

|  メソッド  |  パラメーター  |  説明  |  アルゴリズム  |
| --- | --- | --- | --- |
|   `encrypt`   |      `algorithm`  (オブジェクト): 暗号化アルゴリズムとそのパラメーターを指定します。 オブジェクトの正確な構造は、使用するアルゴリズムによって異なります。        `key`  (オブジェクト): 暗号化キーを含む  `CryptoKey`  を指定します。        `data`  (  `TypedArray`  )     |  指定されたアルゴリズムとキーを使用して、提供されたデータを暗号化します。  |  RSA-OAEP  |
|   `decrypt`   |      `algorithm`  (オブジェクト): 復号アルゴリズムとそのパラメーターを指定します。 オブジェクトの正確な構造は、使用するアルゴリズムによって異なります。        `key`  (オブジェクト): 復号化キーを含む  `CryptoKey`  を指定します。        `data`  (  `TypedArray`  )     |  指定されたアルゴリズムとキーを使用して暗号化されたデータを復号化します。  |  RSA-OAEP  |
|   `sign`   |      `algorithm`  (オブジェクト): デジタル署名を生成するためのアルゴリズムを指定します。 オブジェクトの正確な構造は、使用するアルゴリズムによって異なります。        `key`  (オブジェクト): 署名用の鍵を含む  `CryptoKey`  を指定します。  `algorithm`  が公開鍵暗号システムを識別する場合、鍵は秘密鍵となります。        `data`  (  `TypedArray`  )     |  指定されたアルゴリズムとキーを使用してデジタル署名を生成します。  |  RSASSA-PKCS1-v1_5、RSA-PSS  |
|   `verify`   |      `algorithm`  (オブジェクト): 署名検証アルゴリズムを指定します。 オブジェクトの正確な構造は、使用するアルゴリズムによって異なります。        `key`  (オブジェクト): 署名を検証するための鍵を含む  `CryptoKey`  を指定します。 対称鍵アルゴリズムの場合は秘密鍵、公開鍵アルゴリズムの場合は公開鍵を使用します。        `signature`  (  `TypedArray`  )        `data`  (  `TypedArray`  )     |  指定されたアルゴリズムとキーを使用してデジタル署名を検証します。  |  RSASSA-PKCS1-v1_5、RSA-PSS  |
|   `generateKey`   |      `algorithm`  (オブジェクト): 生成するキーのタイプを定義するアルゴリズムを指定します。        `extractable`  (ブール値):  `crypto.subtle.exportKey()`  または  `crypto.subtle.wrapKey()`  を使用してキーをエクスポートできるようにするには、  `true`  を入力します。        `keyUsages`  (文字列の配列): キーで実行可能な操作のリストを指定します。     |  新しいキー (対称アルゴリズムの場合) またはキーペア (公開鍵アルゴリズムの場合) を生成します。  |  RSASSA-PKCS1-v1_5、RSA-PSS、RSA-OAEP  |
|   `importKey`   |      `format`  (文字列): インポートするキーのデータ形式を指定します。 可能な値:  `pkcs8`  、  `spki`         `keyData`  (  `TypedArray`  )        `algorithm`  (オブジェクト): インポートするキーの型を定義するアルゴリズムを指定し、アルゴリズム固有のパラメーターを提供します。        `extractable`  (ブール値):  `crypto.subtle.exportKey()`  または  `crypto.subtle.wrapKey()`  を使用してキーをエクスポートできるようにするには、  `true`  を入力します。        `keyUsages`  (文字列の配列): キーで実行可能な操作のリストを指定します。     |  外部ポータブル形式でキーをインポートし、  `CryptoKey`  オブジェクトを返します。  |  RSASSA-PKCS1-v1_5、RSA-PSS、RSA-OAEP  |
|   `exportKey`   |      `format`  (文字列): キーをエクスポートするデータ形式を指定します。 可能な値:  `pkcs8`  、  `spki`         `key`  (オブジェクト): エクスポートする  `CryptoKey`  を指定します。     |   `CryptoKey`  をエクスポートし、外部ポータブル形式でキーを返します。  |  RSASSA-PKCS1-v1_5、RSA-PSS、RSA-OAEP  |

例：

```JAVASCRIPT
< {%
    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

```

## ECDSA メソッド。

HTTP クライアントは、  `SubtleCrypto`  インターフェース（  `crypto.subtle`  ）を提供する [Web 暗号 API(英語)](https://w3c.github.io/webcrypto/#algorithms) を介して ECDSA をサポートします。 鍵を生成またはインポートし、リクエスト前のスクリプトでデータの署名と検証を行うことができます。

|  メソッド  |  パラメーター  |  説明  |
| --- | --- | --- |
|   `sign`   |      `algorithm`  : 署名アルゴリズム（例:  `{ name: "ECDSA", hash: "SHA-256" }`  ）を指定します。        `key`  (オブジェクト): プライベート  `CryptoKey`  に  `"sign"`  の使用を提供します。        `data`  : 署名するデータを  `ArrayBuffer`  または  `TypedArray`  として提供します。     |  秘密の ECDSA キーを使用して、指定されたデータにデジタル署名を作成します。  |
|   `verify`   |      `algorithm`  (オブジェクト): 署名検証アルゴリズムを指定します。 オブジェクトの正確な構造は、使用するアルゴリズムによって異なります。        `key`  (オブジェクト): パブリック  `CryptoKey`  に  `"verify"`  の使用箇所を提供します。        `signature`  (  `ArrayBuffer`  )        `data`  (  `ArrayBuffer`  )     |  指定された署名が、提供されたデータと公開 ECDSA キーに対して有効であることを確認します。  |
|   `generateKey`   |      `algorithm`  (オブジェクト): アルゴリズムと曲線を指定します (例:  `{ name: "ECDSA", namedCurve: "P-256" }`  )。        `extractable`  (ブール値):  `crypto.subtle.exportKey()`  を使用してキーをエクスポートできるようにするには、  `true`  を入力します。        `keyUsages`  (文字列の配列): キーを使用して実行可能な操作のリストを指定します (例:  `["sign", "verify"]`  )。     |  指定された曲線の新しい楕円曲線キーペアを生成します。  `{ publicKey, privateKey }`  を持つオブジェクトを返します。  |
|   `importKey`   |      `format`  (文字列): インポートするキーのデータ形式を指定します。 可能な値:  `pkcs8`  、  `spki`         `keyData`  (  `ArrayBuffer`  、  `TypedArray`  、  `DataView`  、または  `JSONWebKey`  )        `algorithm`  (オブジェクト): アルゴリズムと曲線を指定します (例:  `{ name: "ECDSA", namedCurve: "P-256" }`  )。        `extractable`  (ブール値):  `crypto.subtle.exportKey()`  を使用してキーをエクスポートできるようにするには、  `true`  を入力します。        `keyUsages`  (文字列の配列): キーを使用して実行可能な操作のリストを指定します。     |  既存の楕円曲線鍵をインポートし、  `CryptoKey`  を返します。 サポートされる形式は、鍵が公開鍵か秘密鍵かによって異なります。  |
|   `exportKey`   |      `format`  (文字列): キーをエクスポートするデータ形式を指定します。 可能な値:  `pkcs8`  、  `spki`         `key`  (オブジェクト): エクスポートする  `CryptoKey`  を指定します。     |  指定されたフォーマットで指定された ECDSA キーをエクスポートします。 PKCS8/SPKI/RAW の場合はバイナリデータ（  `ArrayBuffer`  ）、JWK の場合は JSON オブジェクトを返します。  |

例：

```JAVASCRIPT
< {%
const base64publicKey = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn8E8vCgnmyDISke4RQVt0uwhE0AFL61crfJ7gmKkLgISv+eV5zAB1GBVQ/mj/4bZO8yJnFCrNGILHN59aCEEfA=='
const base64privateKey = 'MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgXMpTO9h9dsmz9f9XfpvdUbU8PGt7ZMiN95Irv0XAgQyhRANCAASfwTy8KCebIMhKR7hFBW3S7CETQAUvrVyt8nuCYqQuAhK/55XnMAHUYFVD+aP/htk7zImcUKs0Ygsc3n1oIQR8'
const privateKey = crypto.subtle.importKey(
        'pkcs8',
        Uint8Array.from(atob(base64privateKey), c => c.codePointAt(0)),
        { name: "ECDSA", namedCurve: "P-256" },
        true,
        ["sign"]
)

const msg = "Hello from HTTP Client!"
const signature = crypto.subtle.sign(
        { name: "ECDSA", hash: "SHA-256" },
        privateKey,
        Uint8Array.from(msg, c => c.charCodeAt(0))
)

const publicKey = crypto.subtle.importKey(
        'spki',
        Uint8Array.from(atob(base64publicKey), c => c.codePointAt(0)),
        { name: "ECDSA", namedCurve: "P-256" },
        true,
        ["verify"]
)
const verificationResult = crypto.subtle.verify(
        { name: "ECDSA", hash: "SHA-256" },
        publicKey,
        signature,
        Uint8Array.from(msg, c => c.charCodeAt(0))
)
console.log(`verificationResult: ${verificationResult}`)
%}
GET https://example.com/api/path


```

## JWT 署名

HTTP クライアントの事前リクエストスクリプトは、 [JSON Web トークン (JWT)(英語)](https://datatracker.ietf.org/doc/html/rfc7519) の作成と署名をサポートします。 JWT は、base64url エンコードされたヘッダー、base64url エンコードされたペイロード（クレーム）、暗号署名の 3 つの部分で構成されます。

`jwt.*`  関数を使用すると、リクエスト内で直接トークンを生成、インスペクション、検証できます。 署名された JWT はリクエスト前の変数（例:  `jwt_token`  ）に保存し、リクエストの認証に使用できます。

JWT 署名の場合、HTTP クライアントは、次のような [ノード /jsonwebtoken(英語)](https://github.com/auth0/node-jsonwebtoken/blob/master/README.md) などの一般的に使用されるライブラリと同じアルゴリズムをサポートしています。

* HS256 /HS384 /HS512 — SHA-256/SHA-384/SHA-512 を使用した HMAC

* RS256/RS384/RS512 — SHA-256/SHA-384/SHA-512 対応 RSASSA-PKCS1-v1_5

* PS256/PS384/PS512 — SHA-256/SHA-384/SHA-512 を使用した RSA-PSS

* ES256/ES384/ES512 — SHA-256/SHA-384/SHA-512 を使用した ECDSA

|  メソッド  |  パラメーター  |  説明  |
| --- | --- | --- |
|   `jwt.sign`   |      `payload`  : 有効な JSON を表すオブジェクトリテラル、バッファ、文字列を指定します。        `key`  : HMAC の場合は秘密文字列またはバイト、RSA または ECDSA の場合は秘密鍵 (  `CryptoKey`  /PEM) を指定します。        `options`  :  `algorithm`  (HS256、RS256、PS256、ES256、ES384 など) および標準クレーム (たとえば、  `issuer`  、  `audience`  ) を使用してオブジェクトを指定します。     |  JWT を作成して署名します。  |
|   `jwt.verify`   |      `token`  : 検証する JWT 文字列を指定します。        `key` : RSA/ECDSA 用のシークレット (HMAC) または公開鍵 (  `CryptoKey`  / PEM) を指定します。        `options`  :  `algorithm`  (HS256、RS256、PS256、ES256、ES384 など) および標準クレーム (たとえば、  `issuer`  、  `audience`  ) を使用してオブジェクトを指定します。     |  JWT の署名を検証し、必要に応じてクレームを適用します。  |
|   `jwt.decode`   |      `token`  : デコードする JWT 文字列を指定します。     |  署名を検証せずに JWT をデコードします (インスペクションまたはデバッグ用)。  |

次の RSA-PSS 署名の例は次のことを示しています。

* RSA キーペアの生成

* RSA-PSS による任意のメッセージの署名と検証

* PS256 を使用した JWT の作成と検証

* 外部ツールが検証できるように公開鍵を PEM（ `spki` ）にエクスポートする

```JAVASCRIPT
            
< {%
    let algorithm = {
        name: 'RSA-PSS',
        modulusLength: 2048,                       // 2048 or 4096 bits recommended
        publicExponent: new Uint8Array([1, 0, 1]), // 65537 (standard exponent)
        hash: "SHA-256"
    };
    const pair = crypto.subtle.generateKey(algorithm,
            true,
            ['sign', 'verify']);

    let otherClaim = 'Servus, HTTP Client Pre Script!!!';

    const rsaSignature = crypto.subtle.sign({
                name: "RSA-PSS",
                saltLength: 32
            },
            pair.privateKey,
            Uint8Array.from(otherClaim, c => c.charCodeAt(0)))

    console.log(`verify ${otherClaim}: ${crypto.subtle.verify({name: "RSA-PSS", saltLength: 32}, pair.publicKey, rsaSignature, Uint8Array.from(otherClaim, c => c.charCodeAt(0)))}`);


    const rsaJwt = jwt.sign({
        other_claim: otherClaim,
    }, pair.privateKey, {
        algorithm: 'PS256'
    })


    console.log(`RSA JWT: ${rsaJwt}`)

    console.log(`RSA verification: ${jwt.verify(rsaJwt, pair.publicKey, {algorithm: 'PS256'})}`)

    let publicKey = btoa(String.fromCharCode(...new Uint8Array(crypto.subtle.exportKey("spki", pair.publicKey))));
    console.log(`public key: \n-----BEGIN PUBLIC KEY-----\n${publicKey.match(/.{1,64}/g).join('\n')}\n-----END PUBLIC KEY-----`)


%}
GET examples.http-client.intellij.net/path
    
        
```

次の例は、HS256 アルゴリズム（SHA-256 を使用した HMAC）を使用して JWT を生成、デコード、検証する方法を示しています。 トークンには  `aud`  （オーディエンス）クレームが含まれており、検証中に検証されます。

```JAVASCRIPT
            
< {%
    const signature = jwt.sign({
        other_claim: "some value",
        aud:['jetbrains']
    }, client.variables.file.get('secret'))

    console.log(`signature: ${jwt.decode(signature).payload.aud}`)


    client.variables.global.set("jwt_token", signature)
    console.log(jwt.verify(signature, client.variables.file.get('secret'), {
        audience: 'jetbrains',
        algorithm: 'HS256'
    }))
    console.log(signature)
%}

GET examples.http-client.intellij.net/path
            
        
```

