A YANG Data Model for a KeystoreWatsen Networkskent+ietf@watsen.net
Operations
NETCONF Working GroupThis document defines a YANG 1.1 module called "ietf-keystore"
that enables centralized configuration of both symmetric and
asymmetric keys. The secret value for both key types may be
encrypted. Asymmetric keys may be associated with certificates.
Notifications are sent when certificates are about to expire.This draft contains many 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.Artwork in this document contains shorthand references to drafts in
progress. Please apply the following replacements:
VVVV --> the assigned RFC value for this draftArtwork in this document contains placeholder values for the date of publication of this
draft. Please apply the following replacement:
2019-07-02 --> the publication date of this draftThe following Appendix section is to be removed prior to publication:
Appendix A. Change LogThis document defines a YANG 1.1 module called "ietf-keystore"
that enables centralized configuration of both symmetric and
asymmetric keys. The secret value for both key types may be
encrypted. Asymmetric keys may be associated with certificates.
Notifications are sent when certificates are about to expire.The "ietf-keystore" module defines many "grouping" statements
intended for use by other modules that may import it. For instance,
there are groupings that defined enabling a key to be either configured
locally (within the defining data model) or be a reference to a key
in the keystore.
Special consideration has been given for systems that have cryptographic
hardware, such as a Trusted Protection Module (TPM). These systems are
unique in that the cryptographic hardware hides the secret key values.
To support such hardware, symmetric keys may have the value "hidden-key"
and asymmetric keys may have the value "hidden-private-key". While how
such keys are created or destroyed is outside the scope of this document,
the keystore can contain entries for such keys, enabling them to be
reference by other configuration elements.This document in compliant with Network Management Datastore Architecture
(NMDA) . For instance, keys and associated
certificates installed during manufacturing (e.g., for a IDevID
certificate), it is expected that such
data may appear only in <operational>.It is not required that a system has an operating system level
keystore utility to implement this module.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
when, and only when, they appear in all capitals, as shown here.This section provides a tree diagrams for
the "ietf-keystore" module that presents both the protocol-accessible
"keystore" as well the all the groupings intended for external usage.The following example illustrates what a fully configured keystore
might look like in <operational>, as described by Section 5.3 in
. This datastore view illustrates data set by
the manufacturing process alongside conventional configuration. This
keystore instance has four keys, two having one associated certificate,
one having two associated certificates, and one empty key.The following example illustrates the "generate-symmetric-key" RPC.
The key being referenced is defined in the keystore example above.Following is the complimentary RPC-reply.The following non-normative module is used by subsequent examples
to illustrate groupings defined in the ietf-crypto-types module.The following example illustrates what two configured keys,
one local and the other remote, might look like. This example
consistent with other examples above (i.e., the referenced key
is in an example above).This YANG module has normative references to
and ,
and an informative reference to .The YANG module defined in this document is designed to be accessed via YANG
based management protocols, such as NETCONF and
RESTCONF . Both of these protocols have mandatory-to-implement
secure transport layers (e.g., SSH, TLS) with mutual authentication.The NETCONF access control model (NACM) provides the means
to restrict access for particular users to a pre-configured subset of all available
protocol operations and content.There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., config true, which is the default). These data
nodes may be considered sensitive or vulnerable in some network environments. Write
operations (e.g., edit-config) to these data nodes without proper protection can
have a negative effect on network operations. These are the subtrees and data nodes
and their sensitivity/vulnerability:
The entire data tree defined by this module is sensitive to
write operations. For instance, the addition or removal of keys, certificates,
etc., can dramatically alter the implemented security policy.
For this reason, the NACM extension "default-deny-write" has been set for the
entire data tree.When writing this node,
implementations MUST ensure that the strength of the key being configured
is not greater than the strength of the underlying secure transport
connection over which it is communicated. Implementations SHOULD fail the
write-request if ever the strength of the private key is greater then
the strength of the underlying transport, and alert the client that the
strength of the key may have been compromised. Additionally, when deleting
this node, implementations SHOULD automatically (without explicit request)
zeroize these keys in the most secure manner available, so as to prevent
the remnants of their persisted storage locations from being analyzed in
any meaningful way.Some of the readable data nodes 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. These are
the subtrees and data nodes and their sensitivity/vulnerability:
This node
is additionally sensitive to read operations such that, in normal use cases,
it should never be returned to a client. The best reason for returning this
node is to support backup/restore type workflows. For this reason, the
NACM extension "default-deny-all" has been set for this data node.This document registers one URI in the "ns" subregistry of the
IETF XML Registry . Following the format
in , the following registration is
requested:This document registers one YANG module in the
YANG Module Names registry .
Following the format in , the
the following registration is requested:IEEE Standard for Local and metropolitan area networks - Secure Device IdentityIEEE SA-Standards BoardReplaced the 'certificate-chain' structures with PKCS#7 structures.
(Issue #1)Added 'private-key' as a configurable data node, and removed the
'generate-private-key' and 'load-private-key' actions. (Issue #2)Moved 'user-auth-credentials' to the ietf-ssh-client module.
(Issues #4 and #5)Added back 'generate-private-key' action.Removed 'RESTRICTED' enum from the 'private-key' leaf type.Fixed up a few description statements.Changed draft's title.Added missing references.Collapsed sections and levels.Added RFC 8174 to Requirements Language Section.Renamed 'trusted-certificates' to 'pinned-certificates'.Changed 'public-key' from config false to config true.Switched 'host-key' from OneAsymmetricKey to definition from RFC 4253.Added typedefs around leafrefs to common keystore pathsNow tree diagrams reference ietf-netmod-yang-tree-diagramsRemoved Design Considerations sectionMoved key and certificate definitions from data tree to groupingsRemoved trust anchors (now in their own draft)Added back global keystore structureAdded groupings enabling keys to either be locally defined or a reference to the keystore.Added feature "local-keys-supported"Added nacm:default-deny-all and nacm:default-deny-writeRenamed generate-asymmetric-key to generate-hidden-keyAdded an install-hidden-key actionMoved actions inside fo the "asymmetric-key" containerMoved some groupings to draft-ietf-netconf-crypto-typesRemoved a "require-instance false"Clarified some description statementsImproved the keystore-usage examplesAdded "local-definition" containers to avoid posibility of the
action/notification statements being under a "case" statement.Updated copyright date, boilerplate template, affiliation,
folding algorithm, and reformatted the YANG module.Added a 'description' statement to the 'must' in the
/keystore/asymmetric-key node explaining that the descendent
values may exist in <operational> only, and that
implementation MUST assert that the values are either
configured or that they exist in <operational>.Copied above 'must' statement (and description) into
the local-or-keystore-asymmetric-key-grouping,
local-or-keystore-asymmetric-key-with-certs-grouping,
and local-or-keystore-end-entity-cert-with-key-grouping
statements.Updated draft title to match new truststore draft titleMoved everything under a top-level 'grouping' to enable use in other contexts.Renamed feature from 'local-keys-supported' to 'local-definitions-supported' (same name used in truststore)Removed the either-all-or-none 'must' expressions for the key's 3-tuple values (since the values are now 'mandatory true' in crypto-types)Example updated to reflect 'mandatory true' change in crypto-types draftReplaced typedef asymmetric-key-certificate-ref with grouping asymmetric-key-certificate-ref-grouping.Added feature feature 'key-generation'.Cloned groupings symmetric-key-grouping, asymmetric-key-pair-grouping,
asymmetric-key-pair-with-cert-grouping, and asymmetric-key-pair-with-certs-grouping
from crypto-keys, augmenting into each new case statements for values that
have been encrypted by other keys in the keystore. Refactored keystore model
to use these groupings.Added new 'symmetric-keys' lists, as a sibling to the existing 'asymmetric-keys' list.Added RPCs (not actions) 'generate-symmetric-key' and 'generate-asymmetric-key' to
*return* a (potentially encrypted) key.Updated to reflect crypto-type's draft using enumerations over identities.Added examples for the 'generate-symmetric-key' and 'generate-asymmetric-key' RPCs.Updated the Introduction section.The authors would like to thank for following for
lively discussions on list and in the halls (ordered
by first name):
Alan Luchuk,
Andy Bierman,
Benoit Claise,
Bert Wijnen,
Balázs Kovács,
David Lamparter,
Eric Voit,
Ladislav Lhotka,
Liang Xia,
Juergen Schoenwaelder,
Mahesh Jethanandani,
Martin Bjorklund,
Mehmet Ersue,
Phil Shafer,
Radek Krejci,
Ramkumar Dhanapal,
Reshad Rahman,
Sean Turner,
and Tom Petch.