ICANN Monitoring System API (MoSAPI)
Version 2.11.2 2020-06-29
1. Introduction ...... 4 1.1. Date and Time ...... 4 1.2. Credentials ...... 4 1.3. Glossary ...... 4 1.4. Technical requirements ...... 5 2. Common elements used in this specification ...... 6 3. Session handling ...... 7 3.1. Creating a session ...... 7 3.2. Closing a session ...... 9 4. API endpoint authentication ...... 10 5. gTLD Base Registry Agreement - Specification 10 monitoring ...... 11 5.1. Monitoring the state of a TLD ...... 11 5.2. Monitoring the Alarm status of a Service ...... 14 5.3. Monitoring the availability of a Service ...... 15 5.4. Query a list of Incidents for a Service ...... 16 5.5. Monitoring the state of a particular Incident ...... 18 5.6. Monitoring the False Positive flag of an Incident ...... 19 5.7. Querying the list of measurements for an Incident ...... 21 5.8. Querying the details of a particular measurement ...... 22 5.8.1. DNS/DNSSEC Monitoring error codes ...... 28 5.8.2. RDDS Monitoring error codes ...... 33 6. Maintenance window support ...... 37 6.1. Common elements for maintenance window support ...... 37 6.1.1. Schedule object ...... 37 6.1.2. Schedule object identifier ...... 37 6.2. Creating or updating a schedule for a maintenance window ...... 38 6.3. Deleting a schedule for a maintenance window ...... 39 6.4. Retrieving a schedule object for a maintenance window ...... 40 6.5. Getting the list of maintenance windows that have not ended yet ...... 41 7. Probe node network ...... 42 8. HTTP/400 extended error codes ...... 44 9. Domain Abuse Activity Reporting (DAAR) ...... 46 9.1. Getting the latest DAAR report available for the TLD ...... 46 9.2. Querying for a DAAR report for a date ...... 48 9.3. Querying for DAAR reports available ...... 49 10. Recent Measurements ...... 51
1
10.1. Querying years for which reports are available ...... 51 10.2. Querying months for which reports are available ...... 52 10.3. Querying days for which reports are available ...... 53 10.4. Querying for available measurements ...... 54 10.5. Querying the details of a particular measurement ...... 55 11. List of ICANN-accredited Registrars’ RDAP Base URLs ...... 56 12. Alternative methods of authentication ...... 58 12.1. Overview ...... 58 12.2. TLS Client Authentication ...... 58 12.3. Authentication and Authorization with TLS Client Authentication ...... 59
2
Document Revision History
Projected date to Publishing implement the version Version Description of the change date of the specification in production 2.5 2017/11/28 First version released to the public. In production ADDITION - Default rate-limit and expiration date values were added in section 3.1. ADDITION - Maximum length definitions for name and description were added in section 6.1.1. 2.6 2018/02/12 In production ADDITION - Result code 2016 (section 8) was added to the result code table. CHANGE - Result code 2007 message (section 8) was changed to cover the case of equal values in the endTime and startTime. 2.7 2018/03/06 MoSAPI released as a production In production service. 2.8 2018/10/02 ADDITION - UP-inconclusive-no-data Never released to and UP-inconclusive-no-probes were production, replaced added to sections 5.1 and 5.8. with version 2.8.1 CHANGE - Error codes changed in sections 5.8.1 and 5.8.2. CHANGE - Editorial updates. 2.8.1 2018/11/26 CHANGE - Minor adjustments to the list Never released to of error codes in sections 5.8.1 and production, replaced 5.8.2. with version 2.8.2 2.8.2 2019/02/21 CHANGE - Error codes changed in 2019/02/21 sections 5.8.1. 2.9 2019/03/25 ADDITION - Section 9 and 10 were 2019/04/30 added. 2.10 2019/05/30 ADDITION – Section 11. 2019/05/30 CHANGE – Editorial updates. 2.11 2020/01/31 ADDITION – Section 12. Never released to CHANGE – Editorial updates. production, replaced with version 2.11.1 2.11.1 2020/02/26 ADDITION – Additional details in Never released to Section 12. production, replaced CHANGE – Rate-limit in Section 3.1. with version 2.11.2 ADDITION – Section 1.4. 2.11.2 2020/06/29 ADDITION – Additional details in July 2020 Section 12. CHANGE – Response message in Section 4. CHANGE – Technical Requirements in Section 1.4.
3
1. Introduction
This document describes the REST API endpoints provided by ICANN to contracted parties and Country Code Top-Level Domain (ccTLD) registries in order to retrieve monitoring and other information that is intended to be available only to the specific registry or registrar.
1.1. Date and Time
All the fields that represent dates in this document must contain timestamps indicating the date and time in Coordinated Universal Time (UTC).
1.2. Credentials
The MoSAPI uses the same credentials (e.g., username, password, list of IP address blocks - IPv4 and/or IPv6) as the Registration Reporting Interface (RRI). These credentials are managed through the NSP portal provided by ICANN to the contracted parties or through email in the case of ccTLD registries.
The MoSAPI supports both IPv4 and IPv6 transport.
The MoSAPI requires the use of Hypertext Transfer Protocol Secure (HTTPS) to provide confidentiality, server authentication, and integrity in the communication channel.
1.3. Glossary
In the following section, the concepts used in the MoSAPI are explained:
● Service: a service that may be monitored by the MoSAPI. The potential monitored services are: dns, rdds, epp and dnssec.
● Test Cycle: series of tests executed to verify the state of a monitored Service. For Domain Name System (DNS), the Service is considered to be up at a particular moment, if at least two of the delegated name servers registered in the DNS have successful results from tests to each of their public-DNS registered IP addresses in the root zone for the name server. For the Registration Data Directory Services Requirements (RDDS) Services (i.e. Whois tcp/43 and web-Whois) to be considered up at a particular moment, the Services must have successful results from tests to the randomly chosen public-DNS registered IP address to which whois.nic.
4
● Test: for DNS it means one non-recursive DNS query sent to a particular IP address via UDP or TCP; if DNSSEC is offered in the queried DNS zone, for a query to be considered answered, the signatures must be positively verified against a corresponding DS record published in the parent zone. For RDDS it means one query sent to a particular IP address. The answer to the query must contain the corresponding information from the Registry System, otherwise the query will be considered unanswered. A query with a RTT higher than X milliseconds will also be considered unanswered. For DNS (UDP) X=2,500 ms, DNS (TCP) X=7,500 ms for RDDS X=10,000 ms.
● RTT (Round Trip Time): for DNS/UDP, the sequence of two packets, the UDP DNS query and the corresponding UDP DNS response. For DNS/TCP, the sequence of packets from the start of the TCP connection to its end. For Whois tcp/43, the sequence of packets from the start of the TCP connection to its end, including the reception of the Whois tcp/43 response. For web-Whois, the sequence of packets from the start of the TCP connection to its end, including the reception of a HTTP response; if the Registry Operator implements HTTP URL redirection (e.g. HTTP 302), only the last HTTP transaction is measured.
● Emergency Threshold: downtime threshold that if reached by any of the monitored Services may cause the TLD's Services emergency transition to an interim Registry Operator. To reach an Emergency Threshold a Service must accumulate X hours of total downtime during the last 7 days (i.e. rolling week). For DNS X=4, for RDDS X=24.
● Incident: an Incident is the collection of measurements from the moment an Alarm is generated until the moment that the Alarm is cleared. An Incident can have 2 distinct states:
· Active: measurements corresponding to a current downtime. · Resolved: measurements corresponding to past downtime.
The measurements of Incidents that occurred in the last 7 days (i.e. rolling week, from: the current date and time -7days, to: the current date and time) are considered for the Service's Emergency Threshold calculations.
● Alarm: an Alarm signals that a Service has been detected as being down because X consecutive test cycles with Y minutes between them failed. An Alarm is cleared when the Service is detected as being up because X consecutive test cycles with Y minutes between them have been successful. For DNS, X=3 and Y=1. For RDDS, X=2 and Y=5. An alarmed Service triggers the creation of an Incident; if the Alarm is cleared then the Incident will be marked as resolved.
● False Positive: a flag set to an Incident indicating that an Incident was found by a manual process to be a false positive. When an Incident is marked as a False Positive the measurements of the Incident are not used for the Emergency Threshold calculations. 1.4. Technical requirements
● Clients shall send the HTTP Cookies provided by the server on every HTTP request when
5
2. Common elements used in this specification
In the following section, common elements used in this specification are explained:
●
Where:
·
●
6
3. Session handling
The MoSAPI provides two endpoints for session handling, the authentication mechanism is HTTP Basic Access Authentication as specified in RFC 2617.
Authentication credentials for the API endpoints are provided by ICANN per TLD. The credentials must only be used when creating a session using the
Possible results:
● HTTP/401, the
● HTTP/403, the
● HTTP/429, the
Note: Only connections originating from IP addresses whitelisted for the
● HTTP/200, when a valid request is received, the
· The
Example using curl (https://curl.haxx.se/) for a login request:
curl --cookie-jar cookies.txt --user user:passwd https://mosapi.icann.org/mosapi/v1/example/login
Note: Every time the
7
the session is the oldest and a new session is being created that would be above the limit of permitted concurrent sessions.
8
3.2. Closing a session
In order to destroy a session, the client must set the HTTP header Cookie with the value "id=
Possible results:
● HTTP/401, the
● HTTP/403, the
● HTTP/200, when a valid request is received, the
· The
Example using CURL for a logout request:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/logout
9
4. API endpoint authentication
When sending a request to the MoSAPI, the client must set the HTTP header Cookie with the value "id=
The following responses may be provided by the API by the endpoints shown below:
● HTTP/401, the API endpoint provides a HTTP/401 status code, sets the HTTP header Content-type to "text/plain; charset=utf-8", and provides a text response in the HTTP Entity-body with the string "The client could not be authenticated using any of the available methods: TLS-Client-Authentication or Session Cookie" when the specified
● HTTP/403, the API endpoint provides a HTTP/403 status code, sets the HTTP header Content-type to "text/plain; charset=utf-8", and provides a text response in the HTTP Entity-body with the string "Your IP address is not allowed to connect for this TLD" if the specified
10
5. gTLD Base Registry Agreement - Specification 10 monitoring
Registries may access the monitoring information collected by the SLA Monitoring system using the GET HTTP verb in the MoSAPI endpoints described below. The monitoring information will be refreshed at least every 2 minutes. 5.1. Monitoring the state of a TLD
Possible results:
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "tld", a JSON string that contains the monitored TLD.
● "status", a JSON string that contains the status of the TLD as seen from the monitoring system. The "status" field may contain one of the following values:
· Up: all of the monitored Services are up. · Down: one or more of the monitored Services are down. · Up-inconclusive: the SLA monitoring system is under maintenance, therefore all the monitored Services of the TLD are considered to be up by default. Note: if the status is "Up-inconclusive", all Services in the "testedServices" array will have the status with a value of "disabled".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "testedServices", a JSON array that contains detailed information for each potential monitored service (i.e. DNS, RDDS, EPP, DNSSEC). Each
o "status", a JSON string that contains the status of the Service as seen from the monitoring system. The "status" field can contain one of the following values:
· Up: the monitored Service is up. · Down: the monitored Service is down. · Disabled: the Service is not being monitored. · UP-inconclusive-no-data: indicates that there are enough probe nodes online, but not enough raw data points were received to make a determination. · UP-inconclusive-no-probes: indicates that there are not enough probe nodes online to make a determination.
11
o "emergencyThreshold", a JSON number that contains the current percentage of the Emergency Threshold of the Service. Note: the value "0" specifies that the are no Incidents affecting the Emergency Threshold of the Service.
o "incidents", a JSON array that contains "incident" objects. The "incident" object contains:
- "incidentID", a JSON string that contains the Incident identifier (i.e.
- "startTime", a JSON number that contains the Unix time stamp of the start date and time of the Incident.
- "falsePositive", a JSON boolean value that contains true or false with the False Positive status of the Incident.
- "state", a JSON string that contains the current state (i.e. Active or Resolved) of the Incident.
- "endTime", a JSON number that contains the Unix time stamp of the end date and time of the Incident; if the Incident state is active the "endTime" field will contain a null value.
Example using CURL to request the state of a TLD:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/state
12
Example of a JSON response for a TLD state request:
{ "tld": "example", "lastUpdateApiDatabase": 1496923082, "status": "Down", "testedServices": { "DNS": { "status": "Down", "emergencyThreshold": "10.0000", "incidents": [{ "incidentID": "1495811850.1700", "endTime": null, "startTime": "1495811850", "falsePositive": false, "state": "Active" }] }, "DNSSEC": { "status": "Down", "emergencyThreshold": "10.0000", "incidents": [{ "incidentID": "1495811790.1694", "endTime": null, "startTime": "1495811790", "falsePositive": false, "state": "Active" }] }, "EPP": { "status": "Disabled" }, "RDDS": { "status": "Disabled" } }, "version": 1 }
13
5.2. Monitoring the Alarm status of a Service
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "alarmed", a JSON string that contains one of the following values:
· Yes: an Alarm exists for the Service. · No: an Alarm does not exist for the Service. · Disabled: the Service is not being monitored.
Example using CURL to request the Alarm status of a Service:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/alarmed
Example of a JSON response for a Service in Alarm status:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "alarmed": "Yes" }
14
5.3. Monitoring the availability of a Service
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "downtime", a JSON number that contains the number of minutes of downtime of the Service during a rolling week period.
Example using CURL to request the availability of a Service:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/downtime
Example of a JSON response for a Service availability request:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "downtime": 935 }
15
5.4. Query a list of Incidents for a Service
Where:
● Optional
● Optional
● Optional
Note: The
Possible results:
● HTTP/400, see section 8.
● HTTP/404, the
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "incidents", JSON array, see definition in section 5.1.
16
Example using CURL to request a list of Incidents of a Service:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/incidents?startDate=14224924 00&endDate=1422493000
Example of a JSON response showing a list of Incidents:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "incidents": [ { "incidentID": "1422492450.699", "startTime": 1422492450, "falsePositive": false, "state": "Active", "endTime": null }, { "incidentID": "1422492850.3434", "startTime": 1422492850, "falsePositive": true, "state": "Resolved", "endTime": 1422492950 } ] }
17
5.5. Monitoring the state of a particular Incident
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "incidents", JSON array, see definition in section 5.1.
Example using CURL to request the state of an Incident:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/incidents/1422492450.699/sta te
Example of a JSON response for an Incident state request:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "incidents": [ { "incidentID": "1422492450.699", "startTime": 1422492450, "falsePositive": false, "state": "Active", "endTime": null } ] }
18
5.6. Monitoring the False Positive flag of an Incident
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "falsePositive", a JSON boolean value that contains true or false with the False Positive status of the Incident. The default value is false.
● "updateTime", a JSON number that contains the Unix time stamp of the date and time the False Positive status was updated; if the False Positive status has never been updated the "updateTime" field will contain a null value.
Example using CURL to request the False Positive flag of an Incident:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/incidents/1422492930.699/fal sePositive
Example of a JSON response for an Incident flagged as False Positive:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "falsePositive": true, "updateTime": 1422494780 }
19
Note: The False Positive flag is the only thing that may change after an Incident is resolved. The user MAY be notified if an Incident is marked as a false positive by an offline mechanism.
20
5.7. Querying the list of measurements for an Incident
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "measurements", a JSON array that contains a list of
Example using CURL to request the list of measurements of an Incident:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/incidents/1422492930.699
Example of a JSON response showing a list of measurements identifiers:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "measurements": [ "1422492930.699.json", "1422492990.699.json", "1422493050.699.json", "1422493110.699.json" ] }
21
5.8. Querying the details of a particular measurement
Where:
●
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "lastUpdateApiDatabase", a JSON number that contains the Unix time stamp of the date and time that the monitoring information provided in the MoSAPI was last updated from the monitoring system central database.
● "tld", a JSON string that contains the monitored TLD.
● "service", a JSON string that contains the Service being queried. The possible values of Service, as described in Section 1 of Specification 10, are: dns, dnssec, rdds, and epp.
● "cycleCalculationDateTime", a JSON number that contains the date and time the test cycle results were computed.
● "status", a JSON string that contains the status of the Service after computing the test cycle results. The "status" field can contain one of the following values:
o Up: the monitored Service is up. o Down: the monitored Service is down. o UP-inconclusive-no-data: indicates that there are enough probe nodes online, but not enough raw data points were received to make a determination. o UP-inconclusive-no-probes: indicates that there are not enough probe nodes online to make a determination.
22
● "testedInterface", a JSON array that contains information about the interface being tested. The "testedInterface" fields contains the following fields:
o "interface", a JSON string that contains the tested interface.
o "probes", a JSON array that contains detailed monitoring information per probe node. The "probes" field contains the following fields:
▪ "city", a JSON string with the location of the probe node.
▪ "status", a JSON string that contains the status of the interface as seen from the probe node. The "status" field can contain one of the following values:
· Up: the monitored Service is up. · Down: the monitored Service is down. · Offline: the probe node is offline. Note: the probe node is not considered part of the probe node universe when calculating the rolling week thresholds. · No result: results from this probe node were not received by the central server when the calculations were executed. Note: the service is considered to be up for rolling week threshold calculations.
▪ "testData", a JSON array that contains monitoring information. The "testData" field contains the following fields:
+ "target", a JSON string that in the case of the DNS Service contains the name server being tested, in the case of RDDS, this field contains "null".
+ "status", a JSON string that in the case of the DNS Service contains the status of the name server being tested. In the case of RDDS this field contains the status of the IP address being tested (available in the "metrics" element, see below). The "status" field contains the following fields:
· Up: the test was considered successful. · Down: the test was not considered successful.
+ A "metrics", a JSON array with monitoring details of particular tests. The "metrics" field contains the following fields:
- "testDateTime", a JSON number that contains the date and time the result was computed. If the "result" field contains "no data", the "testDateTime" field will contain a null value.
- "targetIP", a JSON string with the IP Address being tested.
- "rtt", a JSON number that contains the milliseconds needed for the query to be resolved. If the "result" field contains an error code or "no data", the "rtt" field will contain a null value.
- "result", a JSON string that contains the value "ok" if the query response was valid, "no data" if no data was received from the probe node, or an error code if the result is not valid. The information regarding the error codes may be found in section 5.8.1 and 5.8.2.
23
Note: in case of "no data" the query response is assumed to be valid for rolling week threshold calculations
Note: the JSON object for the measurement details provides the status of the test cycle computed from the results of all probe nodes.
Example using CURL to request the details of a measurement:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/incidents/1422734490.699/142 2734490.699.json
Example of JSON response for a DNS Service measurement details request:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "tld": "example", "service": "dns", "cycleCalculationDateTime": 1422734490, "status": "Up", "testedInterface": [ { "interface": "DNS", "probes": [ { "city": "WashingtonDC", "status": "Down", "testData": [ { "target": "ns1.nic.example", "status": "Down", "metrics": [ { "testDateTime": 1422734513, "targetIP": "2001:DB8::1", "rtt": null, "result": "-204" }, { "testDateTime": 1422734513, "targetIP": "192.0.2.1", "rtt": null, "result": "-204" } ] }, { "target": "ns2.nic.example", "status": "Down", "metrics": [ { "testDateTime": 1422734513, "targetIP": "2001:DB8::2", "rtt": null, "result": "-204" }, { "testDateTime": 1422734513, "targetIP": "192.0.2.2", "rtt": null, "result": "-204" } ] } ] }, {
24
"city": "Sydney", "status": "Up", "testData": [ { "target": "ns1.nic.example", "status": "Up", "metrics": [ { "testDateTime": 1422734508, "targetIP": "192.0.2.1", "rtt": 5, "result": "ok" } ] }, { "target": "ns2.nic.example", "status": "Up", "metrics": [ { "testDateTime": null, "targetIP": "192.0.2.2", "rtt": null, "result": "no data" } ] } ] }, { "city": "Los Angeles", "status": "Offline", "testData":[] }, { "city": "Sao Paulo", "status": "No result", "testData": [] } ] } ] }
25
Example of JSON response for a RDDS Service measurement details request:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "tld": "example", "service": "rdds", "cycleCalculationDateTime": 1422734490, "status": "Down", "testedInterface": [ { "interface": "RDDS43", "probes": [ { "city": "WashingtonDC", "status": "Down", "testData": [ { "target": null, "status": "Down", "metrics": [ { "testDateTime": 1422734513, "targetIP": "2001:DB8::1", "rtt": null, "result": "-200" } ] } ] }, { "city": "Sydney", "status": "Up", "testData": [ { "target": null, "status": "Up", "metrics": [ { "testDateTime": 1422734508, "targetIP": "192.0.2.1", "rtt": 250, "result": "ok" } ] } ] } ] }, { "interface": "RDDS80", "probes": [ { "city": "WashingtonDC", "status": "Down", "testData": [ { "target": null, "status": "Down", "metrics": [ { "testDateTime": 1422734513, "targetIP": "192.0.2.1", "rtt": null, "result": "-200" } ] }
26
] }, { "city": "Sydney", "status": "Down", "testData": [ { "target": null, "status": "Down", "metrics": [ { "testDateTime": 1422734508, "targetIP": "192.0.2.1", "rtt": null, "result": "-200" } ] } ] } ] } ] }
27
5.8.1. DNS/DNSSEC Monitoring error codes
The following table lists the error codes for DNS/DNSSEC monitoring:
Result Obsolet Interna Code e l Error Interface Description DNS UDP / -1 N Y DNS TCP Internal error. Expecting NOERROR RCODE but got unexpected -2 N Y DNS UDP RCODE from local resolver. Expecting NOERROR RCODE but got unexpected -3 N Y DNS TCP RCODE from local resolver. -200 N N DNS UDP No reply from the authoritative name server. DNS UDP / -201 Y N DNS TCP Invalid reply from Name Server. DNS UDP / -204 Y N DNS TCP DNSSEC error. DNS UDP / -206 Y N DNS TCP Keyset is not valid. Expecting DNS class IN but got class CHAOS in -207 N N DNS UDP the DNS response. Expecting DNS class IN but got class HESIOD in -208 N N DNS UDP the DNS response. Expecting DNS class IN but got something different from class IN, CHAOS or HESIOD in the -209 N N DNS UDP DNS response.
-210 N N DNS UDP Header section incomplete in the DNS response. Question section incomplete in the DNS -211 N N DNS UDP response.
-212 N N DNS UDP Answer section incomplete in the DNS response. Authority section incomplete in the DNS -213 N N DNS UDP response. Additional section incomplete in the DNS -214 N N DNS UDP response. -215 N N DNS UDP Malformed DNS response. Querying for a non-existent domain - the AA flag -250 N N DNS UDP is off (was expecting on) in the DNS response. Querying for a non-existent domain - Domain name being queried not present in question -251 N N DNS UDP section of the DNS response.
28
Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got FORMERR -253 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got SERVFAIL -254 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTIMP -255 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got REFUSED -256 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got -257 N N DNS UDP YXDOMAIN on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got YXRRSET -258 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NXRRSET -259 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTAUTH -260 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTZONE -261 N N DNS UDP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got -270 N N DNS UDP unexpected (i.e. 11-15) on the DNS response. Timeout when waiting for a response from the TLD authoritative servers as reported by the local -400 N N DNS UDP DNS resolver. The TLD is configured as DNSSEC-enabled, but no -401 N N DNS UDP DNSKEY was found in the apex. DNSSEC error in the chain of trust from the root -402 N N DNS UDP to the TLD apex. -403 N N DNS UDP The TLD was not found in the root. Unknown cryptographic algorithm found in a -405 N N DNS UDP DNSSEC signature. Unsupported cryptographic algorithm found in a -406 N N DNS UDP DNSSEC signature. No RRSIGs were found, and the TLD is expected -407 N N DNS UDP to be signed.
29
Querying for a non-existent domain - No NSEC/NSEC3 RRs were found in the authority -408 N N DNS UDP section. -410 N N DNS UDP No signature covering the RRSET was found. An RRSIG was found and it is not signed by a -414 N N DNS UDP DNSKEY from the KEYSET. -415 N N DNS UDP Bogus DNSSEC signature was found. -416 N N DNS UDP An expired DNSSEC signature was found. A DNSSEC signature with an inception date in the -417 N N DNS UDP future was found. A DNSSEC signature with expiration date earlier -418 N N DNS UDP than inception date was found. A resource record (RR) not covered by the given NSEC/NSEC3 RRs was found. Note: the condition -422 N N DNS UDP is only evaluated if RCODE=NXDOMAIN. Malformed RRSIG with too few RDATA fields was -425 N N DNS UDP found. -427 N N DNS UDP Malformed DNSSEC response. Connection to the name server was successful, -600 N N DNS TCP but the connection timed out. Error when opening a connection to the name -601 N N DNS TCP server. Expecting DNS class IN but got CHAOS in the DNS -607 N N DNS TCP response. Expecting DNS class IN but got HESIOD in the -608 N N DNS TCP DNS response. Expecting DNS class IN but got something different from [IN, CHAOS or HESIOD] in the DNS -609 N N DNS TCP response.
-610 N N DNS TCP Header section incomplete in the DNS response. Question section incomplete in the DNS -611 N N DNS TCP response.
-612 N N DNS TCP Answer section incomplete in the DNS response. Authority section incomplete in the DNS -613 N N DNS TCP response. Additional section incomplete in the DNS -614 N N DNS TCP response. -615 N N DNS TCP Malformed DNS response. Querying for a non-existent domain - the AA flag -650 N N DNS TCP is off (expecting on) in the DNS response.
30
Querying for a non-existent domain - Domain name being queried not present in question -651 N N DNS TCP section of the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got FORMERR -653 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got SERVFAIL -654 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTIMP -655 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got REFUSED -656 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got -657 N N DNS TCP YXDOMAIN on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got YXRRSET -658 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NXRRSET -659 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTAUTH -660 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got NOTZONE -661 N N DNS TCP on the DNS response. Querying for a non-existent domain - Expecting NXDOMAIN/NOERROR RCODE but got -670 N N DNS TCP unexpected (i.e. 11-15) on the DNS response. Timeout when waiting for a response from the TLD authoritative servers as reported by the local -800 N N DNS TCP DNS resolver. The TLD is configured as DNSSEC-enabled, but no -801 N N DNS TCP DNSKEY was found in the apex. DNSSEC error in the chain of trust from the root -802 N N DNS TCP zone to the TLD apex. -803 N N DNS TCP The TLD was not found in the root. Unknown cryptographic algorithm found in a -805 N N DNS TCP DNSSEC signature. Unsupported cryptographic algorithm found in a -806 N N DNS TCP DNSSEC signature.
31
No RRSIGs where found, and the TLD is expected -807 N N DNS TCP to be signed. Querying for a non-existent domain - No NSEC/NSEC3 RRs were found in the authority -808 N N DNS TCP section -810 N N DNS TCP No signature covering the RRSET was found. An RRSIG was found and it is not signed by a -814 N N DNS TCP DNSKEY from the KEYSET. -815 N N DNS TCP Bogus DNSSEC signature was found. -816 N N DNS TCP An expired DNSSEC signature was found. A DNSSEC signature with an inception date in the -817 N N DNS TCP future was found. A DNSSEC signature with expiration date earlier -818 N N DNS TCP than inception date was found. A RR not covered by the given NSEC/NSEC3 RRs was found. Note: the condition is only evaluated -822 N N DNS TCP if RCODE=NXDOMAIN. Malformed RRSIG with too few RDATA fields was -825 N N DNS TCP found. -827 N N DNS TCP Malformed DNSSEC response.
Note: error codes marked as Obsolete are listed for documentation purposes.
Note: a test with an error code marked as Internal Error will be considered to be UP.
32
5.8.2. RDDS Monitoring error codes
The following table lists the error codes for RDDS monitoring:
Result Obsolet Interna Code e l Error Interface Description Whois-43 / Web- -1 N Y whois Internal Error Whois-43 / Web- RDDS service could not be tested due to lack of -2 N Y whois IPv4/6 transport in the probe node. Expecting NOERROR RCODE but got unexpected code when resolving the WHOIS-43 hostname -3 N Y Whois-43 using the local DNS resolver. Expecting NOERROR RCODE but got unexpected Web- code when resolving web-whois hostname using -4 N Y whois the local DNS resolver. Connection timed out while trying to get a -200 Y N Whois-43 response from the server. -201 N N Whois-43 Syntax error while parsing the WHOIS-43 response. Web- Connection timed out while trying to get a -204 Y N whois response from the server. Whois-43 / Web- Error when trying to resolve the Whois server -205 Y N whois hostname (e.g. whois.nic.example). Web- An HTTP status code was not found in the HTTP -206 N N whois message. Web- No HTTP/200 status code in response (after -207 Y N whois following redirects). Timeout when waiting for a response from the TLD authoritative servers as reported by the local DNS -222 N N Whois-43 resolver. DNSSEC error when trying to resolve the hostname -224 N N Whois-43 for the WHOIS-43 server. The hostname for the WHOIS-43 server was not -225 N N Whois-43 found in the DNS. Connection to WHOIS-43 server was successful, -227 N N Whois-43 but the connection timed out. -228 N N Whois-43 Connection to WHOIS-43 server was unsuccessful.
-229 N N Whois-43 Empty response received from WHOIS-43 server. Timeout when waiting for a response from the TLD Web- authoritative servers as reported by the local DNS -250 N N whois resolver.
33
Web- DNSSEC error when trying to resolve the hostname -252 N N whois for the web-whois server. Web- The hostname for the web-whois server was not -253 N N whois found in the DNS. Web- Connection to the web-whois server was -255 N N whois successful, but the connection timed out. Web- Error when opening a connection to web-whois -256 N N whois server. Web- -257 N N whois Malformed HTTP message. Web- -258 N N whois Malformed HTTP message or TLS general error. The maximum number of HTTP redirects (301, 302 Web- and 303) were followed, and a 200 / HTTP status -259 N N whois code was not found. Web- -300 N N whois Expecting HTTP status code 200 but got 100. Web- -301 N N whois Expecting HTTP status code 200 but got 101. Web- -302 N N whois Expecting HTTP status code 200 but got 102. Web- -303 N N whois Expecting HTTP status code 200 but got 103. Web- -304 N N whois Expecting HTTP status code 200 but got 201. Web- -305 N N whois Expecting HTTP status code 200 but got 202. Web- -306 N N whois Expecting HTTP status code 200 but got 203. Web- -307 N N whois Expecting HTTP status code 200 but got 204. Web- -308 N N whois Expecting HTTP status code 200 but got 205. Web- -309 N N whois Expecting HTTP status code 200 but got 206. Web- -310 N N whois Expecting HTTP status code 200 but got 207. Web- -311 N N whois Expecting HTTP status code 200 but got 208. Web- -312 N N whois Expecting HTTP status code 200 but got 226. Web- -313 N N whois Expecting HTTP status code 200 but got 300. Web- -317 N N whois Expecting HTTP status code 200 but got 304.
34
Web- -318 N N whois Expecting HTTP status code 200 but got 305. Web- -319 N N whois Expecting HTTP status code 200 but got 306. Web- -320 N N whois Expecting HTTP status code 200 but got 307. Web- -321 N N whois Expecting HTTP status code 200 but got 308. Web- -322 N N whois Expecting HTTP status code 200 but got 400. Web- -323 N N whois Expecting HTTP status code 200 but got 401. Web- -324 N N whois Expecting HTTP status code 200 but got 402. Web- -325 N N whois Expecting HTTP status code 200 but got 403. Web- -326 N N whois Expecting HTTP status code 200 but got 404. Web- -327 N N whois Expecting HTTP status code 200 but got 405. Web- -328 N N whois Expecting HTTP status code 200 but got 406. Web- -329 N N whois Expecting HTTP status code 200 but got 407. Web- -330 N N whois Expecting HTTP status code 200 but got 408. Web- -331 N N whois Expecting HTTP status code 200 but got 409. Web- -332 N N whois Expecting HTTP status code 200 but got 410. Web- -333 N N whois Expecting HTTP status code 200 but got 411. Web- -334 N N whois Expecting HTTP status code 200 but got 412. Web- -335 N N whois Expecting HTTP status code 200 but got 413. Web- -336 N N whois Expecting HTTP status code 200 but got 414. Web- -337 N N whois Expecting HTTP status code 200 but got 415. Web- -338 N N whois Expecting HTTP status code 200 but got 416. Web- -339 N N whois Expecting HTTP status code 200 but got 417. Web- -340 N N whois Expecting HTTP status code 200 but got 421.
35
Web- -341 N N whois Expecting HTTP status code 200 but got 422. Web- -342 N N whois Expecting HTTP status code 200 but got 423. Web- -343 N N whois Expecting HTTP status code 200 but got 424. Web- -344 N N whois Expecting HTTP status code 200 but got 426. Web- -345 N N whois Expecting HTTP status code 200 but got 428. Web- -346 N N whois Expecting HTTP status code 200 but got 429. Web- -347 N N whois Expecting HTTP status code 200 but got 431. Web- -348 N N whois Expecting HTTP status code 200 but got 451. Web- -349 N N whois Expecting HTTP status code 200 but got 500. Web- -350 N N whois Expecting HTTP status code 200 but got 501. Web- -351 N N whois Expecting HTTP status code 200 but got 502. Web- -352 N N whois Expecting HTTP status code 200 but got 503. Web- -353 N N whois Expecting HTTP status code 200 but got 504. Web- -354 N N whois Expecting HTTP status code 200 but got 505. Web- -355 N N whois Expecting HTTP status code 200 but got 506. Web- -356 N N whois Expecting HTTP status code 200 but got 507. Web- -357 N N whois Expecting HTTP status code 200 but got 508. Web- -358 N N whois Expecting HTTP status code 200 but got 510. Web- -359 N N whois Expecting HTTP status code 200 but got 511. Web- Expecting HTTP status code 200 but got an -360 N N whois unexpected status code.
Note: the DNS resolvers used in the system validate DNSSEC.
Note: error codes marked as Obsolete are listed for documentation purposes.
Note: a test with an error code marked as an Internal Error will be considered to be UP.
36
6. Maintenance window support
The gTLD Base Registry Agreement allows the Registry Operator to inform ICANN of planned maintenance times. However, note that per the gTLD Base Registry Agreement, there is no provision for planned outages or similar periods of unavailable or slow service; any downtime, be it for maintenance or due to system failures, will be noted simply as downtime. 6.1. Common elements for maintenance window support
6.1.1. Schedule object
Registry operators use the schedule object to manage maintenance windows in the MoSAPI. The schedule object contains the following fields (required):
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "name", a JSON string that contains a descriptive name of the maintenance window. The maximum length is 255 Unicode characters. Note: Unicode characters beyond the 255 limit will be ignored.
● "enable", a JSON boolean value that contains true when the maintenance window is enabled and false when the maintenance window is disabled.
● "description", a JSON string that contains a description of the maintenance widow. The maximum length is 255 Unicode characters. Note: Unicode characters beyond the 255 limit will be ignored.
● "startTime", a JSON number that contains the date and time (specified in Unix timestamp) when the maintenance window starts being active.
● "endTime", a JSON number that contains the date and time (specified in Unix timestamp) when the maintenance window ends being active.
ICANN will suspend Emergency Escalation services only for the 10% Emergency Threshold alert for RDDS and EPP when an enabled ("enabled"=true) schedule object exist, and the threshold is reached on a time covered by the "startTime" and "endTime".
Example of a JSON schedule object:
{ "version": 1, "name": "load balancer upgrade", "enabled": true, "description": "The load balancer will be upgraded to version 3.4", "startTime": 1485941725, "endTime": 1486001764 }
6.1.2. Schedule object identifier
A schedule object is uniquely identified by a
37
6.2. Creating or updating a schedule for a maintenance window
In order to create or update a schedule for a maintenance window, the user sends a schedule object using the PUT HTTP verb in the API endpoint provided at:
Possible results:
● HTTP/400, see section 8.
● HTTP/404, the
● HTTP/200, the
Example using CURL to create a maintenance window:
curl --cookie cookies.txt -H "Content-Type: application/json" https://mosapi.icann.org/mosapi/v1/example/mntWin/rdds/16beaa07-46a3-42eb-9e71- c2e06cfd8a9b -X PUT -d \ '{ "enable": "true", "name": "Maintenance window for RDDS semester II-2017", "description": "Pre-planned maintenance window for RDDS", "startTime": "1512003600", "endTime": "1512006600", "version": "1" }'
38
6.3. Deleting a schedule for a maintenance window
In order to delete a schedule for a maintenance window, the user make use of the DELETE HTTP verb in the API endpoint provided at:
Possible results:
● HTTP/400, see section 8.
● HTTP/404, the
● HTTP/200, the
Example using CURL to delete a maintenance window:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/mntWin/rdds/16beaa07-46a3-42eb-9e71- c2e06cfd8a9b -X DELETE
39
6.4. Retrieving a schedule object for a maintenance window
In order to get the information of a schedule object, the user make use of the GET HTTP verb in the following URL:
Possible results:
● HTTP/400, see section 8.
● HTTP/404, the
● HTTP/200, the
Example using CURL to request the details of a maintenance window:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/mntWin/rdds/16beaa 07-46a3-42eb-9e71-c2e06cfd8a9b
Example of JSON response for a maintenance window details request:
{ "enable": "true", "name": "Maintenance window for RDDS semester II-2017", "description": "Pre-planned maintenance window for RDDS", "startTime": "1512003600", "endTime": "1512006600", "version": "1" }
40
6.5. Getting the list of maintenance windows that have not ended yet
In order to get a list of maintenance window identifiers (i.e. "scheduleID") that have not ended yet, the user make use of the GET HTTP verb in the API endpoint provided by ICANN at:
Possible results:
● HTTP/404, the
● HTTP/200, the
Example using CURL to request the list of maintenance windows:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/mntWin/rdds
Example of a JSON array that contains the list of maintenance windows identifiers:
{ "schedules": [{ "scheduleID": "7b2d3012-41f7-4bce-89e9-9a9b85575fa6" [INCLUDE REST OF ELEMENTS] }, { "scheduleID": "37e71da9-827d-450a-9909-a64ba42af1d8" }] }
41
7. Probe node network
The current list of probe nodes used by the Monitoring System may be retrieved by using the GET HTTP verb in the API endpoint provided by ICANN at:
Possible results:
● HTTP/200, when a valid request is received, the API provides a HTTP/200 status code and sets the HTTP header Content-type to "application/json; charset=utf-8".
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "updateTime", a JSON number that contains the Unix time stamp of the date and time when the list was updated.
● "probeNodes", a JSON array that provides information per probe node. The "probeNodes" contains the following JSON objects:
o "city", a JSON string that contains the location of the probe node.
o "ipV4", a JSON string that contains the IPv4 address of the probe node. If a probe node does not support IPv4, the "ipV4" field will contain a null value.
o "ipV6", a JSON string that contains the IPv6 address of the probe node. If a probe node does not support IPv6, the "ipV6" field will contain a null value.
Example using CURL to request the list of probe nodes:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/nodes
42
Example of a JSON object that contains the list of probe nodes:
{ "version": 1, "updateTime": 1422492450, "probeNodes": [ { "city": "Amsterdam", "ipV4": "192.0.2.3", "ipV6": "2001:DB8::3" }, { "city": "Beijing", "ipV4": "192.0.2.4", "ipV6": null }, { "city": "Boston", "ipV4": "192.0.2.5", "ipV6": "2001:DB8::5" }, { "city": "Istanbul", "ipV4": "192.0.2.6", "ipV6": null }, { "city": "WashingtonDC", "ipV4": "192.0.2.7", "ipV6": "2001:DB8::7" }, { "city": "Sydney", "ipV4": "192.0.2.8", "ipV6": "2001:DB8::8" } ] }
43
8. HTTP/400 extended error codes
The API endpoints provides a HTTP/400 if the input does not comply with the business rules or the syntax of the input is invalid. The API endpoint sets the HTTP header Content-type to "application/json; charset=utf-8". A JSON object with the fields listed below is provided in the HTTP Entity-body:
● "resultCode", a JSON number that contains the result code.
● "message", a JSON string that contains the standard error message defined in the table below.
● "description", a JSON string that may be used to provide additional error diagnostic information.
Example of a JSON object that contains extended error codes:
{ "resultCode":2001, "message":"The UUID syntax is incorrect", "description":"The UUID (ee69b727-2abb-4f1c-8208-e5e76zzd758f) syntax is incorrect" }
44
The following table contains the extended error codes for the HTTP/400 status:
Result API endpoints HTTP Message Code Verb P D G U E E T L T E T E 2001
45
9. Domain Abuse Activity Reporting (DAAR)
ICANN's Domain Abuse Activity Reporting (DAAR) is a system for studying and reporting on domain name registration and security threat (domain abuse) behavior across top-level domain (TLD) registries and registrars. More information about the DAAR can be found at https://www.icann.org/octo-ssr/daar.
MoSAPI provides registries with access to DAAR-measurements for their TLDs using the GET and HEAD HTTP verbs in the MoSAPI endpoints described below. At the moment, DAAR data in MoSAPI is only available to gTLD registries.
9.1. Getting the latest DAAR report available for the TLD
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
The header "Last-Modified" is set to the date and time when the report was generated.
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body (only when using the HTTP/GET verb):
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "2".
● "tld", a JSON string that contains the monitored TLD.
● "daarReportDate", a JSON string that contains the date of the report in the format
o
● "daarReportData", measurements of the DAAR reporting including the following elements (JSON strings): domains in zone, number of unique abuse domains, number of spam domains, number of phish domains, number of bot c&c domains and number of malware domains.
Example using CURL to request latest DAAR report:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/daar/report/latest
46
Example of a JSON response for the latest DAAR report:
{ "version": 1, "tld": "example", "daarReportDate": "2018-12-12", "daarReportData": { "domainsInZone": 27957, "uniqueAbuseDomains": 14, "spamDomains": 10, "phishDomains": 3, "botnetCcDomains": 0, "malwareDomains": 2 } }
47
9.2. Querying for a DAAR report for a date
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
The header "Last-Modified" is set to the date and time when the report was generated.
Example using CURL to request the details of a measurement:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/daar/report/2019- 01-01
Example of JSON response for the DAAR report for a date:
See example in section 9.1.
48
9.3. Querying for DAAR reports available
Where:
● Optional
● Optional
Note: if both
Possible results:
● HTTP/400, see section 8, only the following error codes apply: 2012, 2013 and 2014.
● HTTP/200, when a valid request is received, the
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body (only when using the HTTP/GET verb):
● "version", a JSON number that contains the version number of the JSON object intended for future upgrades of the specification; for this version the value will always be "1".
● "tld", a JSON string that contains the monitored TLD.
● "daarReports", a JSON array with all the reports available within the period.
The array contains JSON objects with the following elements:
o "daarReportDate", see section 9.1 for definition.
o "daarReportGenerationDate", date and time that the report was generated in the format specified in RFC 3339.
Example using CURL to request the details of a measurement:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/daar/reports
49
Example of a JSON response for a query of reports available:
{ "version": 1, "tld": "example", "daarReports": [{ "daarReportDate": "2018-12-12", "daarReportGenerationDate": "2018-12-13T23:20:50.52Z" }, { "daarReportDate": "2018-12-13", "daarReportGenerationDate": "2018-12-13T23:20:51.52Z" }
] }
Example of a JSON response when no reports are available for the queried period:
{ "version": 1, "tld": "example", "daarReports": [] }
50
10. Recent Measurements
MoSAPI provides registries with access to measurements files for cycles marked as up or down using the GET or HEAD HTTP verbs in the MoSAPI endpoints described below. This functionality allows registries to obtain raw data regarding the tests performed by the monitoring system regardless of the cycle being part of an incident. 10.1. Querying years for which reports are available
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
Example using CURL to request years for which reports are available:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/measurements
Example of JSON response of the years for which reports are available:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "years": ["2018", "2017", "2016"] }
Example of a JSON response when no years are available for the monitored service:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "years": [] }
51
10.2. Querying months for which reports are available
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
Example using CURL to request years for which reports are available:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/measurements/
Example of JSON response of the months for which reports are available:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "months": ["06", "05", "04", "03", "02", "01"] }
Example of a JSON response when no months are available for the monitored service and the
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "months ": [] }
52
10.3. Querying days for which reports are available
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
Example using CURL to request years for which reports are available:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/measurements/
Example of JSON response of the days for which reports are available:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "days": ["03", "02", "01"] }
Example of a JSON response when no days are available for the monitored service and the
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "days ": [] }
53
10.4. Querying for available measurements
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
Example using CURL to request years for which reports are available:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/monitoring/dns/measurements/
Example of JSON response of the days for which measurements are available:
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "measurements": ["1422492930.json", "1422492990.json", "1422493050.json", "1422493110.json"] }
Example of a JSON response when no measurements are available for the monitored service and the
{ "version": 1, "lastUpdateApiDatabase": 1422492450, "measurements ": [] }
54
10.5. Querying the details of a particular measurement
Where:
●
Possible results:
● HTTP/404, the
● HTTP/200, when a valid request is received, the
The Content-Encoding entity header is set to "gzip" indicating that the entity-body is compressed using the Lempel-Ziv coding (LZ77), with a 32-bit CRC.
● HTTP/406, when a valid request is received, the
55
11. List of ICANN-accredited Registrars’ RDAP Base URLs
The list of ICANN-accredited registrars’ RDAP base URLs may be retrieved by using the GET HTTP verb in the API endpoint provided at:
Possible results:
● HTTP/200, when a valid request is received, the API provides an HTTP/200 status code and sets the HTTP header Content-type to "application/json; charset=utf-8".
The header "Last-Modified" is set to the date and time when the list was generated from the data obtained from the system of record regardless of the existence of changes in the contents from a previous version of the list.
If a valid request is received, a JSON object with the fields listed below is provided in the HTTP Entity-body:
● "description", a JSON string that contains a description of the list; for this version the value to be used is: "ICANN-accredited Registrars’ RDAP base URL list".
● "version", a JSON string that contains the version number of the JSON object intended for future upgrades of the specification; for this version, the value will always be "1.0".
● "publication", a JSON string that contains the date and time specified in the format defined in RFC 3339 of the last change in the contents of the list.
● "services", a JSON array with two elements: in order, an Entry Array and a Service URL Array.
o The Entry Array contains all the IANA Registrar IDs that have the same set of base RDAP URLs based on the system of record.
Note: currently, the system of record only allows setting one RDAP URL per IANA Registrar ID, but future updates may allow setting two or more RDAP base URLs. Future updates may also allow setting the RDAP base URL(s) for two or more IANA Registrar IDs.
o The Service URL Array contains the list of base RDAP URLs usable for the entries found in the Entry Array.
Note: the elements within these two arrays are not sorted in any way.
Example using CURL to request the list of probe nodes:
curl --cookie cookies.txt https://mosapi.icann.org/mosapi/v1/example/registrarRdapBaseUrl/list
56
Example of a JSON object that contains the list of ICANN-accredited registrars’ RDAP base URLs:
{ "description": "ICANN-accredited Registrars’ RDAP base URL list", "publication": "2019-05-01T21:00:05Z", "services": [ [ [ "645" ], [ "https://example.com/rdap/" ] ], [ [ "646" ], [ "https://nic.example/rdap/" ] ] ], "version": "1.0" }
57
12. Alternative methods of authentication
In addition to HTTP Basic Access Authentication, and state management using HTTP Cookies described in section 3 and 4, TLS Client Authentication is supported by MoSAPI as an alternative method of authentication and state management. 12.1. Overview
Nowadays it is common for a Registry Operator to subcontract the operation of Registry Services to one or more Registry Service Providers (RSP).
Before the implementation of TLS Client Authentication, the only mechanism of authentication was Basic Authentication with one set of credentials per TLD; therefore, an RSP wanting access to MoSAPI would have been forced to share the credentials with the Registry Operator. Thus, if credentials need to be changed, coordination between the RSP and Registry Operator is required.
RSPs have requested the ability to have separated credentials and additional authentication methods to access MoSAPI. Additionally, RSPs have requested a solution that allows them to change the credentials without going through the Registry Operator to execute such change.
RSPs have also expressed interest in using TLS Client Authentication, based on the experience of some RSPs using TLS Client Authentication in EPP. 12.2. TLS Client Authentication
As the name implies, this alternative method uses TLS with client authentication, meaning that MoSAPI will authenticate the client using X.509 certificates in HTTPS. TLSA DNS resource records (see RFC6698) are used to provide a mechanism to store the client certificates to be authenticated and authorized for a given TLD.
In order to setup TLS Client Authentication, the Registry Operator (logged with an account allowed to make changes for a TLD) needs to provide three pieces of information in the NSP portal:
1. Domain name for TLS client access (e.g. rsp1.nic.example) 2. Authorized roles related to SLAM (more than one may be chosen): a. MoSAPI - TLD SLAM Data (see, section 5 and 10) b. MoSAPI - TLD DAAR Data (see, section 9) c. MoSAPI - Registrars Base RDAP URL List (see, section 11) d. MoSAPI - TLD Maintenance Window Notification (see, section 6) e. MoSAPI - SLAM Probe Node List Note: other non-MoSAPI related roles may be available in NSP. 3. IP prefixes for access control
MoSAPI 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, at least every hour, will query the DNS (validating with DNSSEC) to get the universe of TLSA RRs per owner name.
58
The following combinations of TLSA Certificate Usages Registry, TLSA Selectors and TLSA Matching Types are supported:
TLSA Certificate TLSA Selectors TLSA Matching Usages Registry 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
12.3. Authentication and Authorization with TLS Client Authentication
MoSAPI will perform the following steps when authenticating and authorizing clients using TLS Client Authentication:
1. A client connects to MoSAPI and provides its certificate during the TLS handshake. 2. MoSAPI verifies that the universe of IP ACLs for whitelisting covers the source IP address of the client attempting the connection. HTTP/403 is returned to the client if this step fails. 3. MoSAPI verifies that the client certificate validates with any TLSA RR of the universe of TLSA RRs. If there is a match, the TLS connection is considered TLS-client authenticated. Otherwise, the TLS session is considered to be non-TLS-client authenticated; the client will still have the option to authenticate using HTTP Basic Access Authentication as before. 4. The client requests access to the SLAM monitoring data of a given TLD. 5. MoSAPI validates that the source IP is whitelisted specifically for the TLD. HTTP/403 is returned to the client if this step fails. 6.1 If the TLS connection is considered TLS-client authenticated, using the set of authorized TLSA RRs for the TLD, MoSAPI validates there is a match for the client certificate. In other words, MoSAPI validates that the client certificate is authorized for the TLD based on the roles permitted in NSP. HTTP/401 is returned to the client if this step fails. 6.2 If the TLS connection is considered non-TLS-client authenticated, HTTP cookies will be used to validate the session as described in sections 3 and 4 of this specification. 7 If client requests access to the monitoring data of another TLD, steps 5 and 6 are repeated.
Every time an HTTPS connection is established, an internal new session is created. Only 4 concurrent sessions are permitted per client certificate. A session is only terminated after its expiration date (by default, the value of expiration date is 4 hours after the session is created), or if the session is the oldest and a new session is being created, that would be above the limit of
59
permitted concurrent sessions. When a session is terminated, the server closes the HTTPS connection.
The error codes HTTP/401 and HTTP/403 described in section 3.1 apply to this section.
60