HTTPDNS:ドメイン名前解決 API

1. 概要

HTTP API を使用したドメイン名の解決には、1) 解決エンドポイントの取得、2) API を使用した解決クエリの送信、という 2 つのステップがあります。このトピックでは、2 番目のステップである解決 API の使用に焦点を当てます。

ドメイン名前解決 API は、単一およびバッチでのドメイン名解決をサポートします。また、解決パラメーターの署名と暗号化 (オプション) もサポートします。この API を使用するプロセスは次のとおりです。

1. 解決パラメーターを決定します。ドメイン名のリスト、クライアント IP アドレス（オプション）、および解決タイプ（IPv4 または IPv6）。

2. リクエストメソッドの決定: 解決リクエストにバッチ解決、署名、または暗号化を使用するかどうかを決定します。

3. パラメーターの暗号化 (オプション): 解決パラメーターの暗号文を計算します。

4. リクエストに署名します。署名アルゴリズムを使用して、署名が必要なフィールドの署名を計算します。

5. リクエストの送信: 解決パラメーター、アカウント ID、および署名を URL に追加してサーバーに送信します。

6. 応答の解析: サーバーから返された応答メッセージから解決結果を取得します。

このトピックでは、HTTP API のリクエストと応答の仕様に焦点を当てます。パラメーターの定義、暗号化と署名のルール、および応答構造について説明します。主なセクションは次のとおりです。

• API 形式: HTTP メソッド、パス、一般的な制約など、API アクセス形式について説明します。

• パラメーター：リクエストパラメーターの意味、必須かどうか、署名または暗号化に含まれるかどうかについて説明します。

• パラメーターの暗号化: リクエストパラメーターを暗号化し、enc フィールドでサーバーに送信する方法について説明します。

• リクエストの署名：署名されるパラメーターとソートルールを含む、署名計算プロセスについて説明します。

• API レスポンス: レスポンスメッセージ構造と、暗号化モードでメッセージを復号する方法について説明します。

2. API 形式

解決 API は、http または https 経由でのアクセスをサポートします。API フォーマットは次のとおりです。

• サービス URL：http(s)://{endpoint}/v2/d? + {request_parameters}

• リクエストメソッド: GET

3. パラメーター

この解決 API は、リクエストパラメーターを使用してドメイン名前解決タスクを定義し、暗号化と署名のプロセスを制御します。パラメーターを設定することで、プレーンテキストまたは暗号文、署名付きまたは署名なし、単一またはバッチのドメイン名など、さまざまな組み合わせで解決を実行できます。

3.1 パラメーターリスト

API は、プレーンテキストと暗号化された伝送モードをサポートします。m パラメーターを使用して暗号化メソッドを制御できます。次の表に、サポートされているすべてのリクエストパラメーターを示します。

3.2 リクエストパラメーターの例

• 署名付きプレーンテキストリクエスト

GET /v2/d?id=139450&dn=www.example1.com,www.example2.com&exp=1755526729&cip=192.168.1.1&q=4,6&m=0&sdns-param1=param1&s=20325751683ca72d1dfce8c279b97bc8d42c10436b3510a5dda600aeb71f4897 HTTP/1.1

• 署名付き暗号文リクエスト

GET /v2/d?id=139450&exp=1755527315&&m=2&enc=93ce1ccf1057a0418636ee0d45e2f9308623e4adbcc3bc0f99dcf948da678a3a1abac4922b860dad056fb7abb812de9d26284331853cbbf896a7d461e4d6978679bd34de617f21a20b23a27033c3cd332c0286267a1a14848bda266bd3d3d04a818c10dad3ae98df5bd2681691e5886b7bf95731b2622f8b4d684c&s=895a578136065f95f9c38433757cab6878dfd23ab2011e02a7f33a19556864f1 HTTP/1.1

4. パラメーターの暗号化（オプション）

ドメイン名前解決 API は、dn、cip、q、sdns-* などの解決パラメーターの暗号化をサポートします。これにより、HTTPS 以外の環境でもリクエストパラメーターの機密性が保護されます。解決パラメーターを暗号化する手順は次のとおりです。

4.1 暗号化する文字列を作成する

dn、cip、q、sdns-* など、暗号化するフィールドを JSON フォーマットで保存します。

• フィールドは任意の順序で指定できます。

• オプションのパラメーターは省略できます。

• キーと値の両方が文字列である必要があります。

4.2 暗号化アルゴリズムを選択する

この API は、AES-GCM-128 と AES-CBC-128 の 2 つの暗号化アルゴリズムをサポートしています。次の表に、それらの違いとシナリオを示します。

4.3 キーと IV を取得する

AES 暗号化アルゴリズムのセキュリティは、キーと初期化ベクトル (IV) に依存します。これらは次の方法で取得できます。

• secretKey:

  • コンソールの開発者向け設定から取得します。

  • 長さ: 128 ビット

  • コンソールは 32 文字の 16 進文字列を返します。使用する前に、キーを 16 進数でデコードしてバイナリキーに変換します。

  • 例: 82c0af0d0cb2d69c4f87bb25c2e23929

• IV (初期化ベクトル):

  • AES-GCM モード: 96 ビット

  • AES-CBC モード: 128 ビット

  • 暗号化のセキュリティを確保するために、リクエストごとに安全な乱数ジェネレーターを使用して新しい IV を生成します。

  • 例: 7322e81466eea91d69e7f735 (暗号化する前に値を 16 進数でデコード)。

4.4 暗号化を実行する

1. 選択した暗号化アルゴリズムを使用して JSON 文字列を暗号化します。暗号化パラメーターは次のとおりです。

   パラメーター	AES-CBC-128 (m=1)	AES-GCM-128 (m=2)
   暗号化する文字列	暗号化する文字列（UTF-8 エンコード）	暗号化する文字列（UTF-8 エンコード）
   アルゴリズム	AES-CBC-128	AES-GCM-128
   キーの長さ	128 ビット (16 バイト)	128 ビット (16 バイト)
   IV の長さ	128 ビット (16 バイト)	96 ビット (12 バイト)
   パディングモード	PKCS#7 パディング	パディング不要

2. IV と暗号文を順番に連結します。

   1. 最初の数バイトは IV です (AES-GCM モードの場合は 12 バイト、AES-CBC モードの場合は 16 バイト)。

   2. 残りは暗号文です。

3. 結合されたバイトシーケンスを 16 進エンコードします。

4.5 暗号文リクエストの例

ドメイン名 www.example1.com と www.example2.com をデュアルスタック解決で解決し、カスタムパラメーター param1=value1、クライアント IP アドレス 192.168.1.1 を使用する必要があるとします。AES-GCM-128 アルゴリズムを選択した場合、暗号化プロセスは次のようになります。

1. 暗号化する文字列を作成します。

   {
     "dn":"www.example1.com,www.example2.com",
     "q":"4,6",
     "sdns-param1":"value1",
     "cip":"192.168.1.1"
    }

2. キーと IV を取得します。

   • キー: 82c0af0d0cb2d69c4f87bb25c2e23929

   • IV: 006fe5011c9c2bf94a14f276

   説明

   • ここでのキーと IV は例です。本番環境では、「4.3 キーと IV を取得する」を参照してください。

3. 暗号化を実行して、次の暗号文を生成します。

   006fe5011c9c2bf94a14f2765e987d4df2139141ff71b9f79d71a8e8b4b0592b10c32c4f2f662a0f3d5aa125910148effa6e088d7e4cdb02907e85fa463b8f1a8eaeb0e6e86dc2fe12ada1c5b1560b585a8f6f913d6c4a77c0dcacec84e28fb7d2fdc4cb39e284fc4627b22da5202cc0a20201bcd9c2d6f4f63936

4. 最終的な解決リクエスト。

   GET /v2/d?id=xxxxx&m=2&enc=006fe5011c9c2bf94a14f2765e987d4df2139141ff71b9f79d71a8e8b4b0592b10c32c4f2f662a0f3d5aa125910148effa6e088d7e4cdb02907e85fa463b8f1a8eaeb0e6e86dc2fe12ada1c5b1560b585a8f6f913d6c4a77c0dcacec84e28fb7d2fdc4cb39e284fc4627b22da5202cc0a20201bcd9c2d6f4f63936 HTTP/1.1

5. リクエストの署名（推奨）

認証メカニズムを使用して身分認証を強化し、潜在的な不正使用を防ぐことができます。このセクションでは、署名パラメーター s を計算し、HTTPDNS API のリクエストを構築する方法について説明します。これにより、解決リクエストがサーバーによって検証可能であり、改ざん防止されていることを保証できます。リクエストの署名には、署名する文字列の構築と署名の計算の 2 つのステップが含まれます。

5.1 署名する文字列を作成する

1. 署名の有効期限が切れる時刻のタイムスタンプ exp を生成します。

2. 署名の一部であるすべてのキーと値のペアを収集します。

3. キーの昇順の ASCII 順（大文字と小文字を区別）でソートします。

4. key=value フォーマットで、& 文字で区切って単一行の文字列に連結します。

5.2 署名を計算する

• アルゴリズム: HMAC-SHA256

• キー: コンソールの開発者向け設定から32 文字の 16 進文字列を取得します。使用する前に、キーを 16 進数でデコードして、実際の 128 ビットキーを取得します。

• 入力: 署名する文字列の UTF-8 バイナリ表現。

• 出力：小文字の 64 文字の 16 進エンコード文字列。

5.3 リクエスト署名の例

ドメイン名 www.example1.com と www.example2.com をデュアルスタック解決で解決し、カスタムパラメーター param1=value1、クライアント IP アドレス 192.168.1.1 を使用する必要があるとします。リクエストをプレーンテキストで送信する場合、署名プロセスは次のようになります。

1. 元のリクエストパラメーター

   パラメーター	値
   dn	www.example1.com,www.example2.com
   exp	1755568414
   cip	192.168.1.1
   q	4,6
   m	0
   sdns-param1	value1

2. 署名する文字列に連結する

   cip=192.168.1.1&dn=www.example1.com,www.example2.com&exp=1755568414&id=139450&m=0&q=4,6&sdns-param1=value1

3. 署名を計算する

   • 署名キー: 30b736b6d999700c5f589361fa4da44c

   • 生成された署名: d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0

   説明

   • ここでの署名キーは例です。実際の署名キーは開発者向け設定から取得してください。

4. 最終的な解決リクエスト

   GET /v2/d?id=139450&dn=www.example1.com,www.example2.com&exp=1755568678&cip=192.168.1.1&q=4,6&m=0&sdns-param1=value1&s=d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0 HTTP/1.1

6. API レスポンス

サーバーは、クライアントから有効な解決リクエストを受信すると、リクエストパラメーターを分析し、ドメイン名解決タスクを開始します。タスクが完了すると、サーバーは JSON 形式で解決結果をクライアントに返します。

6.1 レスポンスフィールド

レスポンスメッセージは JSON 形式です。次の表に、パス内の各ノードの意味を示します。

6.2 レスポンスコード

code フィールドは、HTTP 解決リクエストレスポンスの全体的なステータスを示します。次の表に、可能な値、その意味、および対応する HTTP ステータスコードを示します。

6.3 IP なしインジケーターコード

クライアントが応答で IP アドレスを受信しない場合があります。これは、コンソールでドメイン名が解決リストに追加されていないなどのドメイン名設定の問題や、ドメイン名自体に IPv6 レコードが設定されていないなどの問題が原因である可能性があります。no_ip_code フィールドを使用して原因を特定できます。次の表に、指定できる値とその意味を示します。

6.4 レスポンスの例

プレーンテキストモードでの成功レスポンス

• HTTP ステータスコード: 200

• レスポンスボディのサンプル:

{
    "code": "success",
    "mode": 0,
    "data": {
        "answers": [
            {
                "dn": "www.example1.com",
                "v4": {
                    "ips": [
                        "180.101.XX.XX",
                        "180.101.XX.XX"
                    ],
                    "extra": "simplestring",
                    "ttl": 60
                },
                "v6": {
                    "ips": [],
                    "no_ip_code": "RRNotExist",
                    "extra": "simplestring"
                }
            },
            {
                "dn": "www.example2.com",
                "v4": {
                    "ips": [
                        "180.101.51.73",
                        "180.101.49.44"
                    ],
                    "ttl": 60
                },
                "v6": {
                    "ips": [],
                    "no_ip_code": "RRNotExist"
                }
            }
        ],
        "cip": "192.168.1.1"
    }
}

暗号文モードでの成功レスポンス

• HTTP ステータスコード: 200

• レスポンスボディのサンプル:

  {
    "mode": 2,
    "code": "success",
    "data": "fCF3fVHFOrNAyCs9cEJAprAYx+RfdM8zDbXmVLypO/8ei1muFJ3cQ7EbyekDAU9CN+5UpnHf7vYQGplfXmuwbcSNz9J6hNVQ8XI+i5OTmZ3kRkTpPM8yXI7P7DYwRfWzpFB0Xu41iFHtv4uFYsRQAbNwnD7q9r2NXAUkBFPOOIJGeije9F9k5l4ytr1PFq/yruzsHXEktCT0wyEsnTSamplHYLnBfqwyKgaBharveZeGGlU1tfF6QE5xY2CRRBjntCnbvkuP8gv4y14qw8VYh3/YD6z3mTk6sgVO1rPc9YI039drDTpYf16WsPb+tPZ5YC805knG5k2OcsnxwNCfj/+ijJQSFBacCPbL5TfIdXfrAw8eczqIQLcTjQ7PExfHSkFxDJgzcl+V6cqI8lbn5vJsQcF2Bedo6WSLUPiy3vgdwOl8x2g7eqXnBzcSNsclQBVRK7g5gwynRBbZGJ4krH8="
  }

失敗レスポンスの例

• HTTP ステータスコード: 4xx/5xx

• レスポンスボディのサンプル:

  {
    "code": "MissingArgument"
  }

6.5 レスポンスデータの復号（オプション）

サーバーが暗号化されたレスポンスを返す場合（mode フィールドが 1 または 2）、data フィールドを復号して実際の解決結果を取得する必要があります。

復号プロセス

1. 暗号化モードを確認する: レスポンスの mode フィールドから暗号化モードを特定します。

• mode: 1 - AES-CBC モード

• mode: 2 - AES-GCM モード

2. Base64 デコード：レスポンスの data フィールドを Base64 デコードしてバイナリデータを取得します。

3. IV と暗号文を抽出する: 暗号化モードに基づいて、デコードされたデータから IV と暗号文を抽出します。

• AES-CBC モード (mode=1)

  • 最初の 16 バイトは IV です。

  • 後続のバイトは暗号文です。

• AES-GCM モード (mode=2)

  • 最初の 12 バイトは IV です。

  • 後続のバイトは暗号文です。

4. 復号を実行する: コンソールから取得した secretKey と抽出された IV を使用して、暗号文を復号します。

5. 復号結果の取得: 復号されたデータは data フィールドの元のコンテンツです。このデータを応答フィールドのフォーマットに従って解析できます。

レスポンス復号の例

• レスポンスの data フィールドの値

  hvlBFDr8ZaQjNCyqvyn6cUPs/l/QI6Z8pORPdmpl/MpeslasdMi432cW5mFfPnvHmwzZpmgyd6vCnQb89YeIqwz0Yy61l9pm0PWX41xhD19HoTQPxHp90uLxjGYQIGgV6PPGVu84jyKLsao9tUTgTZc6zJnhZKnfMZjP5G67nRrwoU1r1SR68GJ6WyTL4JAqnHJoDx7yg08GAlrzYmbfiCSemy3/+yDvBZAE2jV692t/JAwtuSOlAHBX30Rx/VMdSsgaFDfQmPr+FNxBlPtcrrS2ml8xgvR/m4Gx8CncsQBZX1FoUHlfrGb4kAXvA0ilfCm5/4pO0fzqXwyE8QoBpwC06NtO5F4imdjQKfPWQByabIXE4SetroeGE0m/p6kt6n6xinbkH0oIcw9i4COibLr9TuOtDI+wN9oMtW9Xpo7rgQbsEDr55ABSr+4YgK2zAEuY13FabmgNMPhZQvBZcEpWEOQ=

• 復号されたプレーンテキスト

  {
    "answers": [
      {
        "dn": "www.example1.com",
        "v4": {
          "ips": [
            "192.185.XX.XXX"
          ],
          "ttl": 14400
        },
        "v6": {
          "ips": [],
          "no_ip_code": "RRNotExist",
          "ttl": 600
        }
      },
      {
        "dn": "www.example2.com",
        "v4": {
          "ips": [
            "172.67.XXX.XX",
            "104.21.XX.XX"
          ],
          "ttl": 300
        },
        "v6": {
          "ips": [
            "2606:4700:3037:0:0:0:ac43:c316",
            "2606:4700:3037:0:0:0:6815:2c31"
          ],
          "ttl": 300
        }
      }
    ],
    "cip": "192.168.1.1"
  }

  次のステップ

  このトピックでは、HTTP API を使用してドメイン名を解決する方法について説明しました。プロセスには、リクエストパラメーターの作成、オプションで暗号化と署名、リクエストの送信、レスポンスの解析が含まれます。詳細については、「ベストプラクティス」を参照して、解決 API に基づいて安定した安全で高性能な HTTPDNS クライアントを実装する方法を学んでください。