forked from mxsasha/nrtmv4
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-grow-nrtm-v4.txt
1232 lines (816 loc) · 46.5 KB
/
draft-ietf-grow-nrtm-v4.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
GROW S. Romijn
Internet-Draft Reliably Coded
Intended status: Standards Track J. Snijders
Expires: 17 November 2024 Fastly
E. Shryane
RIPE NCC
S. Konstantaras
AMS-IX
16 May 2024
Near Real Time Mirroring (NRTM) version 4
draft-ietf-grow-nrtm-v4-04
Abstract
This document specifies a one-way synchronization protocol for
Internet Routing Registry (IRR) records. The protocol allows
instances of IRR database servers to mirror IRR records, specified in
the Routing Policy Specification Language (RPSL), between each other.
Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 17 November 2024.
Romijn, et al. Expires 17 November 2024 [Page 1]
Internet-Draft NRTM v4 May 2024
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Informal overview . . . . . . . . . . . . . . . . . . . . . . 3
3. Mirror server use . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Key Configuration . . . . . . . . . . . . . . . . . . . . 5
3.2. Snapshot Initialization . . . . . . . . . . . . . . . . . 5
3.3. Publishing updates . . . . . . . . . . . . . . . . . . . 6
3.3.1. Delta Files . . . . . . . . . . . . . . . . . . . . . 6
3.3.2. Snapshot Files . . . . . . . . . . . . . . . . . . . 7
3.3.3. Update Notification File . . . . . . . . . . . . . . 7
3.3.4. Publication Policy Restrictions . . . . . . . . . . . 8
4. Mirror client use . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Client Configuration . . . . . . . . . . . . . . . . . . 8
4.2. Initialization from snapshot . . . . . . . . . . . . . . 8
4.3. Processing Delta Files . . . . . . . . . . . . . . . . . 9
4.4. Signature and Staleness Verification . . . . . . . . . . 10
4.5. Policy Restrictions . . . . . . . . . . . . . . . . . . . 10
5. Update Notification File . . . . . . . . . . . . . . . . . . 10
5.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2. Cache concerns . . . . . . . . . . . . . . . . . . . . . 11
5.3. File format and validation . . . . . . . . . . . . . . . 11
5.4. Signature . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Snapshot File . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2. Cache Concerns . . . . . . . . . . . . . . . . . . . . . 13
6.3. File format and validation . . . . . . . . . . . . . . . 14
7. Delta File . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.2. Cache Concerns . . . . . . . . . . . . . . . . . . . . . 15
7.3. File format and validation . . . . . . . . . . . . . . . 15
8. Operational Considerations . . . . . . . . . . . . . . . . . 16
8.1. IRR object Validation . . . . . . . . . . . . . . . . . . 17
8.2. Intermediate mirror instances . . . . . . . . . . . . . . 17
Romijn, et al. Expires 17 November 2024 [Page 2]
Internet-Draft NRTM v4 May 2024
8.3. Reading from local files . . . . . . . . . . . . . . . . 18
8.4. Public key rotation . . . . . . . . . . . . . . . . . . . 18
9. Security Considerations . . . . . . . . . . . . . . . . . . . 19
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
12.1. Normative References . . . . . . . . . . . . . . . . . . 20
12.2. Informative References . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
1. Introduction
The Internet Routing Registry (IRR) consists of several IRR
Databases, each storing objects in the Routing Policy Specification
Language (RPSL). About a dozen larger IRR Databases are well known
and widely used, operated by different organisations, like RIRs and
some large network operators. IRR objects serve many purposes,
ranging from manual research by operators to automated network
configuration and filtering.
Most of these well known IRR Databases mirror IRR objects from some
others, so that queries run against these instances provide a
comprehensive view. Some parties also mirror IRR Databases to
private IRR server instances, to reduce latency in queries, analyze
IRR objects, or other purposes.
NRTM version 4 is a protocol for IRR mirroring, designed to address
issues in existing IRR Database mirroring protocols. In NRTMv4, IRR
Databases publish their records on an HTTPS endpoint, with periodic
Snapshot Files and regular Delta Files. Signing allows integrity
checks. By only generating files once and publishing them over
HTTPS, scalability is dramatically improved. It borrows some
concepts in [RFC8182], as there are overlaps between the two
protocols.
2. Informal overview
In NRTMv4, a mirror server is an instance of IRR Database software
that has a database of IRR objects and publishes them to allow
mirroring by others. This can be retrieved by mirror clients, which
then load the IRR objects into their local storage.
Publication consists of three different files:
Romijn, et al. Expires 17 November 2024 [Page 3]
Internet-Draft NRTM v4 May 2024
* A single Update Notification File. This specifies the current
Database version and locations of the Snapshot File and Delta
Files. Additionally, there is an Update Notification Signature
File, used to verify the authenticity of the Update Notification
File.
* A single active Snapshot File. This contains all published IRR
objects at a particular version. The mirror server periodically
generates a new snapshot.
* Zero or more Delta Files. These contain the changes between two
database version numbers.
The Update Notification file MUST be in the JavaScript Object
Notation (JSON) format [RFC8259]. The Snapshot File and Delta Files
MUST be in the JSON Text Sequences [RFC7464] format, so that each
object in large files can be parsed independently. All files MUST
use UTF-8 encoding and MAY be compressed with GZIP [RFC1952].
Mirror clients initially retrieve the small Update Notification File
and a Snapshot File, from which they initialize their local copy of
the Database. After that, mirror clients only retrieve the Update
Notification File periodically to determine whether there are any
changes, and then retrieve only the relevant Delta Files, if any.
This minimizes data transfer. Deltas have sequential versions.
Mirror clients are configured with the URL of an Update Notification
File, name of the IRR Database, and a public signing key. This
public key is used to verify the Update Notification File, which in
turn contains hashes of all the Snapshot and Delta Files.
Upon initialization, the mirror server generates a session ID for the
Database. This allows long term caching and used by the client to
determine that the Delta Files continue to form a full set of changes
allowing an update to the latest version. If the mirror server loses
partial history, or the mirror client starts mirroring from a
different server, the session ID change will force a full reload from
the latest Snapshot File, ensuring there are no accidental mirroring
gaps.
Mirror servers can use caching to reduce their load, particularly
because snapshots and deltas are immutable for a given session ID and
version number. These are also the largest files. Update
Notification Files may not be cached for longer than one minute, but
are fairly small.
Romijn, et al. Expires 17 November 2024 [Page 4]
Internet-Draft NRTM v4 May 2024
Note that in NRTMv4, a contiguous version number is used for the
Database version and Delta Files. This is different and unrelated to
the serial in NRTMv3. NRTMv3 serials refer to a single change to a
single object, whereas a NRTMv4 version refers to one delta, possibly
containing multiple changes to multiple objects. NRTMv3 serials can
also contain gaps, NRTMv4 versions may not.
3. Mirror server use
3.1. Key Configuration
When enabling NRTMv4 publication for an IRR Database, the operator
MUST generate and configure a private Ed25519 [RFC8032] key. The
operator then provides this public key, the name of the IRR Database,
and publication URL of the Update Notification File to any operators
of mirror clients. The published public key MUST be encoded in
base64 [RFC4648]. The process for providing this is not in scope of
this protocol, but a typical case is publication on the operator's
known website. Key rotation is described in Section 8.4.
It is RECOMMENDED that implementations provide easily accessible
tools for operators to generate new Ed25519 keys to enter into their
configuration and assist with key rotation. All 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. The session ID is unique to the IRR Database, so an
instance that serves multiple IRR Databases, will create a
separate session ID for each.
* 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.
Romijn, et al. Expires 17 November 2024 [Page 5]
Internet-Draft NRTM v4 May 2024
* 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 a publication, and its associated session IDs and versions,
always relates to a single specific IRR Database, even if multiple
databases are published from one instance. 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, potentially at
different times. This applies even if the same IRR server instance
produces both.
3.3. Publishing updates
3.3.1. Delta Files
Changes to IRR objects MUST be recorded in Delta Files. One Delta
File can contain multiple changes.
Updates are generated as follows:
* A mirror server MUST publish a Delta File approximately every
minute, if there have been changes to IRR objects in that time
frame.
* If multiple changes have occurred within the time frame that would
cancel each other out, like an addition and immediate deletion of
the same object, the mirror server MUST still include all these
changes.
* If a mirror server is lagging in production of Delta Files, such
as after an initialization or server downtime, it MUST generate
one larger "catch up" Delta File, rather than individual Delta
Files for every one minute window.
* A new Delta File MUST be generated with a new version, one greater
than the last Delta File version, or one greater than the last
Snapshot File version if there were no prior deltas at all.
* The Delta File MUST include all changes that happened during the
time frame, in the order in which they occurred.
Romijn, et al. Expires 17 November 2024 [Page 6]
Internet-Draft NRTM v4 May 2024
* The URL where the Delta File is published MUST contain the session
ID and version number to allow it to be indefinitely cached. It
MUST also contain a random value that can not be predicted before
publication, to counter negative caching issues.
* After generating a new Delta File, a mirror server SHOULD remove
all Delta Files older than 24 hours.
* The Update Notification File MUST be updated to include the new
Delta File and update the database version.
* Note that, as Delta Files always contain changes compared to a
previous state, there can never be a Delta File with version 1.
3.3.2. Snapshot Files
Snapshot Files after initialization are generated as follows:
* The mirror server MUST generate a new Snapshot File between once
per hour and once per day, if there have been changes to the IRR
objects.
* The version number of the new snapshot MUST be equal to the last
Delta File version.
* If there have been no changes to the IRR objects since the last
snapshot, the mirror server MUST NOT generate a new snapshot.
* The URL where the Snapshot File is published MUST contain the
session ID and version number to allow it to be indefinitely
cached. It MUST also contain a random value that can not be
predicted before publication, to counter negative caching issues.
* The Update Notification File MUST be updated to include the new
snapshot, if one was generated.
* Snapshot generation may take some time, and in that time newer
changes may occur that are not part of the snapshot in progress.
The mirror server SHOULD continue to produce Delta Files during
this window, which means the server MAY publish a Snapshot File
with a version number older than the most recent Delta File at the
time of publication.
3.3.3. Update Notification File
The Update Notification File must be updated when a new Delta or
Snapshot File is published and, even if there have been no changes,
at least every 24 hours.
Romijn, et al. Expires 17 November 2024 [Page 7]
Internet-Draft NRTM v4 May 2024
After any update to the Update Notification file, the mirror server
MUST also generate a new Update Notification Signature File for the
new Update Notification File contents.
3.3.4. Publication Policy Restrictions
A mirror server MAY have a policy that restricts the publication of
certain IRR objects or attributes, or modifies these before
publication. Typical scenarios for this include preventing the
distribution of certain personal data or password hashes, or
excluding objects which do not meet validation rules like RPKI
consistency. It is RECOMMENDED to modify objects in such a way that
this change is evident to humans reading the object text, for example
by adding remark lines or comments.
Mirror servers are RECOMMENDED to remove password hashes from the
auth lines in mntner objects, as they have little use beyond the
authoritative server, and their publication may be a security risk.
If a mirror server has a policy that restricts or modifies object
publication, this MUST be applied consistently to Snapshot Files and
Delta Files from the moment the policy is enacted or modified.
4. Mirror client use
4.1. Client Configuration
Mirror clients are configured with the name of the IRR Database, the
URL of the Update Notification File, and the public key currently
used for signing the Update Notification File. Key rotation is
described in Section 8.4.
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.
Romijn, et al. Expires 17 November 2024 [Page 8]
Internet-Draft NRTM v4 May 2024
* The mirror client MUST verify that the hash of the Snapshot File
matches the hash in the Update Notification File that referenced
it. If the Snapshot File was compressed with GZIP, the hash MUST
match the compressed data. In case of a mismatch of this hash,
the file MUST be rejected.
* The client MUST record the session_id and version of the loaded
Snapshot File.
4.3. Processing Delta Files
If a mirror client has previously initialized from a snapshot:
* 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 after the client's
current most recent version up to the latest version in the Update
Notification File. If the Delta File versions are not contiguous,
the Update Notification File MUST be rejected. If the available
Delta File versions do not range from the client's most recent
version plus one, 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. If the Delta File was compressed with
GZIP, the hash MUST match the compressed file. 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.
Romijn, et al. Expires 17 November 2024 [Page 9]
Internet-Draft NRTM v4 May 2024
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. If some
Delta Files are rejected, it MAY process the valid Delta Files, but
MUST NOT skip over any rejected Delta Files while doing so.
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, unless a key rotation is in progress as
described in Section 8.4.
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. Update Notification File
5.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.
Romijn, et al. Expires 17 November 2024 [Page 10]
Internet-Draft NRTM v4 May 2024
5.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.
5.3. File format and validation
Example Update Notification File:
{
"nrtm_version": 4,
"timestamp": "2022-01-01T15:00:00Z",
"type": "notification",
"next_signing_key": "bnJ0..bXY0",
"source": "EXAMPLE",
"session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
"version": 4,
"snapshot": {
"version": 3,
"url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-snapshot.2.047595d0fae972fbed0c51b4a41c7a349e0c47bb.json.gz",
"hash": "9a..86"
},
"deltas": [
{
"version": 2,
"url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.1.784a2a65aba22e001fd25a1b9e8544e058fbc703.json",
"hash": "62..a2"
},
{
"version": 3,
"url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.2.0f681f07cfab5611f3681bf030ec9f6fa3442fb0.json",
"hash": "25..9a"
},
{
"version": 4,
"url": "https://example.com/ca128382-78d9-41d1-8927-1ecef15275be/nrtm-delta.3.d9c194acbb2cb0d4088c9d8a25d5871cdd802c79.json",
"hash": "b4..13"
}
]
}
Romijn, et al. Expires 17 November 2024 [Page 11]
Internet-Draft NRTM v4 May 2024
Note: hash and key values in this example are shortened because of
formatting.
The following validation rules MUST be observed when creating or
parsing Update Notification Files:
* The filename MUST be "update-notification-file.json".
* The nrtm_version MUST be 4.
* The timestamp MUST be an [RFC3339] timestamp.
* The type MUST be "notification".
* The optional field next_signing_key is used for in-band key
rotation. If present, it MUST be an Ed25519 [RFC8032] public key
encoded in base64 [RFC4648], which matches the private key the
mirror server will start using to sign the Update Notification
File in the near future. Key rotation is described in
Section 8.4. If there is no next signing key, this key MUST be
omitted.
* 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. If the snapshot or delta file was compressed with
GZIP, the filename MUST end in ".gz". and the hash MUST match the
compressed data.
* 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.
Romijn, et al. Expires 17 November 2024 [Page 12]
Internet-Draft NRTM v4 May 2024
5.4. Signature
The mirror server publishes a signature for each Update Notification
File, which the client uses to verify the contents against the known
public key.
* The contents of Update Notification File MUST be signed using
Ed25519 [RFC8032].
* The Update Notification File Signature File contains the Ed25519
signature encoded in base64 [RFC4648].
* The Update Notification File Signature File MUST be published
under the same path as the Update Notification File, under the
filename "update-notification-file-[hash].sig", where the hash is
the hexadecimal encoding of the SHA-256 hash [SHS] of the Update
Notification File contents.
* To avoid race conditions, the mirror server MUST publish the new
signature file before publishing the new Update Notification File,
and SHOULD retain old signature files for at least 5 minutes after
a new Update Notification File is published.
6. Snapshot File
6.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.
6.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.
Romijn, et al. Expires 17 November 2024 [Page 13]
Internet-Draft NRTM v4 May 2024
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.
6.3. File format and validation
Example Snapshot File:
␞{
"nrtm_version": 4,
"type": "snapshot",
"source": "EXAMPLE",
"session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
"version": 3
}
␞{"object": "route: 192.0.2.0/24\norigin: AS65530\nsource: EXAMPLE"}
␞{"object": "route: 2001:db8::/32\norigin: AS65530\nsource: EXAMPLE"}
Note: IRR object texts in this example are shortened because of
formatting.
The file is in JSON Text Sequences [RFC7464] format, and MUST contain
one or more records (it must contain at least the header). The first
record is the file header, and the following validation rules MUST be
observed when creating or parsing a Snapshot File header:
* 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 remaining records (zero or more) MUST each contain a string
representation of an IRR object. The source attribute in the IRR
object texts MUST match the source attribute of the Snapshot File.
7. Delta File
Romijn, et al. Expires 17 November 2024 [Page 14]
Internet-Draft NRTM v4 May 2024
7.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.
7.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.
7.3. File format and validation
Example Delta File:
␞{
"nrtm_version": 4,
"type": "delta",
"source": "EXAMPLE",
"session_id": "ca128382-78d9-41d1-8927-1ecef15275be",
"version": 3
}
␞{
"action": "delete",
"object_class": "person",
"primary_key": "PRSN1-EXAMPLE"
}
␞{
"action": "delete",
"object_class": "route",
"primary_key": "192.0.2.0/24AS65530"
}
␞{
"action": "add_modify",
"object": "route: 2001:db8::/32\norigin: AS65530\nsource: EXAMPLE"
}
Romijn, et al. Expires 17 November 2024 [Page 15]
Internet-Draft NRTM v4 May 2024
Note: IRR object texts in this example are shortened because of
formatting.
The file is in JSON Text Sequences [RFC7464] format, and MUST contain
two or more records (at least the header and one change). The first
record is the file header, and the following validation rules MUST be
observed when creating or parsing a Delta File header:
* 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 remaining records (one or more) MUST each contain a JSON object
representing a change, which MUST meet the following rules:
* An action attribute, which is either "delete" for object
deletions, or "add_modify" for additions or modifications.
* If action is "delete": an object_class attribute with the RPSL
object class name, and a primary_key attribute with the primary
key, of the deleted object. For objects that are listed in
[RFC2622] and [RFC4012] the primary key is the value of the RPSL
field defined as "class key". For object classes that define a
pair of attributes as class key, e.g. route, the values of the
individual attributes are appended together without separators.
For any other objects, the primary key is the value of the RPSL
field with the same name as the object class name. The primary
key and object class name are not case sensitive and therefore
mirror clients MUST use case insensitive matching against their
local database.
* If action is "add_modify": an object attribute with the RPSL text
of the new version of the object.
8. Operational Considerations
Romijn, et al. Expires 17 November 2024 [Page 16]
Internet-Draft NRTM v4 May 2024
8.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.
8.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
Romijn, et al. Expires 17 November 2024 [Page 17]
Internet-Draft NRTM v4 May 2024
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.
8.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. Mirror clients MUST NOT allow a mix of reading
from local files and HTTPS for a specific IRR Database.
8.4. Public key rotation
It is RECOMMENDED that IRR Database operators rotate the signing key
on their mirror server about once per year. The next_signing_key
field in the Update Notification File supports in-band key rotation
using the following process:
* The server operator generates a new key and configures this in the
mirror server implementation as the upcoming new signing key.
* The mirror server MUST include this key in the next_signing_key
field in any Update Notification File generated while the new
signing key is configured. Hence, the new signing key will start
being propagated to the mirror clients with the next publication
of the Notification File, which will take at most 24 hours.
Mirror server implementations MAY offer a method to cause the
Notification Update File to be refreshed earlier, with the
new_signing_key included, and thus start the propagation earlier.
* When mirror clients next retrieve the Update Notification File,
they MUST detect the next_signing_key field, and store the key in
their configuration.
* After allowing mirror clients time to have seen the new Update
Notification File with the next_signing_key field, the mirror
server operator configures the new key as currently active key,
and removes the old key. Any Update Notification File generated
after this point MUST be signed with this new key, and will not