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: WG List: Author: Kent Watsen "; 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"; } // typedefs 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)."; } // RPCs 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"; } } } } 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { 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" { description "ssh-dss"; } enum "ssh-rsa" { 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"; } } } 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)."; } } } } } }