Skip to main content
Resources

Registration Reporting Interfaces

The Registration Reporting Interfaces (RRI) system is a set of interfaces provided by ICANN to contracted parties including Registry Operators and Data Escrow Agents (DEA) to fulfill and monitor their applicable reporting requirements, including:

  • Per-registrar transaction reports
  • Registry functions activity report
  • Data escrow deposits reports
  • Data escrow deposits notifications

Additionally, RRI supports:

  • Registry Services – maintenance window management
  • SLA Monitoring (SLAM) – probe node list retrieval

The specification of the interfaces can be found in the following Internet Draft documents:

ICANN uses the following base URLs to provide the interfaces:

  • Registry operators and registry DEAs:
    https://ry-api.icann.org
  • Registrar DEAs:
    https://rr-api.icann.org

Authentication

The following authentication mechanisms are available on the reporting interfaces described in this document:

  1. HTTP Basic Access Authentication as specified in RFC 2617
  2. TLS Client Authentication

HTTP Basic Authentication

The client passes the authentication information to the server by adding a username and password in an Authorization header to the reporting interface.

The passwords and allowed IP prefixes for the Registry Operator and registry DEA users are managed through the Naming Services Portal (NSP).

The Registry Operator user is authorized for all of the Registry Operators' end-points when using HTTP Basic Authentication.

The registry DEA user is authorized for all of the registry DEA's end-points when using HTTP Basic Authentication.

TLS Client Authentication

This method uses TLS with client authentication, meaning that the RRI will authenticate the client using X.509 certificates in HTTPS. TLSA DNS resource records (see RFC 6698) are used to provide a mechanism to link the client certificate to be used.

In order to setup TLS Client Authentication, the registry operator (logged with an account allowed to make changes for a TLD) needs to provide two pieces of information in the NSP portal:

  1. Domain name for TLS Client access ( e.g., rsp1.nic.example)

  2. Authorized roles related to the RRI (more than one role may be linked with a given domain name):

    1. RRI – TLD Monthly Reporting (i.e., Per-registrar transaction reports and Registry functions activity report)
    2. RRI – TLD Data Escrow Daily Reporting
    3. RRI – TLD Data Escrow Agent Notification
    4. RRI – TLD Maintenance Window
    5. RRI – SLAM Probe Node List

RRI uses the domain name for TLS access to find the TLSA RRs to be used to validate the client during the TLS handshake. A batch process that runs at least every hour, will query the DNS (validating with DNSSEC) to get the TLSA RRs per owner name.

The following combinations of TLSA Certificate Usages Registry, TLSA Selectors and TLSA Matching Types are supported:

TLSA Certificate Usages Registry TLSA Selectors TLSA Matching Types
3 1 1
2

The following public key algorithms are supported on the X.509 certificates used for TLS client authentication:

  • RSA encryption with a key size of 4096 or higher.
  • Elliptic Curve public key

The following signature algorithms are supported on the X.509 certificates used for TLS client authentication:

  • sha256WithRSAEncryption
  • sha384WithRSAEncryption
  • sha512WithRSAEncryption
  • ecdsa-with-SHA256
  • ecdsa-with-SHA384
  • ecdsa-with-SHA512

Example

The first step is to generate an X.509 certificate and corresponding private key for the domain name to use in TLS Client Authentication for MoSAPI and RRI systems. The following command will generate a client certificate for "tls-client-example.example.com" persisted in the file "tls-client.crt.pem" and a private key persisted in the file "tls-client.key" (a passphrase will be asked to protect the private key):

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -sha256 -days 3650 -keyout tls-client.key -subj "/C=US/ST=California/L=Los Angeles/O=ICANN/OU=TS/CN=tls-client-example.example.com" -out tls-client.crt.pem

Where:

  • req, creates and processes certificate requests in PKCS#10 format. It can additionally, as in this example, create self-signed certificates

  • -x509, this option outputs a self-signed certificate instead of a certificate request.

  • -newkey ec, this option creates a new certificate request and a new EC (elliptic curve) private key (usable both with ECDSA or ECDH algorithms). Another useful option is "rsa", to generate an RSA key.

  • pkeyopt ec_paramgen_curve:prime256v1, use X9.62/SECG curve over a 256 bit prime field. The list of supported elliptic curves in your openssl installation could be found by executing: openssl ecparam -list_curves

  • -sha256, specifies SHA256 to sign the request.

  • -days, specifies the number of days to certify the certificate for (after the date specified by the number of days, the certificate will be considered as expired)

  • -keyout, this gives the filename to write the newly created private key to

  • -subj, sets subject name for new request or supersedes the subject name when processing a request

    • CN: Common name, in this example, the hostname of the TLSA DNS Resource Record (RR)

    • OU: Organizational Unit

    • O: Organization

    • L: Locality

    • ST: State or province name

    • C: Country name

  • -out, this specifies the output filename for the certificate

The second step is to generate a TLSA DNS Resource Record (RR) from the X.509 certificate. The tool "danetool" from the GnuTLS Transport Layer Security Library is used to generate the TLSA RR:

danetool --tlsa-rr --host tls-client-example.example.com --load-certificate tls-client.crt.pem

_443._tcp.tls-client-example.example.com. IN TLSA ( 03 01 01 2e472dd954df1c59dfa747a05afb649ff058cbf6ca8aef04f3eb46e9c0932602 )

Where:

  • --tlsa-rr, print the DANE RR
  • --host, hostname, in this example, the hostname of the TLSA DNS RR
  • --load-certificate, this is the file with the certificate created in the previous step

The third step is to add the RDATA created in the previous step to a TLSA DNS RR into a DNSSEC-validated zone for the domain name to use in TLS Client Authentication (as opposed to the one listed by the danetool output). The client provides the TLSA DNS RR hostname to ICANN for authentication and authorization of the client.

In this example, "nsupdate" is used to update the zone file (please note that nsupdate command is used for illustration purposes only and the tlsa resource record should be added with the applicable tool or method).

nsupdate
> server 127.0.0.1
> zone example.com.
> update add tls-client-example.example.com. 600 in tlsa 3 1 1 2e472dd954df1c59dfa747a05afb649ff058cbf6ca8aef04f3eb46e9c0932602
> send
> quit

Where:

  • server, indicates the name server to send the dynamic update requests to
  • zone, specifies the zone to which updates are to be made to
  • update add, adds a new resource record
  • send, sends the current message

We verify that the TLSA RR was correctly added by using a DNSSEC-validating DNS resolver:

dig @10.10.10.10 tls-client-example.example.com. tlsa +short +dnssec
3 1 1 2E472DD954DF1C59DFA747A05AFB649FF058CBF6CA8AEF04F3EB46E9 C0932602
[ . . . ]

The fourth and final step is to authorize the domain name (e.g. tls-client-example.example.com) where the TLSA RR exists to access the TLD(s) data, according to selected roles, in the Name Service portal for Registry Operators.

A test connection to check the state of the ".example" TLD in the MoSAPI could be initiated as follows:

curl --cert tls-client.crt.pem --key tls-client.key https://mosapi.icann.org/mosapi/v1/example/monitoring/state

A test connection to check the status of the ".example" TLD in the RRI system could be initiated as follows:

curl --cert tls-client.crt.pem --key tls-client.key https://ry-api.icann.org/info/status/registry/example

Where:

  • --cert, this is the file with the certificate created in the first step
  • --key, this is the file with the private key linked to the certificate

RRI OT&E Environment

ICANN currently hosts an Operational Test and Evaluation (OT&E) environment of RRI exclusively for end-user testing by ICANN's contracted parties. This environment can be used to gain familiarity with the available interfaces, as well as to test system integration with RRI.

To gain access to the RRI OT&E environment, please contact ICANN's Global Support through the NSP portal and indicate the authentication mechanism(s), the list of IP addresses or address ranges that will be used to connect to RRI OT&E, and an email point of contact. Upon approval of the request, a predefined TLD and access credentials to the OT&E environment will be provided.

The URL of the RRI OT&E is: https://test-ry-api.icann.org

A note about our terms of service:

We have updated our electronic terms of service to provide greater transparency and align with laws applicable to us. Learn more.

This site uses cookies to deliver an efficient user experience and to help us see how the site is used. Learn more.OK

Domain Name System
Internationalized Domain Name ,IDN,"IDNs are domain names that include characters used in the local representation of languages that are not written with the twenty-six letters of the basic Latin alphabet ""a-z"". An IDN can contain Latin letters with diacritical marks, as required by many European languages, or may consist of characters from non-Latin scripts such as Arabic or Chinese. Many languages also use other types of digits than the European ""0-9"". The basic Latin alphabet together with the European-Arabic digits are, for the purpose of domain names, termed ""ASCII characters"" (ASCII = American Standard Code for Information Interchange). These are also included in the broader range of ""Unicode characters"" that provides the basis for IDNs. The ""hostname rule"" requires that all domain names of the type under consideration here are stored in the DNS using only the ASCII characters listed above, with the one further addition of the hyphen ""-"". The Unicode form of an IDN therefore requires special encoding before it is entered into the DNS. The following terminology is used when distinguishing between these forms: A domain name consists of a series of ""labels"" (separated by ""dots""). The ASCII form of an IDN label is termed an ""A-label"". All operations defined in the DNS protocol use A-labels exclusively. The Unicode form, which a user expects to be displayed, is termed a ""U-label"". The difference may be illustrated with the Hindi word for ""test"" — परीका — appearing here as a U-label would (in the Devanagari script). A special form of ""ASCII compatible encoding"" (abbreviated ACE) is applied to this to produce the corresponding A-label: xn--11b5bs1di. A domain name that only includes ASCII letters, digits, and hyphens is termed an ""LDH label"". Although the definitions of A-labels and LDH-labels overlap, a name consisting exclusively of LDH labels, such as""icann.org"" is not an IDN."