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:
WG List:
Author: Kent Watsen ";
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)";
}
// features
feature redirect-server {
description
"The server supports being a 'redirect server'.";
}
feature onboarding-server {
description
"The server supports being an 'onboarding server'.";
}
// typedefs
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)";
}
// RPCs
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";
}
}
output {
leaf reporting-level {
if-feature "onboarding-server";
type enumeration {
enum minimal {
description
"Send just the progress reports required by RFC 8572.";
reference
"RFC 8572: Secure Zero Touch Provisioning (SZTP)";
}
enum verbose {
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
'' 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 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 {
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 {
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 {
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 {
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 {
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 {
description
"Indicates that the device is about to start
processing the boot image information.";
}
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' node
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' 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 {
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 {
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 {
description
"Indicates that the device believes that it is
running the correct boot image.";
}
enum pre-script-initiated {
description
"Indicates that the device is about to execute the
'pre-configuration-script'.";
}
enum pre-script-warning {
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 {
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 {
description
"Indicates that the device successfully executed the
'pre-configuration-script'.";
}
enum config-initiated {
description
"Indicates that the device is about to commit the
initial configuration.";
}
enum config-warning {
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 {
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 {
description
"Indicates that the device successfully committed
the initial configuration.";
}
enum post-script-initiated {
description
"Indicates that the device is about to execute the
'post-configuration-script'.";
}
enum post-script-warning {
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 {
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 {
description
"Indicates that the device successfully executed the
'post-configuration-script'.";
}
enum bootstrap-warning {
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 {
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 {
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 {
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:
('\\' 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";
}
}
}
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)";
}
}
}
}
}