mirror of
https://github.com/google/nomulus.git
synced 2025-05-21 11:49:37 +02:00
Add markdown documentation for RDAP
------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=172776631
This commit is contained in:
mountford
jianglai
parent
4828417c73
commit
f89ad27e17
1 changed files with 336 additions and 0 deletions
336
docs/rdap.md
Normal file
336
docs/rdap.md
Normal file
|
|
@ -0,0 +1,336 @@
|
|||
# RDAP user's guide
|
||||
|
||||
[RDAP](https://www.icann.org/rdap) is a JSON REST protocol, served over HTTPS,
|
||||
for retrieving registry information. It returns data similar to the WHOIS
|
||||
service, but in a JSON-structured format. This document describes the Nomulus
|
||||
system's support for the RDAP protocol.
|
||||
|
||||
## Quick example {#quick_example}
|
||||
|
||||
RDAP information is available via regular Web queries. For example, if your App
|
||||
Engine project ID is `project-id`, and `tld` is a TLD managed by that instance
|
||||
of Nomulus, enter the following in a Web browser:
|
||||
|
||||
```
|
||||
https://project-id.appspot.com/rdap/domains?name=*.tld
|
||||
```
|
||||
|
||||
You should get back a long string of JSON apparent gobbledygook, listing the
|
||||
first 100 domains under that TLD. There are a number of online JSON formatters;
|
||||
paste the result string into one of them, and you should be able to scroll
|
||||
though and see the information. You can also use the Chrome browser developer
|
||||
console's network pane, then send the request and look at the Preview tab to see
|
||||
the response in an expandable tree format.
|
||||
|
||||
## Introduction to RDAP {#introduction}
|
||||
|
||||
RDAP is a next-generation protocol for dissemination of registry data. It is
|
||||
eventually intended to replace the WHOIS protocol. RDAP was defined in 2015 in a
|
||||
series of RFCs:
|
||||
|
||||
* [RFC 7480: HTTP Usage in the Registration Data Access Protocol
|
||||
(RDAP)](https://tools.ietf.org/html/rfc7480)
|
||||
* [RFC 7481: Security Services for the Registration Data Access Protocol
|
||||
(RDAP)](https://tools.ietf.org/html/rfc7481)
|
||||
* [RFC 7482: Registration Data Access Protocol (RDAP) Query
|
||||
Format](https://tools.ietf.org/html/rfc7482)
|
||||
* [RFC 7483: JSON Responses for the Registration Data Access Protocol
|
||||
(RDAP)](https://tools.ietf.org/html/rfc7483)
|
||||
* [RFC 7484: Finding the Authoritative Registration Data (RDAP)
|
||||
Service](https://tools.ietf.org/html/rfc7484)
|
||||
|
||||
Using RDAP, users can send in standard HTTP requests with specific URLs (such as
|
||||
`.../rdap/domain/example.com` to get information about the domain `example.com`,
|
||||
or `.../rdap/domains?name=ex*.com` to get information about domains beginning
|
||||
with `ex` and having the TLD `.com`), and receive back a JSON response
|
||||
containing the requested data. The data is more or less the same information
|
||||
that WHOIS provides today, but formatted in a more standardized and
|
||||
machine-readable manner.
|
||||
|
||||
ICANN is sponsoring a one-year [RDAP Pilot
|
||||
Program](https://www.icann.org/news/announcement-2017-09-05-en), allowing
|
||||
registries to implement RDAP and, if desired, make modifications to the protocol
|
||||
to support desired extra features. Nomulus is participating in this program. The
|
||||
experimental extra features supported by Nomulus are described later.
|
||||
|
||||
## Nomulus RDAP request endpoints {#endpoints}
|
||||
|
||||
The suite of URL endpoint paths is listed below. The paths should be tacked onto
|
||||
the usual App Engine server name. For example, if the App Engine project ID is
|
||||
`project-id`, the full path for a domain lookup of domain iam.soy would be:
|
||||
|
||||
```
|
||||
https://project-id.appspot.com/rdap/domain/iam.soy
|
||||
```
|
||||
|
||||
The search endpoints (those with a query string) can return more than one match.
|
||||
The maximum result set size is limited by a configuration parameter, currently
|
||||
set to 100.
|
||||
|
||||
### /rdap/autnum/ {#autnum}
|
||||
|
||||
The RDAP protocol defines an autnum endpoint, but autonomous system numbers are
|
||||
not supported by registries, so queries of this type will always return an
|
||||
error.
|
||||
|
||||
### /rdap/domain/ {#domain}
|
||||
|
||||
Look up a single domain by name. The full domain name is specified at the end of
|
||||
the path.
|
||||
|
||||
```
|
||||
/rdap/domain/abc.tld
|
||||
```
|
||||
|
||||
### /rdap/domains? {#domains}
|
||||
|
||||
Search for one or more domains. The RDAP specification supports three kinds of
|
||||
searches: by domain name, by nameserver name, or by nameserver IP address. It
|
||||
defines a wildcard syntax, but allows the server to limit how wildcards are
|
||||
used; Nomulus' wildcard rules are described below.
|
||||
|
||||
A maximum of 100 domains will be returned in response to a single query. If more
|
||||
than one domain is returned, only data about the domain itself is included. If a
|
||||
single domain is returned, associated nameservers and contacts are also returned
|
||||
(except that requests not authenticated as associated with the registrar of the
|
||||
domain will not see contact information).
|
||||
|
||||
#### Search by domain name
|
||||
|
||||
Domain searches by domain name use the `name` query parameter. The query value
|
||||
can be a domain name without wildcards, in which case the results will be the
|
||||
same as a lookup of that name.
|
||||
|
||||
```
|
||||
/rdap/domains?name=abc.tld
|
||||
```
|
||||
|
||||
The query value can include a wildcard at the end of the string. There must be
|
||||
at least two characters before the wildcard, to avoid very large queries.
|
||||
|
||||
```
|
||||
/rdap/domains?name=abc*
|
||||
```
|
||||
|
||||
Ordinarily, the wildcard must appear at the end of the string. But as a special
|
||||
exception, the wildcard can be followed by .tld to indicate that only domains
|
||||
from a specific TLD are desired. In this case, two characters are not required
|
||||
before the wildcard.
|
||||
|
||||
```
|
||||
/rdap/domains?name=a*.tld
|
||||
/rdap/domains?name=*.tld
|
||||
```
|
||||
|
||||
#### Search by nameserver name
|
||||
|
||||
Domain searches by nameserver name use the `nsLdhName` query parameter (LDH
|
||||
means letters, digits, hyphen; Unicode nameserver names should be specified in
|
||||
punycode form).
|
||||
|
||||
```
|
||||
/rdap/domains?nsLdhName=ns1.abc.tld
|
||||
```
|
||||
|
||||
The query value can include a wildcard at the end of the string. There must be
|
||||
at least two characters before the wildcard.
|
||||
|
||||
```
|
||||
/rdap/domains?nsLdhName=ns*
|
||||
```
|
||||
|
||||
As a special exception, the wildcard can be followed by a domain name managed by
|
||||
the Nomulus system to indicate that only nameservers subordinate to that domain
|
||||
are desired. The two initial characters are not required in this case.
|
||||
|
||||
```
|
||||
/rdap/domains?nsLdhName=n*.localdomain.how
|
||||
/rdap/domains?nsLdhName=*.localdomain.how
|
||||
```
|
||||
|
||||
#### Search by nameserver IP address
|
||||
|
||||
Domain searches by nameserver IP address use the `nsIp` query parameter.
|
||||
Wildcards are not supported for IP address lookup.
|
||||
|
||||
```
|
||||
/rdap/domains?nsIp=1.2.3.4
|
||||
```
|
||||
|
||||
### /rdap/entity/ {#entity}
|
||||
|
||||
Look up a single entity by name. The entity ID is specified at the end of the
|
||||
path. Two types of entities can be looked up: registrars (looked up by IANA
|
||||
registrar ID) and contacts (lookup up by ROID). Registrar contacts are also
|
||||
returned in results as entities, but cannot be looked up by themselves; they
|
||||
only appear as part of information about a registrar.
|
||||
|
||||
```
|
||||
/rdap/entity/registrar-id
|
||||
/rdap/entity/ROID
|
||||
```
|
||||
|
||||
### /rdap/entities? {#entities}
|
||||
|
||||
Search for one or more entities (registrars or contacts). The RDAP specification
|
||||
supports two kinds of searches: by full name or by handle. In either case,
|
||||
requests not authenticated as associated with the registrar owning a contact
|
||||
will not see personal data (name, address, email, phone, etc.) for the contact.
|
||||
The visibility of registrar information, including registrar contacts, is
|
||||
determined by the registrar's chosen WHOIS visibility settings.
|
||||
|
||||
#### Search by full name
|
||||
|
||||
Entity searches by full name use the `fn` query parameter. Results can include
|
||||
contacts with a matching name, registrars with a matching registrar name, or
|
||||
both. For contacts, the name used is the internationalized postal info name, if
|
||||
present, or the localized postal info name otherwise.
|
||||
|
||||
```
|
||||
/rdap/entities?fn=Joseph%20Smith
|
||||
/rdap/entities?fn=tucows
|
||||
```
|
||||
|
||||
A trailing wildcard is allowed, but at least two characters must precede the
|
||||
wildcard.
|
||||
|
||||
```
|
||||
/rdap/entities?fn=Bobby%20Joe*
|
||||
/rdap/entities?fn=tu*
|
||||
```
|
||||
|
||||
#### Search by handle
|
||||
|
||||
Entity searches by handle use the `handle` query parameter. Results can include
|
||||
contacts with a matching ROID, registrars with a matching IANA registrar number,
|
||||
or both.
|
||||
|
||||
```
|
||||
/rdap/entities?handle=12
|
||||
/rdap/entities?handle=ROID-1234
|
||||
```
|
||||
|
||||
A trailing wildcard is allowed, with at least two character preceding it.
|
||||
However, wildcard matching is only performed for contacts. Registrars will never
|
||||
be returned for a wildcard entity search.
|
||||
|
||||
```
|
||||
/rdap/entities?handle=ROID-12*
|
||||
```
|
||||
|
||||
### /rdap/help/ {#help}
|
||||
|
||||
Retrieve help information. The desired help topic is specified at the end of the
|
||||
path; if no topic is specified, the help index is returned.
|
||||
|
||||
```
|
||||
/rdap/help/
|
||||
/rdap/help/index
|
||||
/rdap/help/syntax
|
||||
```
|
||||
|
||||
### /rdap/ip/ {#ip}
|
||||
|
||||
IP addresses are not supported by registries, so queries of this type will
|
||||
always return an error.
|
||||
|
||||
### /rdap/nameserver/ {#nameserver}
|
||||
|
||||
Look up a single nameserver by fully qualified host name. The name is specified
|
||||
at the end of the path.
|
||||
|
||||
```
|
||||
/rdap/nameserver/ns1.abc.tld
|
||||
```
|
||||
|
||||
### /rdap/nameservers? {#nameserver}
|
||||
|
||||
Search for one or more nameservers. The RDAP specification supports two kinds of
|
||||
searches: by name or by IP address. The format for both is the same as for the
|
||||
equivalent domain search by nameserver name and IP address, except that the
|
||||
query parameters used are name and ip. See the domain search section above for
|
||||
details.
|
||||
|
||||
```
|
||||
/rdap/nameservers?name=ns1.abc.tld
|
||||
/rdap/nameservers?name=ns*
|
||||
/rdap/nameservers?name=*.locallydefineddomain.how
|
||||
/rdap/nameservers?ip=1.2.3.4
|
||||
```
|
||||
|
||||
## Experimental features {#experimental_features}
|
||||
|
||||
As part of the RDAP Pilot Project, Nomulus incorporates a few extra features in
|
||||
the RDAP endpoints.
|
||||
|
||||
### Authentication {#authentication}
|
||||
|
||||
The RDAP RFCs do not include support for authentication or access controls. We
|
||||
have implemented an experimental version that allows for authenticated access to
|
||||
sensitive data such as contact names and addresses (a longtime concern with
|
||||
WHOIS). We do this by leveraging the existing authentication/authorization
|
||||
functionality of Nomulus' registrar console. Requests which can be authenticated
|
||||
as coming from a specific registrar have access to all information about that
|
||||
registrar's contact. Requests authenticated as coming from administrators of the
|
||||
App Engine project have access to all contact information. In other cases, the
|
||||
sensitive data will be hidden, and only the contact ROIDs and roles will be
|
||||
displayed.
|
||||
|
||||
The registrar console uses the App Engine Users API to authenticate users. When
|
||||
a request comes in, App Engine attempts to authenticate the user's email
|
||||
address. If authentication is successful, the email address is then checked
|
||||
against all registrar contacts in the system. If Nomulus is able to find a
|
||||
matching registrar contact which has the `allow_console_access` permission, the
|
||||
request is authorized for the associated registrar.
|
||||
|
||||
RDAP uses the same logic, but the registrar association is used only to
|
||||
determine whether the request can see sensitive contact information (and deleted
|
||||
items, as described in the section about the `includeDeleted` parameter).
|
||||
Unauthenticated requests can still retrieve data, but that data will not be
|
||||
visible.
|
||||
|
||||
To use RDAP in an authenticated fashion, first set up your email address for use
|
||||
in the registrar console, as described elsewhere. Then check that you have
|
||||
access to the console by loading the page:
|
||||
|
||||
```
|
||||
https://project-id.appspot.com/registrar
|
||||
```
|
||||
|
||||
If you can see the registrar console, you are logged in correctly. Then change
|
||||
the URL to an RDAP query on that same Nomulus instance, and you will be able to
|
||||
see all data for your associated registrar.
|
||||
|
||||
### `registrar` parameter {#registrar_parameter}
|
||||
|
||||
Ordinarily, all matching domains, hosts and contacts are included in the
|
||||
returned result set. A request can specify that only items owned by a specific
|
||||
registrar be included, by adding an extra parameter:
|
||||
|
||||
```
|
||||
/rdap/domains?name=*.tld&includeDeleted=true
|
||||
```
|
||||
|
||||
This could be useful when designing a registrar user interface that uses RDAP as
|
||||
a backend. Note that this parameter only excludes items; it does not cause items
|
||||
to be shown that otherwise would not.
|
||||
|
||||
### `includeDeleted` parameter {#includedeleted_parameter}
|
||||
|
||||
Ordinarily, deleted domains, hosts and contacts are not included in search
|
||||
results. Authorized requests can specify that deleted items be included, by
|
||||
adding an extra parameter:
|
||||
|
||||
```
|
||||
/rdap/domains?name=*.tld&includeDeleted=true
|
||||
```
|
||||
|
||||
Deleted items are shown only if the request is authorized for the registrar that
|
||||
owns the items, or if the request is authorized as an administrator. This
|
||||
parameter can be combined with the registrar parameter.
|
||||
|
||||
### Additional features
|
||||
|
||||
We anticipate adding additional features during the pilot program, such as the
|
||||
ability to page through search results. We will update the documentation when
|
||||
these features are implemented.
|
||||
Loading…
Add table
Add a link
Reference in a new issue