transport/transport-http/src/main/yang/ietf-http-server@2024-02-08.yang

   1 module ietf-http-server {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-http-server";
   4   prefix https;
   5
   6   import ietf-yang-types {
   7     prefix yang;
   8     reference
   9       "RFC 6991: Common YANG Data Types";
  10   }
  11
  12   import iana-crypt-hash {
  13     prefix ianach;
  14     reference
  15       "RFC 7317: A YANG Data Model for System Management";
  16   }
  17
  18   import ietf-netconf-acm {
  19     prefix nacm;
  20     reference
  21       "RFC 8341: Network Configuration Access Control Model";
  22   }
  23
  24   import ietf-tcp-server {
  25     prefix tcps;
  26     reference
  27       "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers";
  28   }
  29
  30   import ietf-tls-server {
  31     prefix tlss;
  32     reference
  33       "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
  34   }
  35
  36   organization
  37     "IETF NETCONF (Network Configuration) Working Group";
  38
  39   contact
  40     "WG Web:   https://datatracker.ietf.org/wg/netconf
  41      WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  42      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>";
  43
  44   description
  45     "This module defines reusable groupings for HTTP servers that
  46      can be used as a basis for specific HTTP server instances.
  47
  48      Copyright (c) 2024 IETF Trust and the persons identified
  49      as authors of the code. All rights reserved.
  50
  51      Redistribution and use in source and binary forms, with
  52      or without modification, is permitted pursuant to, and
  53      subject to the license terms contained in, the Revised
  54      BSD License set forth in Section 4.c of the IETF Trust's
  55      Legal Provisions Relating to IETF Documents
  56      (https://trustee.ietf.org/license-info).
  57
  58      This version of this YANG module is part of RFC GGGG
  59      (https://www.rfc-editor.org/info/rfcGGGG); see the RFC
  60      itself for full legal notices.
  61
  62      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  63      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  64      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  65      are to be interpreted as described in BCP 14 (RFC 2119)
  66      (RFC 8174) when, and only when, they appear in all
  67      capitals, as shown here.";
  68
  69   revision 2024-02-08 {
  70     description
  71       "Initial version";
  72     reference
  73       "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers";
  74   }
  75
  76   // Features
  77
  78   feature client-auth-supported {
  79     description
  80       "Indicates that the server supports configuring HTTP
  81        servers to authenticate HTTP clients.  HTTP-level client
  82        authentication may not be needed when client authentication
  83        is expected to occur only at another protocol layer (e.g.,
  84        TLS).";
  85   }
  86
  87   feature local-users-supported {
  88     if-feature "client-auth-supported";
  89     description
  90       "Indicates that the server supports configuring client
  91        authentication with its own database of local users, as
  92        opposed to in an application specific location.";
  93   }
  94
  95   feature basic-auth {
  96     if-feature "local-users-supported";
  97     description
  98       "Indicates that the server supports configuring 'basic'
  99        authentication credentials in its local user database.";
 100     reference
 101       "RFC 7617: The 'Basic' HTTP Authentication Scheme";
 102   }
 103
 104   feature tcp-supported {
 105     description
 106       "Indicates that the server supports configuring HTTP
 107        servers to listen for HTTP 1.1/2.0 connections over TCP.";
 108     reference
 109       "RFC 9110: HTTP Semantics";
 110   }
 111
 112   feature tls-supported {
 113     description
 114       "Indicates that the server supports configuring HTTP
 115        servers to listen for HTTP 1.1/2.0 connections over TLS.";
 116     reference
 117       "RFC 9110: HTTP Semantics";
 118   }
 119
 120   // Groupings
 121
 122   grouping http-server-grouping {
 123     description
 124       "A reusable grouping for configuring an HTTP server.
 125
 126        Note that this grouping uses fairly typical descendant
 127        node names such that a stack of 'uses' statements will
 128        have name conflicts.  It is intended that the consuming
 129        data model will resolve the issue (e.g., by wrapping
 130        the 'uses' statement in a container called
 131        'http-server-parameters').  This model purposely does
 132        not do this itself so as to provide maximum flexibility
 133        to consuming models.";
 134
 135     leaf server-name {
 136       nacm:default-deny-write;
 137       type string;
 138       description
 139         "The value of the 'Server' header field.  If not set, then
 140          underlying software's default value is used.  Set to the
 141          empty string to disable.";
 142     }
 143
 144     container client-authentication {
 145       if-feature "client-auth-supported";
 146       nacm:default-deny-write;
 147       presence
 148         "Indicates that HTTP based client authentication is
 149          configured.  This statement is present so the mandatory
 150          descendant nodes do not imply that this node must be
 151          configured.";
 152       description
 153         "Configures how the HTTP server can authenticate HTTP
 154          clients.  The HTTP server will request that the HTTP
 155          client send authentication when needed.";
 156       container users {
 157         if-feature "local-users-supported";
 158         description
 159           "A list of locally configured users.";
 160         list user {
 161           key "user-id";
 162           description
 163             "The list of local users configured on this device.";
 164           leaf user-id {
 165             type string;
 166             description
 167               "The user-id for the authenticating client.";
 168           }
 169           choice auth-type {
 170             mandatory true;
 171             description
 172               "The authentication type.";
 173             case basic {
 174               container basic {
 175                 if-feature "basic-auth";
 176                 leaf username {
 177                   type string;
 178                   description
 179                     "The username for the authenticating HTTP
 180                      client.";
 181                 }
 182                 container password {
 183                   description
 184                     "The hashed password the HTTP server uses to
 185                      authenticate this user.  A user is authenticated
 186                      if the hash of the supplied password matches
 187                      this value.";
 188                   leaf hashed-password {
 189                     type ianach:crypt-hash;
 190                     description
 191                       "The password for the authenticating client.";
 192                   }
 193                   leaf last-modified {
 194                     type yang:date-and-time;
 195                     config false;
 196                     description
 197                       "Identifies when the password was last set.";
 198                   }
 199                 }
 200                 description
 201                   "The 'basic' HTTP scheme credentials.";
 202                 reference
 203                   "RFC 7617:
 204                     The 'Basic' HTTP Authentication Scheme";
 205               }
 206             }
 207           }
 208         }
 209       }
 210     } // container client-authentication
 211   } // grouping http-server-grouping
 212
 213   grouping http-server-stack-grouping {
 214     description
 215       "A grouping that defines common HTTP-based protocol stacks.";
 216     choice transport {
 217       mandatory true;
 218       description
 219         "Choice amongst various transports type.  TCP, with and
 220          without TLS are defined here, with 'feature' statements
 221          so that they may be disabled.  Other transports MAY be
 222          augmented in as 'case' statements by future efforts.";
 223       case tcp {
 224         if-feature "tcp-supported";
 225         container tcp {
 226           description
 227             "Container for TCP-based HTTP protocols.";
 228           container tcp-server-parameters {
 229             description
 230               "TCP-level server parameters to
 231                listen for HTTP connections.";
 232             uses tcps:tcp-server-grouping;
 233           }
 234           container http-server-parameters {
 235             description
 236               "HTTP-level server parameters to
 237                listen for HTTP connections.";
 238             uses http-server-grouping;
 239           }
 240         }
 241       }
 242       case tls {
 243         if-feature "tls-supported";
 244         container tls {
 245           description
 246             "Container for TLS-based HTTP protocols.";
 247           container tcp-server-parameters {
 248             description
 249               "TCP-level server parameters to
 250                listen for HTTPS connections.";
 251             uses tcps:tcp-server-grouping;
 252           }
 253           container tls-server-parameters {
 254             description
 255               "TLS-level server parameters to
 256                listen for HTTPS connections.";
 257             uses tlss:tls-server-grouping;
 258           }
 259           container http-server-parameters {
 260             description
 261               "HTTP-level server parameters to
 262                listen for HTTPS connections.";
 263             uses http-server-grouping;
 264           }
 265         }
 266       }
 267     }
 268   } // http-server-stack-grouping
 269
 270 }