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";

        }

        choice msg-type {
          description
            "Messages are mutually exclusive.";
          case csr-support {
            description
              "Indicates how the SZTP-client supports generating CSRs.

If present and a SZTP-server wishes to request the
SZTP-client generate a CSR, the SZTP-server MUST
respond with an HTTP 400 Bad Request error code with an
'ietf-restconf:errors' message having the 'error-tag'
value 'missing-attribute' and the 'error-info' node
containing the 'csr-request' structure described
in this module.";
            container csr-support {
              description
                "Enables a ZTP-client to indicate that it supports
generating certificate signing requests (CSRs) and
provides details about the CSRs it is able to
generate.";
              container key-generation {
                presence
                  "Indicates that the ZTP-client is capable of
generating a new asymmetric key pair.

If this node is not present, the ZTP-server MAY
request a CSR using the asymmetric key associated
with the device's existing identity certificate
(e.g., an IDevID from IEEE 802.1AR).";
                description
                  "Specifies details for the ZTP-client's ability to
generate a new asymmetric key pair.";
                container supported-algorithms {
                  description
                    "A list of public key algorithms supported by the
ZTP-client for generating a new asymmetric key.";
                  leaf-list algorithm-identifier {
                    type binary;
                    min-elements 1;
                    description
                      "An AlgorithmIdentifier, as defined in RFC 2986,
encoded using ASN.1 Distinguished Encoding Rules
(DER), as specified in ITU-T X.690.";
                    reference
                      "RFC 2986: PKCS #10: Certification Request Syntax
                      	  Specification Version 1.7
                      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)";

                  }
                }  // container supported-algorithms
              }  // container key-generation

              container csr-generation {
                description
                  "Specifies details for the ZTP-client's ability to
generate certificate signing requests.";
                container supported-formats {
                  description
                    "A list of certificate request formats supported
by the ZTP-client for generating a new key.";
                  leaf-list format-identifier {
                    type identityref {
                      base zt:certificate-request-format;
                    }
                    min-elements 1;
                    description
                      "A certificate request format supported by the
ZTP-client.";
                  }
                }  // container supported-formats
              }  // container csr-generation
            }  // container csr-support
          }  // case csr-support

          case csr {
            description
              "Provides the CSR generated by the SZTP-client.

When present, the SZTP-server SHOULD respond with
an SZTP onboarding information message containing
a signed certificate for the conveyed CSR.  The
SZTP-server MAY alternatively respond with another
HTTP error containing another 'csr-request'; in
which case, the SZTP-client MUST delete any key
generated for the previously generated CSR.";
            choice csr-type {
              mandatory true;
              description
                "A choice amongst certificate signing request formats.

Additional formats MAY be augmented into this 'choice'
statement by future efforts.";
              leaf p10-csr {
                type ct:p10-csr;
                description
                  "A CertificationRequest structure, per RFC 2986.
Encoding details are defined in the 'ct:csr'
typedef defined in RFC 9640.

A raw P10 does not support origin authentication in
the CSR structure.  External origin authentication
may be provided via the ZTP-client's authentication
to the ZTP-server at the transport layer (e.g., TLS).";
                reference
                  "RFC 2986: PKCS #10: Certification Request Syntax
                  	  Specification Version 1.7
                   RFC 9640: YANG Data Types and Groupings for
                  	  Cryptography";

              }
              leaf cmc-csr {
                type binary;
                description
                  "A profiled version of the 'Full PKI Request'
message defined in RFC 5272, encoded using ASN.1
Distinguished Encoding Rules (DER), as specified
in ITU-T X.690.

For asymmetric-key-based origin authentication of a
CSR based on the initial device identity certificate's
private key for the associated identity certificate's
public key, the PKIData contains one reqSequence
element and no cmsSequence or otherMsgSequence
elements.  The reqSequence is the TaggedRequest,
and it is the tcr CHOICE branch.  The tcr is the
TaggedCertificationRequest, and it is the bodyPartID
and the certificateRequest elements.  The
certificateRequest is signed with the initial device
identity certificate's private key.  The initial device
identity certificate, and optionally its certificate
chain is included in the SignedData certificates that
encapsulate the PKIData.

For asymmetric-key-based origin authentication based on
the initial device identity certificate's private key
that signs the encapsulated CSR signed by the local
device identity certificate's private key, the
PKIData contains one cmsSequence element and no
reqSequence or otherMsgSequence
elements.  The cmsSequence is the TaggedContentInfo,
and it includes a bodyPartID element and a contentInfo.
The contentInfo is a SignedData encapsulating a PKIData
with one reqSequence element and no cmsSequence or
otherMsgSequence elements.  The reqSequence is the
TaggedRequest, and it is the tcr CHOICE.  The tcr is the
TaggedCertificationRequest, and it is the bodyPartID and
the certificateRequest elements.  PKIData contains one
cmsSequence element and no controlSequence, reqSequence,
or otherMsgSequence elements.  The certificateRequest
is signed with the local device identity certificate's
private key.  The initial device identity certificate
and optionally its certificate chain is included in
the SignedData certificates that encapsulate the
PKIData.

For shared-secret-based origin authentication of a
CSR signed by the local device identity certificate's
private key, the PKIData contains one cmsSequence
element and no reqSequence or otherMsgSequence
elements.  The cmsSequence is the TaggedContentInfo,
and it includes a bodyPartID element and a contentInfo.
The contentInfo is an AuthenticatedData encapsulating
a PKIData with one reqSequence element and no
cmsSequences or otherMsgSequence elements.  The
reqSequence is the TaggedRequest, and it is the tcr
CHOICE.  The tcr is the TaggedCertificationRequest,
and it is the bodyPartID and the certificateRequest
elements.  The certificateRequest is signed with the
local device identity certificate's private key.  The
initial device identity certificate and optionally its
certificate chain is included in the SignedData
certificates that encapsulate the PKIData.";
                reference
                  "RFC 5272: Certificate Management over CMS (CMC)
                  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 cmp-csr {
                type binary;
                description
                  "A PKIMessage structure, as defined in RFC 4210,
encoded using ASN.1 Distinguished Encoding Rules
(DER), as specified in ITU-T X.690.

For asymmetric-key-based origin authentication of a
CSR based on the initial device identity certificate's
private key for the associated initial device identity
certificate's public key, PKIMessages contain one
PKIMessage with the header and body elements, do not
contain a protection element, and SHOULD contain the
extraCerts element.  The header element contains the
pvno, sender, and recipient elements.  The pvno contains
cmp2000, and the sender contains the subject of the
initial device identity certificate. The body element
contains an ir, cr, kur, or p10cr CHOICE of type
CertificationRequest.  It is signed with the initial
device identity certificate's private key.  The
extraCerts element contains the initial device identity
certificate, optionally followed by its certificate
chain excluding the trust anchor.

For asymmetric-key-based origin authentication based
on the initial device identity certificate's private
key that signs the encapsulated CSR signed by the local
device identity certificate's private key, PKIMessages
contain one PKIMessage with the header, body, and
protection elements and SHOULD contain the extraCerts
element.  The header element contains the pvno, sender,
recipient, protectionAlg, and optionally senderKID
elements.  The pvno contains cmp2000, the sender
contains the subject of the initial device identity
certificate, the protectionAlg contains the
AlgorithmIdentifier of the used signature algorithm,
and the senderKID contains the subject key identifier
of the initial device identity certificate. The body
element contains an ir, cr, kur, or p10cr CHOICE of
type CertificationRequest.  It is signed with the local
device identity certificate's private key.  The
protection element contains the digital signature
generated with the initial device identity
certificate's private key.  The extraCerts element
contains the initial device identity certificate,
optionally followed by its certificate chain excluding
the trust anchor.

For shared-secret-based origin authentication of a
CSR signed by the local device identity certificate's
private key, PKIMessages contain one PKIMessage with
the header, body, and protection element and no
extraCerts element.  The header element contains the
pvno, sender, recipient, protectionAlg, and senderKID
elements.  The pvno contains cmp2000, the protectionAlg
contains the AlgorithmIdentifier of the used Message
Authentication Code (MAC) algorithm, and the senderKID
contains a reference the recipient can use to identify
the shared secret.  The body element contains an ir, cr,
kur, or p10cr CHOICE of type CertificationRequest.  It
is signed with the local device identity certificate's
private key.  The protection element contains the MAC
value generated with the shared secret.";
                reference
                  "RFC 4210:
                    Internet X.509 Public Key Infrastructure
                    Certificate Management Protocol (CMP)
                  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)";

              }
            }  // choice csr-type
          }  // case csr
        }  // choice msg-type
      }

      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