netconfcentral logo

ietf-zerotouch-bootstrap-server@2017-10-19



  module ietf-zerotouch-bootstrap-server {

    yang-version 1.1;

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

    prefix ztbs;

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

    contact
      "WG Web:   <http://tools.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>
     Author:   Kent Watsen <mailto:kwatsen@juniper.net>";

    description
      "This module defines an interface for bootstrap servers, as
     defined by RFC XXXX: Zero Touch Provisioning for NETCONF or
     RESTCONF based Management.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
     'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY',
     and 'OPTIONAL' in the module text are to be interpreted as
     described in RFC 2119.

     Copyright (c) 2017 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 (http://trustee.ietf.org/license-info)

     This version of this YANG module is part of RFC XXXX; see the
     RFC itself for full legal notices.";

    revision "2017-10-19" {
      description "Initial version";
      reference
        "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based
        Management";

    }


    typedef pkcs7 {
      type binary;
      description
        "A PKCS #7 SignedData structure, as specified by Section 9.1
       in RFC 2315, encoded using ASN.1 distinguished encoding rules
       (DER), as specified in ITU-T X.690.";
      reference
        "RFC 2315:
          PKCS #7: Cryptographic Message Syntax Version 1.5.
        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 its RESTCONF
       username, to obtain bootstrapping data that has been made
       available for it.";
      input {
        leaf untrusted-connection {
          type empty;
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server that it is unable
           to authenticate the bootstrap server's TLS certificate.
           In such circumstances, the device likely did not send
           any of the other input parameters.  The bootstrap server
           needs to return either unsigned redirect information or
           signed data.";
        }

        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 IDevID certificate,
           to 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 useful
           to a server that wants to return a response optimized
           for the device, negating, for instance, the need for
           a potentially expensive boot-image update.";
        }

        leaf remote-id {
          type string;
          must "../circuit-id";
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server the 'remote-id'
           value it learned from a DHCP server via Option 82,
           as described in Section 2.0 or RFC 3046.

           This information, along with the circuit-id, enables
           the bootstrap server to return a deployment-specific
           response independent of the device's IDevID identity.";
          reference
            "RFC 3046: DHCP Relay Agent Information Option";

        }

        leaf circuit-id {
          type string;
          must "../remote-id";
          description
            "This optional input parameter enables a device to
           communicate to the bootstrap server the 'circuit-id'
           value it learned from a DHCP server via Option 82,
           as described in Section 2.0 or RFC 3046.

           This information, along with the remote-id, enables
           the bootstrap server to return a deployment-specific
           response independent of the device's IDevID identity.";
          reference
            "RFC 3046: DHCP Relay Agent Information Option";

        }

        leaf nonce {
          type string;
          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
           then dynamically obtain from the manufacturer a
           voucher with the nonce value in it, as described
           in I-D.ietf-anima-voucher.";
          reference
            "RFC ZZZZ: Voucher Profile for Bootstrapping Protocols.";

        }
      }

      output {
        container bootstrapping-data {
          description
            "Top-level node for the bootstrapping data.";
          leaf zerotouch-information {
            type pkcs7;
            mandatory true;
            description
              "A 'zerotouch-information' artifact, as described in
             Section 4.1 of RFC XXXX.  In order to be processed by a
             device, when conveyed over an untrusted transport, the
             PKCS#7 SignedData structure MUST contain a 'signerInfo'
             structure, described in Section 9.1 of RFC 2315,
             containing a signature generated using the private key
             associated with the 'owner-certificate'.";
            reference
              "RFC XXXX: Zero Touch Provisioning for NETCONF or
                 RESTCONF based Management.
               RFC 2315:
                 PKCS #7: Cryptographic Message Syntax Version 1.5";

          }

          leaf owner-certificate {
            type pkcs7;
            must '../ownership-voucher' {
              description
                "An ownership voucher must be present whenever an owner
               certificate is presented.";
            }
            description
              "This PKCS#7 structure MUST contain the owner certificate
             and all intermediate certificates leading up to, and
             optionally including, the trust anchor certificate
             specified in the ownership voucher.  Additionally, if
             needed by the device, this structure MAY also contain
             suitably fresh CRL and/or OCSP Responses with which to
             verify the revocation status of the certificates.

             X.509 certificates and CRLs are described in RFC 5280.
             OCSP Responses are described in RFC 6960.";
            reference
              "RFC 2315:
                PKCS #7: Cryptographic Message Syntax Version 1.5.
               RFC 5280:
                Internet X.509 Public Key Infrastructure Certificate
                and Certificate Revocation List (CRL) Profile.
               RFC 6960:
                X.509 Internet Public Key Infrastructure Online
                Certificate Status Protocol - OCSP.
              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).";

          }

          leaf ownership-voucher {
            type pkcs7;
            must '../owner-certificate' {
              description
                "An owner certificate must be present whenever an
               ownership voucher is presented.";
            }
            description
              "A 'voucher' artifact, as described in Section 5 of
             I-D.ietf-anima-voucher.  The voucher informs the device
             who its owner is.  The voucher encodes the device's
             serial number, so that the device can ensure the
             voucher applies to it.  The voucher is signed by the
             device's manufacturer.";
            reference
              "I-D.ietf-anima-voucher:
                Voucher and Voucher Revocation Profiles for
                Bootstrapping Protocols";

          }
        }  // container bootstrapping-data
      }
    }  // rpc get-bootstrapping-data

    rpc report-progress {
      description
        "This RPC enables a device, as identified by its RESTCONF
       username, to report its bootstrapping progress to the
       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' field
               below MAY contain any additional information that
               the manufacturer thinks might be useful.";
            }
            enum "parsing-warning" {
              value 1;
              description
                "Indicates that the device had a non-fatal error when
               parsing the response from the bootstrap server.  The
               'message' field below SHOULD indicate the specific
               warning that occurred.";
            }
            enum "parsing-error" {
              value 2;
              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, because the
               ownership voucher didn't include the device's
               unique identifier, or because the signature didn't
               match.  The 'message' field below SHOULD indicate
               the specific error.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "boot-image-warning" {
              value 3;
              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' field
               below SHOULD indicate any warning messages that were
               generated.";
            }
            enum "boot-image-error" {
              value 4;
              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' field 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 "pre-script-warning" {
              value 5;
              description
                "Indicates that the device obtained a greater than
               zero exit status code from the script when it was
               executed.  The 'message' field below SHOULD indicate
               both the resulting exit status code, as well as
               capture any stdout/stderr messages the script may
               have produced.";
            }
            enum "pre-script-error" {
              value 6;
              description
                "Indicates that the device obtained a less than
               zero exit status code from the script when it was
               executed.  The 'message' field below SHOULD indicate
               both the resulting exit status code, as well as
               capture any stdout/stderr messages the script may
               have produced.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "config-warning" {
              value 7;
              description
                "Indicates that the device obtained warning messages
               when it committed the initial configuration.  The
               'message' field below SHOULD indicate any warning
               messages that were generated.";
            }
            enum "config-error" {
              value 8;
              description
                "Indicates that the device obtained error messages
               when it committed the initial configuration.  The
               'message' field 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 "post-script-warning" {
              value 9;
              description
                "Indicates that the device obtained a greater than
               zero exit status code from the script when it was
               executed.  The 'message' field below SHOULD indicate
               both the resulting exit status code, as well as
               capture any stdout/stderr messages the script may
               have produced.";
            }
            enum "post-script-error" {
              value 10;
              description
                "Indicates that the device obtained a less than
               zero exit status code from the script when it was
               executed.  The 'message' field below SHOULD indicate
               both the resulting exit status code, as well as
               capture any stdout/stderr messages the script may
               have produced.  This progress type also indicates
               that the device has abandoned trying to bootstrap
               off this bootstrap server.";
            }
            enum "bootstrap-complete" {
              value 11;
              description
                "Indicates that the device successfully processed all
               'onboarding-information' provided, and that it is ready
               to be managed.  The 'message' field 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 12;
              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' field 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 trust anchor certificates 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.";
            leaf format {
              type enumeration {
                enum "ssh-dss" {
                  value 0;
                  description "ssh-dss";
                }
                enum "ssh-rsa" {
                  value 1;
                  description "ssh-rsa";
                }
              }
              mandatory true;
              description
                "The format of the SSH host key.";
            }

            leaf key-data {
              type string;
              mandatory true;
              description
                "The key data for the SSH host key";
            }
          }  // list ssh-host-key
        }  // container ssh-host-keys

        container trust-anchors {
          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).";
          reference
            "RFC 6187:
              X.509v3 Certificates for Secure Shell Authentication.";

          list trust-anchor {
            description "A trust anchor.";
            leaf certificate {
              type pkcs7;
              mandatory true;
              description
                "An X.509 v3 certificate structure, as specified
               by Section 4 in RFC 5280, encoded using ASN.1
               distinguished encoding rules (DER), as specified
               in ITU-T X.690.";
              reference
                "RFC 5280:
                  Internet X.509 Public Key Infrastructure
                  Certificate and Certificate Revocation List (CRL)
                  Profile.
                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).";

            }
          }  // list trust-anchor
        }  // container trust-anchors
      }
    }  // rpc report-progress
  }  // module ietf-zerotouch-bootstrap-server