draft-ietf-weirds-using-http-11.txt   draft-ietf-weirds-using-http-12.txt 
Network Working Group A. Newton Network Working Group A. Newton
Internet-Draft ARIN Internet-Draft ARIN
Intended status: Standards Track B. Ellacott Intended status: Standards Track B. Ellacott
Expires: March 8, 2015 APNIC Expires: March 28, 2015 APNIC
N. Kong N. Kong
CNNIC CNNIC
September 4, 2014 September 24, 2014
HTTP usage in the Registration Data Access Protocol (RDAP) HTTP usage in the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-using-http-11 draft-ietf-weirds-using-http-12
Abstract Abstract
This document is one of a collection that together describe the This document is one of a collection that together describe the
Registration Data Access Protocol (RDAP). It describes how RDAP is Registration Data Access Protocol (RDAP). It describes how RDAP is
transported using the Hypertext Transfer Protocol (HTTP). RDAP is a transported using the Hypertext Transfer Protocol (HTTP). RDAP is a
successor protocol to the very old WHOIS protocol. successor protocol to the very old WHOIS protocol. The purpose of
this document is to clarify the use of standard HTTP mechanisms for
this application.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 8, 2015. This Internet-Draft will expire on March 28, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 16 skipping to change at page 2, line 18
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Design Intents . . . . . . . . . . . . . . . . . . . . . . . 4 3. Design Intents . . . . . . . . . . . . . . . . . . . . . . . 4
4. Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.1. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 5 4.1. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 5
4.2. Accept Header . . . . . . . . . . . . . . . . . . . . . . 5 4.2. Accept Header . . . . . . . . . . . . . . . . . . . . . . 5
4.3. Query Parameters . . . . . . . . . . . . . . . . . . . . 5 4.3. Query Parameters . . . . . . . . . . . . . . . . . . . . 5
5. Types of HTTP Response . . . . . . . . . . . . . . . . . . . 5 5. Types of HTTP Response . . . . . . . . . . . . . . . . . . . 6
5.1. Positive Answers . . . . . . . . . . . . . . . . . . . . 5 5.1. Positive Answers . . . . . . . . . . . . . . . . . . . . 6
5.2. Redirects . . . . . . . . . . . . . . . . . . . . . . . . 6 5.2. Redirects . . . . . . . . . . . . . . . . . . . . . . . . 6
5.3. Negative Answers . . . . . . . . . . . . . . . . . . . . 6 5.3. Negative Answers . . . . . . . . . . . . . . . . . . . . 7
5.4. Malformed Queries . . . . . . . . . . . . . . . . . . . . 6 5.4. Malformed Queries . . . . . . . . . . . . . . . . . . . . 7
5.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 7 5.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 7
5.6. Cross-Origin Resource Sharing . . . . . . . . . . . . . . 7 5.6. Cross-Origin Resource Sharing . . . . . . . . . . . . . . 7
6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 8
7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
8.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 8 8.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 9
9. Internationalization Considerations . . . . . . . . . . . . . 9 9. Internationalization Considerations . . . . . . . . . . . . . 10
9.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 9 9.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 10
9.2. Language Identifiers in Queries and Responses . . . . . . 9 9.2. Language Identifiers in Queries and Responses . . . . . . 10
9.3. Language Identifiers in HTTP Headers . . . . . . . . . . 9 9.3. Language Identifiers in HTTP Headers . . . . . . . . . . 10
10. Contributing Authors and Acknowledgements . . . . . . . . . . 10 10. Contributing Authors and Acknowledgements . . . . . . . . . . 10
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
11.1. Normative References . . . . . . . . . . . . . . . . . . 10 11.1. Normative References . . . . . . . . . . . . . . . . . . 11
11.2. Informative References . . . . . . . . . . . . . . . . . 11 11.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 11 Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 12
Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 12 Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 13
Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 13 Appendix C. Bootstrapping and Redirection . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 Appendix D. Changelog . . . . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction 1. Introduction
This document describes the usage of HTTP[RFC7230] for Registration This document describes the usage of the Hypertext Transfer Protocol
Data Directory Services. The goal of this document is to tie (HTTP) [RFC7230] for registration data directory services. The goal
together usage patterns of HTTP into a common profile applicable to of this document is to tie together usage patterns of HTTP into a
the various types of Directory Services serving Registration Data common profile applicable to the various types of directory services
using RESTful practices. By giving the various Directory Services serving registration data using practices informed by the
common behavior, a single client is better able to retrieve data from Representational State Transfer REST [REST] architectural style. By
Directory Services adhering to this behavior. giving the various directory services common behavior, a single
client is better able to retrieve data from directory services
adhering to this behavior.
The registration data expected to be presented by this service is The registration data expected to be presented by this service is
Internet resource registration data - registration of domain names Internet resource registration data - registration of domain names
and Internet number resources. This data is typically provided by and Internet number resources. These data is typically provided by
WHOIS [RFC3912] services, but the WHOIS protocol is insufficient to WHOIS [RFC3912] services, but the WHOIS protocol is insufficient to
modern registration data service requirements. A replacement modern registration data service requirements. A replacement
protocol is expected to retain the simple transactional nature of protocol is expected to retain the simple transactional nature of
WHOIS, while providing a specification for queries and responses, WHOIS, while providing a specification for queries and responses,
redirection to authoritative sources, support for Internationalized redirection to authoritative sources, support for Internationalized
Domain Names (IDNs, [RFC5890]), and support for localized Domain Names (IDNs, [RFC5890]), and support for localized
registration data such as addresses and organisation or person names. registration data such as addresses and organisation or person names.
In designing these common usage patterns, this document introduces In designing these common usage patterns, this document introduces
considerations for a simple use of HTTP. Where complexity may considerations for a simple use of HTTP. Where complexity may
reside, it is the goal of this document to place it upon the server reside, it is the goal of this document to place it upon the server
and to keep the client as simple as possible. A client and to keep the client as simple as possible. A client
implementation should be possible using common operating system implementation should be possible using common operating system
scripting tools (e.g. bash and wget). scripting tools (e.g. bash and wget).
This is the basic usage pattern for this protocol: This is the basic usage pattern for this protocol:
1. A client issues an HTTP query using GET[RFC7231]. As an example, 1. A client determines an appropriate server to query. Once such
a query for the network registration 192.0.2.0 might be method is described in [I-D.ietf-weirds-bootstrap]. See
http://example.com/ip/192.0.2.0. [I-D.ietf-weirds-rdap-query] Appendix C.
details the various queries used in RDAP.
2. If the receiving server has the information for the query, it 2. A client issues an HTTP (or HTTPS) query using GET [RFC7231]. As
an example, a query for the network registration 192.0.2.0 might
be
http://example.com/ip/192.0.2.0
[I-D.ietf-weirds-rdap-query] details the various queries used in
RDAP.
3. If the receiving server has the information for the query, it
examines the Accept header field of the query and returns a 200 examines the Accept header field of the query and returns a 200
response with a response entity appropriate for the requested response with a response entity appropriate for the requested
format. [I-D.ietf-weirds-json-response] details a response in format. [I-D.ietf-weirds-json-response] details a response in
JSON standardized by the IETF. Other formats may be used as JavaScript Object Notation (JSON). Other, non-standard, formats
well. may be used as well.
3. If the receiving server does not have the information for the 4. If the receiving server does not have the information for the
query but does have knowledge of where the information can be query but does have knowledge of where the information can be
found, it will return a redirection response (3xx) with the found, it will return a redirection response (3xx) with the
Location: header field containing an HTTP(S) URL (Uniform Location: header field containing an HTTP(S) URL (Uniform
Resource Locator) pointing to the information or another server Resource Locator) pointing to the information or another server
known to have knowledge of the location of the information. The known to have knowledge of the location of the information. The
client is expected to re-query using that HTTP URL. client is expected to re-query using that HTTP URL.
4. If the receiving server does not have the information being 5. If the receiving server does not have the information being
requested and does not have knowledge of where the information requested and does not have knowledge of where the information
can be found, it returns a 404 response. can be found, it returns a 404 response.
5. If the receiving server will not answer a request for policy 6. If the receiving server will not answer a request for policy
reasons, it will return an error response (4xx) indicating the reasons, it will return an error response (4xx) indicating the
reason for giving no answer. reason for giving no answer.
It is important to note that it is not the intent of this document to It is not the intent of this document to redefine the meaning and
redefine the meaning and semantics of HTTP. The purpose of this semantics of HTTP. The purpose of this document is to clarify the
document is to clarify the use of standard HTTP mechanisms for this use of standard HTTP mechanisms for this application.
application.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
As is noted in Security and Stability Advisory Committee (SSAC) As is noted in Security and Stability Advisory Committee (SSAC)
Report on WHOIS Terminology and Structure [SAC-051], the term "WHOIS" Report on WHOIS Terminology and Structure [SAC-051], the term "WHOIS"
is overloaded, often referring to a protocol, a service and data. In is overloaded, often referring to a protocol, a service and data. In
accordance with [SAC-051], this document describes the base behavior accordance with [SAC-051], this document describes the base behavior
for a Registration Data Access Protocol (RDAP). [SAC-051] describes for a Registration Data Access Protocol (RDAP). [SAC-051] describes
a protocol profile of RDAP for Domain Name Registries (DNRs), the a protocol profile of RDAP for Domain Name Registries (DNRs), the
Domain Name Registration Data Access Protocol (DNRD-AP). Domain Name Registration Data Access Protocol (DNRD-AP).
In this document, an RDAP client is an HTTP User Agent performing an In this document, an RDAP client is an HTTP user agent performing an
RDAP query, and an RDAP server is an HTTP server providing an RDAP RDAP query, and an RDAP server is an HTTP server providing an RDAP
response. RDAP query and response formats are described in response. RDAP query and response formats are described in
[I-D.ietf-weirds-rdap-query] and [I-D.ietf-weirds-json-response], [I-D.ietf-weirds-rdap-query] and [I-D.ietf-weirds-json-response],
while this document describes how RDAP clients and servers use HTTP while this document describes how RDAP clients and servers use HTTP
to exchange queries and responses. [I-D.ietf-weirds-rdap-sec] to exchange queries and responses. [I-D.ietf-weirds-rdap-sec]
describes security consideration for RDAP. describes security considerations for RDAP.
3. Design Intents 3. Design Intents
There are a few design criteria this document attempts to meet. There are a few design criteria this document attempts to meet.
First, each query is meant to return either zero or one result. With First, each query is meant to return only one path of execution to
the maximum upper bound being set to one, the issuance of redirects obtain an answer. A response may contain an answer, no answer, or a
is simplified to the traditional query/response model used by HTTP redirect, and clients are not expected to fork multiple paths of
[RFC7230]. Should an entity contain more than one result, some of execution to satisfy a query.
which are better served by other servers, the redirection model
becomes much more complicated.
Second, the semantics of the request/response allow for future and/or Second, the semantics of the request/response allow for future and/or
non-standard response formats. In this document, only a JSON non-standard response formats. In this document, only a JSON
[RFC7159] response media type is noted, with the response contents to [RFC7159] response media type is noted, with the response contents to
be described separately (see [I-D.ietf-weirds-json-response]). This be described separately (see [I-D.ietf-weirds-json-response]). This
document only describes how RDAP is transported using HTTP with this document only describes how RDAP is transported using HTTP with this
format. format.
Third, this protocol is intended to be able to make use of the range Third, this protocol is intended to be able to make use of the range
of mechanisms available for use with HTTP. HTTP offers a number of of mechanisms available for use with HTTP. HTTP offers a number of
mechanisms not described further in this document. Operators are mechanisms not described further in this document. Operators are
able to make use of these mechanisms according to their local policy, able to make use of these mechanisms according to their local policy,
including cache control, authorization, compression, and redirection. including cache control, authorization, compression, and redirection.
skipping to change at page 5, line 4 skipping to change at page 5, line 15
[RFC7159] response media type is noted, with the response contents to [RFC7159] response media type is noted, with the response contents to
be described separately (see [I-D.ietf-weirds-json-response]). This be described separately (see [I-D.ietf-weirds-json-response]). This
document only describes how RDAP is transported using HTTP with this document only describes how RDAP is transported using HTTP with this
format. format.
Third, this protocol is intended to be able to make use of the range Third, this protocol is intended to be able to make use of the range
of mechanisms available for use with HTTP. HTTP offers a number of of mechanisms available for use with HTTP. HTTP offers a number of
mechanisms not described further in this document. Operators are mechanisms not described further in this document. Operators are
able to make use of these mechanisms according to their local policy, able to make use of these mechanisms according to their local policy,
including cache control, authorization, compression, and redirection. including cache control, authorization, compression, and redirection.
HTTP also benefits from widespread investment in scalability, HTTP also benefits from widespread investment in scalability,
reliability, and performance, and widespread programmer understanding reliability, and performance, and widespread programmer understanding
of client behaviours for RESTful web services, reducing the cost to of client behaviours for web services styled after REST [REST],
deploy Registration Data Directory Services and clients. reducing the cost to deploy Registration Data Directory Services and
clients.
4. Queries 4. Queries
4.1. HTTP Methods 4.1. HTTP Methods
Clients SHOULD use either the HTTP GET or HEAD methods (see Clients SHOULD use either the HTTP GET or HEAD methods (see
[RFC7231]). The GET method should be used to retreive a response [RFC7231]). The GET method can be used to retrieve a response body.
body. The HEAD method can be used to determine existence of data on The HEAD method can be used to determine existence of data on the
the server. Servers are under no obligation to support other HTTP server. Servers are under no obligation to support other HTTP
methods. methods, therefore clients using other methods will likely not
interoperate properly.
Clients MUST support HTTPS as well as HTTP.
4.2. Accept Header 4.2. Accept Header
To indicate to servers that an RDAP response is desired, clients To indicate to servers that an RDAP response is desired, clients
include an Accept: header field with an RDAP specific JSON media include an Accept: header field with an RDAP specific JSON media
type, the generic JSON media type, or both. Servers receiving an type, the generic JSON media type, or both. Servers receiving an
RDAP request return an entity with a Content-Type: header containing RDAP request return an entity with a Content-Type: header containing
the RDAP specific JSON media type. the RDAP specific JSON media type.
This specification does not define the responses a server returns to This specification does not define the responses a server returns to
skipping to change at page 5, line 44 skipping to change at page 6, line 11
Servers MUST ignore unknown query parameters. Use of unknown query Servers MUST ignore unknown query parameters. Use of unknown query
parameters for cache-busting is described in Appendix B. parameters for cache-busting is described in Appendix B.
5. Types of HTTP Response 5. Types of HTTP Response
This section describes the various types of responses a server may This section describes the various types of responses a server may
send to a client. While no standard HTTP response code is forbidden send to a client. While no standard HTTP response code is forbidden
in usage, at a minimum clients SHOULD understand the response codes in usage, at a minimum clients SHOULD understand the response codes
described in this section as they will be in common use by servers. described in this section as they will be in common use by servers.
It is expected that usage of response codes and types for this While some clients may be constructed with simple tooling that does
application not defined here will be described in subsequent not account for all of these response codes, a more robust client
accounting for these codes will likely provide a better user
experience. It is expected that usage of response codes and types
for this application not defined here will be described in subsequent
documents. documents.
5.1. Positive Answers 5.1. Positive Answers
If a server has the information requested by the client and wishes to If a server has the information requested by the client and wishes to
respond to the client with the information according to its policies, respond to the client with the information according to its policies,
it returns that answer in the body of a 200 response. it returns that answer in the body of a 200 response.
5.2. Redirects 5.2. Redirects
skipping to change at page 6, line 25 skipping to change at page 6, line 44
the URL to follow it. Servers are under no obligation to return a the URL to follow it. Servers are under no obligation to return a
URL conformant to [I-D.ietf-weirds-rdap-query]. URL conformant to [I-D.ietf-weirds-rdap-query].
For this application, such an example of a permanent move might be a For this application, such an example of a permanent move might be a
Top Level Domain (TLD) operator informing a client the information Top Level Domain (TLD) operator informing a client the information
being sought can be found with another TLD operator (i.e. a query for being sought can be found with another TLD operator (i.e. a query for
the domain bar in foo.example is found at http://foo.example/domain/ the domain bar in foo.example is found at http://foo.example/domain/
bar). bar).
For example, if the client sends For example, if the client sends
http://serv1.example.com/weirds/domain/example.com, the server
redirecting to https://serv2.example.net/weirds2/ would set the http://serv1.example.com/weirds/domain/example.com
Location: field to the value:
https://serv2.example.net/weirds2/domain/example.com. the server redirecting to
https://serv2.example.net/weirds2/
would set the Location: field to the value
https://serv2.example.net/weirds2/domain/example.com
5.3. Negative Answers 5.3. Negative Answers
If a server wishes to respond that it has an empty result set, it If a server wishes to respond that it has an empty result set (that
returns a 404 response code. Optionally, it MAY include additional is, no data appropriately satisfying the query), it returns a 404
information regarding the negative answer in the HTTP entity body. response code. Optionally, it MAY include additional information
regarding the negative answer in the HTTP entity body.
If a server wishes to inform the client that information about the If a server wishes to inform the client that information about the
query is available, but cannot include the information in the query is available, but cannot include the information in the
response to the client for policy reasons, the server MUST respond response to the client for policy reasons, the server MUST respond
with an appropriate response code out of HTTP's 4xx range. Clients with an appropriate response code out of HTTP's 4xx range. Clients
MAY retry the query based on the respective response code. MAY retry the query based on the respective response code.
5.4. Malformed Queries 5.4. Malformed Queries
If a server receives a query which it cannot interpret as an RDAP If a server receives a query which it cannot interpret as an RDAP
query, it returns a 400 response code. Optionally, it MAY include query, it returns a 400 response code. Optionally, it MAY include
additional information regarding this negative answer in the HTTP additional information regarding this negative answer in the HTTP
entity body. entity body.
5.5. Rate Limits 5.5. Rate Limits
Some servers apply rate limits to deter address scraping and other Some servers apply rate limits to deter address scraping and other
abuses. When a server declines to answer a query due to rate limits, abuses. When a server declines to answer a query due to rate limits,
it returns a 429 response code as described in [RFC6585]. A client it returns a 429 response code as described in [RFC6585]. A client
that receives a 429 response SHOULD decrease its query rate, and that receives a 429 response SHOULD decrease its query rate, and
honor the Retry-After header field if one is present. honor the Retry-After header field if one is present. Clients that
do not honor the Retry-After header may stricter limits placed upon
them.
Note that this is not a defense against denial-of-service attacks, Note that this is not a defense against denial-of-service attacks,
since a malicious client could ignore the code and continue to send since a malicious client could ignore the code and continue to send
queries at a high rate. A server might use another response code if queries at a high rate. A server might use another response code if
it did not wish to reveal to a client that rate limiting is the it did not wish to reveal to a client that rate limiting is the
reason for the denial of a reply. reason for the denial of a reply.
5.6. Cross-Origin Resource Sharing 5.6. Cross-Origin Resource Sharing
When responding to queries, it is RECOMMENDED that servers use the When responding to queries, it is RECOMMENDED that servers use the
Access-Control-Allow-Origin header field, as specified by Access-Control-Allow-Origin header field, as specified by
[W3C.CR-cors-20130129]. As the use of RDAP is for public resources, [W3C.CR-cors-20130129]. As the use of RDAP is for public resources,
a value of "*" is suitable for most cases. a value of "*" is suitable for most cases.
This header (often called the CORS header), helps in-browser web This header (often called the CORS header) helps in-browser web
applications by lifting the "same-origin" restriction. applications by lifting the "same-origin" restriction.
6. Extensibility 6. Extensibility
For extensibility purposes, this document defines an IANA registry For extensibility purposes, this document defines an IANA registry
for prefixes used in JSON [RFC7159] data serialization and URI path for prefixes used in JSON [RFC7159] data serialization and URI path
segments (see Section 8). segments (see Section 8).
Prefixes and identifiers SHOULD only consist of the alphabetic ASCII Prefixes and identifiers SHOULD only consist of the alphabetic ASCII
characters A through Z in both uppercase and lowercase, the numerical characters A through Z in both uppercase and lowercase, the numerical
skipping to change at page 8, line 24 skipping to change at page 9, line 4
clients MUST support HTTPS. clients MUST support HTTPS.
This document made recommendations for server implementations against This document made recommendations for server implementations against
denial-of-service (Section 5.5) and interoperability with existing denial-of-service (Section 5.5) and interoperability with existing
security mechanism in HTTP clients (Section 5.6). security mechanism in HTTP clients (Section 5.6).
Additional security considerations to the RDAP protocol are covered Additional security considerations to the RDAP protocol are covered
in [I-D.ietf-weirds-rdap-sec]. in [I-D.ietf-weirds-rdap-sec].
8. IANA Considerations 8. IANA Considerations
8.1. RDAP Extensions Registry 8.1. RDAP Extensions Registry
This specification proposes an IANA registry for RDAP extensions. This specification proposes an IANA registry for RDAP extensions.
The purpose of this registry is to ensure uniqueness of extension The purpose of this registry is to ensure uniqueness of extension
identifiers. The extension identifier is used as a prefix in JSON identifiers. The extension identifier is used as a prefix in JSON
names and as a prefix of path segments in RDAP URLs. names and as a prefix of path segments in RDAP URLs.
The production rule for these identifiers is specified in Section 6. The production rule for these identifiers is specified in Section 6.
In accordance with RFC5226, the IANA policy for assigning new values In accordance with [RFC5226], the IANA policy for assigning new
shall be Specification Required: values and their meanings must be values shall be Specification Required: values and their meanings
documented in an RFC or in some other permanent and readily available must be documented in an RFC or in some other permanent and readily
reference, in sufficient detail that interoperability between available reference, in sufficient detail that interoperability
independent implementations is possible. between independent implementations is possible.
The following is a preliminary template for an RDAP extension The following is a preliminary template for an RDAP extension
registration: registration:
Extension identifier: the identifier of the extension Extension identifier: the identifier of the extension
Registry operator: the name of the registry operator Registry operator: the name of the registry operator
Published specification: RFC number, bibliographical reference or Published specification: RFC number, bibliographical reference or
URL to a permanent and readily available specification URL to a permanent and readily available specification
skipping to change at page 9, line 4 skipping to change at page 9, line 28
The following is a preliminary template for an RDAP extension The following is a preliminary template for an RDAP extension
registration: registration:
Extension identifier: the identifier of the extension Extension identifier: the identifier of the extension
Registry operator: the name of the registry operator Registry operator: the name of the registry operator
Published specification: RFC number, bibliographical reference or Published specification: RFC number, bibliographical reference or
URL to a permanent and readily available specification URL to a permanent and readily available specification
Person & email address to contact for further information: The Person & email address to contact for further information: The
names and email addresses of individuals for contact regarding names and email addresses of individuals for contact regarding
this registry entry this registry entry
Intended usage: brief reasons for this registry entry Intended usage: brief reasons for this registry entry (as defined
by [RFC5226].
The following is an example of a registration in the RDAP extension The following is an example of a registration in the RDAP extension
registry: registry:
Extension identifier: lunarNic Extension identifier: lunarNic
Registry operator: The Registry of the Moon, LLC Registry operator: The Registry of the Moon, LLC
Published specification: http://www.example/moon_apis/rdap Published specification: http://www.example/moon_apis/rdap
skipping to change at page 9, line 50 skipping to change at page 10, line 31
language identifiers whenever they are available, thus allowing language identifiers whenever they are available, thus allowing
clients to process and display the data accordingly. clients to process and display the data accordingly.
The mechanism for including a language identifier in a response will The mechanism for including a language identifier in a response will
be defined in subsequent documents describing specific response be defined in subsequent documents describing specific response
formats. formats.
9.3. Language Identifiers in HTTP Headers 9.3. Language Identifiers in HTTP Headers
Given the description of the use of language identifiers in Given the description of the use of language identifiers in
Section 9.2, unless otherwise specified servers SHOULD ignore the Section 9.2, unless otherwise specified, servers SHOULD ignore the
HTTP [RFC7231] Accept-Language header field when formulating HTTP HTTP [RFC7231] Accept-Language header field when formulating HTTP
entity responses, so that clients do not conflate the Accept-Language entity responses, so that clients do not conflate the Accept-Language
header with the 'lang' values in the entity body. header with the 'lang' values in the entity body.
However, servers MAY return language identifiers in the Content- However, servers MAY return language identifiers in the Content-
Language header field so as to inform clients of the intended Language header field so as to inform clients of the intended
language of HTTP layer messages. language of HTTP layer messages.
10. Contributing Authors and Acknowledgements 10. Contributing Authors and Acknowledgements
John Levine provided text to tighten up the Accept header field usage John Levine provided text to tighten up the Accept header field usage
and the text for the section on 429 responses. and the text for the section on 429 responses.
Marc Blanchet provided some clarifying text regarding the use of URLs Marc Blanchet provided some clarifying text regarding the use of URLs
with redirects, as well as very useful feedback during WGLC. with redirects, as well as very useful feedback during WGLC.
Normative language reviews were provided by Murray S. Kucherawy and Normative language reviews were provided by Murray S. Kucherawy,
Andrew Sullivan. Andrew Sullivan, Tom Harrison, Ed Lewis, and Alexander Mayrhofer.
Jean-Phillipe Dionne provided text for the Security Considerations Jean-Phillipe Dionne provided text for the Security Considerations
section. section.
The concept of the redirector server informatively discussed in
Appendix C was documented by Carlos M. Martinez and Gerardo Rada of
LACNIC and Linlin Zhou of CNNIC and subsequently incorporated into
this document.
This document is the work product of the IETF's WEIRDS working group,
of which Olaf Kolkman and Murray Kucherawy were chairs.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-weirds-bootstrap]
Blanchet, M. and G. Leclanche, "Finding the Authoritative
Registration Data (RDAP) Service", draft-ietf-weirds-
bootstrap-06 (work in progress), September 2014.
[I-D.ietf-weirds-json-response] [I-D.ietf-weirds-json-response]
Newton, A. and S. Hollenbeck, "JSON Responses for the Newton, A. and S. Hollenbeck, "JSON Responses for the
Registration Data Access Protocol (RDAP)", draft-ietf- Registration Data Access Protocol (RDAP)", draft-ietf-
weirds-json-response-08 (work in progress), August 2014. weirds-json-response-08 (work in progress), August 2014.
[I-D.ietf-weirds-rdap-query] [I-D.ietf-weirds-rdap-query]
Newton, A. and S. Hollenbeck, "Registration Data Access Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol Query Format", draft-ietf-weirds-rdap-query-13 Protocol Query Format", draft-ietf-weirds-rdap-query-13
(work in progress), August 2014. (work in progress), August 2014.
skipping to change at page 11, line 8 skipping to change at page 11, line 47
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005. Identifiers (IRIs)", RFC 3987, January 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status
Codes", RFC 6585, April 2012. Codes", RFC 6585, April 2012.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014. 2014.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014. (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[W3C.CR-cors-20130129] [W3C.CR-cors-20130129]
Kesteren, A., "Cross-Origin Resource Sharing", World Wide Kesteren, A., "Cross-Origin Resource Sharing", World Wide
Web Consortium Candidate Recommendation CR-cors-20130129, Web Consortium Candidate Recommendation CR-cors-20130129,
January 2013, January 2013,
<http://www.w3.org/TR/2013/CR-cors-20130129>. <http://www.w3.org/TR/2013/CR-cors-20130129>.
11.2. Informative References 11.2. Informative References
[REST] Fielding, R. and R. Taylor, "Principled Design of the
Modern Web Architecture", ACM Transactions on Internet
Technology Vol. 2, No. 2, May 2002.
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004. September 2004.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5890] Klensin, J., "Internationalized Domain Names for [RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010. RFC 5890, August 2010.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS [SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS
Terminology and Structure", September 2011. Terminology and Structure", September 2011.
[lacnic-joint-whois]
LACNIC, "LACNIC Joint WHOIS Implementation", 2005,
<ftp://anonymous@ftp.registro.br/pub/gter/gter20/02-
jwhois-lacnic.pdf>.
Appendix A. Protocol Example Appendix A. Protocol Example
To demonstrate typical behaviour of an RDAP client and server, the To demonstrate typical behaviour of an RDAP client and server, the
following is an example of an exchange, including a redirect. The following is an example of an exchange, including a redirect. The
data in the response has been elided for brevity, as the data format data in the response has been elided for brevity, as the data format
is not described in this document. The media type used here is is not described in this document. The media type used here is
described in [I-D.ietf-weirds-json-response]. described in [I-D.ietf-weirds-json-response].
An example of an RDAP client and server exchange: An example of an RDAP client and server exchange:
skipping to change at page 13, line 9 skipping to change at page 14, line 9
parameters, this is unlikely to have any known side effects. parameters, this is unlikely to have any known side effects.
An example of using an unknown query parameter to bust caches: An example of using an unknown query parameter to bust caches:
http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123 http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123
Use of an unknown parameter to overcome misbehaving caches is not Use of an unknown parameter to overcome misbehaving caches is not
part of any specification and is offered here for informational part of any specification and is offered here for informational
purposes. purposes.
Appendix C. Changelog Appendix C. Bootstrapping and Redirection
The traditional deployment model of WHOIS [RFC3912] does not provide
a mechanism for determining the authoritative source for information.
Some approaches have been implemented in the past, most notably the
Joint WHOIS [lacnic-joint-whois] initiative. However, among other
shortcomings, Joint WHOIS is implemented using proxies and server-
side referrals.
These issues are solved in RDAP using HTTP redirects and
bootstrapping. Bootstrapping is discussed in
[I-D.ietf-weirds-bootstrap]. In constrained environments, the
processes outlined in [I-D.ietf-weirds-bootstrap] may not be viable
and there may be need for servers acting as a "redirector".
Redirector servers issue HTTP redirects to clients using a
redirection table informed by [I-D.ietf-weirds-bootstrap]. Figure 2
diagrams a client using a redirector for bootstrapping.
REDIRECTOR ARIN
RDAP RDAP
. .
| |
Q: 23.1.1.1? -----------------> | |
| |
<---------- HTTP 301 --------| |
('Try ARIN RDAP') | |
| |
|
Q: 23.1.1.1? -------------------------------> |
|
<---------- HTTP 200 --------------------- |
(JSON response is returned) |
|
|
.
Querying RDAP data for 23.1.1.1
Figure 2
In some cases, particularly sub-delegations made between RIRs known
as "ERX space" and transfers of networks, multiple HTTP redirects
will be issued. Figure 3 shows such a scenario.
REDIRECTOR LACNIC ARIN
RDAP RDAP RDAP
. . .
Q: 23.1.1.1? ----> | | |
| | |
<-- HTTP 301 --- | | |
('Try LACNIC') | | |
| | |
| | |
Q: 23.1.1.1? -----------------> | |
| |
<---------- HTTP 301 --------| |
('Try ARIN RDAP') | |
| |
|
Q: 23.1.1.1? -------------------------------> |
|
<---------- HTTP 200 --------------------- |
(JSON response is returned) |
|
|
.
Querying RDAP data for data that has been transfered
Figure 3
Appendix D. Changelog
RFC Editor: Please remove this section. RFC Editor: Please remove this section.
Initial WG -00: Updated to working group document 2012-September-20 Initial WG -00: Updated to working group document 2012-September-20
-01 -01
* Updated for the sections moved to the JSON responses draft. * Updated for the sections moved to the JSON responses draft.
* Simplified media type, removed "level" parameter. * Simplified media type, removed "level" parameter.
skipping to change at page 16, line 7 skipping to change at page 18, line 36
* Explanded SSAC (comment by Sean Turner) * Explanded SSAC (comment by Sean Turner)
* Added text about HEAD and GET. * Added text about HEAD and GET.
-11 -11
* Changed JSON reference to RFC 7159. * Changed JSON reference to RFC 7159.
* Noted that clients MUST support HTTPS. * Noted that clients MUST support HTTPS.
-12
* Added reference to REST.
* Numerous textual clarifications.
* Added an actual reference to RFC 5226 instead of just talking
about it.
* A reference to draft-ietf-weirds-bootstrap was added.
* Included a section on redirectors.
Authors' Addresses Authors' Addresses
Andrew Lee Newton Andrew Lee Newton
American Registry for Internet Numbers American Registry for Internet Numbers
3635 Concorde Parkway 3635 Concorde Parkway
Chantilly, VA 20151 Chantilly, VA 20151
US US
Email: andy@arin.net Email: andy@arin.net
URI: http://www.arin.net URI: http://www.arin.net
 End of changes. 44 change blocks. 
81 lines changed or deleted 219 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/