YANG Data Types and Groupings for Cryptography
Extracted elements (30)
Key generation RPCs were removed from earlier revisions of this document due to an inability to reach consensus on how to generically identify the key algorithm to use. As a result, this module only supports keys configured via an external client; protocol-specific key generation is delegated to separate modules (e.g., RFC 9644, RFC 9645).
PKCS #10 (RFC 2986) was chosen for the generate-csr action over Certificate Request Message Format (CRMF, RFC 4211) because it was unclear whether there was market demand for CRMF. A backwards-compatible CRMF-supporting solution can be defined in the future if desired.
The ietf-crypto-types module is the foundational dependency in a layered RFC family: truststore (RFC 9641) and keystore (RFC 9642) depend on it; these in turn support SSH, TLS, HTTP, NETCONF, and RESTCONF client/server modules. Implementors must implement ietf-crypto-types for the identity namespace to be available to all consuming modules.
Certificate expiration notifications are RECOMMENDED to be sent once a month for 3 months, then once a week for four weeks, then once a day until resolved. The notification MAY also be sent when the issuer's CRL is about to expire.
Cleartext key values (cleartext-symmetric-key and cleartext-private-key nodes) SHOULD be zeroized when deleted to prevent analysis of remnant data in persistent storage locations.
Storing cleartext values for passwords and keys is NOT RECOMMENDED. The module enables cleartext storage only when specific feature statements (cleartext-passwords, cleartext-symmetric-keys, cleartext-private-keys) are explicitly enabled.
The cms-enveloped-data-format identity requires that the EnvelopedData structure MUST have exactly one RecipientInfo. For RSA keys, it MUST be KeyTransRecipientInfo with subjectKeyIdentifier using method 1 from RFC 7093. For ECC keys, it MUST be KeyAgreeRecipientInfo using OriginatorPublicKey with no UserKeyingMaterial and exactly one RecipientEncryptedKeys.
The 'encrypted-by' container in encrypted-value-grouping MUST be augmented by consuming modules with key references. A symmetric key MUST be referenced via a leaf named 'symmetric-key-ref' and an asymmetric key via 'asymmetric-key-ref'. These leaf nodes MUST be direct descendants in the data tree.
The 'generate-csr' action SHOULD only be executed by authorized users; NACM 'default-deny-all' is applied to it. It is RECOMMENDED that implementations assert channel binding (RFC 5056) to ensure the requesting application layer matches the device authenticated at the secure transport layer.
The 'ietf-crypto-types' module does not define protocol-accessible nodes but MUST be 'implemented' (per RFC 7950 Section 5.6.5) in order for the identities defined in Section 2.1.2 to be available for use by other modules.
To securely encrypt a password or key with a symmetric key, a proper block cipher mode such as AEAD or CBC MUST be used to ensure a random IV is included. The Electronic Codebook (ECB) block cipher mode MUST NOT be used, as it leaks whether identical keys/passwords share the same ciphertext.
Five base identity hierarchies are defined: 'public-key-format' (with derived ssh-public-key-format and subject-public-key-info-format), 'private-key-format' (rsa-private-key-format, ec-private-key-format, one-asymmetric-key-format), 'symmetric-key-format' (octet-string-key-format, one-symmetric-key-format), 'encrypted-value-format' (symmetrically- and asymmetrically-encrypted-value-format), and 'csr-format' (p10-csr-format). Base identities are abstract; additional derived identities MAY be defined by future efforts.
The 'asymmetric-key-pair-grouping' combines public-key-grouping and private-key-grouping, with public key fields made optional via refine. Implementations MUST ensure that when both keys are specified, they are a matching pair.
The 'asymmetric-key-pair-with-certs-grouping' combines asymmetric-key-pair-grouping, a 'certificates' container (list of named end-entity-cert-grouping instances), and generate-csr-grouping. Implementations MUST assert that certificates contain the matching public key. This is the primary grouping for managing asymmetric keys with multiple associated certificates.
The 'certificate-expiration-grouping' defines a 'certificate-expiration' notification (guarded by certificate-expiration-notification feature) with a mandatory 'expiration-date' leaf of type yang:date-and-time. It is used by trust-anchor-cert-grouping and end-entity-cert-grouping.
The 'encrypted-value-grouping' grouping contains three nodes: 'encrypted-by' (an empty container that consuming modules MUST augment with key references), 'encrypted-value-format' (identityref indicating the encoding format), and 'encrypted-value' (binary containing the ciphertext). The 'encrypted-by' container has NACM 'default-deny-write' applied.
The 'generate-csr-grouping' defines a 'generate-csr' action (guarded by csr-generation feature, protected by NACM 'default-deny-all') that takes 'csr-format' (identityref) and 'csr-info' (DER-encoded CertificationRequestInfo) as inputs and returns the CSR in the requested format. Only available when the associated public key uses subject-public-key-info-format.
The 'ietf-crypto-types' YANG 1.1 module defines identities, typedefs, and groupings for cryptographic applications. It serves as the foundational dependency for a collection of RFCs supporting NETCONF and RESTCONF client/server configuration, including truststore, keystore, SSH, TLS, and HTTP client/server modules.
The 'password-grouping' grouping provides a choice between 'cleartext-password' (string, guarded by cleartext-passwords feature) and 'encrypted-password' (uses encrypted-value-grouping, guarded by encrypted-passwords feature). Intended for remote authentication credentials; for local account passwords, the 'ianach:crypt-hash' typedef from RFC 7317 should be used instead.
The 'private-key-grouping' grouping provides 'private-key-format' identityref and a three-way choice: 'cleartext-private-key' (binary), 'hidden-private-key' (type empty), or 'encrypted-private-key' (uses encrypted-value-grouping). All nodes carry NACM 'default-deny-write'; cleartext-private-key additionally has 'default-deny-all'.
The 'public-key-grouping' grouping contains two mandatory nodes: 'public-key-format' (identityref to public-key-format base identity) and 'public-key' (binary). No choice statement is provided to hide or encrypt public key data because it is unnecessary for public keys.
The 'symmetric-key-grouping' grouping provides a 'key-format' identityref and a three-way choice: 'cleartext-symmetric-key' (binary), 'hidden-symmetric-key' (type empty, not exportable via management interfaces), or 'encrypted-symmetric-key' (uses encrypted-value-grouping). Each case is gated by a corresponding feature statement.
IANA has registered the namespace URI 'urn:ietf:params:xml:ns:yang:ietf-crypto-types' in the 'ns' registry of the IETF XML Registry (RFC 3688), with the IESG as registrant contact.
IANA has registered the YANG module 'ietf-crypto-types' in the YANG Module Names registry (RFC 6020), with namespace 'urn:ietf:params:xml:ns:yang:ietf-crypto-types', prefix 'ct', and reference RFC 9640.
NACM 'default-deny-all' is applied to cleartext-password, cleartext-symmetric-key, and cleartext-private-key nodes so they are never returned to clients in normal use. NACM 'default-deny-write' is applied to all writable data nodes in the module, because even modification of a public key or certificate can dramatically alter the security policy.
The cert-data node (in both trust-anchor-cert-grouping and end-entity-cert-grouping) has NACM 'default-deny-all' applied because certificates may reveal which servers this device communicates with and may contain personally identifying information in end-entity certificates.
The ietf-crypto-types YANG module is accessed via NETCONF and RESTCONF, both of which have mandatory-to-implement secure transport (SSH, TLS, QUIC) and mandatory mutual authentication. NACM (RFC 8341) provides access control for restricting users to authorized protocol operations and content.
The public-key-grouping and asymmetric-key-pair-grouping enable configuration of keys without usage constraints (e.g., encryption vs. verification). The asymmetric-key-pair-with-cert-grouping partially mitigates this by requiring associated certificates to constrain key usage according to local policy.
All typedefs in the module extend the 'binary' YANG base type and encode ASN.1 structures using DER (ITU-T X.690). Specific typedefs include: x509 (RFC 5280 Certificate), crl (RFC 5280 CertificateList), p10-csr (RFC 2986 CertificationRequest), csr-info (RFC 2986 CertificationRequestInfo), and CMS content types (cms, signed-data-cms, enveloped-data-cms, encrypted-data-cms, authenticated-data-cms).
The 'trust-anchor-cert-cms' typedef is a signed-data-cms that MUST contain a single chain of X.509 certificates with exactly one self-signed root certificate, and MAY contain revocation objects. The 'end-entity-cert-cms' typedef MUST contain exactly one end-entity certificate, MUST NOT contain spurious certificates, and MAY contain intermediate CA certificates and revocation objects.