527 lines
20 KiB
YANG
527 lines
20 KiB
YANG
module ietf-tls-server {
|
|
yang-version 1.1;
|
|
namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server";
|
|
prefix tlss;
|
|
|
|
import ietf-netconf-acm {
|
|
prefix nacm;
|
|
reference
|
|
"RFC 8341: Network Configuration Access Control Model";
|
|
}
|
|
|
|
import ietf-crypto-types {
|
|
prefix ct;
|
|
reference
|
|
"RFC AAAA: YANG Data Types and Groupings for Cryptography";
|
|
}
|
|
|
|
import ietf-truststore {
|
|
prefix ts;
|
|
reference
|
|
"RFC BBBB: A YANG Data Model for a Truststore";
|
|
}
|
|
|
|
import ietf-keystore {
|
|
prefix ks;
|
|
reference
|
|
"RFC CCCC: A YANG Data Model for a Keystore";
|
|
}
|
|
|
|
import ietf-tls-common {
|
|
prefix tlscmn;
|
|
reference
|
|
"RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
|
|
}
|
|
|
|
organization
|
|
"IETF NETCONF (Network Configuration) Working Group";
|
|
|
|
contact
|
|
"WG List: NETCONF WG list <mailto:netconf@ietf.org>
|
|
WG Web: https://datatracker.ietf.org/wg/netconf
|
|
Author: Kent Watsen <mailto:kent+ietf@watsen.net>
|
|
Author: Jeff Hartley <mailto:jeff.hartley@commscope.com>";
|
|
|
|
description
|
|
"This module defines reusable groupings for TLS servers that
|
|
can be used as a basis for specific TLS server instances.
|
|
|
|
Copyright (c) 2023 IETF Trust and the persons identified
|
|
as authors of the code. All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with
|
|
or without modification, is permitted pursuant to, and
|
|
subject to the license terms contained in, the Revised
|
|
BSD License set forth in Section 4.c of the IETF Trust's
|
|
Legal Provisions Relating to IETF Documents
|
|
(https://trustee.ietf.org/license-info).
|
|
|
|
This version of this YANG module is part of RFC FFFF
|
|
(https://www.rfc-editor.org/info/rfcFFFF); see the RFC
|
|
itself for full legal notices.
|
|
|
|
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 (RFC 2119)
|
|
(RFC 8174) when, and only when, they appear in all
|
|
capitals, as shown here.";
|
|
|
|
revision 2023-12-28 {
|
|
description
|
|
"Initial version";
|
|
reference
|
|
"RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
|
|
}
|
|
|
|
// Features
|
|
|
|
feature tls-server-keepalives {
|
|
description
|
|
"Per socket TLS keepalive parameters are configurable for
|
|
TLS servers on the server implementing this feature.";
|
|
}
|
|
|
|
feature server-ident-x509-cert {
|
|
description
|
|
"Indicates that the server supports identifying itself
|
|
using X.509 certificates.";
|
|
reference
|
|
"RFC 5280:
|
|
Internet X.509 Public Key Infrastructure Certificate
|
|
and Certificate Revocation List (CRL) Profile";
|
|
}
|
|
|
|
feature server-ident-raw-public-key {
|
|
description
|
|
"Indicates that the server supports identifying itself
|
|
using raw public keys.";
|
|
reference
|
|
"RFC 7250:
|
|
Using Raw Public Keys in Transport Layer Security (TLS)
|
|
and Datagram Transport Layer Security (DTLS)";
|
|
}
|
|
|
|
feature server-ident-tls12-psk {
|
|
if-feature "tlscmn:tls12";
|
|
description
|
|
"Indicates that the server supports identifying itself
|
|
using TLS-1.2 PSKs (pre-shared or pairwise-symmetric keys).";
|
|
reference
|
|
"RFC 4279:
|
|
Pre-Shared Key Ciphersuites for Transport Layer Security
|
|
(TLS)";
|
|
}
|
|
|
|
feature server-ident-tls13-epsk {
|
|
if-feature "tlscmn:tls13";
|
|
description
|
|
"Indicates that the server supports identifying itself
|
|
using TLS-1.3 External PSKs (pre-shared keys).";
|
|
reference
|
|
"RFC 8446:
|
|
The Transport Layer Security (TLS) Protocol Version 1.3";
|
|
}
|
|
|
|
feature client-auth-supported {
|
|
description
|
|
"Indicates that the configuration for how to authenticate
|
|
clients can be configured herein. TLS-level client
|
|
authentication may not be needed when client authentication
|
|
is expected to occur only at another protocol layer.";
|
|
}
|
|
|
|
feature client-auth-x509-cert {
|
|
description
|
|
"Indicates that the server supports authenticating clients
|
|
using X.509 certificates.";
|
|
reference
|
|
"RFC 5280:
|
|
Internet X.509 Public Key Infrastructure Certificate
|
|
and Certificate Revocation List (CRL) Profile";
|
|
}
|
|
|
|
feature client-auth-raw-public-key {
|
|
description
|
|
"Indicates that the server supports authenticating clients
|
|
using raw public keys.";
|
|
reference
|
|
"RFC 7250:
|
|
Using Raw Public Keys in Transport Layer Security (TLS)
|
|
and Datagram Transport Layer Security (DTLS)";
|
|
}
|
|
|
|
feature client-auth-tls12-psk {
|
|
description
|
|
"Indicates that the server supports authenticating clients
|
|
using PSKs (pre-shared or pairwise-symmetric keys).";
|
|
reference
|
|
"RFC 4279:
|
|
Pre-Shared Key Ciphersuites for Transport Layer Security
|
|
(TLS)";
|
|
}
|
|
|
|
feature client-auth-tls13-epsk {
|
|
description
|
|
"Indicates that the server supports authenticating clients
|
|
using TLS-1.3 External PSKs (pre-shared keys).";
|
|
reference
|
|
"RFC 8446:
|
|
The Transport Layer Security (TLS) Protocol Version 1.3";
|
|
}
|
|
|
|
// Groupings
|
|
|
|
grouping tls-server-grouping {
|
|
description
|
|
"A reusable grouping for configuring a TLS server without
|
|
any consideration for how underlying TCP sessions are
|
|
established.
|
|
|
|
Note that this grouping uses fairly typical descendant
|
|
node names such that a stack of 'uses' statements will
|
|
have name conflicts. It is intended that the consuming
|
|
data model will resolve the issue (e.g., by wrapping
|
|
the 'uses' statement in a container called
|
|
'tls-server-parameters'). This model purposely does
|
|
not do this itself so as to provide maximum flexibility
|
|
to consuming models.";
|
|
|
|
container server-identity {
|
|
nacm:default-deny-write;
|
|
description
|
|
"A locally-defined or referenced end-entity certificate,
|
|
including any configured intermediate certificates, the
|
|
TLS server will present when establishing a TLS connection
|
|
in its Certificate message, as defined in Section 7.4.2
|
|
in RFC 5246 and Section 4.4.2 in RFC 8446.";
|
|
reference
|
|
"RFC 5246: The Transport Layer Security (TLS) Protocol
|
|
Version 1.2
|
|
RFC 8446: The Transport Layer Security (TLS) Protocol
|
|
Version 1.3
|
|
RFC CCCC: A YANG Data Model for a Keystore";
|
|
choice auth-type {
|
|
mandatory true;
|
|
description
|
|
"A choice amongst authentication types, of which one must
|
|
be enabled (via its associated 'feature') and selected.";
|
|
case certificate {
|
|
if-feature "server-ident-x509-cert";
|
|
container certificate {
|
|
description
|
|
"Specifies the server identity using a certificate.";
|
|
uses
|
|
"ks:inline-or-keystore-end-entity-cert-with-key-"
|
|
+ "grouping" {
|
|
refine "inline-or-keystore/inline/inline-definition" {
|
|
must 'not(public-key-format) or derived-from-or-self'
|
|
+ '(public-key-format,' + ' "ct:subject-public-'
|
|
+ 'key-info-format")';
|
|
}
|
|
refine "inline-or-keystore/central-keystore/"
|
|
+ "central-keystore-reference/asymmetric-key" {
|
|
must 'not(deref(.)/../ks:public-key-format) or '
|
|
+ 'derived-from-or-self(deref(.)/../ks:public-key'
|
|
+ '-format, "ct:subject-public-key-info-format")';
|
|
}
|
|
}
|
|
}
|
|
}
|
|
case raw-private-key {
|
|
if-feature "server-ident-raw-public-key";
|
|
container raw-private-key {
|
|
description
|
|
"Specifies the server identity using a raw
|
|
private key.";
|
|
uses ks:inline-or-keystore-asymmetric-key-grouping {
|
|
refine "inline-or-keystore/inline/inline-definition" {
|
|
must 'not(public-key-format) or derived-from-or-self'
|
|
+ '(public-key-format,' + ' "ct:subject-public-'
|
|
+ 'key-info-format")';
|
|
}
|
|
refine "inline-or-keystore/central-keystore/"
|
|
+ "central-keystore-reference" {
|
|
must 'not(deref(.)/../ks:public-key-format) or '
|
|
+ 'derived-from-or-self(deref(.)/../ks:public-key'
|
|
+ '-format, "ct:subject-public-key-info-format")';
|
|
}
|
|
}
|
|
}
|
|
}
|
|
case tls12-psk {
|
|
if-feature "server-ident-tls12-psk";
|
|
container tls12-psk {
|
|
description
|
|
"Specifies the server identity using a PSK (pre-shared
|
|
or pairwise-symmetric key).";
|
|
uses ks:inline-or-keystore-symmetric-key-grouping;
|
|
leaf id-hint {
|
|
type string;
|
|
description
|
|
"The key 'psk_identity_hint' value used in the TLS
|
|
'ServerKeyExchange' message.";
|
|
reference
|
|
"RFC 4279: Pre-Shared Key Ciphersuites for
|
|
Transport Layer Security (TLS)";
|
|
}
|
|
}
|
|
}
|
|
case tls13-epsk {
|
|
if-feature "server-ident-tls13-epsk";
|
|
container tls13-epsk {
|
|
description
|
|
"An External Pre-Shared Key (EPSK) is established
|
|
or provisioned out-of-band, i.e., not from a TLS
|
|
connection. An EPSK is a tuple of (Base Key,
|
|
External Identity, Hash). External PSKs MUST
|
|
NOT be imported for (D)TLS 1.2 or prior versions.
|
|
When PSKs are provisioned out of band, the PSK
|
|
identity and the KDF hash algorithm to be used
|
|
with the PSK MUST also be provisioned.
|
|
|
|
The structure of this container is designed to
|
|
satisfy the requirements of RFC 8446 Section
|
|
4.2.11, the recommendations from Section 6 in
|
|
RFC 9257, and the EPSK input fields detailed in
|
|
Section 5.1 in RFC 9258. The base-key is based
|
|
upon ks:inline-or-keystore-symmetric-key-grouping
|
|
in order to provide users with flexible and
|
|
secure storage options.";
|
|
reference
|
|
"RFC 8446: The Transport Layer Security (TLS)
|
|
Protocol Version 1.3
|
|
RFC 9257: Guidance for External Pre-Shared Key
|
|
(PSK) Usage in TLS
|
|
RFC 9258: Importing External Pre-Shared Keys
|
|
(PSKs) for TLS 1.3";
|
|
uses ks:inline-or-keystore-symmetric-key-grouping;
|
|
leaf external-identity {
|
|
type string;
|
|
mandatory true;
|
|
description
|
|
"As per Section 4.2.11 of RFC 8446, and Section 4.1
|
|
of RFC 9257, a sequence of bytes used to identify
|
|
an EPSK. A label for a pre-shared key established
|
|
externally.";
|
|
reference
|
|
"RFC 8446: The Transport Layer Security (TLS)
|
|
Protocol Version 1.3
|
|
RFC 9257: Guidance for External Pre-Shared Key
|
|
(PSK) Usage in TLS";
|
|
}
|
|
leaf hash {
|
|
type tlscmn:epsk-supported-hash;
|
|
default sha-256;
|
|
description
|
|
"As per Section 4.2.11 of RFC 8446, for externally
|
|
established PSKs, the Hash algorithm MUST be set
|
|
when the PSK is established or default to SHA-256
|
|
if no such algorithm is defined. The server MUST
|
|
ensure that it selects a compatible PSK (if any)
|
|
and cipher suite. Each PSK MUST only be used
|
|
with a single hash function.";
|
|
reference
|
|
"RFC 8446: The Transport Layer Security (TLS)
|
|
Protocol Version 1.3";
|
|
}
|
|
leaf context {
|
|
type string;
|
|
description
|
|
"Per Section 5.1 of RFC 9258, context MUST include
|
|
the context used to determine the EPSK, if
|
|
any exists. For example, context may include
|
|
information about peer roles or identities
|
|
to mitigate Selfie-style reflection attacks.
|
|
Since the EPSK is a key derived from an external
|
|
protocol or sequence of protocols, context MUST
|
|
include a channel binding for the deriving
|
|
protocols [RFC5056]. The details of this
|
|
binding are protocol specfic and out of scope
|
|
for this document.";
|
|
reference
|
|
"RFC 9258: Importing External Pre-Shared Keys
|
|
(PSKs) for TLS 1.3";
|
|
}
|
|
leaf target-protocol {
|
|
type uint16;
|
|
description
|
|
"As per Section 3.1 of RFC 9258, the protocol
|
|
for which a PSK is imported for use.";
|
|
reference
|
|
"RFC 9258: Importing External Pre-Shared Keys
|
|
(PSKs) for TLS 1.3";
|
|
}
|
|
leaf target-kdf {
|
|
type uint16;
|
|
description
|
|
"As per Section 3 of RFC 9258, the KDF for
|
|
which a PSK is imported for use.";
|
|
reference
|
|
"RFC 9258: Importing External Pre-Shared Keys
|
|
(PSKs) for TLS 1.3";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} // container server-identity
|
|
|
|
container client-authentication {
|
|
if-feature "client-auth-supported";
|
|
nacm:default-deny-write;
|
|
must 'ca-certs or ee-certs or raw-public-keys or tls12-psks
|
|
or tls13-epsks';
|
|
presence
|
|
"Indicates that client authentication is supported (i.e.,
|
|
that the server will request clients send certificates).
|
|
If not configured, the TLS server SHOULD NOT request the
|
|
TLS clients provide authentication credentials.";
|
|
description
|
|
"Specifies how the TLS server can authenticate TLS clients.
|
|
Any combination of credentials is additive and unordered.
|
|
|
|
Note that no configuration is required for PSK (pre-shared
|
|
or pairwise-symmetric key) based authentication as the key
|
|
is necessarily the same as configured in the '../server-
|
|
identity' node.";
|
|
container ca-certs {
|
|
if-feature "client-auth-x509-cert";
|
|
presence
|
|
"Indicates that CA certificates have been configured.
|
|
This statement is present so the mandatory descendant
|
|
nodes do not imply that this node must be configured.";
|
|
description
|
|
"A set of certificate authority (CA) certificates used by
|
|
the TLS server to authenticate TLS client certificates.
|
|
A client certificate is authenticated if it has a valid
|
|
chain of trust to a configured CA certificate.";
|
|
reference
|
|
"RFC BBBB: A YANG Data Model for a Truststore";
|
|
uses ts:inline-or-truststore-certs-grouping;
|
|
}
|
|
container ee-certs {
|
|
if-feature "client-auth-x509-cert";
|
|
presence
|
|
"Indicates that EE certificates have been configured.
|
|
This statement is present so the mandatory descendant
|
|
nodes do not imply that this node must be configured.";
|
|
description
|
|
"A set of client certificates (i.e., end entity
|
|
certificates) used by the TLS server to authenticate
|
|
certificates presented by TLS clients. A client
|
|
certificate is authenticated if it is an exact
|
|
match to a configured client certificate.";
|
|
reference
|
|
"RFC BBBB: A YANG Data Model for a Truststore";
|
|
uses ts:inline-or-truststore-certs-grouping;
|
|
}
|
|
container raw-public-keys {
|
|
if-feature "client-auth-raw-public-key";
|
|
presence
|
|
"Indicates that raw public keys have been configured.
|
|
This statement is present so the mandatory descendant
|
|
nodes do not imply that this node must be configured.";
|
|
description
|
|
"A set of raw public keys used by the TLS server to
|
|
authenticate raw public keys presented by the TLS
|
|
client. A raw public key is authenticated if it
|
|
is an exact match to a configured raw public key.";
|
|
reference
|
|
"RFC BBBB: A YANG Data Model for a Truststore";
|
|
uses ts:inline-or-truststore-public-keys-grouping {
|
|
refine "inline-or-truststore/inline/inline-definition/"
|
|
+ "public-key" {
|
|
must 'derived-from-or-self(public-key-format,'
|
|
+ ' "ct:subject-public-key-info-format")';
|
|
}
|
|
refine "inline-or-truststore/central-truststore/"
|
|
+ "central-truststore-reference" {
|
|
must 'not(deref(.)/../ts:public-key/ts:public-key-'
|
|
+ 'format[not(derived-from-or-self(., "ct:subject-'
|
|
+ 'public-key-info-format"))])';
|
|
}
|
|
}
|
|
}
|
|
leaf tls12-psks {
|
|
if-feature "client-auth-tls12-psk";
|
|
type empty;
|
|
description
|
|
"Indicates that the TLS server can authenticate TLS clients
|
|
using configured PSKs (pre-shared or pairwise-symmetric
|
|
keys).
|
|
|
|
No configuration is required since the PSK value is the
|
|
same as PSK value configured in the 'server-identity'
|
|
node.";
|
|
}
|
|
leaf tls13-epsks {
|
|
if-feature "client-auth-tls13-epsk";
|
|
type empty;
|
|
description
|
|
"Indicates that the TLS 1.3 server can authenticate TLS
|
|
clients using configured external PSKs (pre-shared keys).
|
|
|
|
No configuration is required since the PSK value is the
|
|
same as PSK value configured in the 'server-identity'
|
|
node.";
|
|
}
|
|
} // container client-authentication
|
|
|
|
container hello-params {
|
|
nacm:default-deny-write;
|
|
if-feature "tlscmn:hello-params";
|
|
uses tlscmn:hello-params-grouping;
|
|
description
|
|
"Configurable parameters for the TLS hello message.";
|
|
} // container hello-params
|
|
|
|
container keepalives {
|
|
nacm:default-deny-write;
|
|
if-feature "tls-server-keepalives";
|
|
description
|
|
"Configures the keepalive policy for the TLS server.";
|
|
leaf peer-allowed-to-send {
|
|
type empty;
|
|
description
|
|
"Indicates that the remote TLS client is allowed to send
|
|
HeartbeatRequest messages, as defined by RFC 6520
|
|
to this TLS server.";
|
|
reference
|
|
"RFC 6520: Transport Layer Security (TLS) and Datagram
|
|
Transport Layer Security (DTLS) Heartbeat Extension";
|
|
}
|
|
container test-peer-aliveness {
|
|
presence
|
|
"Indicates that the TLS server proactively tests the
|
|
aliveness of the remote TLS client.";
|
|
description
|
|
"Configures the keep-alive policy to proactively test
|
|
the aliveness of the TLS client. An unresponsive
|
|
TLS client is dropped after approximately max-wait
|
|
* max-attempts seconds.";
|
|
leaf max-wait {
|
|
type uint16 {
|
|
range "1..max";
|
|
}
|
|
units "seconds";
|
|
default "30";
|
|
description
|
|
"Sets the amount of time in seconds after which if
|
|
no data has been received from the TLS client, a
|
|
TLS-level message will be sent to test the
|
|
aliveness of the TLS client.";
|
|
}
|
|
leaf max-attempts {
|
|
type uint8;
|
|
default "3";
|
|
description
|
|
"Sets the maximum number of sequential keep-alive
|
|
messages that can fail to obtain a response from
|
|
the TLS client before assuming the TLS client is
|
|
no longer alive.";
|
|
}
|
|
}
|
|
} // container keepalives
|
|
} // grouping tls-server-grouping
|
|
|
|
}
|