netconfcentral logo

ietf-sztp-bootstrap-server@2019-04-30



  module ietf-sztp-bootstrap-server {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-sztp-bootstrap-server";

    prefix sztp-svr;

    organization
      "IETF NETCONF (Network Configuration) Working Group";

    contact
      "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>
     Author:   Kent Watsen <mailto:kent+ietf@watsen.net>";

    description
      "This module defines an interface for bootstrap servers, as
     defined by RFC 8572 ('Secure Zero Touch Provisioning (SZTP)').

     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.

     Copyright (c) 2019 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 Simplified 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 8572; see the
     RFC itself for full legal notices.";

    revision "2019-04-30" {
      description "Initial version";
      reference
        "RFC 8572: Secure Zero Touch Provisioning (SZTP)";

    }


    feature redirect-server {
      description
        "The server supports being a 'redirect server'.";
    }

    feature onboarding-server {
      description
        "The server supports being an 'onboarding server'.";
    }

    typedef cms {
      type binary;
      description
        "A CMS structure, as specified in RFC 5652, encoded using
       ASN.1 distinguished encoding rules (DER), as specified in
       ITU-T X.690.";
      reference
        "RFC 5652:
          Cryptographic Message Syntax (CMS)
        ITU-T X.690:
          Information technology - ASN.1 encoding rules:
          Specification of Basic Encoding Rules (BER),
          Canonical Encoding Rules (CER) and Distinguished
          Encoding Rules (DER)";

    }

    rpc get-bootstrapping-data {
      description
        "This RPC enables a device, as identified by the RESTCONF
       username, to obtain bootstrapping data that has been made
       available for it.";
      input {
        leaf signed-data-preferred {
          type empty;
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server that it prefers
           to receive signed data.  Devices SHOULD always send
           this parameter when the bootstrap server is untrusted.
           Upon receiving this input parameter, the bootstrap
           server MUST return either signed data or unsigned
           redirect information; the bootstrap server MUST NOT
           return unsigned onboarding information.";
        }

        leaf hw-model {
          type string;
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server its vendor-specific
           hardware model number.  This parameter may be needed,
           for instance, when a device's IDevID certificate does
           not include the 'hardwareModelName' value in its
           subjectAltName field, as is allowed by 802.1AR.";
          reference
            "IEEE 802.1AR: IEEE Standard for Local and
              metropolitan area networks - Secure
              Device Identity";

        }

        leaf os-name {
          type string;
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server the name of its
           operating system.  This parameter may be useful if
           the device, as identified by its serial number, can
           run more than one type of operating system (e.g.,
           on a white-box system.";
        }

        leaf os-version {
          type string;
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server the version of its
           operating system.  This parameter may be used by a
           bootstrap server to return an operating-system-specific
           response to the device, thus negating the need for a
           potentially expensive boot image update.";
        }

        leaf nonce {
          type binary {
            length "16..32";
          }
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server a nonce value.
           This may be especially useful for devices lacking
           an accurate clock, as then the bootstrap server
           can dynamically obtain from the manufacturer a
           voucher with the nonce value in it, as described
           in RFC 8366.";
          reference
            "RFC 8366:
              A Voucher Artifact for Bootstrapping Protocols";

        }
      }

      output {
        leaf reporting-level {
          if-feature onboarding-server;
          type enumeration {
            enum "minimal" {
              value 0;
              description
                "Send just the progress reports required by RFC 8572.";
              reference
                "RFC 8572: Secure Zero Touch Provisioning (SZTP)";

            }
            enum "verbose" {
              value 1;
              description
                "Send additional progress reports that might help
               troubleshooting an SZTP bootstrapping issue.";
            }
          }
          default "minimal";
          description
            "Specifies the reporting level for progress reports the
           bootstrap server would like to receive when processing
           onboarding information.  Progress reports are not sent
           when processing redirect information or when the
           bootstrap server is untrusted (e.g., device sent the
           '<signed-data-preferred>' input parameter).";
        }

        leaf conveyed-information {
          type cms;
          mandatory true;
          description
            "An SZTP conveyed information artifact, as described in
           Section 3.1 of RFC 8572.";
          reference
            "RFC 8572: Secure Zero Touch Provisioning (SZTP)";

        }

        leaf owner-certificate {
          type cms;
          must '../ownership-voucher' {
            description
              "An ownership voucher must be present whenever an owner
             certificate is presented.";
          }
          description
            "An owner certificate artifact, as described in Section
           3.2 of RFC 8572.  This leaf is optional because it is
           only needed when the conveyed information artifact is
           signed.";
          reference
            "RFC 8572: Secure Zero Touch Provisioning (SZTP)";

        }

        leaf ownership-voucher {
          type cms;
          must '../owner-certificate' {
            description
              "An owner certificate must be present whenever an
             ownership voucher is presented.";
          }
          description
            "An ownership voucher artifact, as described by Section
           3.3 of RFC 8572.  This leaf is optional because it is
           only needed when the conveyed information artifact is
           signed.";
          reference
            "RFC 8572: Secure Zero Touch Provisioning (SZTP)";

        }
      }
    }  // rpc get-bootstrapping-data

    rpc report-progress {
      if-feature onboarding-server;
      description
        "This RPC enables a device, as identified by the RESTCONF
       username, to report its bootstrapping progress to the
       bootstrap server.  This RPC is expected to be used when
       the device obtains onboarding-information from a trusted
       bootstrap server.";
      input {
        leaf progress-type {
          type enumeration {
            enum "bootstrap-initiated" {
              value 0;
              description
                "Indicates that the device just used the
               'get-bootstrapping-data' RPC.  The 'message' node
               below MAY contain any additional information that
               the manufacturer thinks might be useful.";
            }
            enum "parsing-initiated" {
              value 1;
              description
                "Indicates that the device is about to start parsing
               the onboarding information.  This progress type is
               only for when parsing is implemented as a distinct
               step.";
            }
            enum "parsing-warning" {
              value 2;
              description
                "Indicates that the device had a non-fatal error when
               parsing the response from the bootstrap server.  The
               'message' node below SHOULD indicate the specific
               warning that occurred.";
            }
            enum "parsing-error" {
              value 3;
              description
                "Indicates that the device encountered a fatal error
               when parsing the response from the bootstrap server.
               For instance, this could be due to malformed encoding,
               the device expecting signed data when only unsigned
               data is provided, the ownership voucher not listing
               the device's serial number, or because the signature
               didn't match.  The 'message' node below SHOULD
               indicate the specific error.  This progress type
               also indicates that the device has abandoned trying
               to bootstrap off this bootstrap server.";
            }
            enum "parsing-complete" {
              value 4;
              description
                "Indicates that the device successfully completed
               parsing the onboarding information.  This progress
               type is only for when parsing is implemented as a
               distinct step.";
            }
            enum "boot-image-initiated" {
              value 5;
              description
                "Indicates that the device is about to start
               processing the boot image information.";
            }
            enum "boot-image-warning" {
              value 6;
              description
                "Indicates that the device encountered a non-fatal
               error condition when trying to install a boot image.
               A possible reason might include a need to reformat a
               partition causing loss of data.  The 'message' node
               below SHOULD indicate any warning messages that were
               generated.";
            }
            enum "boot-image-error" {
              value 7;
              description
                "Indicates that the device encountered an error when
               trying to install a boot image, which could be for
               reasons such as a file server being unreachable,
               file not found, signature mismatch, etc.  The
               'message' node SHOULD indicate the specific error
               that occurred.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "boot-image-mismatch" {
              value 8;
              description
                "Indicates that the device has determined that
               it is not running the correct boot image.  This
               message SHOULD precipitate trying to download
               a boot image.";
            }
            enum
              "boot-image-installed-rebooting" {
              value 9;
              description
                "Indicates that the device successfully installed
               a new boot image and is about to reboot.  After
               sending this progress type, the device is not
               expected to access the bootstrap server again
               for this bootstrapping attempt.";
            }
            enum "boot-image-complete" {
              value 10;
              description
                "Indicates that the device believes that it is
               running the correct boot image.";
            }
            enum "pre-script-initiated" {
              value 11;
              description
                "Indicates that the device is about to execute the
               'pre-configuration-script'.";
            }
            enum "pre-script-warning" {
              value 12;
              description
                "Indicates that the device obtained a warning from the
               'pre-configuration-script' when it was executed.  The
               'message' node below SHOULD capture any output the
               script produces.";
            }
            enum "pre-script-error" {
              value 13;
              description
                "Indicates that the device obtained an error from the
               'pre-configuration-script' when it was executed.  The
               'message' node below SHOULD capture any output the
               script produces.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "pre-script-complete" {
              value 14;
              description
                "Indicates that the device successfully executed the
               'pre-configuration-script'.";
            }
            enum "config-initiated" {
              value 15;
              description
                "Indicates that the device is about to commit the
               initial configuration.";
            }
            enum "config-warning" {
              value 16;
              description
                "Indicates that the device obtained warning messages
               when it committed the initial configuration.  The
               'message' node below SHOULD indicate any warning
               messages that were generated.";
            }
            enum "config-error" {
              value 17;
              description
                "Indicates that the device obtained error messages
               when it committed the initial configuration.  The
               'message' node below SHOULD indicate the error
               messages that were generated.  This progress type
               also indicates that the device has abandoned trying
               to bootstrap off this bootstrap server.";
            }
            enum "config-complete" {
              value 18;
              description
                "Indicates that the device successfully committed
               the initial configuration.";
            }
            enum "post-script-initiated" {
              value 19;
              description
                "Indicates that the device is about to execute the
               'post-configuration-script'.";
            }
            enum "post-script-warning" {
              value 20;
              description
                "Indicates that the device obtained a warning from the
               'post-configuration-script' when it was executed.  The
               'message' node below SHOULD capture any output the
               script produces.";
            }
            enum "post-script-error" {
              value 21;
              description
                "Indicates that the device obtained an error from the
               'post-configuration-script' when it was executed.  The
               'message' node below SHOULD capture any output the
               script produces.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "post-script-complete" {
              value 22;
              description
                "Indicates that the device successfully executed the
               'post-configuration-script'.";
            }
            enum "bootstrap-warning" {
              value 23;
              description
                "Indicates that a warning condition occurred for which
               no other 'progress-type' enumeration is deemed
               suitable.  The 'message' node below SHOULD describe
               the warning.";
            }
            enum "bootstrap-error" {
              value 24;
              description
                "Indicates that an error condition occurred for which
               no other 'progress-type' enumeration is deemed
               suitable.  The 'message' node below SHOULD describe
               the error.  This progress type also indicates that
               the device has abandoned trying to bootstrap off
               this bootstrap server.";
            }
            enum "bootstrap-complete" {
              value 25;
              description
                "Indicates that the device successfully processed
               all 'onboarding-information' provided and that it
               is ready to be managed.  The 'message' node below
               MAY contain any additional information that the
               manufacturer thinks might be useful.  After sending
               this progress type, the device is not expected to
               access the bootstrap server again.";
            }
            enum "informational" {
              value 26;
              description
                "Indicates any additional information not captured
               by any of the other progress types.  For instance,
               a message indicating that the device is about to
               reboot after having installed a boot image could
               be provided.  The 'message' node below SHOULD
               contain information that the manufacturer thinks
               might be useful.";
            }
          }
          mandatory true;
          description
            "The type of progress report provided.";
        }

        leaf message {
          type string;
          description
            "An optional arbitrary value.";
        }

        container ssh-host-keys {
          when
            "../progress-type = 'bootstrap-complete'" {
            description
              "SSH host keys are only sent when the progress type
             is 'bootstrap-complete'.";
          }
          description
            "A list of SSH host keys an NMS may use to authenticate
           subsequent SSH-based connections to this device (e.g.,
           netconf-ssh, netconf-ch-ssh).";
          list ssh-host-key {
            description
              "An SSH host key an NMS may use to authenticate
             subsequent SSH-based connections to this device
             (e.g., netconf-ssh and netconf-ch-ssh).";
            reference
              "RFC 4253: The Secure Shell (SSH) Transport Layer
              	  Protocol";

            leaf algorithm {
              type string;
              mandatory true;
              description
                "The public key algorithm name for this SSH key.

               Valid values are listed in the 'Public Key Algorithm
               Names' subregistry of the 'Secure Shell (SSH) Protocol
               Parameters' registry maintained by IANA.";
              reference
                "RFC 4250: The Secure Shell (SSH) Protocol Assigned
                	  Numbers
                IANA URL: <https://www.iana.org/assignments/ssh-para\
                	  meters>
                	  ('\' added for formatting reasons)";

            }

            leaf key-data {
              type binary;
              mandatory true;
              description
                "The binary public key data for this SSH key, as
               specified by RFC 4253, Section 6.6; that is:

                 string    certificate or public key format
                           identifier
                 byte[n]   key/certificate data.";
              reference
                "RFC 4253: The Secure Shell (SSH) Transport Layer
                	  Protocol";

            }
          }  // list ssh-host-key
        }  // container ssh-host-keys

        container trust-anchor-certs {
          when
            "../progress-type = 'bootstrap-complete'" {
            description
              "Trust anchors are only sent when the progress type
             is 'bootstrap-complete'.";
          }
          description
            "A list of trust anchor certificates an NMS may use to
           authenticate subsequent certificate-based connections
           to this device (e.g., restconf-tls, netconf-tls, or
           even netconf-ssh with X.509 support from RFC 6187).
           In practice, trust anchors for IDevID certificates do
           not need to be conveyed using this mechanism.";
          reference
            "RFC 6187: X.509v3 Certificates for Secure Shell
            	  Authentication";

          leaf-list trust-anchor-cert {
            type cms;
            description
              "A CMS structure whose topmost content type MUST be the
             signed-data content type, as described by Section 5 of
             RFC 5652.

             The CMS MUST contain the chain of X.509 certificates
             needed to authenticate the certificate presented by
             the device.

             The CMS MUST contain only a single chain of
             certificates.  The last certificate in the chain
             MUST be the issuer for the device's end-entity
             certificate.

             In all cases, the chain MUST include a self-signed
             root certificate.  In the case where the root
             certificate is itself the issuer of the device's
             end-entity certificate, only one certificate is
             present.

             This CMS encodes the degenerate form of the SignedData
             structure that is commonly used to disseminate X.509
             certificates and revocation objects (RFC 5280).";
            reference
              "RFC 5280: Internet X.509 Public Key Infrastructure
              	  Certificate and Certificate Revocation List
              	  (CRL) Profile
               RFC 5652: Cryptographic Message Syntax (CMS)";

          }
        }  // container trust-anchor-certs
      }
    }  // rpc report-progress
  }  // module ietf-sztp-bootstrap-server