1 Internet Engineering Task Force (IETF) A. Newton
2 Request for Comments: 7482 ARIN
3 Category: Standards Track S. Hollenbeck
4 ISSN: 2070-1721 Verisign Labs
5 March 2015
6
7
8 Registration Data Access Protocol (RDAP) Query Format
9
10 Abstract
11
12 This document describes uniform patterns to construct HTTP URLs that
13 may be used to retrieve registration information from registries
14 (including both Regional Internet Registries (RIRs) and Domain Name
15 Registries (DNRs)) using "RESTful" web access patterns. These
16 uniform patterns define the query syntax for the Registration Data
17 Access Protocol (RDAP).
18
19 Status of This Memo
20
21 This is an Internet Standards Track document.
22
23 This document is a product of the Internet Engineering Task Force
24 (IETF). It represents the consensus of the IETF community. It has
25 received public review and has been approved for publication by the
26 Internet Engineering Steering Group (IESG). Further information on
27 Internet Standards is available in Section 2 of RFC 5741.
28
29 Information about the current status of this document, any errata,
30 and how to provide feedback on it may be obtained at
31 http://www.rfc-editor.org/info/rfc7482.
32
33 Copyright Notice
34
35 Copyright (c) 2015 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
37
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents
40 (http://trustee.ietf.org/license-info) in effect on the date of
41 publication of this document. Please review these documents
42 carefully, as they describe your rights and restrictions with respect
43 to this document. Code Components extracted from this document must
44 include Simplified BSD License text as described in Section 4.e of
45 the Trust Legal Provisions and are provided without warranty as
46 described in the Simplified BSD License.
47
48
49
50
51
52 Newton & Hollenbeck Standards Track [Page 1]
53 RFC 7482 RDAP Query Format March 2015
54
55
56 Table of Contents
57
58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
59 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
60 2.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . 4
61 3. Path Segment Specification . . . . . . . . . . . . . . . . . 4
62 3.1. Lookup Path Segment Specification . . . . . . . . . . . . 5
63 3.1.1. IP Network Path Segment Specification . . . . . . . . 6
64 3.1.2. Autonomous System Path Segment Specification . . . . 7
65 3.1.3. Domain Path Segment Specification . . . . . . . . . . 7
66 3.1.4. Nameserver Path Segment Specification . . . . . . . . 8
67 3.1.5. Entity Path Segment Specification . . . . . . . . . . 9
68 3.1.6. Help Path Segment Specification . . . . . . . . . . . 9
69 3.2. Search Path Segment Specification . . . . . . . . . . . . 9
70 3.2.1. Domain Search . . . . . . . . . . . . . . . . . . . . 10
71 3.2.2. Nameserver Search . . . . . . . . . . . . . . . . . . 11
72 3.2.3. Entity Search . . . . . . . . . . . . . . . . . . . . 12
73 4. Query Processing . . . . . . . . . . . . . . . . . . . . . . 13
74 4.1. Partial String Searching . . . . . . . . . . . . . . . . 13
75 4.2. Associated Records . . . . . . . . . . . . . . . . . . . 14
76 5. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 14
77 6. Internationalization Considerations . . . . . . . . . . . . . 15
78 6.1. Character Encoding Considerations . . . . . . . . . . . . 15
79 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
80 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
81 8.1. Normative References . . . . . . . . . . . . . . . . . . 17
82 8.2. Informative References . . . . . . . . . . . . . . . . . 19
83 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19
84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20
85
86 1. Introduction
87
88 This document describes a specification for querying registration
89 data using a RESTful web service and uniform query patterns. The
90 service is implemented using the Hypertext Transfer Protocol (HTTP)
91 [RFC7230] and the conventions described in [RFC7480]. These uniform
92 patterns define the query syntax for the Registration Data Access
93 Protocol (RDAP).
94
95 The protocol described in this specification is intended to address
96 deficiencies with the WHOIS protocol [RFC3912] that have been
97 identified over time, including:
98
99 o lack of standardized command structures;
100
101 o lack of standardized output and error structures;
102
103 o lack of support for internationalization and localization; and
104
105
106
107 Newton & Hollenbeck Standards Track [Page 2]
108 RFC 7482 RDAP Query Format March 2015
109
110
111 o lack of support for user identification, authentication, and
112 access control.
113
114 The patterns described in this document purposefully do not encompass
115 all of the methods employed in the WHOIS and other RESTful web
116 services used by the RIRs and DNRs. The intent of the patterns
117 described here are to enable queries of:
118
119 o networks by IP address;
120
121 o Autonomous System (AS) numbers by number;
122
123 o reverse DNS metadata by domain;
124
125 o nameservers by name;
126
127 o registrars by name; and
128
129 o entities (such as contacts) by identifier.
130
131 Server implementations are free to support only a subset of these
132 features depending on local requirements. Servers MUST return an
133 HTTP 501 (Not Implemented) [RFC7231] response to inform clients of
134 unsupported query types. It is also envisioned that each registry
135 will continue to maintain WHOIS and/or other RESTful web services
136 specific to their needs and those of their constituencies, and the
137 information retrieved through the patterns described here may
138 reference such services.
139
140 Likewise, future IETF standards may add additional patterns for
141 additional query types. A simple pattern namespacing scheme is
142 described in Section 5 to accommodate custom extensions that will not
143 interfere with the patterns defined in this document or patterns
144 defined in future IETF standards.
145
146 WHOIS services, in general, are read-only services. Therefore, URL
147 [RFC3986] patterns specified in this document are only applicable to
148 the HTTP [RFC7231] GET and HEAD methods.
149
150 This document does not describe the results or entities returned from
151 issuing the described URLs with an HTTP GET. The specification of
152 these entities is described in [RFC7483].
153
154 Additionally, resource management, provisioning, and update functions
155 are out of scope for this document. Registries have various and
156 divergent methods covering these functions, and it is unlikely a
157 uniform approach is needed for interoperability.
158
159
160
161
162 Newton & Hollenbeck Standards Track [Page 3]
163 RFC 7482 RDAP Query Format March 2015
164
165
166 HTTP contains mechanisms for servers to authenticate clients and for
167 clients to authenticate servers (from which authorization schemes may
168 be built), so such mechanisms are not described in this document.
169 Policy, provisioning, and processing of authentication and
170 authorization are out of scope for this document as deployments will
171 have to make choices based on local criteria. Supported
172 authentication mechanisms are described in [RFC7481].
173
174 2. Conventions Used in This Document
175
176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
178 document are to be interpreted as described in [RFC2119].
179
The IETF is responsible for the creation and maintenance of the DNS RFCs. The ICANN DNS RFC annotation project provides a forum for collecting community annotations on these RFCs as an aid to understanding for implementers and any interested parties. The annotations displayed here are not the result of the IETF consensus process.
This RFC is included in the DNS RFCs annotation project whose home page is here.
180 2.1. Acronyms and Abbreviations
181
182 IDN: Internationalized Domain Name
183
184 IDNA: Internationalized Domain Names in Applications, a protocol
185 for the handling of IDNs.
186
187 DNR: Domain Name Registry
188
189 NFC: Unicode Normalization Form C [Unicode-UAX15]
190
191 NFKC: Unicode Normalization Form KC [Unicode-UAX15]
192
193 RDAP: Registration Data Access Protocol
194
195 REST: Representational State Transfer. The term was first
196 described in a doctoral dissertation [REST].
197
198 RESTful: An adjective that describes a service using HTTP and the
199 principles of REST.
200
201 RIR: Regional Internet Registry
202
203 3. Path Segment Specification
204
205 The base URLs used to construct RDAP queries are maintained in an
206 IANA registry described in [RFC7484]. Queries are formed by
207 retrieving an appropriate base URL from the registry and appending a
208 path segment specified in either Sections 3.1 or 3.2. Generally, a
209 registry or other service provider will provide a base URL that
210 identifies the protocol, host, and port, and this will be used as a
211 base URL that the complete URL is resolved against, as per Section 5
212
213
214
215
216
217 Newton & Hollenbeck Standards Track [Page 4]
218 RFC 7482 RDAP Query Format March 2015
219
220
221 of RFC 3986 [RFC3986]. For example, if the base URL is
222 "https://example.com/rdap/", all RDAP query URLs will begin with
223 "https://example.com/rdap/".
224
225 The bootstrap registry does not contain information for query objects
226 that are not part of a global namespace, including entities and help.
227 A base URL for an associated object is required to construct a
228 complete query.
229
230 For entities, a base URL is retrieved for the service (domain,
231 address, etc.) associated with a given entity. The query URL is
232 constructed by concatenating the base URL to the entity path segment
233 specified in either Sections 3.1.5 or 3.2.3.
234
235 For help, a base URL is retrieved for any service (domain, address,
236 etc.) for which additional information is required. The query URL is
237 constructed by concatenating the base URL to the help path segment
238 specified in Section 3.1.6.
239
240 3.1. Lookup Path Segment Specification
241
242 A simple lookup to determine if an object exists (or not) without
243 returning RDAP-encoded results can be performed using the HTTP HEAD
244 method as described in Section 4.1 of [RFC7480].
245
246 The resource type path segments for exact match lookup are:
247
248 o 'ip': Used to identify IP networks and associated data referenced
249 using either an IPv4 or IPv6 address.
250
251 o 'autnum': Used to identify Autonomous System number registrations
252 and associated data referenced using an asplain Autonomous System
253 number.
254
255 o 'domain': Used to identify reverse DNS (RIR) or domain name (DNR)
256 information and associated data referenced using a fully qualified
257 domain name.
258
259 o 'nameserver': Used to identify a nameserver information query
260 using a host name.
261
262 o 'entity': Used to identify an entity information query using a
263 string identifier.
264
265
266
267
268
269
270
271
272 Newton & Hollenbeck Standards Track [Page 5]
273 RFC 7482 RDAP Query Format March 2015
274
275
276 3.1.1. IP Network Path Segment Specification
277
278 Syntax: ip/<IP address> or ip/<CIDR prefix>/<CIDR length>
279
280 Queries for information about IP networks are of the form /ip/XXX/...
281 or /ip/XXX/YY/... where the path segment following 'ip' is either an
282 IPv4 dotted decimal or IPv6 [RFC5952] address (i.e., XXX) or an IPv4
283 or IPv6 Classless Inter-domain Routing (CIDR) [RFC4632] notation
284 address block (i.e., XXX/YY). Semantically, the simpler form using
285 the address can be thought of as a CIDR block with a bitmask length
286 of 32 for IPv4 and a bitmask length of 128 for IPv6. A given
287 specific address or CIDR may fall within multiple IP networks in a
288 hierarchy of networks; therefore, this query targets the "most-
289 specific" or smallest IP network that completely encompasses it in a
290 hierarchy of IP networks.
291
292 The IPv4 and IPv6 address formats supported in this query are
293 described in Section 3.2.2 of RFC 3986 [RFC3986] as IPv4address and
294 IPv6address ABNF definitions. Any valid IPv6 text address format
295 [RFC4291] can be used. This includes IPv6 addresses written using
296 with or without compressed zeros and IPv6 addresses containing
297 embedded IPv4 addresses. The rules to write a text representation of
298 an IPv6 address [RFC5952] are RECOMMENDED. However, the zone_id
299 [RFC4007] is not appropriate in this context; therefore, the
300 corresponding syntax extension in RFC 6874 [RFC6874] MUST NOT be
301 used, and servers are to ignore it if possible.
302
303 For example, the following URL would be used to find information for
304 the most specific network containing 192.0.2.0:
305
306 https://example.com/rdap/ip/192.0.2.0
307
308 The following URL would be used to find information for the most
309 specific network containing 192.0.2.0/24:
310
311 https://example.com/rdap/ip/192.0.2.0/24
312
313 The following URL would be used to find information for the most
314 specific network containing 2001:db8::0:
315
316 https://example.com/rdap/ip/2001:db8::0
317
318
319
320
321
322
323
324
325
326
327 Newton & Hollenbeck Standards Track [Page 6]
328 RFC 7482 RDAP Query Format March 2015
329
330
331 3.1.2. Autonomous System Path Segment Specification
332
333 Syntax: autnum/<autonomous system number>
334
335 Queries for information regarding Autonomous System number
336 registrations are of the form /autnum/XXX/... where XXX is an asplain
337 Autonomous System number [RFC5396]. In some registries, registration
338 of Autonomous System numbers is done on an individual number basis,
339 while other registries may register blocks of Autonomous System
340 numbers. The semantics of this query are such that if a number falls
341 within a range of registered blocks, the target of the query is the
342 block registration and that individual number registrations are
343 considered a block of numbers with a size of 1.
344
345 For example, the following URL would be used to find information
346 describing Autonomous System number 12 (a number within a range of
347 registered blocks):
348
349 https://example.com/rdap/autnum/12
350
351 The following URL would be used to find information describing 4-byte
352 Autonomous System number 65538:
353
354 https://example.com/rdap/autnum/65538
355
356 3.1.3. Domain Path Segment Specification
357
358 Syntax: domain/<domain name>
359
360 Queries for domain information are of the form /domain/XXXX/...,
361 where XXXX is a fully qualified (relative to the root) domain name
362 (as specified in [RFC0952] and [RFC1123]) in either the in-addr.arpa
363 or ip6.arpa zones (for RIRs) or a fully qualified domain name in a
364 zone administered by the server operator (for DNRs).
365 Internationalized Domain Names (IDNs) represented in either A-label
366 or U-label format [RFC5890] are also valid domain names. See
367 Section 6.1 for information on character encoding for the U-label
368 format.
369
370 IDNs SHOULD NOT be represented as a mixture of A-labels and U-labels;
371 that is, internationalized labels in an IDN SHOULD be either all
372 A-labels or all U-labels. It is possible for an RDAP client to
373 assemble a query string from multiple independent data sources. Such
374 a client might not be able to perform conversions between A-labels
375 and U-labels. An RDAP server that receives a query string with a
376 mixture of A-labels and U-labels MAY convert all the U-labels to
377 A-labels, perform IDNA processing, and proceed with exact-match
378
379
380
381
382 Newton & Hollenbeck Standards Track [Page 7]
383 RFC 7482 RDAP Query Format March 2015
384
385
386 lookup. In such cases, the response to be returned to the query
387 source may not match the input from the query source. Alternatively,
388 the server MAY refuse to process the query.
389
390 The server MAY perform the match using either the A-label or U-label
391 form. Using one consistent form for matching every label is likely
392 to be more reliable.
393
394 The following URL would be used to find information describing the
395 zone serving the network 192.0.2/24:
396
397 https://example.com/rdap/domain/2.0.192.in-addr.arpa
398
399 The following URL would be used to find information describing the
400 zone serving the network 2001:db8:1::/48:
401
402 https://example.com/rdap/domain/1.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa
403
404 The following URL would be used to find information for the
405 blah.example.com domain name:
406
407 https://example.com/rdap/domain/blah.example.com
408
409 The following URL would be used to find information for the
410 xn--fo-5ja.example IDN:
411
412 https://example.com/rdap/domain/xn--fo-5ja.example
413
414 3.1.4. Nameserver Path Segment Specification
415
416 Syntax: nameserver/<nameserver name>
417
418 The <nameserver name> parameter represents a fully qualified host
419 name as specified in [RFC0952] and [RFC1123]. Internationalized
420 names represented in either A-label or U-label format [RFC5890] are
421 also valid nameserver names. IDN processing for nameserver names
422 uses the domain name processing instructions specified in
423 Section 3.1.3. See Section 6.1 for information on character encoding
424 for the U-label format.
425
426 The following URL would be used to find information for the
427 ns1.example.com nameserver:
428
429 https://example.com/rdap/nameserver/ns1.example.com
430
431
432
433
434
435
436
437 Newton & Hollenbeck Standards Track [Page 8]
438 RFC 7482 RDAP Query Format March 2015
439
440
441 The following URL would be used to find information for the
442 ns1.xn--fo-5ja.example nameserver:
443
444 https://example.com/rdap/nameserver/ns1.xn--fo-5ja.example
445
446 3.1.5. Entity Path Segment Specification
447
448 Syntax: entity/<handle>
449
450 The <handle> parameter represents an entity (such as a contact,
451 registrant, or registrar) identifier whose syntax is specific to the
452 registration provider. For example, for some DNRs, contact
453 identifiers are specified in [RFC5730] and [RFC5733].
454
455 The following URL would be used to find information for the entity
456 associated with handle XXXX:
457
458 https://example.com/rdap/entity/XXXX
459
460 3.1.6. Help Path Segment Specification
461
462 Syntax: help
463
464 The help path segment can be used to request helpful information
465 (command syntax, terms of service, privacy policy, rate-limiting
466 policy, supported authentication methods, supported extensions,
467 technical support contact, etc.) from an RDAP server. The response
468 to "help" should provide basic information that a client needs to
469 successfully use the service. The following URL would be used to
470 return "help" information:
471
472 https://example.com/rdap/help
473
474 3.2. Search Path Segment Specification
475
476 Pattern matching semantics are described in Section 4.1. The
477 resource type path segments for search are:
478
479 o 'domains': Used to identify a domain name information search using
480 a pattern to match a fully qualified domain name.
481
482 o 'nameservers': Used to identify a nameserver information search
483 using a pattern to match a host name.
484
485 o 'entities': Used to identify an entity information search using a
486 pattern to match a string identifier.
487
488
489
490
491
492 Newton & Hollenbeck Standards Track [Page 9]
493 RFC 7482 RDAP Query Format March 2015
494
495
496 RDAP search path segments are formed using a concatenation of the
497 plural form of the object being searched for and an HTTP query
498 string. The HTTP query string is formed using a concatenation of the
499 question mark character ('?', US-ASCII value 0x003F), the JSON object
500 value associated with the object being searched for, the equal sign
501 character ('=', US-ASCII value 0x003D), and the search pattern.
502 Search pattern query processing is described more fully in Section 4.
503 For the domain, nameserver, and entity objects described in this
504 document, the plural object forms are "domains", "nameservers", and
505 "entities".
506
507 Detailed results can be retrieved using the HTTP GET method and the
508 path segments specified here.
509
510 3.2.1. Domain Search
511
512 Syntax: domains?name=<domain search pattern>
513
514 Syntax: domains?nsLdhName=<domain search pattern>
515
516 Syntax: domains?nsIp=<domain search pattern>
517
518 Searches for domain information by name are specified using this
519 form:
520
521 domains?name=XXXX
522
523 XXXX is a search pattern representing a domain name in "letters,
524 digits, hyphen" (LDH) format [RFC5890] in a zone administered by the
525 server operator of a DNR. The following URL would be used to find
526 DNR information for domain names matching the "example*.com" pattern:
527
528 https://example.com/rdap/domains?name=example*.com
529
530 IDNs in U-label format [RFC5890] can also be used as search patterns
531 (see Section 4). Searches for these names are of the form
532 /domains?name=XXXX, where XXXX is a search pattern representing a
533 domain name in U-label format [RFC5890]. See Section 6.1 for
534 information on character encoding for the U-label format.
535
536 Searches for domain information by nameserver name are specified
537 using this form:
538
539 domains?nsLdhName=YYYY
540
541
542
543
544
545
546
547 Newton & Hollenbeck Standards Track [Page 10]
548 RFC 7482 RDAP Query Format March 2015
549
550
551 YYYY is a search pattern representing a host name in "letters,
552 digits, hyphen" format [RFC5890] in a zone administered by the server
553 operator of a DNR. The following URL would be used to search for
554 domains delegated to nameservers matching the "ns1.example*.com"
555 pattern:
556
557 https://example.com/rdap/domains?nsLdhName=ns1.example*.com
558
559 Searches for domain information by nameserver IP address are
560 specified using this form:
561
562 domains?nsIp=ZZZZ
563
564 ZZZZ is a search pattern representing an IPv4 [RFC1166] or IPv6
565 [RFC5952] address. The following URL would be used to search for
566 domains that have been delegated to nameservers that resolve to the
567 "192.0.2.0" address:
568
569 https://example.com/rdap/domains?nsIp=192.0.2.0
570
571 3.2.2. Nameserver Search
572
573 Syntax: nameservers?name=<nameserver search pattern>
574
575 Syntax: nameservers?ip=<nameserver search pattern>
576
577 Searches for nameserver information by nameserver name are specified
578 using this form:
579
580 nameservers?name=XXXX
581
582 XXXX is a search pattern representing a host name in "letters,
583 digits, hyphen" format [RFC5890] in a zone administered by the server
584 operator of a DNR. The following URL would be used to find DNR
585 information for nameserver names matching the "ns1.example*.com"
586 pattern:
587
588 https://example.com/rdap/nameservers?name=ns1.example*.com
589
590 Internationalized nameserver names in U-label format [RFC5890] can
591 also be used as search patterns (see Section 4). Searches for these
592 names are of the form /nameservers?name=XXXX, where XXXX is a search
593 pattern representing a nameserver name in U-label format [RFC5890].
594 See Section 6.1 for information on character encoding for the U-label
595 format.
596
597
598
599
600
601
602 Newton & Hollenbeck Standards Track [Page 11]
603 RFC 7482 RDAP Query Format March 2015
604
605
606 Searches for nameserver information by nameserver IP address are
607 specified using this form:
608
609 nameservers?ip=YYYY
610
611 YYYY is a search pattern representing an IPv4 [RFC1166] or IPv6
612 [RFC5952] address. The following URL would be used to search for
613 nameserver names that resolve to the "192.0.2.0" address:
614
615 https://example.com/rdap/nameservers?ip=192.0.2.0
616
617 3.2.3. Entity Search
618
619 Syntax: entities?fn=<entity name search pattern>
620
621 Syntax: entities?handle=<entity handle search pattern>
622
623 Searches for entity information by name are specified using this
624 form:
625
626 entities?fn=XXXX
627
628 XXXX is a search pattern representing the "FN" property of an entity
629 (such as a contact, registrant, or registrar) name as specified in
630 Section 5.1 of [RFC7483]. The following URL would be used to find
631 information for entity names matching the "Bobby Joe*" pattern:
632
633 https://example.com/rdap/entities?fn=Bobby%20Joe*
634
635 Searches for entity information by handle are specified using this
636 form:
637
638 entities?handle=XXXX
639
640 XXXX is a search pattern representing an entity (such as a contact,
641 registrant, or registrar) identifier whose syntax is specific to the
642 registration provider. The following URL would be used to find
643 information for entity handles matching the "CID-40*" pattern:
644
645 https://example.com/rdap/entities?handle=CID-40*
646
647 URLs MUST be properly encoded according to the rules of [RFC3986].
648 In the example above, "Bobby Joe*" is encoded to "Bobby%20Joe*".
649
650
651
652
653
654
655
656
657 Newton & Hollenbeck Standards Track [Page 12]
658 RFC 7482 RDAP Query Format March 2015
659
660
661 4. Query Processing
662
663 Servers indicate the success or failure of query processing by
664 returning an appropriate HTTP response code to the client. Response
665 codes not specifically identified in this document are described in
666 [RFC7480].
667
668 4.1. Partial String Searching
669
670 Partial string searching uses the asterisk ('*', US-ASCII value
671 0x002A) character to match zero or more trailing characters. A
672 character string representing multiple domain name labels MAY be
673 concatenated to the end of the search pattern to limit the scope of
674 the search. For example, the search pattern "exam*" will match
675 "example.com" and "example.net". The search pattern "exam*.com" will
676 match "example.com". If an asterisk appears in a search string, any
677 label that contains the non-asterisk characters in sequence plus zero
678 or more characters in sequence in place of the asterisk would match.
679 Additional pattern matching processing is beyond the scope of this
680 specification.
681
682 If a server receives a search request but cannot process the request
683 because it does not support a particular style of partial match
684 searching, it SHOULD return an HTTP 422 (Unprocessable Entity)
685 [RFC4918] response. When returning a 422 error, the server MAY also
686 return an error response body as specified in Section 6 of [RFC7483]
687 if the requested media type is one that is specified in [RFC7480].
688
689 Partial matching is not feasible across combinations of Unicode
690 characters because Unicode characters can be combined with each
691 other. Servers SHOULD NOT partially match combinations of Unicode
692 characters where a legal combination is possible. It should be
693 noted, though, that it may not always be possible to detect cases
694 where a character could have been combined with another character,
695 but was not, because characters can be combined in many different
696 ways.
697
698 Clients should avoid submitting a partial match search of Unicode
699 characters where a Unicode character may be legally combined with
700 another Unicode character or characters. Partial match searches with
701 incomplete combinations of characters where a character must be
702 combined with another character or characters are invalid. Partial
703 match searches with characters that may be combined with another
704 character or characters are to be considered non-combined characters
705 (that is, if character x may be combined with character y but
706 character y is not submitted in the search string, then character x
707 is a complete character and no combinations of character x are to be
708 searched).
709
710
711
712 Newton & Hollenbeck Standards Track [Page 13]
713 RFC 7482 RDAP Query Format March 2015
714
715
716 4.2. Associated Records
717
718 Conceptually, any query-matching record in a server's database might
719 be a member of a set of related records, related in some fashion as
720 defined by the server -- for example, variants of an IDN. The entire
721 set ought to be considered as candidates for inclusion when
722 constructing the response. However, the construction of the final
723 response needs to be mindful of privacy and other data-releasing
724 policies when assembling the RDAP response set.
725
726 Note too that due to the nature of searching, there may be a list of
727 query-matching records. Each one of those is subject to being a
728 member of a set as described in the previous paragraph. What is
729 ultimately returned in a response will be the union of all the sets
730 that has been filtered by whatever policies are in place.
731
732 Note that this model includes arrangements for associated names,
733 including those that are linked by policy mechanisms and names bound
734 together for some other purposes. Note also that returning
735 information that was not explicitly selected by an exact-match
736 lookup, including additional names that match a relatively fuzzy
737 search as well as lists of names that are linked together, may cause
738 privacy issues.
739
740 Note that there might not be a single, static information return
741 policy that applies to all clients equally. Client identity and
742 associated authorizations can be a relevant factor in determining how
743 broad the response set will be for any particular query.
744
745 5. Extensibility
746
747 This document describes path segment specifications for a limited
748 number of objects commonly registered in both RIRs and DNRs. It does
749 not attempt to describe path segments for all of the objects
750 registered in all registries. Custom path segments can be created
751 for objects not specified here using the process described in
752 Section 6 of "HTTP Usage in the Registration Data Access Protocol
753 (RDAP)" [RFC7480].
754
755 Custom path segments can be created by prefixing the segment with a
756 unique identifier followed by an underscore character (0x5F). For
757 example, a custom entity path segment could be created by prefixing
758 "entity" with "custom_", producing "custom_entity". Servers MUST
759 return an appropriate failure status code for a request with an
760 unrecognized path segment.
761
762
763
764
765
766
767 Newton & Hollenbeck Standards Track [Page 14]
768 RFC 7482 RDAP Query Format March 2015
769
770
771 6. Internationalization Considerations
772
773 There is value in supporting the ability to submit either a U-label
774 (Unicode form of an IDN label) or an A-label (US-ASCII form of an IDN
775 label) as a query argument to an RDAP service. Clients capable of
776 processing non-US-ASCII characters may prefer a U-label since this is
777 more visually recognizable and familiar than A-label strings, but
778 clients using programmatic interfaces might find it easier to submit
779 and display A-labels if they are unable to input U-labels with their
780 keyboard configuration. Both query forms are acceptable.
781
782 Internationalized domain and nameserver names can contain character
783 variants and variant labels as described in [RFC4290]. Clients that
784 support queries for internationalized domain and nameserver names
785 MUST accept service provider responses that describe variants as
786 specified in "JSON Responses for the Registration Data Access
787 Protocol (RDAP)" [RFC7483].
788
789 6.1. Character Encoding Considerations
790
791 Servers can expect to receive search patterns from clients that
792 contain character strings encoded in different forms supported by
793 HTTP. It is entirely possible to apply filters and normalization
794 rules to search patterns prior to making character comparisons, but
795 this type of processing is more typically needed to determine the
796 validity of registered strings than to match patterns.
797
798 An RDAP client submitting a query string containing non-US-ASCII
799 characters converts such strings into Unicode in UTF-8 encoding. It
800 then performs any local case mapping deemed necessary. Strings are
801 normalized using Normalization Form C (NFC) [Unicode-UAX15]; note
802 that clients might not be able to do this reliably. UTF-8 encoded
803 strings are then appropriately percent-encoded [RFC3986] in the query
804 URL.
805
806 After parsing any percent-encoding, an RDAP server treats each query
807 string as Unicode in UTF-8 encoding. If a string is not valid UTF-8,
808 the server can immediately stop processing the query and return an
809 HTTP 400 (Bad Request) response.
810
811 When processing queries, there is a difference in handling DNS names,
812 including those with putative U-labels, and everything else. DNS
813 names are treated according to the DNS matching rules as described in
814 Section 3.1 of RFC 1035 [RFC1035] for Non-Reserved LDH (NR-LDH)
815 labels and the matching rules described in Section 5.4 of RFC 5891
816 [RFC5891] for U-labels. Matching of DNS names proceeds one label at
817 a time because it is possible for a combination of U-labels and
818 NR-LDH labels to be found in a single domain or host name. The
819
820
821
822 Newton & Hollenbeck Standards Track [Page 15]
823 RFC 7482 RDAP Query Format March 2015
824
825
826 determination of whether a label is a U-label or an NR-LDH label is
827 based on whether the label contains any characters outside of the
828 US-ASCII letters, digits, or hyphen (the so-called LDH rule).
829
830 For everything else, servers map fullwidth and halfwidth characters
831 to their decomposition equivalents. Servers convert strings to the
832 same coded character set of the target data that is to be looked up
833 or searched, and each string is normalized using the same
834 normalization that was used on the target data. In general, storage
835 of strings as Unicode is RECOMMENDED. For the purposes of
836 comparison, Normalization Form KC (NFKC) [Unicode-UAX15] with case
837 folding is used to maximize predictability and the number of matches.
838 Note the use of case-folded NFKC as opposed to NFC in this case.
839
840 7. Security Considerations
841
842 Security services for the operations specified in this document are
843 described in "Security Services for the Registration Data Access
844 Protocol (RDAP)" [RFC7481].
845
846 Search functionality typically requires more server resources (such
847 as memory, CPU cycles, and network bandwidth) when compared to basic
848 lookup functionality. This increases the risk of server resource
849 exhaustion and subsequent denial of service due to abuse. This risk
850 can be mitigated by developing and implementing controls to restrict
851 search functionality to identified and authorized clients. If those
852 clients behave badly, their search privileges can be suspended or
853 revoked. Rate limiting as described in Section 5.5 of "HTTP Usage in
854 the Registration Data Access Protocol (RDAP)" [RFC7480] can also be
855 used to control the rate of received search requests. Server
856 operators can also reduce their risk by restricting the amount of
857 information returned in response to a search request.
858
859 Search functionality also increases the privacy risk of disclosing
860 object relationships that might not otherwise be obvious. For
861 example, a search that returns IDN variants [RFC6927] that do not
862 explicitly match a client-provided search pattern can disclose
863 information about registered domain names that might not be otherwise
864 available. Implementers need to consider the policy and privacy
865 implications of returning information that was not explicitly
866 requested.
867
868 Note that there might not be a single, static information return
869 policy that applies to all clients equally. Client identity and
870 associated authorizations can be a relevant factor in determining how
871 broad the response set will be for any particular query.
872
873
874
875
876
877 Newton & Hollenbeck Standards Track [Page 16]
878 RFC 7482 RDAP Query Format March 2015
879
880
881 8. References
882
883 8.1. Normative References
884
885 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet
886 host table specification", RFC 952, October 1985,
887 <http://www.rfc-editor.org/info/rfc952>.
888
889 [RFC1035] Mockapetris, P., "Domain names - implementation and
890 specification", STD 13, RFC 1035, November 1987,
891 <http://www.rfc-editor.org/info/rfc1035>.
892
893 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts -
894 Application and Support", STD 3, RFC 1123, October 1989,
895 <http://www.rfc-editor.org/info/rfc1123>.
896
897 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet
898 numbers", RFC 1166, July 1990,
899 <http://www.rfc-editor.org/info/rfc1166>.
900
901 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
902 Requirement Levels", BCP 14, RFC 2119, March 1997,
903 <http://www.rfc-editor.org/info/rfc2119>.
904
905 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
906 Resource Identifier (URI): Generic Syntax", STD 66, RFC
907 3986, January 2005,
908 <http://www.rfc-editor.org/info/rfc3986>.
909
910 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing
911 Architecture", RFC 4291, February 2006,
912 <http://www.rfc-editor.org/info/rfc4291>.
913
914 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing
915 (CIDR): The Internet Address Assignment and Aggregation
916 Plan", BCP 122, RFC 4632, August 2006,
917 <http://www.rfc-editor.org/info/rfc4632>.
918
919 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
920 Authoring and Versioning (WebDAV)", RFC 4918, June 2007,
921 <http://www.rfc-editor.org/info/rfc4918>.
922
923 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of
924 Autonomous System (AS) Numbers", RFC 5396, December 2008,
925 <http://www.rfc-editor.org/info/rfc5396>.
926
927
928
929
930
931
932 Newton & Hollenbeck Standards Track [Page 17]
933 RFC 7482 RDAP Query Format March 2015
934
935
936 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
937 STD 69, RFC 5730, August 2009,
938 <http://www.rfc-editor.org/info/rfc5730>.
939
940 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
941 Contact Mapping", STD 69, RFC 5733, August 2009,
942 <http://www.rfc-editor.org/info/rfc5733>.
943
944 [RFC5890] Klensin, J., "Internationalized Domain Names for
945 Applications (IDNA): Definitions and Document Framework",
946 RFC 5890, August 2010,
947 <http://www.rfc-editor.org/info/rfc5890>.
948
949 [RFC5891] Klensin, J., "Internationalized Domain Names in
950 Applications (IDNA): Protocol", RFC 5891, August 2010,
951 <http://www.rfc-editor.org/info/rfc5891>.
952
953 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
954 Address Text Representation", RFC 5952, August 2010,
955 <http://www.rfc-editor.org/info/rfc5952>.
956
957 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
958 Protocol (HTTP/1.1): Message Syntax and Routing", RFC
959 7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
960
961 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
962 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
963 June 2014, <http://www.rfc-editor.org/info/rfc7231>.
964
965 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the
966 Registration Data Access Protocol (RDAP)", RFC 7480, March
967 2015, <http://www.rfc-editor.org/info/rfC7480>.
968
969 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the
970 Registration Data Access Protocol (RDAP)", RFC 7481, March
971 2015, <http://www.rfc-editor.org/info/rfc7481>.
972
973 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the
974 Registration Data Access Protocol (RDAP)", RFC 7483, March
975 2015, <http://www.rfc-editor.org/info/rfc7483>.
976
977 [RFC7484] Blanchet, M., "Finding the Authoritative Registration Data
978 (RDAP) Service", RFC 7484, March 2015,
979 <http://www.rfc-editor.org/info/rfc7484>.
980
981
982
983
984
985
986
987 Newton & Hollenbeck Standards Track [Page 18]
988 RFC 7482 RDAP Query Format March 2015
989
990
991 [Unicode-UAX15]
992 The Unicode Consortium, "Unicode Standard Annex #15:
993 Unicode Normalization Forms", September 2013,
994 <http://www.unicode.org/reports/tr15/>.
995
996 8.2. Informative References
997
998 [REST] Fielding, R., "Architectural Styles and the Design of
999 Network-based Software Architectures", Ph.D. Dissertation,
1000 University of California, Irvine, 2000,
1001 <http://www.ics.uci.edu/~fielding/pubs/dissertation/
1002 fielding_dissertation.pdf>.
1003
1004 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
1005 September 2004, <http://www.rfc-editor.org/info/rfc3912>.
1006
1007 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and
1008 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007,
1009 March 2005, <http://www.rfc-editor.org/info/rfc4007>.
1010
1011 [RFC4290] Klensin, J., "Suggested Practices for Registration of
1012 Internationalized Domain Names (IDN)", RFC 4290, December
1013 2005, <http://www.rfc-editor.org/info/rfc4290>.
1014
1015 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing
1016 IPv6 Zone Identifiers in Address Literals and Uniform
1017 Resource Identifiers", RFC 6874, February 2013,
1018 <http://www.rfc-editor.org/info/rfc6874>.
1019
1020 [RFC6927] Levine, J. and P. Hoffman, "Variants in Second-Level Names
1021 Registered in Top-Level Domains", RFC 6927, May 2013,
1022 <http://www.rfc-editor.org/info/rfc6927>.
1023
1024 Acknowledgements
1025
1026 This document is derived from original work on RIR query formats
1027 developed by Byron J. Ellacott of APNIC, Arturo L. Servin of LACNIC,
1028 Kaveh Ranjbar of the RIPE NCC, and Andrew L. Newton of ARIN.
1029 Additionally, this document incorporates DNR query formats originally
1030 described by Francisco Arias and Steve Sheng of ICANN and Scott
1031 Hollenbeck of Verisign Labs.
1032
1033 The authors would like to acknowledge the following individuals for
1034 their contributions to this document: Francisco Arias, Marc Blanchet,
1035 Ernie Dainow, Jean-Philippe Dionne, Byron J. Ellacott, Behnam
1036 Esfahbod, John Klensin, John Levine, Edward Lewis, Mark Nottingham,
1037 Kaveh Ranjbar, Arturo L. Servin, Steve Sheng, and Andrew Sullivan.
1038
1039
1040
1041
1042 Newton & Hollenbeck Standards Track [Page 19]
1043 RFC 7482 RDAP Query Format March 2015
1044
1045
1046 Authors' Addresses
1047
1048 Andrew Lee Newton
1049 American Registry for Internet Numbers
1050 3635 Concorde Parkway
1051 Chantilly, VA 20151
1052 United States
1053
1054 EMail: andy@arin.net
1055 URI: http://www.arin.net
1056
1057
1058 Scott Hollenbeck
1059 Verisign Labs
1060 12061 Bluemont Way
1061 Reston, VA 20190
1062 United States
1063
1064 EMail: shollenbeck@verisign.com
1065 URI: http://www.verisignlabs.com/
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097 Newton & Hollenbeck Standards Track [Page 20]
1098
IDN: Internationalized Domain Name
IDNA: Internationalized Domain Names in Applications, a protocol
for the handling of IDNs.
IDN: Internationalized Domain Name, a [fully-qualified] domain name containing one or more labels that are intended to include one or more Unicode code points outside the ASCII range (cf. "domain name", "fully-qualified domain name" and "internationalized domain name" in RFC 8499). IDNA: Internationalized Domain Names in Applications, a protocol for the handling of IDNs. In this document, "IDNA" refers specifically to the version of those specifications known as "IDNA2008" [RFC5980].
While the proposed new text above borders on the painfully pedantic, failure to be specific about these things undermines the technical validity and consistency of the text (making this a technical issue rather than exclusively an editorial one like a missing reference). IDNA2008 [RFC5890 Section 2.3.2.3] is very precise about what an "IDN" is (a definition incorporated by reference in RFC 6365 and consistent with the definition in RFC 8499) , but there are other things around that, e.g., assume either that "IDN" refers to a label, not an FQDN; that an ASCII label, even one in ACE form, does not make the FQDN in which it is imbedded an IDN; that all of the label components of an IDN must be U-labels or A-labels, etc. Without the definition being clear, some of the statements in the document make no sense. A reference to 8499 is suggested above because it is the most recent authoritative definition (and because I didn't write it), but 5980 would be equally legitimate if the authors prefer. Pinning down the IDNA definition is even more important. While there are IDNA2008 references further on in the document, if the question of what the generic term "IDNA" means is left to the imagination of the reader, then the specification is missing language about what to do if, e.g., a query is inconsistent with the U-label form of what is stored in the registry database without mapping. The opportunity for that sort of problem is clearly created by the "performs any local case mapping deemed necessary" statement in Section 6.1 of the document, at least unless that case mapping is constrained to not be applied to domain name labels (which the text definitely does not say).