RPKI ReadTheDocs

By on 13 Jul 2021

Category: Tech matters

Tags: , , , , ,

Blog home

Looking at the Resource Public Key Infrastructure (RPKI) landscape today, it is vastly different from two to three years ago. At the time, resource holders around the world had created a considerable amount of Route Origin Authorization (ROAs), but actually using RPKI data to perform Route Origin Validation (ROV) was only done by a handful of networks.

As the interest in RPKI was ramping up in leaps and bounds, I noticed during meetings and online conversations there were a lot of misconceptions about what RPKI can and cannot do. The more than 40 Requests For Comment (RFCs) that describe RPKI aren’t always helpful in this regard, as they will just give you the idea that it’s an X.509 PKI in which certificates and other signed objects that make use of Cryptographic Message Syntax (CMS) using an ASN.1 profile are published, without even mentioning it’s for routing security. This is to be expected of an Internet Engineering Task Force (IETF) document of course, as the RFCs naturally focus on intricate details of the syntax and encoding of data needed by implementers.

On the other side of the spectrum, you may conclude that you’re merely dealing with a bunch of fancy ‘route:’ objects from the Internet Routing Registry (IRR).

Lastly, the fact that RPKI suffers from the same acronym overload that our entire industry faces doesn’t help either. Let’s face it, I’ve already used seven TLAs (Three-letter acronyms) since I started this article.


Since 2009, I had been responsible for the RIPE NCC RPKI implementation — or perhaps I should say — the Réseaux Internet Protocol Européens Network Coordination Centre Resource Public Key Infrastructure implementation. I recall one of the biggest challenges was to clearly separate what is important to convey to the user and what is ‘safe to hide’. I noticed that the developers I worked with were often unsure whether to include a data point or not and, when in doubt, would include it because ‘it might be useful to someone’. This left us with documentation and a user interface that exposed every detail about the signed objects, much like what you see in the researcher-oriented toolset JDR today.

For example, we concluded early on that explaining and displaying the Subject Information Access (SIA) and Authority Information Access (AIA) pointers in the user interface weren’t going to help anyone. What is important, however, is that people understand the difference between a valid ROA and a valid route. I can no longer count the number of times I have explained that only a valid ROA can make a route invalid, or that a single ROA can authorize one route but at the same time make hundreds of more-specific customer announcements invalid.

These were the things people needed to know!


With these experiences under my belt, in 2017 I started a new adventure at NLnet Labs, building open source software that supports core Internet infrastructure. Having written documentation about RPKI once before from an RIR perspective, we needed to document the brand new tooling we were building: the Certificate Authority software, Krill and the Relying Party software, Routinator

While I was at it, I figured it would be a nice idea to document RPKI itself as an open source project, putting everything I had learned over the years in a single place. The idea was that documenting Krill and Routinator would be like explaining how some of the tools in your tool chest work and documenting RPKI would be akin to teaching you how to build a house using all the tools at your disposal.

Read: How to create RPKI ROAs in MyAPNIC

I decided the easiest way to make the project truly collaborative was to use a well-documented markup language (ReStructuredText), use a well-known version control system (Git), a commonly used platform to host the source (GitHub), and an equally well-known platform to publish the documentation (ReadTheDocs).

Now, anyone can open a pull request suggesting an edit, or an addition to the documentation. Fantastic!

What we attempt to do with rpki.readthedocs.io is to explain the things that matter when using RPKI to publish statements about your authorized routes, as well as using these statements to filter invalid routes. It doesn’t try to summarize the 40 RFCs that make up the RPKI but instead, explains what it is, what it can and cannot do, and how to use the rather sharp tools without cutting yourself. At the same time, it purposely leaves out what is ‘safe to hide’. 

The documentation is currently organized into three main sections:

  • The General section contains this introduction as well as information about the licensing, authors, and more. It also contains the FAQ and the Quick Help.
  • The RPKI Technology section explains the RPKI technology and standards in order for you to get a good sense of the requirements and moving parts. It will help you choose the right RPKI solution for your organization, with regard to generating, publishing, and using RPKI data.
  • The Operations section is about various open source projects that are maintained to support RPKI, as well as router support and external resources.

In short, rpki.readthedocs.io explains how RPKI is all about IP resources. Specifically, it explains how currently RPKI only allows the legitimate holder of an IP prefix to publish an authoritative statement about which Autonomous System is authorized to originate their prefixes in the Border Gateway Protocol. It also explains how network operators around the world can use the collection of these statements to filter unauthorized route origins.

On top of that, it lays out the certificate structure which enables ROV, as well as the difference between hosted and delegated RPKI, functional differences across RIRs, and offers an overview of supported software and hardware, as well as additional resources for further reading.

If you feel there is something wrong or missing, you can always create a pull request on the GitHub repository, open an issue, post a message on the RPKI mailing list or discuss RPKI on Discord. It is the power of open source and the community that makes this project work and contributions are encouraged.

Going forward, as the capabilities of RPKI evolve, new topics will be added.

Alex Band is the Director of Product Development at NLnet Labs.

Rate this article

The views expressed by the authors of this blog are their own and do not necessarily reflect the views of APNIC. Please note a Code of Conduct applies to this blog.

Leave a Reply

Your email address will not be published. Required fields are marked *