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 {
107 "Indicates that the server supports identifying itself
108 using TLS-1.2 PSKs (pre-shared or pairwise-symmetric keys).";
111 Pre-Shared Key Ciphersuites for Transport Layer Security
115 feature server-ident-tls13-epsk {
117 "Indicates that the server supports identifying itself
118 using TLS-1.3 External PSKs (pre-shared keys).";
121 The Transport Layer Security (TLS) Protocol Version 1.3";
124 feature client-auth-supported {
126 "Indicates that the configuration for how to authenticate
127 clients can be configured herein. TLS-level client
128 authentication may not be needed when client authentication
129 is expected to occur only at another protocol layer.";
132 feature client-auth-x509-cert {
134 "Indicates that the server supports authenticating clients
135 using X.509 certificates.";
138 Internet X.509 Public Key Infrastructure Certificate
139 and Certificate Revocation List (CRL) Profile";
142 feature client-auth-raw-public-key {
144 "Indicates that the server supports authenticating clients
145 using raw public keys.";
148 Using Raw Public Keys in Transport Layer Security (TLS)
149 and Datagram Transport Layer Security (DTLS)";
152 feature client-auth-tls12-psk {
154 "Indicates that the server supports authenticating clients
155 using PSKs (pre-shared or pairwise-symmetric keys).";
158 Pre-Shared Key Ciphersuites for Transport Layer Security
162 feature client-auth-tls13-epsk {
164 "Indicates that the server supports authenticating clients
165 using TLS-1.3 External PSKs (pre-shared keys).";
168 The Transport Layer Security (TLS) Protocol Version 1.3";
173 grouping tls-server-grouping {
175 "A reusable grouping for configuring a TLS server without
176 any consideration for how underlying TCP sessions are
179 Note that this grouping uses fairly typical descendant
180 node names such that a stack of 'uses' statements will
181 have name conflicts. It is intended that the consuming
182 data model will resolve the issue (e.g., by wrapping
183 the 'uses' statement in a container called
184 'tls-server-parameters'). This model purposely does
185 not do this itself so as to provide maximum flexibility
186 to consuming models.";
188 container server-identity {
189 nacm:default-deny-write;
191 "A locally-defined or referenced end-entity certificate,
192 including any configured intermediate certificates, the
193 TLS server will present when establishing a TLS connection
194 in its Certificate message, as defined in Section 7.4.2
195 in RFC 5246 and Section 4.4.2 in RFC 8446.";
197 "RFC 5246: The Transport Layer Security (TLS) Protocol
199 RFC 8446: The Transport Layer Security (TLS) Protocol
201 RFC CCCC: A YANG Data Model for a Keystore";
205 "A choice amongst authentication types, of which one must
206 be enabled (via its associated 'feature') and selected.";
208 if-feature "server-ident-x509-cert";
209 container certificate {
211 "Specifies the server identity using a certificate.";
213 "ks:inline-or-keystore-end-entity-cert-with-key-"
215 refine "inline-or-keystore/inline/inline-definition" {
216 must 'derived-from-or-self(public-key-format,'
217 + ' "ct:subject-public-key-info-format")';
219 refine "inline-or-keystore/keystore/keystore-reference"
220 + "/asymmetric-key" {
221 must 'derived-from-or-self(deref(.)/../ks:public-'
222 + 'key-format, "ct:subject-public-key-info-'
228 case raw-private-key {
229 if-feature "server-ident-raw-public-key";
230 container raw-private-key {
232 "Specifies the server identity using a raw
234 uses ks:inline-or-keystore-asymmetric-key-grouping {
235 refine "inline-or-keystore/inline/inline-definition" {
236 must 'derived-from-or-self(public-key-format,'
237 + ' "ct:subject-public-key-info-format")';
240 "inline-or-keystore/keystore/keystore-reference" {
241 must 'derived-from-or-self(deref(.)/../ks:public-'
242 + 'key-format, "ct:subject-public-key-info-'
249 if-feature "server-ident-tls12-psk";
250 container tls12-psk {
252 "Specifies the server identity using a PSK (pre-shared
253 or pairwise-symmetric key).";
254 uses ks:inline-or-keystore-symmetric-key-grouping;
258 "The key 'psk_identity_hint' value used in the TLS
259 'ServerKeyExchange' message.";
261 "RFC 4279: Pre-Shared Key Ciphersuites for
262 Transport Layer Security (TLS)";
267 if-feature "server-ident-tls13-epsk";
268 container tls13-epsk {
270 "An External Pre-Shared Key (EPSK) is established
271 or provisioned out-of-band, i.e., not from a TLS
272 connection. An EPSK is a tuple of (Base Key,
273 External Identity, Hash). External PSKs MUST
274 NOT be imported for (D)TLS 1.2 or prior versions.
275 When PSKs are provisioned out of band, the PSK
276 identity and the KDF hash algorithm to be used
277 with the PSK MUST also be provisioned.
279 The structure of this container is designed
280 to satisfy the requirements of RFC 8446
281 Section 4.2.11, the recommendations from
282 I-D ietf-tls-external-psk-guidance Section 6,
283 and the EPSK input fields detailed in
284 I-D draft-ietf-tls-external-psk-importer
285 Section 3.1. The base-key is based upon
286 ks:inline-or-keystore-symmetric-key-grouping
287 in order to provide users with flexible and
288 secure storage options.";
290 "RFC 8446: The Transport Layer Security (TLS)
292 I-D.ietf-tls-external-psk-importer: Importing
293 External PSKs for TLS
294 I-D.ietf-tls-external-psk-guidance: Guidance
295 for External PSK Usage in TLS";
296 uses ks:inline-or-keystore-symmetric-key-grouping;
297 leaf external-identity {
301 "As per Section 4.2.11 of RFC 8446, and Section 4.1
302 of I-D. ietf-tls-external-psk-guidance: A sequence
303 of bytes used to identify an EPSK. A label for a
304 pre-shared key established externally.";
306 "RFC 8446: The Transport Layer Security (TLS)
308 I-D.ietf-tls-external-psk-guidance:
309 Guidance for External PSK Usage in TLS";
312 type tlscmn:epsk-supported-hash;
315 "As per Section 4.2.11 of RFC 8446, for externally
316 established PSKs, the Hash algorithm MUST be set
317 when the PSK is established or default to SHA-256
318 if no such algorithm is defined. The server MUST
319 ensure that it selects a compatible PSK (if any)
320 and cipher suite. Each PSK MUST only be used
321 with a single hash function.";
323 "RFC 8446: The Transport Layer Security (TLS)
324 Protocol Version 1.3";
329 "As per Section 4.1 of I-D.
330 ietf-tls-external-psk-guidance: Context
331 may include information about peer roles or
332 identities to mitigate Selfie-style reflection
333 attacks [Selfie]. If the EPSK is a key derived
334 from some other protocol or sequence of protocols,
335 context MUST include a channel binding for the
336 deriving protocols [RFC5056]. The details of
337 this binding are protocol specific.";
339 "I-D.ietf-tls-external-psk-importer:
340 Importing External PSKs for TLS
341 I-D.ietf-tls-external-psk-guidance:
342 Guidance for External PSK Usage in TLS";
344 leaf target-protocol {
347 "As per Section 3.1 of I-D.
348 ietf-tls-external-psk-guidance: The protocol
349 for which a PSK is imported for use.";
351 "I-D.ietf-tls-external-psk-importer:
352 Importing External PSKs for TLS";
357 "As per Section 3.1 of I-D.
358 ietf-tls-external-psk-guidance: The specific Key
359 Derivation Function (KDF) for which a PSK is
362 "I-D.ietf-tls-external-psk-importer:
363 Importing External PSKs for TLS";
368 } // container server-identity
370 container client-authentication {
371 if-feature "client-auth-supported";
372 nacm:default-deny-write;
373 must 'ca-certs or ee-certs or raw-public-keys or tls12-psks
376 "Indicates that client authentication is supported (i.e.,
377 that the server will request clients send certificates).
378 If not configured, the TLS server SHOULD NOT request the
379 TLS clients provide authentication credentials.";
381 "Specifies how the TLS server can authenticate TLS clients.
382 Any combination of credentials is additive and unordered.
384 Note that no configuration is required for PSK (pre-shared
385 or pairwise-symmetric key) based authentication as the key
386 is necessarily the same as configured in the '../server-
389 if-feature "client-auth-x509-cert";
391 "Indicates that CA certificates have been configured.
392 This statement is present so the mandatory descendant
393 nodes do not imply that this node must be configured.";
395 "A set of certificate authority (CA) certificates used by
396 the TLS server to authenticate TLS client certificates.
397 A client certificate is authenticated if it has a valid
398 chain of trust to a configured CA certificate.";
400 "RFC BBBB: A YANG Data Model for a Truststore";
401 uses ts:inline-or-truststore-certs-grouping;
404 if-feature "client-auth-x509-cert";
406 "Indicates that EE certificates have been configured.
407 This statement is present so the mandatory descendant
408 nodes do not imply that this node must be configured.";
410 "A set of client certificates (i.e., end entity
411 certificates) used by the TLS server to authenticate
412 certificates presented by TLS clients. A client
413 certificate is authenticated if it is an exact
414 match to a configured client certificate.";
416 "RFC BBBB: A YANG Data Model for a Truststore";
417 uses ts:inline-or-truststore-certs-grouping;
419 container raw-public-keys {
420 if-feature "client-auth-raw-public-key";
422 "Indicates that raw public keys have been configured.
423 This statement is present so the mandatory descendant
424 nodes do not imply that this node must be configured.";
426 "A set of raw public keys used by the TLS server to
427 authenticate raw public keys presented by the TLS
428 client. A raw public key is authenticated if it
429 is an exact match to a configured raw public key.";
431 "RFC BBBB: A YANG Data Model for a Truststore";
432 uses ts:inline-or-truststore-public-keys-grouping {
433 refine "inline-or-truststore/inline/inline-definition/"
435 must 'derived-from-or-self(public-key-format,'
436 + ' "ct:subject-public-key-info-format")';
438 refine "inline-or-truststore/truststore/truststore-"
440 must 'not(deref(.)/../ts:public-key/ts:public-key-'
441 + 'format[not(derived-from-or-self(., "ct:subject-'
442 + 'public-key-info-format"))])';
447 if-feature "client-auth-tls12-psk";
450 "Indicates that the TLS server can authenticate TLS clients
451 using configured PSKs (pre-shared or pairwise-symmetric
454 No configuration is required since the PSK value is the
455 same as PSK value configured in the 'server-identity'
459 if-feature "client-auth-tls13-epsk";
462 "Indicates that the TLS 1.3 server can authenticate TLS
463 clients using configured external PSKs (pre-shared keys).
465 No configuration is required since the PSK value is the
466 same as PSK value configured in the 'server-identity'
469 } // container client-authentication
471 container hello-params {
472 nacm:default-deny-write;
473 if-feature "tlscmn:hello-params";
474 uses tlscmn:hello-params-grouping;
476 "Configurable parameters for the TLS hello message.";
477 } // container hello-params
479 container keepalives {
480 nacm:default-deny-write;
481 if-feature "tls-server-keepalives";
483 "Configures the keepalive policy for the TLS server.";
484 leaf peer-allowed-to-send {
487 "Indicates that the remote TLS client is allowed to send
488 HeartbeatRequest messages, as defined by RFC 6520
489 to this TLS server.";
491 "RFC 6520: Transport Layer Security (TLS) and Datagram
492 Transport Layer Security (DTLS) Heartbeat Extension";
494 container test-peer-aliveness {
496 "Indicates that the TLS server proactively tests the
497 aliveness of the remote TLS client.";
499 "Configures the keep-alive policy to proactively test
500 the aliveness of the TLS client. An unresponsive
501 TLS client is dropped after approximately max-wait
502 * max-attempts seconds.";
510 "Sets the amount of time in seconds after which if
511 no data has been received from the TLS client, a
512 TLS-level message will be sent to test the
513 aliveness of the TLS client.";
519 "Sets the maximum number of sequential keep-alive
520 messages that can fail to obtain a response from
521 the TLS client before assuming the TLS client is
525 } // container keepalives
526 } // grouping tls-server-grouping