| 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; |
| revision-date 2022-07-18; // stable grouping definitions |
| 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> |
| Author: Gary Wu <mailto:garywu@cisco.com>"; |
| |
| description |
| "This module defines reusable groupings for TLS servers that |
| can be used as a basis for specific TLS server instances. |
| |
| Copyright (c) 2022 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 2022-07-18 { |
| 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 { |
| 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 { |
| 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:local-or-keystore-end-entity-cert-with-key-grouping{ |
| refine "local-or-keystore/local/local-definition" { |
| must 'public-key-format' |
| + ' = "ct:subject-public-key-info-format"'; |
| } |
| refine "local-or-keystore/keystore/keystore-reference" |
| + "/asymmetric-key" { |
| must '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:local-or-keystore-asymmetric-key-grouping { |
| refine "local-or-keystore/local/local-definition" { |
| must 'public-key-format' |
| + ' = "ct:subject-public-key-info-format"'; |
| } |
| refine "local-or-keystore/keystore/keystore-reference"{ |
| must '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:local-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 |
| I-D ietf-tls-external-psk-guidance Section 6, |
| and the EPSK input fields detailed in |
| I-D draft-ietf-tls-external-psk-importer |
| Section 3.1. The base-key is based upon |
| ks:local-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 |
| I-D.ietf-tls-external-psk-importer: Importing |
| External PSKs for TLS |
| I-D.ietf-tls-external-psk-guidance: Guidance |
| for External PSK Usage in TLS"; |
| uses ks:local-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 I-D. ietf-tls-external-psk-guidance: 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 |
| I-D.ietf-tls-external-psk-guidance: |
| Guidance for External PSK Usage in TLS"; |
| } |
| leaf hash { |
| type tlscmn:epsk-supported-hash; |
| mandatory true; |
| 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 |
| "As per Section 4.1 of I-D. |
| ietf-tls-external-psk-guidance: Context |
| may include information about peer roles or |
| identities to mitigate Selfie-style reflection |
| attacks [Selfie]. If the EPSK is a key derived |
| from some other protocol or sequence of protocols, |
| context MUST include a channel binding for the |
| deriving protocols [RFC5056]. The details of |
| this binding are protocol specific."; |
| reference |
| "I-D.ietf-tls-external-psk-importer: |
| Importing External PSKs for TLS |
| I-D.ietf-tls-external-psk-guidance: |
| Guidance for External PSK Usage in TLS"; |
| } |
| leaf target-protocol { |
| type uint16; |
| description |
| "As per Section 3.1 of I-D. |
| ietf-tls-external-psk-guidance: The protocol |
| for which a PSK is imported for use."; |
| reference |
| "I-D.ietf-tls-external-psk-importer: |
| Importing External PSKs for TLS"; |
| } |
| leaf target-kdf { |
| type uint16; |
| description |
| "As per Section 3.1 of I-D. |
| ietf-tls-external-psk-guidance: The specific Key |
| Derivation Function (KDF) for which a PSK is |
| imported for use."; |
| reference |
| "I-D.ietf-tls-external-psk-importer: |
| Importing External PSKs for TLS"; |
| } |
| } |
| } |
| } |
| } // 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:local-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:local-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:local-or-truststore-public-keys-grouping { |
| refine "local-or-truststore/local/local-definition" |
| + "/public-key" { |
| must 'public-key-format' |
| + ' = "ct:subject-public-key-info-format"'; |
| } |
| refine "local-or-truststore/truststore" |
| + "/truststore-reference" { |
| must 'deref(.)/../*/ts:public-key-format' |
| + ' = "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 |
| |
| } |