module ietf-zerotouch-bootstrap-server {
yang-version "1.1";
namespace
"urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server";
prefix "ztbs";
import ietf-yang-types { // RFC 6991
prefix yang;
}
import ietf-inet-types { // RFC 6991
prefix inet;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web:
WG List:
WG Chair: Mehmet Ersue
WG Chair: Mahesh Jethanandani
Editor: Kent Watsen
";
description
"This module defines the southbound interface for Zero Touch
bootstrap servers.
Copyright (c) 2014 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 "2016-04-06" {
description
"Initial version";
reference
"RFC XXXX: Zero Touch Provisioning for NETCONF Call Home";
}
container devices {
config false;
description
"This is the top-level container for a device-facing protocol.
As such it is read-only, how this data is configured is outside
the scope of this data-model. Further, it is expected that
devices would only be able to access their data and not the
data for any other device.";
list device {
key unique-id;
description
"A device's record entry. This is the only RESTCONF resource
that a device is expected to GET. Getting this just this
top-level provides the device with all the data it needs in
a single request, which is ideal from both a performance and
a resiliency perspectives..";
leaf unique-id {
type string;
description
"A unique identifier for the device (e.g., serial number).
Each device accesses its bootstrapping record by its unique
identifier.";
}
choice type {
description
"This choice statement ensures the response only contains
redirect-information or bootstrap-information.";
container redirect-information {
description
"This is redirect information data. Its purpose is to
redirect the device to another bootstrap server. It
contains a list of bootstrap servers.";
list bootstrap-server {
key address;
description
"A bootstrap server entry.";
leaf address {
type inet:host;
description
"The IP address or hostname of the bootstrap server
the device should redirect to.";
}
leaf port {
type inet:port-number;
default 443;
description
"The port number the bootstrap server listens on.";
}
leaf trust-anchor {
type binary;
mandatory true;
description
"An X.509 v3 certificate structure as specified by RFC
5280, Section 4 encoded using the ASN.1 distinguished
encoding rules (DER), as specified in ITU-T X.690. A
certificate that a device can use as a trust anchor to
authenticate the bootstrap server it is being redirected
to.";
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).";
}
}
}
container bootstrap-information {
description
"This is bootstrap information data. Its purpose is to
provide the device everything it needs to bootstrap
itself.";
container boot-image {
description
"Specifies criteria for the boot image the device MUST be
running.";
container modules {
description
"Specifies a list of YANG modules that the device MUST
support. This node is optional. When this node is
specified, the remaining nodes MUST be processed only
in case the currently running image does not support
any of the YANG modules, as a means to obtain a valid
image. When this node is not specified, then the
device MUST ensure it is running the exact image, as
specified by the remaining 'boot-image' nodes.";
list module {
description
"Specifies a specific YANG modules, by its name and
revision date. The revision date is provided as a
minimal revision date, and supported revision
thereafter is considered sufficient";
leaf name {
type yang:yang-identifier;
description
"The YANG module's name.";
}
leaf revision {
type string {
pattern '\d{4}-\d{2}-\d{2}';
}
description
"Represents a specific date in 2016-04-06 format.";
}
}
}
leaf name {
type string;
mandatory true;
description
"The name of a software image that either the device
MUST be running, or MUST install only if its currently
running image cannot support any of the required YANG
modules.";
}
leaf md5 {
type string;
mandatory true;
description
"The hex-encoded MD5 hash over the boot-image file.";
}
leaf sha1 {
type string;
mandatory true;
description
"The hex-encoded SHA-1 hash over the boot-image file.";
}
leaf-list uri {
type inet:uri;
min-elements 1;
description
"An ordered list of URIs to where the boot-image file
may be obtained. When the bootstrap information is
obtained from a bootstrap server, it is RECOMMENDED
that the list begins with absolute paths (e.g.,
beginning with '/') to the bootstrap server, so as
to leverage the existing secure connection. If remote
URLs are also present in the list, deployments MUST
know in advance which URI schemes (https, http, ftp,
file, etc.) a device supports. If a secure scheme
(e.g., https) is provided, devices MAY blindly accept
the server's credentials (e.g., TLS certificate).
Regardless how obtained, the device MUST ensure that
the boot-image is valid, either by leveraging a
signature embedded in the boot-image itself, if it
exists, or by first comparing the downloaded image to
both the MD5 and SHA1 fingerprints provided above.";
}
}
anyxml configuration { // pyang doesn't support anydata yet!
description
"Any configuration data model known to the device. It may
contain manufacturer-specific and/or standards-based data
models.";
}
leaf script {
type string;
description
"A device specific script that enables the execution of
commands to perform actions not possible thru configuration
alone. The script SHOULD be executed with 'root' level
permissions.
If a script is erroneously provided to a device that
does not support the execution of scripts, the device
SHOULD send a 'script-warning' notification message,
but otherwise continue processing the bootstrapping
data as if the script had not been present.
The script would return exit status code '0' on success
and non-zero on error, with accompanying stderr/stdout
for logging purposes. In the case of an error, the exit
status code will specify what the device should do.
If the exit status code is greater than zero, then the
device should assume that the script had soft failure
that the script believes does not affect manageability.
If the device obtained the bootstrap information from
a bootstrap server, it SHOULD send a 'script-warning'
notification message.
If the exit status code is less than zero, the device
should assume the script had a hard error that the
script believes will affect manageability. In this
case, the device should try to send a 'script-error'
notification message followed by a reset that will
force a new boot-image install (wiping out anything
the script may have done) and restart the entire
bootstrapping process again.";
}
}
}
container owner-certificate {
when "../ownership-voucher" {
description
"The owner certificate is only configurable when there
also exists an ownership voucher.";
}
description
"It is intended that the device will fetch this container
as a whole, as it contains values that need to be
processed together.";
leaf certificate {
type binary;
mandatory true;
description
"An X.509 v3 certificate structure as specified by RFC
5280, Section 4 encoded using the ASN.1 distinguished
encoding rules (DER), as specified in ITU-T X.690.
This certificate, signed by a manufacturer or delegate,
for an owner, must encode a manufacturer-assigned value
identifying the organization. This identifier must match
the owner identifier encoded in the ownership voucher.";
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).";
}
leaf issuer-crl {
type binary;
description
"An CRL structure as specified by RFC 5280, Section 5
encoded using the ASN.1 distinguished encoding rules
(DER), as specified in ITU-T X.690. The CRL for the
CA that signed the owner certificate. The CRL should
be as up to date as possible. This leaf is optional
as it is only needed to support deployments where the
device is unable to download the CRL from and of the
distribution points listed in the owner certificate.";
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).";
}
}
container ownership-voucher {
when "../signature" {
description
"An ownership voucher is only configurable when there
also exists a signature.";
}
must "../owner-certificate" {
description
"An owner certificate must be present whenever an
ownership voucher is present.";
}
description
"This container contains the ownership voucher that the
device uses to ascertain the identity of its rightful
owner, as certified by its manufacturer.";
leaf voucher {
type binary;
mandatory true;
description
"A manufacturer-specific encoding binding unique device
identifiers to an owner identifier value matching the
value encoded in the owner-certificate below.";
}
leaf issuer-vrl {
type binary;
description
"An manufacturer-specific encoding of a voucher revocation
list (VRL) for the issuer used by the manufacturer or
delegate to sign ownership vouchers. The VRL should be
as up to date as possible. This leaf is optional as it
is only needed to support deployments where the device
is unable to download the VRL from the manufacturer or
delegate using some manufacturer-specific mechanism.";
}
}
leaf signature {
type binary;
must "../ownership-voucher" {
description
"An ownership voucher must be present whenever an
signature is present.";
}
description
"A PKCS #7 SignedData structure as specified by RFC
2315, Section 9.1 encoded using the ASN.1 distinguished
encoding rules (DER), as specified in ITU-T X.690.
This signature is generated using the owner's private
private key and an owner-selected digest algorithm over
the redirect-information or the bootstrap-information
nodes, which ever is present, and in whatever encoding
they are presented in (e.g., XML, JSON, etc.).";
// is there a canonical format?
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).";
}
action notification {
input {
leaf notification-type {
type enumeration {
enum bootstrap-initiated {
description
"Indicates that the device has just accessed
the bootstrap server. The 'message' field
below SHOULD contain any additional information
that the manufacturer thinks might be useful,
or omitted entirely.";
}
enum validation-error {
description
"Indicates that the device had an issue validating
the response from the bootstrap server. The
'message' field below SHOULD indicate the specific
error. This message also indicates that the device
has abandoned trying to bootstrap off this bootstrap
server.";
}
enum signature-validation-error {
description
"Indicates that the device had an issue validating
the bootstrapping data. For instance, this could
be due to the device expecting signed data, but
only found unsigned data, or because the ownership
voucher didn't include its unique identifier, or
because the signature didn't match, or and other
relevant error. This 'message' field below SHOULD
indicate the specific error. This message also
indicates that the device has abandoned trying to
bootstrap off this bootstrap server.";
}
enum image-mismatch {
description
"Indicates that the device has determined that
its running image does not meet the specified
criteria. The 'message' field below SHOULD
indicate both what image the device is currently
running as well as the criteria that failed.";
}
enum image-download-error {
description
"Indicates that the device had an issue downloading
the image, which could be anything from the file
server being unreachable to the downloaded file
being the incorrect file (signature mismatch). The
'message' field about SHOULD indicate the specific
error. This message 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 the 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 message also
indicates that the device has abandoned trying to
bootstrap off this bootstrap server.";
}
enum 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 and well as
capture any stdout/stderr messages the script may
have produced.";
}
enum 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 and well as capture any
stdout/stderr messages the script may have produced.
This message also indicates that the device has
abandoned trying to bootstrap off this bootstrap
server.";
}
enum bootstrap-complete {
description
"Indicates that the device successfully processed the
all the bootstrapping data and that it is ready to
be managed. The 'message' field below SHOULD contain
any additional information that the manufacturer
thinks might be useful, or omitted entirely. At
this point, the device is not expected to access
the bootstrap server again.";
}
enum informational {
description
"Provided any additional information not captured by
any of the other notification-type. The 'message'
field below SHOULD contain any additional information
that the manufacturer thinks might be useful, or
omitted entirely.";
}
}
mandatory true;
description
"The type of notification provided.";
}
leaf message {
type string;
description
"An optional human-readable value.";
}
container ssh-host-keys {
description
"A list of SSH host keys an NMS may use to authenticate
a NETCONF connection to the device with.";
list ssh-host-key {
when "../type = bootstrap-complete" {
description
"SSH host keys are only sent when the notification
type is 'bootstrap-complete'.";
}
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 {
description
"A list of trust anchor certificates an NMS may use to
authenticate a NETCONF or RESTCONF connection to the
device with.";
list trust-anchor {
when "../type = bootstrap-complete" {
description
"Trust anchors are only sent when the notification
type is 'bootstrap-complete'.";
}
description
"A list of trust anchor certificates an NMS may use to
authenticate a NETCONF or RESTCONF connection to the
device with.";
leaf-list protocol {
type enumeration {
enum netconf-ssh { description "netconf-ssh"; }
enum netconf-tls { description "netconf-tls"; }
enum restconf-tls { description "restconf-tls"; }
enum netconf-ch-ssh { description "netconf-ch-ssh"; }
enum netconf-ch-tls { description "netconf-ch-tls"; }
enum restconf-ch-tls { description "restconf-ch-tls"; }
}
min-elements 1;
description
"The protocols that this trust anchor secures.";
}
leaf certificate {
type binary;
mandatory true;
description
"An X.509 v3 certificate structure as specified by RFC
5280, Section 4 encoded using the 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).";
}
}
}
}
} // end action
}
}
}