YANG Data Model for Key Chains
Extracted elements (25)
Hexadecimal key string encoding provides greater key entropy compared to ASCII for the same number of internal key-string octets, and discourages usage of well-known words or numbers as keys.
Key chains enable graceful key rollover by overlapping send and accept lifetimes across multiple key entries. The sender uses the key with the most recent send lifetime; receivers accept all keys with a valid accept lifetime during the rollover window, avoiding traffic disruption.
Specifying 'always' for a key's send lifetime prevents graceful key rollover because it makes that key the permanent most-recent-start-time sender. The rollover technique depends on a future start-time for the new key.
Unlike the RFC 7210 crypto key table, this YANG model does not include key selection criteria or a deployment model where application/service details permeate the key database. It does not preclude augmentation for key selection criteria, as described in draft-chen-rtg-key-table-yang.
YANG features are used to handle vendor implementation differences (e.g., not all vendors support accept-tolerance or hexadecimal key strings) and to support security requirements such as TCP-AO algorithms not yet universally implemented.
Some protocols (e.g., TCP-AO) do not use the key chain key directly for authentication but apply a key derivation function to derive short-lived keys from the key chain element key (master key). The YANG model accommodates this usage.
For graceful key rollover, the receiver MAY accept all keys with a valid accept lifetime and the sender MAY send the key with the most recent send lifetime.
It is RECOMMENDED that key strings be encrypted using AES Key Wrap encryption to prevent key chains from being retrieved and stored with key strings in cleartext. This recommendation is independent of the NACM access protection.
Keys used with the cleartext algorithm are considered insecure and SHOULD NOT be reused with more secure algorithms. Similarly, MD5 and SHA-1 usage is NOT RECOMMENDED and should be confined to backward-compatibility deployments.
The cleartext algorithm feature usage is NOT RECOMMENDED except in cases where the application and device have no other alternative (e.g., legacy BFD devices authenticating at 10 ms intervals or less for many peers).
The 'key-chain-ref' typedef SHOULD be used by other YANG modules when they need to reference a configured key chain, rather than specifying the complete YANG XPath expression directly.
Crypto algorithm identities defined in the module include: hmac-sha-1-12 (if-feature crypto-hmac-sha-1-12), aes-cmac-prf-128, md5, sha-1, hmac-sha-1, hmac-sha-256, hmac-sha-384, hmac-sha-512, cleartext (if-feature cleartext), and replay-protection-only (if-feature replay-protection-only).
Operational state fields 'send-lifetime-active' and 'accept-lifetime-active' (both read-only boolean, config false) indicate whether a key's send or accept lifetime is currently active. The 'last-modified-timestamp' (yang:date-and-time, config false) records the most recent key-chain update.
The 'accept-tolerance' container (if-feature accept-tolerance) holds a uint32 'duration' leaf in seconds (default 0) that defines the tolerance window for accepting keys whose accept lifetime has recently expired or not yet begun.
The 'aes-key-wrap' container (if-feature aes-key-wrap) contains a boolean 'enable' leaf (default false). When enabled, key strings are encrypted using AES Key Wrap and encoded as hexadecimal key strings; the AES KEK is configured outside the YANG model.
The ietf-key-chain YANG module defines a list of key chains, each identified by a unique name, containing one or more keys indexed by a uint64 Key ID. Each key includes a key string, a mandatory cryptographic algorithm (identityref), and optional send/accept lifetimes.
The 'independent-send-accept-lifetime' feature allows separate lifetime specifications for send and accept operations on a single key. Without this feature, a single 'send-accept-lifetime' container governs both directions.
The 'key-chain-ref' typedef is a leafref to '/key-chain:key-chains/key-chain:key-chain/key-chain:name', providing a reusable type for other YANG modules to reference a configured key chain without specifying the full XPath expression.
The key-string container carries a NACM default-deny-all annotation and supports two styles: ASCII 'keystring' (type string) or, via the hex-key-string feature, 'hexadecimal-string' (type yang:hex-string). The hexadecimal form is required when AES Key Wrap encryption is in use.
The 'lifetime' grouping provides three end-time options for a key: 'always' (always valid, the default), 'start-end-time' with sub-choices of 'infinite' (no-end-time leaf), fixed 'duration' in seconds (uint32, 1–2147483646), or explicit 'end-date-time' (yang:date-and-time).
This document registers the URI 'urn:ietf:params:xml:ns:yang:ietf-key-chain' in the IETF XML Registry (BCP 81, RFC 3688) as an XML namespace.
This document registers the YANG module 'ietf-key-chain' (namespace urn:ietf:params:xml:ns:yang:ietf-key-chain, prefix key-chain) in the YANG Module Names registry.
MD5 and SHA-1 have been proven insecure; usage is NOT RECOMMENDED and should be confined to backward-compatibility deployments. Implementations with keys provided via this model should store them using best current security practices.
The AES key-encryption key (KEK) used for AES Key Wrap is not included in the YANG model and must be set or derived independently of key chain configuration. The hex-key-string feature is also required when AES key encryption is enabled, because encrypted keys contain non-ASCII characters.
The YANG module MUST be accessed via NETCONF over SSH or RESTCONF over HTTPS (TLS). The NETCONF access control model (NACM, RFC 6536) restricts access; key strings are not accessible by default and require explicit NACM rules to configure or retrieve.