域名解析接口

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 客户端。