في السابق، كانت التطبيقات المستندة إلى الويب تتطلب إضافات المتصفّح لاستخدام ميزات نظام أسماء النطاقات المتقدمة، مثل DANE أو اكتشاف خدمة نظام أسماء النطاقات-SD أو حتى حل أي مشاكل أخرى غير عناوين IP، مثل سجلات MX. لاستخدام الميزات المعتمدة على ملحقات أمان نظام أسماء النطاقات (DNSSEC)، مثل سجلّات SSHFP، يجب أن تتحقّق أي من هذه الإضافات من صحة ملحقات أمان نظام أسماء النطاقات (DNSSEC) بنفسها، لأن المتصفّح أو نظام التشغيل قد لا يتمكّن من ذلك.
قدّم "نظام أسماء النطاقات العام من Google" منذ العام 2016 واجهة برمجة تطبيقات متوافقة مع الويب لإدارة وزارة الصحة مع التحقّق من ملحقات أمان نظام أسماء النطاقات (DNSSEC) الذي لا يتطلّب ضبط المتصفّح أو نظام التشغيل أو الإضافات. إنّ معلَمات طلب البحث GET وردود JSON البسيطة تتيح للعملاء تحليل النتائج باستخدام واجهات برمجة تطبيقات الويب الشائعة وتجنُّب التفاصيل المعقدة لتنسيق رسائل نظام أسماء النطاقات، مثل ضغط المؤشر لأسماء النطاقات.
راجِع صفحة مستندات DoH العامة للحصول على معلومات حول DoH بشكل عام، مثل عناوين HTTP ومعالجة عمليات إعادة التوجيه وأفضل ممارسات الخصوصية ورموز حالة HTTP.
تحتوي صفحة عمليات النقل الآمن على
curl أمثلة على سطر الأوامر DoH، ومعلومات شائعة بين DoH ونظام أسماء النطاقات عبر
بروتوكول أمان طبقة النقل (DoT)، مثل التوافق مع بروتوكول أمان طبقة النقل (TLS) واقتطاع نظام أسماء النطاقات.
مواصفات JSON API
كل طلبات البيانات من واجهة برمجة التطبيقات هي طلبات HTTP GET. في حالة المعلَمات المكررة، يتم استخدام القيمة الأولى فقط.
المَعلمات المتوافقة
- اسم
سلسلة، مطلوبة
المعلمة الوحيدة المطلوبة. يتم قبول عمليات إلغاء الشرطة المائلة للخلف وفقًا لمعيار RFC 4343.
- يجب أن يكون الطول (بعد استبدال أحرف الإلغاء للشرطة المائلة للخلف) بين 1 و253 (مع تجاهل نقطة لاحقة اختيارية في حال توفّرها).
- يجب أن يتراوح طول جميع التصنيفات (أجزاء من الاسم بين النقاط) من 1 إلى 63 بايت.
- تحصل الأسماء غير الصالحة، مثل
.example.comأوexample..comأو السلسلة الفارغة، على 400 طلب غير صالح. - يجب أن تكون الأحرف غير ASCII punycoded (
xn--qxam، وليسελ).
- كتابة
سلسلة، القيمة التلقائية:
1يمكن تمثيل نوع RR كرقم في [1، 65535] أو سلسلة أساسية (غير حساسة لحالة الأحرف، مثل
Aأوaaaa). يمكنك استخدام255لطلبات البحث "ANY" ولكن يُرجى العلم أنّ هذا لا بديل لإرسال طلبات البحث لكل من سجلات A وAAAA أو MX. لا تحتاج خوادم الأسماء الموثوقة إلى عرض جميع السجلات لطلبات البحث هذه، فبعضها لا يستجيب، والبعض الآخر (مثل cloudflare.com) لا تعرض سوى HINFO.- cd
منطقية، القيمة التلقائية:
falseعلامة القرص المضغوط (التحقق معطلة). استخدِم
cd=1أوcd=trueلإيقاف عملية التحقّق من ملحقات أمان نظام أسماء النطاقات (DNSSEC). واستخدِمcd=0أوcd=falseأو لا تستخدم أي مَعلمةcdلتفعيل التحقّق من ملحقات أمان نظام أسماء النطاقات (DNSSEC).- عدد
سلسلة، القيمة التلقائية: فارغة
خيار نوع المحتوى المطلوب استخدِم
ct=application/dns-messageلتلقّي رسالة نظام أسماء نطاقات ثنائية في نص استجابة HTTP بدلاً من نص JSON. يمكنك استخدامct=application/x-javascriptلطلب نص JSON بشكل صريح. ويتم تجاهل قيم أنواع المحتوى الأخرى ويتم عرض محتوى JSON التلقائي.- do
منطقية، القيمة التلقائية:
falseعلامة DO (موافق على ملحقات أمان نظام أسماء النطاقات (DNSSEC)). يمكنك استخدام
do=1أوdo=trueلتضمين سجلّات ملحقات أمان نظام أسماء النطاقات (DNSSEC) (RRSIG أو NSEC أو NSEC3)، واستخدامdo=0أوdo=falseأو عدم استخدام أي مَعلمةdoلحذف سجلّات ملحقات أمان نظام أسماء النطاقات (DNSSEC).يجب أن تعالج التطبيقات دائمًا (وتتجاهل، إذا لزم الأمر) أي سجلّات ملحقات أمان نظام أسماء النطاقات (DNSSEC) في استجابات JSON، إذ إنّ عمليات التنفيذ الأخرى قد تتضمّنها دائمًا، ويمكن أن نغيّر السلوك التلقائي لردود JSON في المستقبل. (تحترم استجابات رسائل نظام أسماء النطاقات الثنائية دائمًا قيمة علامة DO).
- edns_client_subnet
سلسلة، القيمة التلقائية: فارغة
خيار الشبكة الفرعية edns0-client-client. التنسيق هو عنوان IP مع قناع شبكة فرعية. أمثلة:
1.2.3.4/24و2001:700:300::/48إذا كنت تستخدم معالجة نظام أسماء النطاقات عبر بروتوكول HTTPS بسبب مخاوف تتعلّق بالخصوصية، ولا تريد إرسال أي جزء من عنوان IP إلى خوادم أسماء موثوقة لدقة الموقع الجغرافي، استخدِم
edns_client_subnet=0.0.0.0/0. عادةً ما يرسل "نظام أسماء النطاقات العام من Google" معلومات تقريبية عن الشبكة (عادةً ما يُصدِر الجزء الأخير من عنوان IPv4).- random_padding
سلسلة، تم التجاهل
ويتم تجاهل قيمة هذه المَعلمة. مثال:
XmkMw~o_mgP2pf.gpw-Oi5dKويمكن لعملاء واجهة برمجة التطبيقات المعنيين بهجمات الخصوصية المحتملة على القنوات الجانبية التي تستخدم أحجام حِزم طلبات HTTPS GET استخدام هذا الحجم لجعل جميع الطلبات بنفس الحجم عن طريق إضافة بيانات عشوائية إلى الطلبات. لمنع إساءة تفسير عنوان URL، يجب تقييد حروف المساحة المتروكة لأحرف عنوان URL غير المحجوزة، مثل الأحرف الكبيرة والصغيرة والأرقام والواصلة والنقطة والشرطة السفلية وتلدة.
استجابة نظام أسماء النطاقات بتنسيق JSON
استجابة ناجحة (التعليقات التي تتم إضافتها هنا غير متوفرة في الردود الفعلية):
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question":
[
{
"name": "apple.com.", // FQDN with trailing dot
"type": 1 // A - Standard DNS RR type
}
],
"Answer":
[
{
"name": "apple.com.", // Always matches name in the Question section
"type": 1, // A - Standard DNS RR type
"TTL": 3599, // Record's time-to-live in seconds
"data": "17.178.96.59" // Data for A - IP address as text
},
{
"name": "apple.com.",
"type": 1,
"TTL": 3599,
"data": "17.172.224.47"
},
{
"name": "apple.com.",
"type": 1,
"TTL": 3599,
"data": "17.142.160.59"
}
],
"edns_client_subnet": "12.34.56.78/0" // IP address / scope prefix-length
}
راجِع RFC 7871 (الشبكة الفرعية لعميل EDNS) للحصول على تفاصيل حول "طول بادئة النطاق" وكيفية تأثيره في التخزين المؤقت.
استجابة للفشل مع معلومات التشخيص:
{
"Status": 2, // SERVFAIL - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question":
[
{
"name": "dnssec-failed.org.", // FQDN with trailing dot
"type": 1 // A - Standard DNS RR type
}
],
"Comment": "DNSSEC validation failure. Please check http://dnsviz.net/d/dnssec-failed.org/dnssec/."
}
سجلّات نظام التعرّف على هوية المرسل (SPF) وسجلّات TXT مع علامات اقتباس مضمّنة وإسناد خادم الأسماء:
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question": [
{
"name": "*.dns-example.info.", // FQDN with trailing dot
"type": 99 // SPF - Standard DNS RR type
}
],
"Answer": [
{
"name": "*.dns-example.info.", // Always matches name in Question
"type": 99, // SPF - Standard DNS RR type
"TTL": 21599, // Record's time-to-live in seconds
"data": "\"v=spf1 -all\"" // Data for SPF - quoted string
}
],
"Comment": "Response from 216.239.38.110"
// Uncached responses are attributed to the authoritative name server
}
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question": [
{
"name": "s1024._domainkey.yahoo.com.", // FQDN with trailing dot
"type": 16 // TXT - Standard DNS RR type
}
],
"Answer": [
{
"name": "s1024._domainkey.yahoo.com.", // Always matches Question name
"type": 16, // TXT - Standard DNS RR type
"data": "\"k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDrEee0Ri4Juz+QfiWYui/E9UGSXau/2P8LjnTD8V4Unn+2FAZVGE3kL23bzeoULYv4PeleB3gfm\"\"JiDJOKU3Ns5L4KJAUUHjFwDebt0NP+sBK0VKeTATL2Yr/S3bT/xhy+1xtj4RkdV7fVxTn56Lb4udUnwuxK4V5b5PdOKj/+XcwIDAQAB; n=A 1024 bit key;\""
// Data for TXT - multiple quoted strings
}
],
}
سلاسل نظام أسماء النطاقات
يتم ترميز جميع سجلات TXT في صورة سلسلة JSON واحدة، بما في ذلك استخدامات تنسيقات سجلات TXT الأطول، مثل RFC 4408 (SPF) أو RFC 4871 (DKIM).
نظام أسماء النطاقات (EDNS)
إنّ آلية إضافة EDNS العامة غير متوافقة. خيار الشبكة الفرعية لعميل EDNS (edns-client-subnet) هو معلَمة في طلب GET وحقل مستوى أعلى في استجابة JSON.