-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdraft-ietf-netconf-keystore.xml
1335 lines (1268 loc) · 66 KB
/
draft-ietf-netconf-keystore.xml
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
<?xml version='1.0'?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc linkmailto="no" ?>
<?rfc editing="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes"?>
<?rfc rfcedstyle="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<!--<?rfc strict="no"?> -->
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"
category="std"
consensus="true"
submissionType="IETF"
ipr="trust200902"
docName="draft-ietf-netconf-keystore-latest" >
<front>
<title>A YANG Data Model for a Keystore and Keystore Operations</title>
<author initials="K." surname="Watsen" fullname="Kent Watsen">
<organization>Watsen Networks</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date/>
<area>Operations</area>
<workgroup>NETCONF Working Group</workgroup>
<abstract>
<t>This document presents a YANG module called "ietf-keystore"
that enables centralized configuration of both symmetric and
asymmetric keys. The secret value for both key types may be
encrypted or hidden. Asymmetric keys may be associated with
certificates. Notifications are sent when certificates are
about to expire.</t>
</abstract>
<note title="Editorial Note (To be removed by RFC Editor)">
<t>This draft contains placeholder values that need to be replaced
with finalized values at the time of publication. This note summarizes
all of the substitutions that are needed. No other RFC Editor
instructions are specified elsewhere in this document.</t>
<t>Artwork in this document contains shorthand references to drafts in
progress. Please apply the following replacements:
<list style="symbols">
<t><spanx style="verb">AAAA</spanx> --> the assigned RFC value for draft-ietf-netconf-crypto-types</t>
<t><spanx style="verb">CCCC</spanx> --> the assigned RFC value for this draft</t>
</list>
</t>
<t>Artwork in this document contains placeholder values for the date of publication of this
draft. Please apply the following replacement:
<list style="symbols">
<t><spanx style="verb">YYYY-MM-DD</spanx> --> the publication date of this draft</t>
</list>
</t>
<t>The "Relation to other RFCs" section <xref target="collective-effort"/> contains
the text "one or more YANG modules" and, later, "modules". This text is sourced
from a file in a context where it is unknown how many modules a draft defines.
The text is not wrong as is, but it may be improved by stating more directly how
many modules are defined.</t>
<t>The "Relation to other RFCs" section <xref target="collective-effort"/> contains
a self-reference to this draft, along with a corresponding reference in
the Appendix. Please replace the self-reference in this section with "This RFC"
(or similar) and remove the self-reference in the "Normative/Informative References"
section, whichever it is in.</t>
<t>Tree-diagrams in this draft may use the '\' line-folding mode defined in RFC 8792.
However, nicer-to-the-eye is when the '\\' line-folding mode is used. The AD suggested
suggested putting a request here for the RFC Editor to help convert "ugly" '\' folded
examples to use the '\\' folding mode. "Help convert" may be interpreted as, identify
what looks ugly and ask the authors to make the adjustment.</t>
<t>The following Appendix section is to be removed prior to publication:
<list style="symbols">
<t><xref target="change-log"/>. Change Log</t>
</list>
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>This document presents a YANG 1.1 <xref target="RFC7950"/> module called
"ietf-keystore" that enables centralized configuration of both symmetric
and asymmetric keys. The secret value for both key types may be
encrypted or hidden (see <xref target="I-D.ietf-netconf-crypto-types"/>).
Asymmetric keys may be associated with certificates. Notifications are
sent when certificates are about to expire.</t>
<t>The "ietf-keystore" module defines many "grouping" statements
intended for use by other modules that may import it. For instance,
there are groupings that define enabling a key to be either configured
inline (within the defining data model) or as a reference to a key
in the central keystore.
</t>
<t>Special consideration has been given for servers that have cryptographic
hardware, such as a Trusted Platform Module (TPM). These servers are
unique in that the cryptographic hardware hides the secret key values.
Additionally, such hardware is commonly initialized when manufactured
to protect a "built-in" asymmetric key for which its public half is
conveyed in an identity certificate (e.g., an IDevID
<xref target="Std-802.1AR-2018"/> certificate). Please see
<xref target="built-ins"/> to see how built-in keys are supported.</t>
<t>This document is intended to reflect existing practices that many
server implementations support at the time of writing. To simplify
implementation, advanced key formats may be selectively implemented.</t>
<t>Implementations may utilize operating-system level
keystore utilities (e.g., "Keychain Access" on MacOS) and/or cryptographic
hardware (e.g., TPMs).</t>
INSERT_TEXT_FROM_FILE(../common-intro-snippet.xml,150)
<section title="Terminology">
<t>The terms "client" and "server" are defined in <xref target="RFC6241"/> and are not redefined here.</t>
<t>The term "keystore" is defined in this document as a mechanism that intends to safeguard secrets.</t>
<t>The nomenclature "<running>" and "<operational>" are defined in <xref target="RFC8342"/>.</t>
<t>The sentence fragments "augmented" and "augmented in" are used herein as the past tense verbified
form of the "augment" statement defined in <relref section="7.17" target="RFC7950"/>.</t>
<t>The term "key" may be used to mean one of three things in this document: 1) the YANG-defined
"asymmetric-key" or "symmetric-key" node defined in this document, 2) the raw key data possessed by the
aforementioned key nodes, and 3) the "key" of a YANG "list" statement. This
document attempts to always qualify types '2' and '3' using, "raw key value" and
"YANG list key" where needed. In all other cases, an unqualified "key" refers to a YANG-defined
"asymmetric-key" or "symmetric-key" node.</t>
</section>
<section title="Adherence to the NMDA">
<t>This document is compliant with Network Management Datastore Architecture
(NMDA) <xref target="RFC8342"/>. For instance, keys and associated
certificates installed during manufacturing (e.g., for an IDevID
certificate) are expected to appear in <operational>
(see <xref target="built-ins"/>).</t>
</section>
<section title="Conventions">
<t>Various examples in this document use "BASE64VALUE=" as a
placeholder value for binary data that has been base64
encoded (per <xref section="9.8" target="RFC7950"/>). This
placeholder value is used because real base64 encoded structures
are often many lines long and hence distracting to the example
being presented.</t>
<t>This document uses the adjective "central" to the word "keystore"
to refer to the top-level instance of the "keystore-grouping", when
the "central-keystore-supported" feature is enabled. Please be
aware that consuming YANG modules MAY instantiate the "keystore-grouping"
in other locations. All such other instances are not the "central"
instance.</t>
</section>
</section>
<!--
<t>For the trusted-certificates list, Trust Anchor Format
<xref target="RFC5914"/> was evaluated and deemed inappropriate due
to this document's need to also support pinning. That is, pinning
a client-certificate to support NETCONF over TLS client authentication.</t>
-->
<section title="The "ietf-keystore" Module">
<t>This section defines a YANG 1.1 <xref target="RFC7950"/> module called
"ietf-keystore". A high-level overview of the module is provided in
<xref target="overview"/>. Examples illustrating the module's use
are provided in <xref target="examples"/>. The YANG module itself is
defined in <xref target="keystore-yang-module"/>.</t>
<section title="Data Model Overview" anchor="overview">
<t>This section provides an overview of the "ietf-keystore" module
in terms of its features, typedefs, groupings, and protocol-accessible
nodes.</t>
<section title="Features" anchor="features" toc="exclude">
<t>The following diagram lists all the "feature" statements
defined in the "ietf-keystore" module:</t>
<t>
<figure>
<artwork><![CDATA[
Features:
+-- central-keystore-supported
+-- inline-definitions-supported
+-- asymmetric-keys
+-- symmetric-keys
]]></artwork>
</figure>
</t>
<!--<aside>-->
<t>The diagram above uses syntax that is similar to but not
defined in <xref target="RFC8340"/>.</t>
<!--</aside>-->
</section>
<section title="Typedefs" anchor="typedefs" toc="exclude">
<t>The following diagram lists the "typedef" statements defined in
the "ietf-keystore" module:</t>
<t>
<figure>
<artwork><![CDATA[
Typedefs:
leafref
+-- central-symmetric-key-ref
+-- central-asymmetric-key-ref
]]></artwork>
</figure>
</t>
<!--<aside>-->
<t>The diagram above uses syntax that is similar to but not
defined in <xref target="RFC8340"/>.</t>
<!--</aside>-->
<t>Comments:</t>
<ul>
<li>All the typedefs defined in the "ietf-keystore" module
extend the base "leafref" type defined in <xref target="RFC7950"/>.</li>
<li>The leafrefs refer to symmetric and asymmetric keys in the
central keystore, when this module is implemented.</li>
<li>These typedefs are provided as an aid to consuming
modules that import the "ietf-keystore" module.</li>
</ul>
</section>
<section title="Groupings" toc="exclude">
<t>The "ietf-keystore" module defines the following "grouping" statements:</t>
<ul spacing="compact">
<li>encrypted-by-grouping</li>
<li>central-asymmetric-key-certificate-ref-grouping</li>
<li>inline-or-keystore-symmetric-key-grouping</li>
<li>inline-or-keystore-asymmetric-key-grouping</li>
<li>inline-or-keystore-asymmetric-key-with-certs-grouping</li>
<li>inline-or-keystore-end-entity-cert-with-key-grouping</li>
<li>keystore-grouping</li>
</ul>
<t>Each of these groupings are presented in the following subsections.</t>
<section title="The "encrypted-by-grouping" Grouping" anchor="encrypted-by-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"encrypted-by-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-encrypted-by-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>This grouping defines a "choice" statement with options to reference
either a symmetric or an asymmetric key configured in the keystore.</li>
<li>This grouping is usable only when the keystore module is implemented.
Servers defining custom keystore locations MUST augment in alternate
"encrypted-by" references to the alternate locations.</li>
</ul>
</section>
<section title="The "central-asymmetric-key-certificate-ref-grouping" Grouping" anchor="central-asymmetric-key-certificate-ref-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"central-asymmetric-key-certificate-ref-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-central-asymmetric-key-certificate-ref-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>This grouping defines a reference to a certificate in two parts: the
first being the name of the asymmetric key the certificate is associated
with, and the second being the name of the certificate itself.</li>
<li>This grouping is usable only when the keystore module is implemented.
Servers defining custom keystore locations can define an alternate grouping
for references to the alternate locations.</li>
</ul>
</section>
<section title="The "inline-or-keystore-symmetric-key-grouping" Grouping" anchor="inline-or-keystore-symmetric-key-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"inline-or-keystore-symmetric-key-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-inline-or-keystore-symmetric-key-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>The "inline-or-keystore-symmetric-key-grouping" grouping is provided
solely as convenience to consuming modules that wish to offer
an option for whether a symmetric key is defined inline
or as a reference to a symmetric key in the keystore.</li>
<li>A "choice" statement is used to expose the various options.
Each option is enabled by a "feature" statement. Additional
"case" statements MAY be augmented in if, e.g., there is a
need to reference a symmetric key in an alternate location.</li>
<li>For the "inline-definition" option, the definition uses the
"symmetric-key-grouping" grouping discussed in <relref section="2.1.4.3"
target="I-D.ietf-netconf-crypto-types"/>.</li>
<li>For the "central-keystore" option, the "central-keystore-reference" is an
instance of the "symmetric-key-ref" discussed in <xref target="typedefs"/>.</li>
</ul>
</section>
<section title="The "inline-or-keystore-asymmetric-key-grouping" Grouping" anchor="inline-or-keystore-asymmetric-key-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"inline-or-keystore-asymmetric-key-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-inline-or-keystore-asymmetric-key-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>The "inline-or-keystore-asymmetric-key-grouping" grouping is provided
solely as convenience to consuming modules that wish to offer
an option for whether an asymmetric key is defined inline
or as a reference to an asymmetric key in the keystore.</li>
<li>A "choice" statement is used to expose the various options.
Each option is enabled by a "feature" statement. Additional
"case" statements MAY be augmented in if, e.g., there is a
need to reference an asymmetric key in an alternate location.</li>
<li>For the "inline-definition" option, the definition uses the
"asymmetric-key-pair-grouping" grouping discussed in <relref section="2.1.4.6"
target="I-D.ietf-netconf-crypto-types"/>.</li>
<li>For the "central-keystore" option, the "central-keystore-reference" is an
instance of the "asymmetric-key-ref" typedef discussed in
<xref target="typedefs"/>.</li>
</ul>
</section>
<section title="The "inline-or-keystore-asymmetric-key-with-certs-grouping" Grouping" anchor="inline-or-keystore-asymmetric-key-with-certs-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"inline-or-keystore-asymmetric-key-with-certs-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-inline-or-keystore-asymmetric-key-with-certs-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>The "inline-or-keystore-asymmetric-key-with-certs-grouping" grouping is provided
solely as convenience to consuming modules that wish to offer
an option for whether an asymmetric key is defined inline
or as a reference to an asymmetric key in the keystore.</li>
<li>A "choice" statement is used to expose the various options.
Each option is enabled by a "feature" statement. Additional
"case" statements MAY be augmented in if, e.g., there is a
need to reference an asymmetric key in an alternate location.</li>
<li>For the "inline-definition" option, the definition uses the
"asymmetric-key-pair-with-certs-grouping" grouping discussed in <relref section="2.1.4.12"
target="I-D.ietf-netconf-crypto-types"/>.</li>
<li>For the "central-keystore" option, the "central-keystore-reference" is an
instance of the "asymmetric-key-ref" typedef discussed in
<xref target="typedefs"/>.</li>
</ul>
</section>
<section title="The "inline-or-keystore-end-entity-cert-with-key-grouping" Grouping" anchor="inline-or-keystore-end-entity-cert-with-key-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"inline-or-keystore-end-entity-cert-with-key-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-inline-or-keystore-end-entity-cert-with-key-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>The "inline-or-keystore-end-entity-cert-with-key-grouping" grouping is provided
solely as convenience to consuming modules that wish to offer
an option for whether a symmetric key is defined inline
or as a reference to a symmetric key in the keystore.</li>
<li>A "choice" statement is used to expose the various options.
Each option is enabled by a "feature" statement. Additional
"case" statements MAY be augmented in if, e.g., there is a
need to reference a symmetric key in an alternate location.</li>
<li>For the "inline-definition" option, the definition uses the
"asymmetric-key-pair-with-certs-grouping" grouping discussed in <relref section="2.1.4.12"
target="I-D.ietf-netconf-crypto-types"/>.</li>
<li>For the "central-keystore" option, the "central-keystore-reference" uses the
"central-asymmetric-key-certificate-ref-grouping" grouping discussed in
<xref target="central-asymmetric-key-certificate-ref-grouping"/>.</li>
</ul>
</section>
<section title="The "keystore-grouping" Grouping" anchor="keystore-grouping">
<t>The following tree diagram <xref target="RFC8340"/> illustrates the
"keystore-grouping" grouping:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/tree-keystore-grouping.no-expand.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>The "keystore-grouping" grouping defines a keystore instance
as being composed of symmetric and asymmetric keys. The structure
for the symmetric and asymmetric keys is essentially the same,
being a "list" inside a "container".</li>
<li>For asymmetric keys, each "asymmetric-key" uses the
"asymmetric-key-pair-with-certs-grouping" grouping discussed in
<relref section="2.1.4.12" target="I-D.ietf-netconf-crypto-types"/>.</li>
<li>For symmetric keys, each "symmetric-key" uses the
"symmetric-key-grouping" grouping discussed in
<relref section="2.1.4.3" target="I-D.ietf-netconf-crypto-types"/>.</li>
</ul>
</section>
</section>
<section title="Protocol-accessible Nodes" anchor="proto-access-nodes" toc="exclude">
<t>The following tree diagram <xref target="RFC8340"/> lists all the
protocol-accessible nodes defined in the "ietf-keystore" module, without
expanding the "grouping" statements:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ietf-keystore-tree-no-expand.txt)
]]></artwork>
</figure>
</t>
<t>The following tree diagram <xref target="RFC8340"/> lists all the
protocol-accessible nodes defined in the "ietf-keystore" module, with
all "grouping" statements expanded, enabling the keystore's full
structure to be seen:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ietf-keystore-tree.txt)
]]></artwork>
</figure>
</t>
<t>Comments:</t>
<ul>
<li>Protocol-accessible nodes are those nodes that are accessible
when the module is "implemented", as described in <relref
section="5.6.5" target="RFC7950"/>.</li>
<li>The protocol-accessible nodes for the "ietf-keystore" module
are instances of the "keystore-grouping" grouping discussed in
<xref target="keystore-grouping"/>.
</li>
<li>The top-level node "keystore" is additionally constrained
by the feature "central-keystore-supported".</li>
<li>The "keystore-grouping" grouping is discussed in
<xref target="keystore-grouping"/>.</li>
<li>The reason for why "keystore-grouping" exists separate from
the protocol-accessible nodes definition is so as to enable
instances of the keystore to be instantiated in other
locations, as may be needed or desired by some modules.</li>
</ul>
</section>
</section>
<section title="Example Usage" anchor="examples">
<t>The examples in this section are encoded using XML, such as might
be the case when using the NETCONF protocol. Other encodings MAY
be used, such as JSON when using the RESTCONF protocol.</t>
<section title="A Keystore Instance" anchor="ks-inst" toc="exclude">
<t>The following example illustrates keys in <running>.
Please see <xref target="built-ins"/> for an example illustrating
built-in values in <operational>.</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore.xml)
]]></artwork>
</figure>
</t>
</section>
<section title="A Certificate Expiration Notification" toc="exclude">
<t>The following example illustrates a "certificate-expiration"
notification for a certificate associated with an asymmetric
key configured in the keystore.</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-notification-ce.xml)
]]></artwork>
</figure>
</t>
</section>
<section title="The "Local or Keystore" Groupings" toc="exclude">
<t>This section illustrates the various "inline-or-keystore" groupings
defined in the "ietf-keystore" module, specifically the
"inline-or-keystore-symmetric-key-grouping"
(<xref target="inline-or-keystore-symmetric-key-grouping"/>),
"inline-or-keystore-asymmetric-key-grouping"
(<xref target="inline-or-keystore-asymmetric-key-grouping"/>),
"inline-or-keystore-asymmetric-key-with-certs-grouping"
(<xref target="inline-or-keystore-asymmetric-key-with-certs-grouping"/>), and
"inline-or-keystore-end-entity-cert-with-key-grouping"
(<xref target="inline-or-keystore-end-entity-cert-with-key-grouping"/>) groupings.</t>
<t>These examples assume the existence of an example module called "ex-keystore-usage"
having the namespace "https://example.com/ns/example-keystore-usage".</t>
<t>The ex-keystore-usage module is first presented using tree diagrams
<xref target="RFC8340"/>, followed by an instance example illustrating
all the "inline-or-keystore" groupings in use, followed by the YANG
module itself.</t>
<section title='Tree Diagrams for the "ex-keystore-usage" Module' toc="exclude">
<t>The following tree diagram illustrates "ex-keystore-usage" without
expanding the "grouping" statements:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-usage-tree-no-expand.txt)
]]></artwork>
</figure>
</t>
<t>The following tree diagram illustrates the "ex-keystore-usage"
module, with all "grouping" statements expanded, enabling the
usage's full structure to be seen:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-usage-tree.txt)
]]></artwork>
</figure>
</t>
</section>
<section title='Example Usage for the "ex-keystore-usage" Module' toc="exclude">
<t>The following example provides two equivalent instances of
each grouping, the first being a reference to a keystore
and the second being inlined. The instance having
a reference to a keystore is consistent with the keystore
defined in <xref target="ks-inst"/>. The two instances are
equivalent, as the inlined instance example contains
the same values defined by the keystore instance referenced
by its sibling example.</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-usage.xml)
]]></artwork>
</figure>
</t>
</section>
<section title='The "ex-keystore-usage" YANG Module' toc="exclude">
<t>Following is the "ex-keystore-usage" module's YANG definition:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE([email protected])
]]></artwork>
</figure>
</t>
</section>
</section>
</section>
<section title="YANG Module" anchor="keystore-yang-module">
<t>This YANG module has normative references to <xref target="RFC8341"/>
and <xref target="I-D.ietf-netconf-crypto-types"/>.</t>
<t>
<figure>
<preamble><CODE BEGINS> file "[email protected]"</preamble>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE([email protected])
]]></artwork>
<postamble><CODE ENDS></postamble>
</figure>
</t>
</section>
</section>
<section title="Support for Built-in Keys" anchor="built-ins">
<t>In some implementations, a server may support keys built into the server.
Built-in keys MAY be set during the manufacturing process or be dynamically
generated the first time the server is booted or a particular service
(e.g., SSH) is enabled.</t>
<t>Built-in keys are "hidden" keys expected to be set by a vendor-specific process.
Any ability for operators to set and/or modify built-in keys is outside the
scope of this document.</t>
<t>The primary characteristic of the built-in keys is that they are provided
by the server, as opposed to configuration. As such, they are present in
<operational> (<xref section="5.3" target="RFC8342"/>), and <system>
<xref target="I-D.ietf-netmod-system-config"/>, if implemented.</t>
<t>The example below illustrates what the keystore in <operational>
might look like for a server in its factory default state. Note that the
built-in keys have the "or:origin" annotation value "or:system".</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-default-operational.xml)
]]></artwork>
</figure>
</t>
<t>The following example illustrates how a single built-in key definition
from the previous example has been propagated to <running>:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-default-running.xml)
]]></artwork>
</figure>
</t>
<t>After the above configuration is applied, <operational> should appear
as follows:</t>
<t>
<figure>
<artwork><![CDATA[
INSERT_TEXT_FROM_FILE(refs/ex-keystore-default-operational-applied.xml)
]]></artwork>
</figure>
</t>
</section>
<section title="Encrypting Keys in Configuration">
<t>This section describes an approach that enables both the symmetric
and asymmetric keys on a server to be encrypted, such that traditional
backup/restore procedures can be used without concern for raw key
data being compromised when in transit.</t>
<t>The approach presented in this section is not normative. This section
answers how a configuration containing secrets that are encrypted by a
built-in key (<xref target="built-ins"/>) can be backup'ed from one server
and restored on a different server, when each server has unique master keys.
The API defined by the "ietf-keystore" YANG module presented in this
document is sufficient to support the workflow described in this section.</t>
<section title="Key Encryption Key" toc="exclude">
<t>The ability to encrypt configured keys is predicated on the
existence of a "key encryption key" (KEK). There may be any
number of KEKs in a server. A KEK, by its namesake, is a key
that is used to encrypt other keys. A KEK MAY be either a
symmetric key or an asymmetric key.</t>
<t>If a KEK is a symmetric key, then the server MUST provide an API for
administrators to encrypt other keys without needing to know
the symmetric key's value. If the KEK is an asymmetric key, then
the server SHOULD provide an API enabling the encryption of other
keys or, alternatively, assume the administrators can do so themselves
using the asymmetric key's public half.</t>
<t>A server MUST possess access to the KEK, or an API using the KEK,
so that it can decrypt the other keys in the configuration at runtime.</t>
</section>
<section title="Configuring Encrypted Keys" toc="exclude">
<t>Each time a new key is configured, it SHOULD be encrypted by
a KEK.</t>
<t>In "ietf-crypto-types" <xref target="I-D.ietf-netconf-crypto-types"/>,
the format for encrypted values is described by identity statements
derived from the "symmetrically-encrypted-value-format" and
"asymmetrically-encrypted-value-format" identity statements.</t>
<t>Implementations of servers implementing the "ietf-keystore" module
SHOULD provide an API that simultaneously generates a key and encrypts
the generated key using a KEK. Thus the cleartext value of the newly
generated key may never be known to the administrators generating the keys.
Such API is defined in the "ietf-ssh-common" and the "ietf-tls-common"
YANG modules defined in <xref target="I-D.ietf-netconf-ssh-client-server"/>,
and <xref target="I-D.ietf-netconf-tls-client-server"/>, respectively.</t>
<t>In case the server implementation does not provide such an API, then
the generating and encrypting steps MAY be performed outside the
server, e.g., by an administrator with special access control rights
(e.g., an organization's crypto officer).</t>
<t>In either case, the encrypted key can be configured into the keystore
using either the "encrypted-symmetric-key" (for symmetric keys) or the
"encrypted-private-key" (for asymmetric keys) nodes. These two nodes
contain both the encrypted raw key value as well as a reference to
the KEK that encrypted the key.</t>
</section>
<section title="Migrating Configuration to Another Server" toc="exclude">
<t>When a KEK is used to encrypt other keys, migrating the configuration
to another server is only possible if the second server has the same KEK.
How the second server comes to have the same KEK is discussed in this
section.</t>
<t>In some deployments, mechanisms outside the scope of this document
may be used to migrate a KEK from one server to another. That said,
beware that the ability to do so typically entails having access to
the first server but, in some scenarios, the first server may no
longer be operational.</t>
<t>In other deployments, an organization's crypto officer, possessing a
KEK's cleartext value, configures the same KEK on the second server,
presumably as a hidden key or a key protected by access-control, so
that the cleartext value is not
disclosed to regular administrators. However, this approach creates
high-coupling to and dependency on the crypto officers that does not
scale in production environments.</t>
<t>In order to decouple the crypto officers from the regular administrators,
a special KEK, called the "master key" (MK), may be used.</t>
<t>A MK is commonly a globally-unique built-in (see <xref target="built-ins"/>)
asymmetric key. The private raw key value, due to its long lifetime, is hidden
(i.e., "hidden-private-key" in <relref section="2.1.4.5."
target="I-D.ietf-netconf-crypto-types"/>). The raw public key value is often
contained in an identity certificate (e.g., IDevID). How to
configure a MK during the manufacturing process is outside the
scope of this document.</t>
<t>Assuming the server has a MK, the MK can be used to encrypt a
"shared KEK", which is then used to encrypt the keys configured
by regular administrators.</t>
<t>With this extra level of indirection, it is possible for a
crypto officer to encrypt the same KEK for a multiplicity of
servers offline using the public key contained in their identity
certificates. The crypto officer can then safely handoff
the encrypted KEKs to regular administrators responsible for
server installations, including migrations.</t>
<t>In order to migrate the configuration from a first server, an
administrator would need to make just a single modification to
the configuration before loading it onto a second server, which
is to replace the encrypted KEK keystore entry from the first
server with the encrypted KEK for the second server. Upon doing
this, the configuration (containing many encrypted keys) can be
loaded into the second server while enabling the second server
to decrypt all the encrypted keys in the configuration.</t>
<t>The following diagram illustrates this idea:</t>
<t>
<figure>
<artwork><![CDATA[
+-------------+ +-------------+
| shared KEK | | shared KEK |
|(unencrypted)|-------------------------------> | (encrypted) |
+-------------+ encrypts offline using +-------------+
^ each server's MK |
| |
| |
| possesses \o |
+-------------- |\ |
/ \ shares with |
crypto +--------------------+
officer |
|
|
+----------------------+ | +----------------------+
| server-1 | | | server-2 |
| configuration | | | configuration |
| | | | |
| | | | |
| +----------------+ | | | +----------------+ |
| | MK-1 | | | | | MK-2 | |
| | (hidden) | | | | | (hidden) | |
| +----------------+ | | | +----------------+ |
| ^ | | | ^ |
| | | | | | |
| | | | | | |
| | encrypted | | | | encrypted |
| | by | | | | by |
| | | | | | |
| | | | | | |
| +----------------+ | | | +----------------+ |
| | shared KEK | | | | | shared KEK | |
| | (encrypted) | | v | | (encrypted) | |
| +----------------+ | | +----------------+ |
| ^ | regular | ^ |
| | | admin | | |
| | | | | |
| | encrypted | \o | | encrypted |
| | by | |\ | | by |
| | | / \ | | |
| | | | | |
| +----------------+ |----------------->| +----------------+ |
| | all other keys | | migrate | | all other keys | |
| | (encrypted) | | configuration | | (encrypted) | |
| +----------------+ | | +----------------+ |
| | | |
+----------------------+ +----------------------+
]]></artwork>
</figure>
</t>
</section>
</section>
<section title="Security Considerations">
<section title="Security of Data at Rest and in Motion">
<t>The YANG module defined in this document defines a mechanism called a
"keystore" that intends to protect its contents from unauthorized
disclosure and modification.</t>
<t>In order to satisfy the expectations of a "keystore", it
is RECOMMENDED that server implementations ensure that the keystore
contents are encrypted when persisted to non-volatile memory,
and ensure that the keystore contents that have been decrypted
in volatile memory are zeroized when not in use.</t>
<t>The keystore contents may be encrypted either by encrypting
the contents individually (e.g., using the "encrypted" value
formats) or, in case cleartext values are used (which is NOT
RECOMMENDED per <xref section="3.5" target="I-D.ietf-netconf-crypto-types"/>),
then, e.g., disk-level encryption may be used.</t>
<t>If the keystore contents are not encrypted when persisted,
then server implementations MUST ensure the persisted storage
is inaccessible.</t>
</section>
<section title="Unconstrained Private Key Usage">
<t>This module enables the configuration of private keys without
constraints on their usage, e.g., what operations the key is
allowed to be used for (e.g., signature, decryption, both).</t>
<t>This module also does not constrain the usage of the associated
public keys, other than in the context of a configured certificate
(e.g., an identity certificate), in which case the key usage is
constrained by the certificate.</t>
</section>
<section title="Considerations for the "ietf-keystore" YANG Module" anchor="sec-mod">
<t>This section follows the template defined in <xref section="3.7.1" target="RFC8407"/>.</t>
<t>The YANG module defined in this document is designed to be accessed via YANG
based management protocols, such as NETCONF <xref target="RFC6241"/> and
RESTCONF <xref target="RFC8040"/>. Both of these protocols have mandatory-to-implement
secure transport layers (e.g., SSH, TLS) with mutual authentication.</t>
<t>The Network Access Control Model (NACM) <xref target="RFC8341"/> provides the means
to restrict access for particular users to a pre-configured subset of all available
protocol operations and content.</t>
<t>Please be aware that this YANG module uses groupings from
other YANG modules that define nodes that may be considered
sensitive or vulnerable in network environments. Please
review the Security Considerations for dependent YANG modules
for information as to which nodes may be considered sensitive
or vulnerable in network environments.</t>
<t>Some of the readable data nodes defined in this YANG module
may be considered sensitive or vulnerable in some network
environments. It is thus important to control read access
(e.g., via get, get-config, or notification) to these
data nodes. The following subtrees and data nodes have particular
sensitivity/vulnerability:
<list style="symbols">
<t>The "cleartext-symmetric-key" node:
<ul empty="true">
<li>The "cleartext-symmetric-key" node, imported from the "symmetric-key-grouping"
grouping defined in <xref target="I-D.ietf-netconf-crypto-types"/> is
additionally sensitive to read operations such that,
in normal use cases, it should never be returned to a client.
For this reason, the NACM extension "default-deny-all" was
applied to it in <xref target="I-D.ietf-netconf-crypto-types"/>.</li>
</ul>
</t>
<t>The "cleartext-private-key" node:
<ul empty="true">
<li>The "cleartext-private-key" node defined in the "asymmetric-key-pair-grouping"
grouping defined in <xref target="I-D.ietf-netconf-crypto-types"/> is
additionally sensitive to read operations such that, in
normal use cases, it should never be returned to a client. For this
reason, the NACM extension "default-deny-all" is applied
to it in <xref target="I-D.ietf-netconf-crypto-types"/>.</li>
</ul>
</t>
</list>
</t>
<t>All the writable data nodes defined by this module, both in the
"grouping" statements as well as the protocol-accessible "keystore"
instance, may be considered sensitive or vulnerable in some network
environments. For instance, any modification to a key or reference
to a key may dramatically alter the implemented security policy.
For this reason, the NACM extension "default-deny-write" has been
set for all data nodes defined in this module.</t>
<t>This module does not define any "rpc" or "action" statements, and
thus the security considerations for such is not provided here.</t>
<t>Built-in key types SHOULD be either hidden and/or encrypted (not
cleartext). If this is not possible, access control mechanisms
like NACM SHOULD be used to limit access to the key's secret data
to only the most trusted authorized clients (e.g., belonging to
an organization’s crypto officer).</t>
</section>
</section>
<section title="IANA Considerations">
<section title='The "IETF XML" Registry'>
<t>This document registers one URI in the "ns" subregistry of the
IETF XML Registry <xref target="RFC3688"/>. Following the format
in <xref target="RFC3688"/>, the following registration is
requested:</t>
<t>
<figure>
<artwork>
URI: urn:ietf:params:xml:ns:yang:ietf-keystore
Registrant Contact: The IESG
XML: N/A, the requested URI is an XML namespace.
</artwork>
</figure>
</t>
</section>
<section title='The "YANG Module Names" Registry'>
<t>This document registers one YANG module in the
YANG Module Names registry <xref target="RFC6020"/>.
Following the format in <xref target="RFC6020"/>, the
following registration is requested:</t>
<t>
<figure>
<artwork><![CDATA[
name: ietf-keystore
namespace: urn:ietf:params:xml:ns:yang:ietf-keystore
prefix: ks
reference: RFC CCCC
]]></artwork>
</figure>
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119.xml"?>
<?rfc include="reference.RFC.6020.xml"?>
<?rfc include="reference.RFC.7950.xml"?>
<?rfc include="reference.RFC.8341.xml"?>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-crypto-types.xml"/>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.3688.xml"?>
<?rfc include="reference.RFC.6241.xml"?>
<?rfc include="reference.RFC.8040.xml"?>
<?rfc include="reference.RFC.8174.xml"?>
<?rfc include="reference.RFC.8340.xml"?>
<?rfc include="reference.RFC.8342.xml"?>
<?rfc include="reference.RFC.8407.xml"?>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-trust-anchors.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-keystore.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-tcp-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-ssh-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-tls-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-http-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-netconf-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netconf-restconf-client-server.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-netmod-system-config.xml"/>
<reference anchor="Std-802.1AR-2018" target="https://standards.ieee.org/standard/802_1AR-2018.html">
<front>
<title>IEEE Standard for Local and metropolitan area networks - Secure Device Identity</title>
<author>
<organization>IEEE SA-Standards Board</organization>
</author>
<date month="August" year="2018"/>
</front>
</reference>
</references>
<section title="Change Log" anchor="change-log">
<section title="00 to 01">
<t>
<list style="symbols">
<t>Replaced the 'certificate-chain' structures with PKCS#7 structures.
(Issue #1)</t>
<t>Added 'private-key' as a configurable data node, and removed the
'generate-private-key' and 'load-private-key' actions. (Issue #2)</t>
<t>Moved 'user-auth-credentials' to the ietf-ssh-client module.
(Issues #4 and #5)</t>
</list>
</t>
</section>
<section title="01 to 02">
<t>
<list style="symbols">
<t>Added back 'generate-private-key' action.</t>
<t>Removed 'RESTRICTED' enum from the 'private-key' leaf type.</t>
<t>Fixed up a few description statements.</t>
</list>
</t>
</section>
<section title="02 to 03">
<t>
<list style="symbols">
<t>Changed draft's title.</t>
<t>Added missing references.</t>
<t>Collapsed sections and levels.</t>
<t>Added RFC 8174 to Requirements Language Section.</t>
<t>Renamed 'trusted-certificates' to 'pinned-certificates'.</t>
<t>Changed 'public-key' from config false to config true.</t>
<t>Switched 'host-key' from OneAsymmetricKey to definition from RFC 4253.</t>
</list>
</t>
</section>
<section title="03 to 04">
<t>
<list style="symbols">
<t>Added typedefs around leafrefs to common keystore paths</t>
<t>Now tree diagrams reference ietf-netmod-yang-tree-diagrams</t>
<t>Removed Design Considerations section</t>
<t>Moved key and certificate definitions from data tree to groupings</t>
</list>
</t>
</section>
<section title="04 to 05">