Near Real Time Mirroring (NRTM) version 4

3.1. Key Configuration and the Database Configuration File

REMOVE BEFORE PUBLICATION: this whole section is wide open to suggestions / ideas¶

When enabling NRTMv4 publication for an IRR Database, the operator MUST generate and configure a private Ed25519 [RFC8032] key. Then, the operator MUST publish the public key, the name of the IRR Database and the URL of the Update Notification File in the Database Configuration File. This is a JSON file on a well-known URI on the "irr-nrtm.json" suffix on the operator's authoritative domain name [RFC8615].¶

The authoritative domain name is the domain which is generally known by the IRR community to belong to the operator of the IRR Database. Note that the Update Notification File, Snapshot File and Delta Files MAY also be hosted on the authoritative domain, or an entirely different host or domain.¶

It is RECOMMENDED that implementations provide easily accessible tools for operators to generate new Ed25519 keys to enter into their configuration, and propose a Database Configuration File from the current configuration. Configuration options SHOULD be clearly named to indicate that they are private keys.¶

3.2. Snapshot Initialization

A mirror server MUST follow the initialization steps upon the first export for an IRR Database by that mirror server, or if the server lost history and can not reliably produce a continuous set of deltas from a previous state.¶

In other words, either the mirror server guarantees that clients following the deltas have a correct and complete view, or MUST reinitialize, which will force clients to reinitialize as well.¶

Initialization consists of these actions:¶

• The mirror server MUST generate a new session ID. This MUST be a random v4 UUID [RFC4122] and MUST be the same across all client sessions. However, if the server instance is serving two different IRR databases (e.g. RIPE IRR and RIPE-NONAUTH IRR), then it MUST generate two session IDs, each one associated with the different database.¶
• The server MUST generate a snapshot for version number one. This may contain an empty array of objects if the IRR Database is currently empty.¶
• The server MUST generate a new Update Notification File with the new session ID, a reference to the new snapshot, and no deltas.¶
• The Update Notification Signature File MUST be updated for the new Update Notification File contents.¶

Note that session IDs, versions and all files always relate to a specific IRR Database. For example, a mirror server publishing NRTMv4 for RIPE and RIPE-NONAUTH, will generate two Update Notification Files, referring two Snapshot Files, and two sets of Delta Files each with contiguous version numbers - all completely independent to each other, with different session IDs. This applies even if the same IRR server instance produces both.¶

3.3. Publishing updates

4.1. Configuration

REMOVE BEFORE PUBLICATION: this whole section is wide open to suggestions / ideas¶

Mirror clients are configured with the name of an IRR Database to mirror and the domain considered authoritative by the mirror client operator, which hosts the Database Configuration File. The mirror client MUST retrieve this file, look for an entry under the expected IRR Database name, and read the Update Notification File URL and the public key. The mirror client MUST only allow retrieval of this file over HTTPS.¶

The mirror client MUST retrieve the Database Configuration File every 24 hours, and update its local configuration if any settings in the file have changed.¶

4.2. Initialization from snapshot

Clients MUST initialize from a Snapshot File when initially configured or if they are not able to update their local data from the provided Delta Files:¶

• The client MUST retrieve the Update Notification File.¶
• The client MUST verify that the source attribute in the Update Notification File matches the configured IRR Database name.¶
• The client MUST retrieve the Snapshot File and load the objects into its local storage.¶
• The mirror client MUST verify that the hash of the Snapshot File matches the hash in the Update Notification File that referenced it. In case of a mismatch of this hash, the file MUST be rejected.¶
• The client MUST record the configured authoritative domain, the session_id and version from the Update Notification File.¶

4.3. Processing Delta Files

If a mirror client has previously initialized from a snapshot:¶

• The client MUST verify that the configured Update Notification File URL matches the previously known URL. If this does not match, the client MUST reinitialize from the Snapshot File, using the new Update Notification File URL.¶
• The client MUST retrieve the Update Notification File.¶
• The client MUST verify that the session ID matches the previously known session ID. If this does not match, the client MUST reinitialize from the snapshot.¶
• The client MUST verify that the Update Notification File version is the same or higher than the client's current most recent version, to the latest version in the Update Notification File. If not, the Update Notification File MUST be rejected.¶
• The client MUST verify that the Update Notification File contains one contiguous set of Delta File versions from the client's current most recent version up to the latest version in the Update Notification File. If this is not found, the client MUST reinitialize from the snapshot.¶
• The client MUST retrieve all Delta Files for versions since the client's last known version, if there are any.¶
• The mirror client MUST verify that the hash of each newly downloaded Delta File matches the hash in the Update Notification File that referenced it. In case of a mismatch of this hash, the Delta File MUST be rejected.¶
• The client MUST process all changes in the Delta Files in order: lowest Delta File version number first, and in the order of the changes list in the Delta File.¶
• The client MUST update its record of the most recent version to the version of the Update Notification File.¶

If the Update Notification File or one of the Delta Files is rejected, the mirror client MUST NOT process any newer Deltas than those that are valid and have been successfully verified.¶

4.4. Signature and Staleness Verification

Every time a mirror client retrieves a new version of the Update Notification File, it MUST retrieve and verify the Update Notification Signature File. The signature MUST be valid for the configured public key for the contents of the Update Notification File.¶

If the signature does not match, the mirror client MUST reject the Update Notification File and retrieve the Database Configuration File, as a mismatch may be caused by a key rotation by the mirror server operator. If the Database Configuration File contains a new public key, the mirror client will attempt to use that key for signature verification instead.¶

A mirror client can use the generation timestamp in the Update Notification File to check whether the file is stale, as the mirror server must update this file at least every 24 hours. If the generation timestamp is more than 24 hours ago, the file is stale and the mirror client SHOULD warn the operator in log messages or other alerting, but MAY continue to process it otherwise.¶

4.5. Policy Restrictions

A mirror client MAY have a policy that restricts the processing of objects to certain object classes, or other limitations on which objects it processes.¶

If a mirror client has a policy that restricts object processing, this MUST be applied consistently to Snapshot Files and Delta Files from the moment the policy is enacted or modified.¶

5.1. Purpose

The Database Configuration File is provided by the IRR Database operator as configuration information for mirror clients. For each IRR Database run by an operator, it contains the current signing key, Snapshot Notification File URL and the IRR Database name. This JSON file MUST be placed on a well-known URI [RFC8615] on the "irr-nrtm.json" suffix on the authoritative domain name of the IRR Database operator and must be available over HTTPS.¶

The operator MUST update this file if any of these configuration details change.¶

5.2. Cache concerns

A mirror server may use caching infrastructure to cache the Database Configuration File and reduce the load of HTTPS requests. Unlike some of the other files, this file is both very small and quite rarely retrieved, limiting the need for and benefits of caching. Since this file is used by mirror clients to determine the current signing key, this SHOULD not cached for longer than one minute to support key rotations.¶

5.3. File format and validation

Example Database Configuration File:¶

[
  {
    "source": "EXAMPLE-A",
    "update_notification": "https://example.net/db/nrtmv4/example-a/notification.json",
    "key": "96..ae"
  },
  {
    "source": "EXAMPLE-B",
    "update_notification": "https://cdn.example.com/db/nrtmv4/example-b/notification.json",
    "key": "b6..3d"
  }
]

Note: the keys in this example are shortened because of formatting.¶

The following validation rules MUST be observed when creating or parsing Database Configuration Files:¶

• The source contains the IRR Database name and MUST be a valid IRR object name [RFC2622], which matches the source in the referred Update Notification File.¶
• The update_notification MUST be the HTTPS URL of the Update Notification File.¶
• The key MUST be the Ed25519 [RFC8032] public key encoded in base64 [RFC4648], which matches the private key the mirror server uses to sign the Update Notification File.¶
• The file MUST contain at least one entry for an IRR Database, but MAY contain multiple with different source values.¶
• The file MUST only contain US-ASCII characters.¶

6.1. Purpose

The Update Notification File is generated by the mirror server and used by mirror clients to discover whether any changes exist between the state of the IRR mirror server and of the mirror client's. It also describes the location of the Snapshot File and incremental Delta Files. Finally, the generation timestamp can be used to detect whether the file is stale.¶

The mirror server MUST generate a new Update Notification File every time there are new deltas or snapshots and, even if there have been no changes, at least every 24 hours.¶

6.2. Cache concerns

A mirror server may use caching infrastructure to cache the Update Notification File and reduce the load of HTTPS requests.¶

However, since this file is used by mirror clients to determine whether any updates are available, the mirror server SHOULD ensure that this file is not cached for longer than one minute. An exception to this rule is that it is better to serve a stale Update Notification File rather than no Update Notification File.¶

6.3. File format and validation

Example Update Notification File:¶

{
  "nrtm_version": 4,
  "timestamp": "2022-01-00T15:00:00Z",
  "type": "notification",
  "source": "EXAMPLE",
  "session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
  "version": 3,
  "snapshot": {
    "version": 2,
    "url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-snapshot.2.047595d0fae972fbed0c51b4a41c7a349e0c47bb.json",
    "hash": "9a..86"
  },
  "deltas": [
    {
      "version": 1,
      "url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.1.784a2a65aba22e001fd25a1b9e8544e058fbc703.json",
      "hash": "62..a2"
    },
    {
      "version": 2,
      "url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.2.0f681f07cfab5611f3681bf030ec9f6fa3442fb0.json",
      "hash": "25..9a"
    },
    {
      "version": 3,
      "url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.3.d9c194acbb2cb0d4088c9d8a25d5871cdd802c79.json",
      "hash": "b4..13"
    }
  ]
}

Note: hash values in this example are shortened because of formatting.¶

The following validation rules MUST be observed when creating or parsing Update Notification Files:¶

• The nrtm_version MUST be 4.¶
• The timestamp MUST be an [RFC3339] timestamp.¶
• The type MUST be "notification".¶
• The source MUST be a valid IRR object name [RFC2622].¶
• The session_id attribute MUST be a random v4 UUID [RFC4122] unique to this session for this source.¶
• The version MUST be an unsigned positive integer and be equal to the highest version of the deltas and snapshot.¶
• The file MUST contain exactly one snapshot.¶
• The file MAY contain one or more deltas.¶
• The deltas MUST have a sequential contiguous set of version numbers.¶
• Each snapshot and delta element MUST have a version, HTTPS URL and hash attribute.¶
• The hash attribute in snapshot and delta elements MUST be the hexadecimal encoding of the SHA-256 hash [SHS] of the referenced file. The mirror client MUST verify this hash when the file is retrieved and reject the file if the hash does not match.¶
• The file MUST only contain US-ASCII characters.¶

6.4. Signature

The contents of Update Notification File MUST be signed using Ed25519 [RFC8032]. The public key for this signature is published in the Database Configuration File. The signature of the Update Notification File MUST be published under the same path as the Update Notification File, appending ".sig".¶

7.1. Purpose

The Snapshot File reflects the complete and current contents of all IRR objects in an IRR Database. Mirror clients MUST use this to initialize their local copy of the IRR Database.¶

7.2. Cache Concerns

A snapshot reflects the content of the IRR Database at a specific point in time; for that reason, it can be considered immutable data. Snapshot Files MUST be published at a URL that is unique to the specific session and version. The URL MUST also contain a random value that can not be predicted before publication, to counter negative caching issues.¶

Because these files never change, they MAY be cached indefinitely. However, as snapshots are large and old snapshots will no longer be referred by newer Update Notification Files, it is RECOMMENDED that a limited interval is used in the order of hours or days.¶

To avoid race conditions where a mirror client retrieves an Update Notification File moments before it's updated, mirror servers SHOULD retain old Snapshot Files for at least 5 minutes after a new Update Notification File is published.¶

7.3. File format and validation

Example Snapshot File:¶

{
  "nrtm_version": 4,
  "type": "snapshot",
  "source": "EXAMPLE",
  "session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
  "version": 2,
  "objects": [
    "route: 192.0.2.0/24\norigin: AS65530\nsource: EXAMPLE",
    "route: 2001:db8::/32\norigin: AS65530\nsource: EXAMPLE"
  ]
}

Note: IRR object texts in this example are shortened because of formatting.¶

The following validation rules MUST be observed when creating or parsing Snapshot Files:¶

• The nrtm_version MUST be 4.¶
• The type MUST be "snapshot".¶
• The source MUST match the source in the Update Notification File.¶
• The session_id attribute MUST match the session_id in the Update Notification File.¶
• The version MUST be an unsigned positive integer, matching the Update Notification File entry for this snapshot.¶
• The objects attribute MUST be an array of zero or more elements, each containing a string representation of an IRR object. The string representation MUST be encoded in UTF-8 in Quoted-Printable encoding [RFC2045].¶
• The source attribute in the IRR object texts MUST match the source attribute of the Snapshot File.¶
• The file MUST only contain US-ASCII characters.¶

8.1. Purpose

A Delta File contains all changes for exactly one incremental update of the IRR Database. It may include new, modified and deleted objects. Delta Files can contain multiple alterations to multiple objects.¶

8.2. Cache Concerns

Deltas reflect the difference in content of the IRR Database from one version to another; for that reason, it can be considered immutable data. Delta Files MUST be published at a URL that is unique to the specific session and version. The URL MUST also contain a random value that can not be predicted before publication, to counter negative caching issues.¶

To avoid race conditions where a mirror client retrieves an Update Notification File moments before it's updated, mirror servers SHOULD retain old Delta Files for at least 5 minutes after a new Update Notification File is published that no longer contains these Delta Files.¶

8.3. File format and validation

Example Delta File:¶

{
  "nrtm_version": 4,
  "type": "delta",
  "source": "EXAMPLE",
  "session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
  "version": 3,
  "changes": [
    {
      "action": "delete",
      "existing_object": "route: 192.0.2.0/24\norigin: AS65530\nsource: EXAMPLE"
    },
    {
      "action": "add_modify",
      "new_object": "route: 2001:db8::/32\norigin: AS65530\nsource: EXAMPLE"
    }
  ]
}

Note: IRR object texts in this example are shortened because of formatting.¶

The following validation rules MUST be observed when creating or parsing Delta Files:¶

• The nrtm_version MUST be 4.¶
• The type MUST be "delta".¶
• The source MUST match the source in the Update Notification File.¶
• The session_id attribute MUST match the session_id in the Update Notification File.¶
• The version MUST be an unsigned positive integer, matching the Update Notification File entry for this delta.¶

• The changes attribute MUST be an array of one or more elements, each having:¶

  • An action attribute, which is either "delete" for object deletions, or "add_modify" for additions or modifications.¶
  • If action is "delete": an existing_object attribute with the RPSL text of the last version of the object prior to deletion.¶
  • If action is "add_modify": a new_object attribute with the RPSL text of the new version of the object.¶
  • The string representation of the objects MUST be encoded in UTF-8 in Quoted-Printable encoding [RFC2045].¶
• The source attribute in the IRR object texts MUST match the source attribute of the Delta File.¶
• The file MUST only contain US-ASCII characters.¶

9.1. IRR object Validation

Throughout the years, various implementations of IRR servers have taken liberties with the various RFCs regarding RPSL. Implementations have introduced different new object classes, attributes and validation rules. Current IRR Databases also contain legacy objects which were created under different validation rules. In practice, there is no uniformly implemented standard for RPSL, but merely rough outlines partially documented in different places.¶

This has the potential to create interoperability issues. Some are addressed by NRTMv4, like having a consistent character set when mirroring data between implementations. However, some issues can not be addressed in this way, such as one implementation introducing a new object class that is entirely unknown to another implementation.¶

A mirror client SHOULD be able to handle unknown object classes and objects that are invalid according to its own validation rules, which may mean simply discarding them, without rejecting remaining objects or preventing future updates.¶

It is RECOMMENDED for mirror clients to log these cases, particularly those where an object was discarded due to violating validation rules. These cases create an inconsistency between the IRR objects of the server and client, and logs facilitate later analysis.¶

It is RECOMMENDED for mirror clients to be flexible where possible and reasonable when applying their own validation rules to IRR objects retrieved from mirror servers. For example, a route object with an origin attribute that is not a valid AS number can't be usefully interpreted. There is no way for an IRR server to correctly parse and index such an object. However, a route-set object whose name does not start with "RS-" [RFC2622], or an inetnum with an unknown extra "org" attribute, still allows the mirror client to interpret it unambiguously even if it does not meet the mirror client's own validation rules for authoritative records.¶

9.2. Intermediate mirror instances

An IRR Database generally has a single authoritative source. In some cases, an instance run by a third party will function as a kind of intermediate: both being a mirror client, mirroring IRR objects from the authoritative source, and simultaneously function as a mirror server to yet another mirror client.¶

There are various operational reasons for such a setup, such as the intermediate filtering certain records. Regardless of the reason, the mirror client and server function of an IRR server must be treated as separate processes. In particular, this means they MUST have separate session IDs. The intermediate server MUST NOT republish the same files it retrieved from the authoritative source with the same session ID.¶

9.3. Reading from local files

In the typical use case for NRTMv4, a mirror client retrieves files from an HTTPS endpoint. However, implementations MAY also support reading from files on the local filesystem instead, for when operators want to use a different method to retrieve or distribute the files. When reading from local files, mirror clients SHOULD still follow all validation rules, including the validation of the signature and hashes.¶

9.4. Public key rotation

It is RECOMMENDED that IRR Database operators rotate the signing key on their mirror server about once per year. To support this, the mirror server implementation MUST provide a way for operators to immediately generate a new Update Notification File on demand. To perform the rotation, the operator then:¶

• Generates a new key.¶
• Prepares a new Database Configuration File with the new public key.¶
• Configures the new private key in the mirror server software.¶
• Makes the mirror server software generate a new Update Notification File.¶
• Publishes the new Database Configuration File.¶

Mirror clients will load the Update Notification File, find the signature to be invalid, retrieve the Database Configuration File and configure the new key. Note that key rotation will briefly but significantly increase the retrievals of the Database Configuration File, as almost every current mirror client will retrieve it within the minute after publication of the new Update Notification File.¶

13.1. Normative References

[RFC2045]

Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, <https://www.rfc-editor.org/info/rfc2045>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC2622]

Alaettinoglu, C., Villamizar, C., Gerich, E., Kessens, D., Meyer, D., Bates, T., Karrenberg, D., and M. Terpstra, "Routing Policy Specification Language (RPSL)", RFC 2622, DOI 10.17487/RFC2622, June 1999, <https://www.rfc-editor.org/info/rfc2622>.

[RFC3339]

Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/info/rfc3339>.

[RFC4122]

Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005, <https://www.rfc-editor.org/info/rfc4122>.

[RFC4648]

Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/info/rfc4648>.

[RFC7525]

Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <https://www.rfc-editor.org/info/rfc7525>.

[RFC8032]

Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, <https://www.rfc-editor.org/info/rfc8032>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/info/rfc8615>.

[SHS]

National Institute of Standards and Technology, "Secure Hash Standard", March 2012, <http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf>.

13.2. Informative References

[RFC8182]

Bruijnzeels, T., Muravskiy, O., Weber, B., and R. Austein, "The RPKI Repository Delta Protocol (RRDP)", RFC 8182, DOI 10.17487/RFC8182, July 2017, <https://www.rfc-editor.org/info/rfc8182>.