HTTPDNS：網域名稱解析介面

1. 概述

通過HTTP API進行網域名稱解析，分為兩步：1）擷取解析服務地址；2）使用解析介面發起解析請求。本文主要聚焦第2部分，即解析介面的使用。

網域名稱解析介面支援單網域名稱解析與批量網域名稱解析兩種請求形式，並且可按業務需要對解析參數進行加簽與加密。該介面的使用流程如下：

1. 確定解析參數：網域名稱列表，用戶端IP（可選），解析類型（IPv4或IPv6）

2. 確定請求方式：根據需求決策解析請求是否使用批量解析，是否需要加簽，是否需要加密

3. 參數加密（可選）：根據加密步驟計算解析參數的密文

4. 請求加簽：對需要加簽的欄位按照加簽演算法計算簽名

5. 發起請求: 把解析參數、帳號ID、簽名等參數拼接到URL並發送到服務端

6. 響應報文解析：從服務端返回的報文中擷取解析結果

本文重點介紹 HTTP API 的請求與響應描述規範，涵蓋參數定義、加密/加簽規則與返回結構，章節主要內容如下：

• 介面形式：介紹介面訪問格式，包括HTTP 方法、路徑與通用約束

• 參數說明：介紹請求參數，包括參數含義，是否必選，是否參與加簽，是否參與加密等

• 解析參數加密：介紹如何對請求參數進行加密，以enc欄位發送到服務端

• 請求加簽：介紹簽名計算的過程，包括參與簽名的參數與定序

• API響應說明：介紹響應報文結構，以及在加密模式下如何進行對報文進行解密

2. 介面形式

解析介面支援通過http或https進行訪問，介面形式如下：

• 服務URL：http(s)://{服務接入地址}/v2/d? + {請求參數}

• 請求方式：GET

3. 參數說明

該解析介面通過請求參數定義網域名稱解析任務，並控制加密與簽名流程。您可以靈活設定參數，實現明文/密文、加簽/不加簽、單網域名稱/批量網域名稱等多種組合方式的解析。

3.1 參數列表

新版介面支援明文和加密兩種傳輸模式，通過 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. 解析參數加密（可選）

網域名稱解析介面支援對解析參數（包括dn、cip、q、sdns-*）進行加密，在非HTTPS環境下也能保護請求參數的機密性。可以通過以下流程完成解析參數的加密。

4.1 構建加密字串

將需加密的欄位（ dn、cip、q、sdns-*等）以 JSON 格式儲存。

• 不要求欄位順序

• 選擇性參數可不傳

• 索引值都為字串類型

4.2 選擇密碼編譯演算法

該API支援兩種密碼編譯演算法，AES-GCM-128和AES-CBC-128，兩種演算法區別以及應用情境如下：

4.3 擷取密鑰與 IV

AES密碼編譯演算法的安全性依賴密鑰和初始化向量值，通過以下方式擷取：

• secretKey：

  • 從控制台的開發配置處擷取

  • 長度：128 bit

  • 控制台返回為 32 位 hex 字串，使用前需對密鑰進行十六進位解碼，轉換為二進位密鑰

  • 樣本：82c0af0d0cb2d69c4f87bb25c2e23929

• IV（初始化向量）：

  • AES-GCM 模式：96 bit

  • AES-CBC 模式：128 bit

  • 每次請求前通過安全隨機數產生器產生新的 IV，確保加密安全性

  • 樣本：7322e81466eea91d69e7f735 （加密計算前需要進行十六進位解碼）

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. 請求加簽（推薦）

通過接入鑒權機制加強身份認證，防範可能存在的盜刷問題。這裡介紹 HTTPDNS 介面請求的簽名參數 s 的計算與請求構造，確保解析請求在服務端可校正且防篡改。請求加簽包括簽名串構造和簽名計算兩個步驟，詳情如下。

5.1 簽名串構造

1. 產生簽名失效的時間戳記exp。

2. 取出參與加簽的所有 索引值對。

3. 按鍵名 ASCII 升序 排序（區分大小寫）。

4. 使用 key=value 形式並以 & 串連為 單行字串。

5.2 簽名計算

• 演算法：HMAC-SHA256

• 密鑰：從控制台的開發配置出擷取 長度為32的 hex 字串（使用前需對密鑰進行十六進位解碼，擷取128 bit的實際密鑰）。

• 輸入：簽名字串的 UTF-8 二進位表示

• 輸出：小寫 hex 編碼字串，長度64字元

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. 計算簽名

   • 加簽Key：30b736b6d999700c5f589361fa4da44c

   • 產生簽名：d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0

   說明

   • 這裡的加簽Key只是樣本，實際加簽Key通過開發配置擷取。

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說明

code欄位是整個HTTP解析請求響應的整體狀態原因，取值、含義、以及對應的HTTP狀態代碼如下。

6.3 無IP指示碼

由於網域名稱配置的原因（如未在控制台將該網域名稱接入解析列表）或者網域名稱本身的原因（如網域名稱沒有配置IPv6記錄），用戶端可能在響應中拿不到IP，這裡您可以通過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 進行網域名稱解析的流程，包括構造請求參數、可選的加密與加簽、以及發起請求與解析響應的步驟。後續您可以參考最佳實務建議，基於解析介面實現穩定、安全、高效能的 HTTPDNS 用戶端。