1 module ietf-tls-server {
3 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server";
6 import ietf-netconf-acm {
9 "RFC 8341: Network Configuration Access Control Model";
12 import ietf-crypto-types {
15 "RFC AAAA: YANG Data Types and Groupings for Cryptography";
18 import ietf-truststore {
21 "RFC BBBB: A YANG Data Model for a Truststore";
24 import ietf-keystore {
27 "RFC CCCC: A YANG Data Model for a Keystore";
30 import ietf-tls-common {
33 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
37 "IETF NETCONF (Network Configuration) Working Group";
40 "WG List: NETCONF WG list <mailto:netconf@ietf.org>
41 WG Web: https://datatracker.ietf.org/wg/netconf
42 Author: Kent Watsen <mailto:kent+ietf@watsen.net>
43 Author: Jeff Hartley <mailto:jeff.hartley@commscope.com>";
46 "This module defines reusable groupings for TLS servers that
47 can be used as a basis for specific TLS server instances.
49 Copyright (c) 2023 IETF Trust and the persons identified
50 as authors of the code. All rights reserved.
52 Redistribution and use in source and binary forms, with
53 or without modification, is permitted pursuant to, and
54 subject to the license terms contained in, the Revised
55 BSD License set forth in Section 4.c of the IETF Trust's
56 Legal Provisions Relating to IETF Documents
57 (https://trustee.ietf.org/license-info).
59 This version of this YANG module is part of RFC FFFF
60 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC
61 itself for full legal notices.
63 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
64 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
65 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
66 are to be interpreted as described in BCP 14 (RFC 2119)
67 (RFC 8174) when, and only when, they appear in all
68 capitals, as shown here.";
74 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
79 feature tls-server-keepalives {
81 "Per socket TLS keepalive parameters are configurable for
82 TLS servers on the server implementing this feature.";
85 feature server-ident-x509-cert {
87 "Indicates that the server supports identifying itself
88 using X.509 certificates.";
91 Internet X.509 Public Key Infrastructure Certificate
92 and Certificate Revocation List (CRL) Profile";
95 feature server-ident-raw-public-key {
97 "Indicates that the server supports identifying itself
98 using raw public keys.";
101 Using Raw Public Keys in Transport Layer Security (TLS)
102 and Datagram Transport Layer Security (DTLS)";
105 feature server-ident-tls12-psk {
106 if-feature "tlscmn:tls12";
108 "Indicates that the server supports identifying itself
109 using TLS-1.2 PSKs (pre-shared or pairwise-symmetric keys).";
112 Pre-Shared Key Ciphersuites for Transport Layer Security
116 feature server-ident-tls13-epsk {
117 if-feature "tlscmn:tls13";
119 "Indicates that the server supports identifying itself
120 using TLS-1.3 External PSKs (pre-shared keys).";
123 The Transport Layer Security (TLS) Protocol Version 1.3";
126 feature client-auth-supported {
128 "Indicates that the configuration for how to authenticate
129 clients can be configured herein. TLS-level client
130 authentication may not be needed when client authentication
131 is expected to occur only at another protocol layer.";
134 feature client-auth-x509-cert {
136 "Indicates that the server supports authenticating clients
137 using X.509 certificates.";
140 Internet X.509 Public Key Infrastructure Certificate
141 and Certificate Revocation List (CRL) Profile";
144 feature client-auth-raw-public-key {
146 "Indicates that the server supports authenticating clients
147 using raw public keys.";
150 Using Raw Public Keys in Transport Layer Security (TLS)
151 and Datagram Transport Layer Security (DTLS)";
154 feature client-auth-tls12-psk {
156 "Indicates that the server supports authenticating clients
157 using PSKs (pre-shared or pairwise-symmetric keys).";
160 Pre-Shared Key Ciphersuites for Transport Layer Security
164 feature client-auth-tls13-epsk {
166 "Indicates that the server supports authenticating clients
167 using TLS-1.3 External PSKs (pre-shared keys).";
170 The Transport Layer Security (TLS) Protocol Version 1.3";
175 grouping tls-server-grouping {
177 "A reusable grouping for configuring a TLS server without
178 any consideration for how underlying TCP sessions are
181 Note that this grouping uses fairly typical descendant
182 node names such that a stack of 'uses' statements will
183 have name conflicts. It is intended that the consuming
184 data model will resolve the issue (e.g., by wrapping
185 the 'uses' statement in a container called
186 'tls-server-parameters'). This model purposely does
187 not do this itself so as to provide maximum flexibility
188 to consuming models.";
190 container server-identity {
191 nacm:default-deny-write;
193 "A locally-defined or referenced end-entity certificate,
194 including any configured intermediate certificates, the
195 TLS server will present when establishing a TLS connection
196 in its Certificate message, as defined in Section 7.4.2
197 in RFC 5246 and Section 4.4.2 in RFC 8446.";
199 "RFC 5246: The Transport Layer Security (TLS) Protocol
201 RFC 8446: The Transport Layer Security (TLS) Protocol
203 RFC CCCC: A YANG Data Model for a Keystore";
207 "A choice amongst authentication types, of which one must
208 be enabled (via its associated 'feature') and selected.";
210 if-feature "server-ident-x509-cert";
211 container certificate {
213 "Specifies the server identity using a certificate.";
215 "ks:inline-or-keystore-end-entity-cert-with-key-"
217 refine "inline-or-keystore/inline/inline-definition" {
218 must 'not(public-key-format) or derived-from-or-self'
219 + '(public-key-format,' + ' "ct:subject-public-'
220 + 'key-info-format")';
222 refine "inline-or-keystore/central-keystore/"
223 + "central-keystore-reference/asymmetric-key" {
224 must 'not(deref(.)/../ks:public-key-format) or '
225 + 'derived-from-or-self(deref(.)/../ks:public-key'
226 + '-format, "ct:subject-public-key-info-format")';
231 case raw-private-key {
232 if-feature "server-ident-raw-public-key";
233 container raw-private-key {
235 "Specifies the server identity using a raw
237 uses ks:inline-or-keystore-asymmetric-key-grouping {
238 refine "inline-or-keystore/inline/inline-definition" {
239 must 'not(public-key-format) or derived-from-or-self'
240 + '(public-key-format,' + ' "ct:subject-public-'
241 + 'key-info-format")';
243 refine "inline-or-keystore/central-keystore/"
244 + "central-keystore-reference" {
245 must 'not(deref(.)/../ks:public-key-format) or '
246 + 'derived-from-or-self(deref(.)/../ks:public-key'
247 + '-format, "ct:subject-public-key-info-format")';
253 if-feature "server-ident-tls12-psk";
254 container tls12-psk {
256 "Specifies the server identity using a PSK (pre-shared
257 or pairwise-symmetric key).";
258 uses ks:inline-or-keystore-symmetric-key-grouping;
262 "The key 'psk_identity_hint' value used in the TLS
263 'ServerKeyExchange' message.";
265 "RFC 4279: Pre-Shared Key Ciphersuites for
266 Transport Layer Security (TLS)";
271 if-feature "server-ident-tls13-epsk";
272 container tls13-epsk {
274 "An External Pre-Shared Key (EPSK) is established
275 or provisioned out-of-band, i.e., not from a TLS
276 connection. An EPSK is a tuple of (Base Key,
277 External Identity, Hash). External PSKs MUST
278 NOT be imported for (D)TLS 1.2 or prior versions.
279 When PSKs are provisioned out of band, the PSK
280 identity and the KDF hash algorithm to be used
281 with the PSK MUST also be provisioned.
283 The structure of this container is designed to
284 satisfy the requirements of RFC 8446 Section
285 4.2.11, the recommendations from Section 6 in
286 RFC 9257, and the EPSK input fields detailed in
287 Section 5.1 in RFC 9258. The base-key is based
288 upon ks:inline-or-keystore-symmetric-key-grouping
289 in order to provide users with flexible and
290 secure storage options.";
292 "RFC 8446: The Transport Layer Security (TLS)
294 RFC 9257: Guidance for External Pre-Shared Key
296 RFC 9258: Importing External Pre-Shared Keys
298 uses ks:inline-or-keystore-symmetric-key-grouping;
299 leaf external-identity {
303 "As per Section 4.2.11 of RFC 8446, and Section 4.1
304 of RFC 9257, a sequence of bytes used to identify
305 an EPSK. A label for a pre-shared key established
308 "RFC 8446: The Transport Layer Security (TLS)
310 RFC 9257: Guidance for External Pre-Shared Key
314 type tlscmn:epsk-supported-hash;
317 "As per Section 4.2.11 of RFC 8446, for externally
318 established PSKs, the Hash algorithm MUST be set
319 when the PSK is established or default to SHA-256
320 if no such algorithm is defined. The server MUST
321 ensure that it selects a compatible PSK (if any)
322 and cipher suite. Each PSK MUST only be used
323 with a single hash function.";
325 "RFC 8446: The Transport Layer Security (TLS)
326 Protocol Version 1.3";
331 "Per Section 5.1 of RFC 9258, context MUST include
332 the context used to determine the EPSK, if
333 any exists. For example, context may include
334 information about peer roles or identities
335 to mitigate Selfie-style reflection attacks.
336 Since the EPSK is a key derived from an external
337 protocol or sequence of protocols, context MUST
338 include a channel binding for the deriving
339 protocols [RFC5056]. The details of this
340 binding are protocol specfic and out of scope
343 "RFC 9258: Importing External Pre-Shared Keys
346 leaf target-protocol {
349 "As per Section 3.1 of RFC 9258, the protocol
350 for which a PSK is imported for use.";
352 "RFC 9258: Importing External Pre-Shared Keys
358 "As per Section 3 of RFC 9258, the KDF for
359 which a PSK is imported for use.";
361 "RFC 9258: Importing External Pre-Shared Keys
367 } // container server-identity
369 container client-authentication {
370 if-feature "client-auth-supported";
371 nacm:default-deny-write;
372 must 'ca-certs or ee-certs or raw-public-keys or tls12-psks
375 "Indicates that client authentication is supported (i.e.,
376 that the server will request clients send certificates).
377 If not configured, the TLS server SHOULD NOT request the
378 TLS clients provide authentication credentials.";
380 "Specifies how the TLS server can authenticate TLS clients.
381 Any combination of credentials is additive and unordered.
383 Note that no configuration is required for PSK (pre-shared
384 or pairwise-symmetric key) based authentication as the key
385 is necessarily the same as configured in the '../server-
388 if-feature "client-auth-x509-cert";
390 "Indicates that CA certificates have been configured.
391 This statement is present so the mandatory descendant
392 nodes do not imply that this node must be configured.";
394 "A set of certificate authority (CA) certificates used by
395 the TLS server to authenticate TLS client certificates.
396 A client certificate is authenticated if it has a valid
397 chain of trust to a configured CA certificate.";
399 "RFC BBBB: A YANG Data Model for a Truststore";
400 uses ts:inline-or-truststore-certs-grouping;
403 if-feature "client-auth-x509-cert";
405 "Indicates that EE certificates have been configured.
406 This statement is present so the mandatory descendant
407 nodes do not imply that this node must be configured.";
409 "A set of client certificates (i.e., end entity
410 certificates) used by the TLS server to authenticate
411 certificates presented by TLS clients. A client
412 certificate is authenticated if it is an exact
413 match to a configured client certificate.";
415 "RFC BBBB: A YANG Data Model for a Truststore";
416 uses ts:inline-or-truststore-certs-grouping;
418 container raw-public-keys {
419 if-feature "client-auth-raw-public-key";
421 "Indicates that raw public keys have been configured.
422 This statement is present so the mandatory descendant
423 nodes do not imply that this node must be configured.";
425 "A set of raw public keys used by the TLS server to
426 authenticate raw public keys presented by the TLS
427 client. A raw public key is authenticated if it
428 is an exact match to a configured raw public key.";
430 "RFC BBBB: A YANG Data Model for a Truststore";
431 uses ts:inline-or-truststore-public-keys-grouping {
432 refine "inline-or-truststore/inline/inline-definition/"
434 must 'derived-from-or-self(public-key-format,'
435 + ' "ct:subject-public-key-info-format")';
437 refine "inline-or-truststore/central-truststore/"
438 + "central-truststore-reference" {
439 must 'not(deref(.)/../ts:public-key/ts:public-key-'
440 + 'format[not(derived-from-or-self(., "ct:subject-'
441 + 'public-key-info-format"))])';
446 if-feature "client-auth-tls12-psk";
449 "Indicates that the TLS server can authenticate TLS clients
450 using configured PSKs (pre-shared or pairwise-symmetric
453 No configuration is required since the PSK value is the
454 same as PSK value configured in the 'server-identity'
458 if-feature "client-auth-tls13-epsk";
461 "Indicates that the TLS 1.3 server can authenticate TLS
462 clients using configured external PSKs (pre-shared keys).
464 No configuration is required since the PSK value is the
465 same as PSK value configured in the 'server-identity'
468 } // container client-authentication
470 container hello-params {
471 nacm:default-deny-write;
472 if-feature "tlscmn:hello-params";
473 uses tlscmn:hello-params-grouping;
475 "Configurable parameters for the TLS hello message.";
476 } // container hello-params
478 container keepalives {
479 nacm:default-deny-write;
480 if-feature "tls-server-keepalives";
482 "Configures the keepalive policy for the TLS server.";
483 leaf peer-allowed-to-send {
486 "Indicates that the remote TLS client is allowed to send
487 HeartbeatRequest messages, as defined by RFC 6520
488 to this TLS server.";
490 "RFC 6520: Transport Layer Security (TLS) and Datagram
491 Transport Layer Security (DTLS) Heartbeat Extension";
493 container test-peer-aliveness {
495 "Indicates that the TLS server proactively tests the
496 aliveness of the remote TLS client.";
498 "Configures the keep-alive policy to proactively test
499 the aliveness of the TLS client. An unresponsive
500 TLS client is dropped after approximately max-wait
501 * max-attempts seconds.";
509 "Sets the amount of time in seconds after which if
510 no data has been received from the TLS client, a
511 TLS-level message will be sent to test the
512 aliveness of the TLS client.";
518 "Sets the maximum number of sequential keep-alive
519 messages that can fail to obtain a response from
520 the TLS client before assuming the TLS client is
524 } // container keepalives
525 } // grouping tls-server-grouping