A YANG Data Model for a Keystore
Extracted elements (27)
Built-in keys (e.g., manufacturer-installed IDevID keys) are represented as 'hidden' keys in the YANG model and are expected to appear in the <operational> datastore with 'or:origin' set to 'or:system', reflecting that they are provided by the server rather than configured by an operator.
The KEK + primary key (PK) indirection model (Section 4.3) is designed to decouple crypto officers from regular administrators during server migrations. A globally unique built-in asymmetric PK encrypts a shared KEK offline per server; regular administrators then only need to swap the server-specific encrypted KEK entry when migrating a configuration, without ever seeing cleartext key material.
The 'keystore-grouping' grouping is defined separately from the protocol-accessible 'keystore' container specifically to enable the keystore structure to be instantiated in other locations beyond the single top-level central keystore, accommodating modules that may need to place a keystore instance elsewhere in their data model.
The 'ietf-keystore' module is compliant with the Network Management Datastore Architecture (NMDA, RFC 8342). Keys and certificates installed during manufacturing are expected to appear in <operational>, and the module uses 'or:origin' annotations accordingly.
The 'ietf-keystore' module is part of a layered suite of YANG modules for NETCONF/RESTCONF client-server configuration. It depends on 'ietf-crypto-types' (RFC 9640) and is itself a dependency of 'tls-client-server' (RFC 9645), 'ssh-client-server' (RFC 9644), and the NETCONF/RESTCONF client-server modules.
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.
Each time a new key is configured, it SHOULD be encrypted by a KEK. Server implementations SHOULD provide an API that simultaneously generates and encrypts a key using a KEK so the cleartext value is never exposed to administrators.
If a key encryption key (KEK) is a symmetric key, the server MUST provide an API for administrators to encrypt other keys without needing to know the symmetric key's cleartext value.
If the keystore contents are not encrypted when persisted to non-volatile memory, server implementations MUST ensure the persisted storage is inaccessible to unauthorized parties.
It is RECOMMENDED that server implementations encrypt keystore contents when persisted to non-volatile memory and zeroize decrypted keystore contents in volatile memory when not in use. If storing cleartext values, persistence-layer-level encryption SHOULD be used.
Servers that define custom keystore locations MUST augment alternate 'encrypted-by' references to those alternate locations into the 'encrypted-by-grouping' choice, since the standard grouping only references the central keystore.
When the 'keystore-grouping' is instantiated in locations other than the central keystore, implementations MUST augment new 'case' statements into the various inline-or-keystore 'choice' statements to supply leafrefs to the model-specific location(s).
A 'certificate-expiration' notification is defined under each certificate node (guarded by the 'certificate-expiration-notification' feature) and carries a single 'expiration-date' leaf of type 'yang:date-and-time' to alert operators before a certificate expires.
Each asymmetric key in the keystore carries 'public-key-format' (identityref), 'public-key' (binary), 'private-key-format' (identityref), and a 'private-key-type' choice with three cases: 'cleartext-private-key' (binary), 'hidden-private-key' (empty), or 'encrypted-private-key' (containing 'encrypted-by', 'encrypted-value-format', and 'encrypted-value'). An asymmetric key may also contain a 'certificates' list and a 'generate-csr' action.
Each symmetric key in the keystore carries an optional 'key-format' (identityref) and a 'key-type' choice with three cases: 'cleartext-symmetric-key' (binary), 'hidden-symmetric-key' (empty), or 'encrypted-symmetric-key' (containing 'encrypted-by', 'encrypted-value-format', and 'encrypted-value').
Four 'inline-or-keystore' groupings provide a YANG choice between defining a key inline (guarded by 'inline-definitions-supported') and referencing a key in the central keystore (guarded by 'central-keystore-supported'). The four variants cover: symmetric keys, asymmetric keys without certs, asymmetric keys with certs, and end-entity cert with key.
The 'central-asymmetric-key-certificate-ref-grouping' provides a two-part reference to a certificate: 'asymmetric-key' (leafref to the key name) and 'certificate' (leafref to the certificate name within that key). Each leaf has a 'must' constraint requiring the other leaf to also be present.
The 'encrypted-by-grouping' defines a mandatory choice between referencing a central symmetric key ('symmetric-key-ref') or a central asymmetric key ('asymmetric-key-ref') as the encrypting key. Both cases are guarded by 'central-keystore-supported' and the respective key-type feature.
The 'generate-csr' action (guarded by 'csr-generation' feature) on an asymmetric key accepts 'csr-format' (identityref) and 'csr-info' as input, and returns a 'p10-csr' (PKCS#10) as output, enabling server-side CSR generation without exposing the private key.
The 'ietf-keystore' module defines a top-level 'keystore' container (constrained by the 'central-keystore-supported' feature) composed of an 'asymmetric-keys' list and a 'symmetric-keys' list, each entry identified by a 'name' string. The structure for both key types is defined by the 'keystore-grouping' grouping.
The module defines four YANG features: 'central-keystore-supported' (server supports the top-level keystore container), 'inline-definitions-supported' (server supports locally defined keys), 'asymmetric-keys' (server implements /keystore/asymmetric-keys), and 'symmetric-keys' (server implements /keystore/symmetric-keys).
Two typedefs are defined: 'central-symmetric-key-ref' (leafref to /ks:keystore/ks:symmetric-keys/ks:symmetric-key/ks:name) and 'central-asymmetric-key-ref' (leafref to /ks:keystore/ks:asymmetric-keys/ks:asymmetric-key/ks:name), provided as aids for consuming modules.
IANA has registered the URI 'urn:ietf:params:xml:ns:yang:ietf-keystore' in the 'ns' registry of the IETF XML Registry (RFC 3688).
IANA has registered the YANG module 'ietf-keystore' (prefix 'ks', namespace 'urn:ietf:params:xml:ns:yang:ietf-keystore', not maintained by IANA) in the 'YANG Module Names' registry defined in RFC 6020.
All writable data nodes in the 'ietf-keystore' module have the NACM extension 'default-deny-write' applied, because any modification to a key or key reference may dramatically alter the implemented security policy. The 'cleartext-symmetric-key' and 'cleartext-private-key' nodes (imported from RFC 9640) have 'default-deny-all' applied and should never be returned to a client.
Built-in key types SHOULD be hidden and/or encrypted (not cleartext). If this is not possible, NACM access control SHOULD be used to limit access to the key's secret data to only the most trusted authorized clients such as an organization's crypto officer.
The module does not constrain the usage of private keys (e.g., signature vs. decryption) nor constrain public key usage except where a configured certificate imposes key usage constraints. Implementors should be aware of this unconstrained key usage.