HTTPDNS:API resolusi nama domain

1. Ikhtisar

Resolusi nama domain menggunakan HTTP API mencakup dua langkah: 1) mendapatkan titik akhir resolusi, dan 2) mengirim permintaan resolusi menggunakan API. Topik ini berfokus pada langkah kedua: penggunaan API resolusi.

API resolusi nama domain mendukung resolusi nama domain tunggal maupun batch, serta opsional penandatanganan dan enkripsi parameter resolusi. Proses penggunaannya adalah sebagai berikut:

1. Tentukan parameter resolusi: daftar nama domain, alamat IP klien (opsional), dan jenis resolusi (IPv4 atau IPv6).

2. Tentukan metode permintaan: putuskan apakah akan menggunakan resolusi batch, penandatanganan, atau enkripsi untuk permintaan resolusi.

3. Enkripsi parameter (opsional): Hitung ciphertext dari parameter resolusi.

4. Tandatangani permintaan: Hitung tanda tangan untuk bidang yang memerlukan penandatanganan menggunakan algoritma penandatanganan.

5. Kirim permintaan: Tambahkan parameter resolusi, ID akun, dan tanda tangan ke URL, lalu kirim ke server.

6. Urai tanggapan: Ambil hasil resolusi dari pesan tanggapan yang dikembalikan oleh server.

Topik ini berfokus pada spesifikasi permintaan dan tanggapan HTTP API, mencakup definisi parameter, aturan enkripsi dan penandatanganan, serta struktur tanggapan. Bagian utamanya adalah sebagai berikut:

• Format API: Menjelaskan format akses API, termasuk metode HTTP, jalur, dan batasan umum.

• Parameter: Menjelaskan parameter permintaan, termasuk artinya, apakah diperlukan, dan apakah termasuk dalam penandatanganan atau enkripsi.

• Enkripsi Parameter: Menjelaskan cara mengenkripsi parameter permintaan dan mengirimkannya ke server di bidang enc.

• Penandatanganan Permintaan: Menjelaskan proses perhitungan tanda tangan, termasuk parameter yang harus ditandatangani dan aturan pengurutan.

• Respons API: Menjelaskan struktur pesan respons dan cara mendekripsi pesan dalam mode terenkripsi.

2. Format API

API resolusi mendukung akses melalui http atau https. Format API-nya adalah sebagai berikut:

• URL Layanan: http(s)://{endpoint}/v2/d? + {request_parameters}

• Metode Permintaan: GET

3. Parameter

API resolusi ini menggunakan parameter permintaan untuk menentukan tugas resolusi nama domain dan mengontrol proses enkripsi serta penandatanganan. Anda dapat mengatur parameter untuk melakukan resolusi dalam berbagai kombinasi, seperti teks biasa atau ciphertext, ditandatangani atau tidak, serta untuk nama domain tunggal atau batch.

3.1 Daftar Parameter

API ini mendukung mode transmisi teks biasa dan terenkripsi. Anda dapat menggunakan parameter m untuk mengontrol metode enkripsi. Tabel berikut mencantumkan semua parameter permintaan yang didukung.

3.2 Contoh parameter permintaan

• Permintaan teks biasa yang ditandatangani

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

• Permintaan teks sandi yang ditandatangani

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

4. Enkripsi Parameter (opsional)

API resolusi nama domain mendukung enkripsi parameter resolusi, termasuk dn, cip, q, dan sdns-*. Ini melindungi kerahasiaan parameter permintaan bahkan di lingkungan non-HTTPS. Langkah-langkah berikut menjelaskan cara mengenkripsi parameter resolusi.

4.1 Bangun string untuk dienkripsi

Simpan field yang akan dienkripsi, seperti dn, cip, q, dan sdns-*, dalam format JSON.

• Bidang dapat dalam urutan apa pun.

• Parameter opsional dapat dihilangkan.

• Baik kunci maupun nilai harus berupa string.

4.2 Pilih algoritma enkripsi

API ini mendukung dua algoritma enkripsi: AES-GCM-128 dan AES-CBC-128. Tabel berikut menjelaskan perbedaan dan skenario mereka.

4.3 Dapatkan kunci dan IV

Keamanan algoritma enkripsi AES bergantung pada kunci dan vektor inisialisasi (IV). Anda dapat memperolehnya dengan cara berikut:

• secretKey:

  • Dapatkan dari Konfigurasi pengembang di konsol.

  • Panjang: 128 bit

  • Konsol mengembalikan string heksadesimal sepanjang 32 karakter. Sebelum digunakan, dekripsi-heksa kunci tersebut untuk mengonversinya menjadi kunci biner.

  • Contoh: 82c0af0d0cb2d69c4f87bb25c2e23929

• IV (vektor inisialisasi):

  • Mode AES-GCM: 96 bit

  • Mode AES-CBC: 128 bit

  • Hasilkan IV baru menggunakan penghasil angka acak yang aman sebelum setiap permintaan untuk memastikan keamanan enkripsi.

  • Contoh: 7322e81466eea91d69e7f735 (Dekripsi-heksa nilai sebelum enkripsi).

4.4 Lakukan enkripsi

1. Enkripsi string JSON menggunakan algoritma enkripsi yang dipilih. Parameter enkripsi adalah sebagai berikut:

   Parameter	AES-CBC-128 (m=1)	AES-GCM-128 (m=2)
   String untuk dienkripsi	String untuk dienkripsi (dikodekan UTF-8)	String untuk dienkripsi (dikodekan UTF-8)
   Algoritma	AES-CBC-128	AES-GCM-128
   Panjang kunci	128 bit (16 byte)	128 bit (16 byte)
   IV Length	128 bit (16 byte)	96 bit (12 byte)
   Padding mode	Padding PKCS#7	Tidak memerlukan padding

2. Gabungkan IV dan teks sandi secara berurutan.

   1. Beberapa byte pertama adalah IV (12 byte untuk mode AES-GCM, 16 byte untuk mode AES-CBC).

   2. Sisanya adalah teks sandi.

3. Kodekan heksadesimal urutan byte gabungan tersebut.

4.5 Contoh Permintaan Teks Sandi

Asumsikan Anda perlu meresolusi nama domain www.example1.com dan www.example2.com dengan resolusi dual-stack, parameter kustom param1=value1, dan alamat IP klien 192.168.1.1. Jika Anda memilih algoritma AES-GCM-128, proses enkripsinya adalah sebagai berikut:

1. Bangun string untuk dienkripsi.

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

2. Dapatkan kunci dan IV.

   • Kunci: 82c0af0d0cb2d69c4f87bb25c2e23929

   • IV: 006fe5011c9c2bf94a14f276

   Catatan

   • Kunci dan IV di sini adalah contoh. Dalam lingkungan produksi, lihat 4.3 Dapatkan kunci dan IV.

3. Lakukan enkripsi untuk menghasilkan teks sandi berikut.

   006fe5011c9c2bf94a14f2765e987d4df2139141ff71b9f79d71a8e8b4b0592b10c32c4f2f662a0f3d5aa125910148effa6e088d7e4cdb02907e85fa463b8f1a8eaeb0e6e86dc2fe12ada1c5b1560b585a8f6f913d6c4a77c0dcacec84e28fb7d2fdc4cb39e284fc4627b22da5202cc0a20201bcd9c2d6f4f63936

4. Permintaan resolusi akhir.

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

5. Penandatanganan Permintaan (disarankan)

Anda dapat menggunakan mekanisme otentikasi untuk meningkatkan otentikasi identitas dan mencegah penyalahgunaan potensial. Bagian ini menjelaskan cara menghitung parameter tanda tangan s dan menyusun permintaan untuk HTTPDNS API guna memastikan bahwa permintaan resolusi dapat diverifikasi oleh server dan tidak dapat dimanipulasi. Penandatanganan permintaan mencakup dua langkah: menyusun string yang akan ditandatangani dan menghitung tanda tangan.

5.1 Bangun string untuk ditandatangani

1. Hasilkan timestamp exp untuk waktu kedaluwarsa tanda tangan.

2. Kumpulkan semua pasangan kunci-nilai yang termasuk dalam tanda tangan.

3. Urutkan mereka dalam urutan ASCII naik berdasarkan kunci (sensitif huruf besar-kecil).

4. Gabungkan menjadi string satu baris dalam format key=value, dipisahkan oleh karakter &.

5.2 Hitung tanda tangan

• Algoritma: HMAC-SHA256

• Kunci: Dapatkan string heksadesimal sepanjang 32 karakter dari Konfigurasi pengembang di konsol. Sebelum digunakan, dekripsi-heksa kunci tersebut untuk mendapatkan kunci 128-bit yang sebenarnya.

• Input: Representasi biner UTF-8 dari string untuk ditandatangani.

• Output: String heksadesimal 64 karakter huruf kecil.

5.3 Contoh Penandatanganan Permintaan

Asumsikan Anda perlu meresolusi nama domain www.example1.com dan www.example2.com dengan resolusi dual-stack, parameter kustom param1=value1, dan alamat IP klien 192.168.1.1. Jika Anda mengirim permintaan dalam teks biasa, proses penandatanganannya adalah sebagai berikut:

1. Parameter permintaan asli

   Parameter	Nilai
   dn	www.example1.com,www.example2.com
   exp	1755568414
   cip	192.168.1.1
   q	4,6
   m	0
   sdns-param1	value1

2. Gabungkan menjadi string untuk ditandatangani

   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. Hitung tanda tangan

   • Kunci penandatanganan: 30b736b6d999700c5f589361fa4da44c

   • Tanda tangan yang dihasilkan: d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0

   Catatan

   • Kunci penandatanganan di sini hanya contoh. Dapatkan kunci penandatanganan sebenarnya dari Konfigurasi pengembang.

4. Permintaan resolusi akhir.

   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. Respons API

Setelah server menerima permintaan resolusi yang valid dari klien, ia menganalisis parameter permintaan dan memulai tugas resolusi nama domain. Saat tugas selesai, server mengembalikan hasil resolusi ke klien dalam format JSON.

6.1 Bidang Respons

Pesan respons dalam format JSON. Tabel berikut menjelaskan arti setiap node dalam jalur.

6.2 Kode Respons

Bidang code menggambarkan status keseluruhan respons permintaan resolusi HTTP. Tabel berikut mencantumkan nilai yang mungkin, artinya, dan kode status HTTP yang sesuai.

6.3 Kode Indikator No-IP

Klien mungkin tidak menerima alamat IP dalam tanggapan. Hal ini dapat disebabkan oleh masalah konfigurasi nama domain, seperti nama domain belum ditambahkan ke daftar resolusi di konsol, atau masalah pada nama domain itu sendiri, seperti tidak adanya catatan IPv6 yang dikonfigurasi. Anda dapat menggunakan field no_ip_code untuk menentukan alasannya. Tabel berikut mencantumkan nilai yang mungkin dan maknanya.

6.4 Contoh Respons

Respons berhasil dalam mode teks biasa

• Kode status HTTP: 200

• Contoh badan respons:

{
    "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"
    }
}

Respons berhasil dalam mode teks sandi

• Kode status HTTP: 200

• Contoh badan respons:

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

Contoh respons gagal

• Kode status HTTP: 4xx/5xx

• Contoh badan respons:

  {
    "code": "MissingArgument"
  }

6.5 Dekripsi Data Respons (opsional)

Saat server mengembalikan respons terenkripsi (bidang mode adalah 1 atau 2), Anda perlu mendekripsi bidang data untuk mendapatkan hasil resolusi sebenarnya.

Proses dekripsi

1. Periksa mode enkripsi: Tentukan mode enkripsi dari bidang mode dalam respons:

• mode: 1 - Mode AES-CBC

• mode: 2 - Mode AES-GCM

2. Dekode Base64: Dekode Base64 bidang data dalam respons untuk mendapatkan data biner.

3. Ekstrak IV dan teks sandi: Ekstrak IV dan teks sandi dari data yang didekode berdasarkan mode enkripsi:

• Mode AES-CBC (mode=1)

  • 16 byte pertama adalah IV.

  • Byte berikutnya adalah teks sandi.

• Mode AES-GCM (mode=2)

  • 12 byte pertama adalah IV.

  • Byte berikutnya adalah teks sandi.

4. Lakukan dekripsi: Dekripsi teks sandi menggunakan secretKey yang diperoleh dari konsol dan IV yang diekstraksi.

5. Dapatkan hasil dekripsi: Data yang didekripsi adalah konten asli field data. Anda dapat mengurai data ini sesuai dengan format field tanggapan.

Contoh dekripsi respons

• Nilai bidang data dalam respons

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

• Teks biasa yang didekripsi

  {
    "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"
  }

  Apa yang harus dilakukan selanjutnya

  Topik ini menjelaskan cara menyelesaikan nama domain menggunakan API HTTP. Prosesnya meliputi pembuatan parameter permintaan, opsional mengenkripsi dan menandatanganinya, mengirimkan permintaan, dan mem-parsing respons. Untuk informasi lebih lanjut, lihat Praktik Terbaik untuk mempelajari cara mengimplementasikan klien HTTPDNS yang stabil, aman, dan berkinerja tinggi berdasarkan API resolusi.