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).";
}
}
}
}
}
}