RPKI Validator API

The RPKI Validator API allows you to export all Route Origin Authorisations (ROAs) in CSV and JSON format. In addition, you can query the Validator for the RPKI validity state of a BGP announcement through a RESTful API. The responses are in JSON format and in addition to the validity state, the ROAs that caused the state are returned, along with the reason.

When the RPKI Validator is running, a web server is available for configuring and querying the application. In RPKI Validator 2.11 and newer, you can query a RESTful API. When you supply a combination of Autonomous System (AS) and prefix, they will be matched against all the Validated ROA Prefixes (VRPs) that are in the cache of the RPKI Validator. The result is returned in JSON format and contains the following information:

  • The RPKI validity state, as described in RFC 6811
  • The Validated ROA Prefixes (VRPs) that caused the state
  • In case of an 'Invalid' state, the reason:
    • The prefix is originated from an unauthorised AS
    • The prefix is more specific than allowed in the Maximum Length of the ROA

Usage

Example 1: Valid

For this BGP announcement, there is at least one ROA that matches the prefix and AS:

$ curl http://localhost:8080/api/v1/validity/AS12654/93.175.146.0/24
{
"validated_route":{
"route":{
"origin_asn":"AS12654",
"prefix":"93.175.146.0/24"
},
"validity":{
"state":"Valid",
"description":"At least one VRP Matches the Route Prefix",
"VRPs":{
"matched":[{
"asn":"AS12654",
"prefix":"93.175.146.0/24",
"max_length":24
}],
"unmatched_as":[],
"unmatched_length":[]
}
}
}
}

All of the ROAs that match with the prefix will be returned in the response and grouped according to the validation result. As long as there is at least one ROA that matches with the AS and the Maximum Prefix length, the BGP announcement will be regarded as Valid:

$ curl http://localhost:8080/api/v1/validity/AS559/193.5.22.0/24
{
"validated_route":{
"route":{
"origin_asn":"AS559",
"prefix":"193.5.22.0/24"
},
"validity":{
"state":"Valid",
"description":"At least one VRP Matches the Route Prefix",
"VRPs":{
"matched":[{
"asn":"AS559",
"prefix":"193.5.22.0/24",
"max_length":24
}],
"unmatched_as":[{
"asn":"AS3303",
"prefix":"193.5.0.0/16",
"max_length":24
}],
"unmatched_length":[]
}
}
}
}

Example 2: Invalid, because of an unauthorised AS

For this BGP announcement there is a ROA that matches the prefix, but it is being originated from a unauthorised AS:

$ curl http://localhost:8080/api/v1/validity/AS12654/93.175.147.0/24
{
"validated_route":{
"route":{
"origin_asn":"AS12654",
"prefix":"93.175.147.0/24"
},
"validity":{
"state":"Invalid",
"reason":"as",
"description":"At least one VRP Covers the Route Prefix, but no VRP ASN matches the route origin ASN",
"VRPs":{
"matched":[],
"unmatched_as":[{
"asn":"AS196615",
"prefix":"93.175.147.0/24",
"max_length":24
}],
"unmatched_length":[]
}
}
}

Example 3: Invalid, because the BGP announcement is too specific

For this BGP announcement there is a ROA that matches the prefix, but it is more specific than is allowed by the Maximum Length in the ROA:

$ curl http://localhost:8080/api/v1/validity/AS196615/93.175.147.0/25
{
"validated_route":{
"route":{
"origin_asn":"AS196615",
"prefix":"93.175.147.0/25"
},
"validity":{
"state":"Invalid",
"reason":"length",
"description":"At least one VRP Covers the Route Prefix, but the Route Prefix length is greater than the maximum length allowed by VRP(s) matching this route origin ASN",
"VRPs":{
"matched":[],
"unmatched_as":[],
"unmatched_length":[{
"asn":"AS196615",
"prefix":"93.175.147.0/24",
"max_length":24
}]
}
}
}
}

Example 4: Not Found

For this BGP announcement, there is no ROA that matches the prefix and AS:

$ curl http://localhost:8080/api/v1/validity/AS12654/2001:7fb:ff03::/48
{
"validated_route":{
"route":{
"origin_asn":"AS12654",
"prefix":"2001:7fb:ff03::/48"
},
"validity":{
"state":"NotFound",
"description":"No VRP Covers the Route Prefix",
"VRPs":{
"matched":[],
"unmatched_as":[],
"unmatched_length":[]
}
}
}
}

Error Codes

If you make a mistake in the notation of the RESTful URL, the RPKI Validator API will return detailed messages. In these examples, the '-i' flag is added to curl to display the associated HTTP status codes.

Malformed URL

$ curl -i http://localhost:8080/api/foo
HTTP/1.1 404 Not Found
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/json;charset=UTF-8
Content-Length: 61
Server: Jetty(8.1.3.v20120416)

{
"message":"Unrecognized request URL (GET: /api/foo})."
}

Malformed AS Number

The AS Number can be formatted as "AS12654" or simply "12654", but any other notation is not supported:

$ curl -i http://localhost:8080/api/v1/validity/ASN12654/93.175.1460/24
HTTP/1.1 400 Bad Request
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/json;charset=UTF-8
Cache-Control: no-cache,no-store
Content-Length: 47
Server: Jetty(8.1.3.v20120416)

{
"message":"'ASN12654' is not a valid ASN"
}

Malformed IP Prefix

IPv4 prefixes should be written in CIDR notation, i.e. 4-octets followed by the "/" (slash) character, followed by a decimal value that describes the number of significant bits. IPv6 prefixes should use the standard notation of 4 hexadecimal digits in groups separated by colons (:). Removing leading zeros and replacing consecutive sections of zeroes with a double colon (::) is supported. Other notations, such as a single IP address followed by a prefix is not supported:

$ curl -i http://localhost:8080/api/v1/validity/AS12654/2001:7fb:ff03::1/48
HTTP/1.1 400 Bad Request
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/json;charset=UTF-8
Cache-Control: no-cache,no-store
Content-Length: 83
Server: Jetty(8.1.3.v20120416)

{
"message":"'2001:7fb:ff03::1/48' is not a valid IPv4 or IPv6 prefix"
}