ietf-voucher.yang

module ietf-voucher {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-voucher";
  prefix vch;

  import ietf-yang-types {
    prefix yang;
    reference "RFC 6991: Common YANG Data Types";
  }

  import ietf-inet-types {
    prefix ietf;
    reference "RFC 6991: Common YANG Data Types";
  }

  import ietf-yang-structure-ext {
    prefix sx;
  }

  organization
    "IETF ANIMA Working Group";
  contact
   "WG Web:   <https://datatracker.ietf.org/wg/anima/>
    WG List:  <mailto:anima@ietf.org>
    Author:   Kent Watsen
              <mailto:kent+ietf@watsen.net>
    Author:   Michael Richardson
              <mailto:mcr+ietf@sandelman.ca>
    Author:   Max Pritikin
              <mailto:pritikin@cisco.com>
    Author:   Toerless Eckert
              <mailto:tte@cs.fau.de>
    Author:   Qiufang Ma
              <mailto:maqiufang1@huawei.com>";

  description
    "This module defines the format for a voucher, which is
     produced by a pledge's manufacturer or delegate (MASA)
     to securely assign a pledge to an 'owner', so that the
     pledge may establish a secure connection to the owner's
     network infrastructure.

     Copyright (c) 2024 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 Revised 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 XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.

RFCEDITOR: please replace XXXX with the RFC number assigned.

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

  revision YYYY-MM-DD {
    description
      "updated to support new assertion enumerated type";
    reference "RFC ZZZZ Voucher Profile for Bootstrapping Protocols";
  }

  // Top-level statement
  sx:structure voucher {
    uses voucher-artifact-grouping;
  }

  // Grouping defined for future augmentations

  grouping voucher-artifact-grouping {
    description
      "Grouping to allow reuse/extensions in future work.";
    container voucher {
      description
        "A voucher assigns a pledge to an owner using
         the (pinned-domain-cert) value.";

      leaf created-on {
        type yang:date-and-time;
        description
          "A value indicating the date this voucher was created.
           This node is primarily for human consumption and auditing.
           Future work MAY create verification requirements based on
           this node.";
      }
      leaf assertion {
        type enumeration {
          enum verified {
            value 0;
            description
              "Indicates that the ownership has been positively
               verified by the MASA (e.g., through sales channel
               integration).";
          }
          enum logged {
            value 1;
            description
              "Indicates that the voucher has been issued after
               minimal verification of ownership or control.  The
               issuance has been logged for detection of
               potential security issues (e.g., recipients of
               vouchers might verify for themselves that unexpected
               vouchers are not in the log).  This is similar to
               unsecured trust-on-first-use principles but with the
               logging providing a basis for detecting unexpected
               events.";
          }
          enum proximity {
            value 2;
            description
              "Indicates that the voucher has been issued after
               the MASA verified a proximity proof provided by the
               device and target domain.  The issuance has been
               logged for detection of potential security issues.";
          }
          enum agent-proximity {
            value 3;
            description
              "Mostly identical to proximity, but
              indicates that the voucher has been issued
              after the MASA has verified a statement that
              a registrar agent has made contact with the device.";
          }
        }
        description
          "The assertion is a statement from the MASA regarding how
           the owner was verified.  This statement enables pledges
           to support more detailed policy checks.  Pledges MUST
           ensure that the assertion provided is acceptable, per
           local policy, before processing the voucher.";
      }
      leaf serial-number {
        type string;
        mandatory true;
        description
          "The serial-number of the hardware.  When processing a
           voucher, a pledge MUST ensure that its serial-number
           matches this value.  If no match occurs, then the
           pledge MUST NOT process this voucher.";
      }
      leaf idevid-issuer {
        type binary;
        description
          "The Authority Key Identifier OCTET STRING (as defined in
           Section 4.2.1.1 of RFC 5280) from the pledge's IDevID
           certificate.  Optional since some serial-numbers are
           already unique within the scope of a MASA.
           Inclusion of the statistically unique key identifier
           ensures statistically unique identification of the
           hardware.
           When processing a voucher, a pledge MUST ensure that its
           IDevID Authority Key Identifier matches this value.  If no
           match occurs, then the pledge MUST NOT process this
           voucher.
           When issuing a voucher, the MASA MUST ensure that this
           field is populated for serial-numbers that are not
           otherwise unique within the scope of the MASA.";
      }
      choice pinning {
        description "One of these attributes is used by the pledge to
                     specify the registrar, and how the pledge would like
                     the registrar's identity to be pinned";
        leaf pinned-domain-cert {
          type binary;
          description
            "An X.509 v3 certificate structure, as specified by
           RFC 5280, using Distinguished Encoding Rules (DER)
           encoding, as defined in ITU-T X.690.

           This certificate is used by a pledge to trust a Public Key
           Infrastructure in order to verify a domain certificate
           supplied to the pledge separately by the bootstrapping
           protocol.  The domain certificate MUST have this
           certificate somewhere in its chain of certificates.
           This certificate MAY be an end-entity certificate,
           including a self-signed entity.";
          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 pinned-domain-pubk {
          type binary;
          description
            "The pinned-domain-pubk may replace the
             pinned-domain-cert in constrained uses of
             the voucher. The pinned-domain-pubk
             is the Raw Public Key of the Registrar.
             This field is encoded as a Subject Public Key Info block
             as specified in RFC7250, in section 3.
             The ECDSA algorithm MUST be supported.
             The EdDSA algorithm as specified in
             draft-ietf-tls-rfc4492bis-17 SHOULD be supported.
             Support for the DSA algorithm is not recommended.
             Support for the RSA algorithm is a MAY.";
        }

        leaf pinned-domain-pubk-sha256 {
          type binary;
          description
            "The pinned-domain-pubk-sha256 is a second
             alternative to pinned-domain-cert.  In many cases the
             public key of the domain has already been transmitted
             during the key agreement process, and it is wasteful
             to transmit the public key another two times.
             The use of a hash of public key info, at 32-bytes for
             sha256 is a significant savings compared to an RSA
             public key, but is only a minor savings compared to
             a 256-bit ECDSA public-key.
             Algorithm agility is provided by extensions to this
             specification which can define a new leaf for another
             hash type.";
        }
      }

      leaf domain-cert-revocation-checks {
        type boolean;
        description
          "A processing instruction to the pledge that it MUST (true)
           or MUST NOT (false) verify the revocation status for the
           pinned domain certificate.  If this field is not set, then
           normal PKIX behavior applies to validation of the domain
           certificate.";
      }
      choice nonceless {
        description "Either a nonce must be present, or an expires-on header";
        leaf expires-on {
          type yang:date-and-time;
          description
            "A value indicating when this voucher expires.  The node is
             optional as not all pledges support expirations, such as
             pledges lacking a reliable clock.

             If this field exists, then the pledges MUST ensure that
             the expires-on time has not yet passed. A pledge without
             an accurate clock cannot meet this requirement.

             The expires-on value MUST NOT exceed the expiration date
             of any of the listed 'pinned-domain-cert' certificates.";
        }
        leaf nonce {
          type binary {
            length "8..32";
          }
          description
            "A value that can be used by a pledge in some bootstrapping
             protocols to enable anti-replay protection.  This node is
             optional because it is not used by all bootstrapping
             protocols.

             When present, the pledge MUST compare the provided nonce
             value with another value that the pledge randomly
             generated and sent to a bootstrap server in an earlier
             bootstrapping message.  If the value is present, but
             the values do not match, then the pledge MUST NOT process
             this voucher.";
        }
      }
      leaf last-renewal-date {
        type yang:date-and-time;
        must '../expires-on';
        description
          "The date that the MASA projects to be the last date it
           will renew a voucher on. This field is merely
           informative; it is not processed by pledges.

           Circumstances may occur after a voucher is generated that
           may alter a voucher's validity period.  For instance,
           a vendor may associate validity periods with support
           contracts, which may be terminated or extended
           over time.";
      }

      // from BRSKI-CLOUD
      leaf est-domain {
        type ietf:uri;
        description
          "The est-domain is a URL from which the Pledge should
             continue doing enrollment rather than with the
             Cloud Registrar.
             The pinned-domain-cert contains a trust-anchor
             which is to be used to authenticate the server
             found at this URI.
            ";
      }
      leaf additional-configuration-url {
        type ietf:uri;
        description
          "The additional-configuration attribute contains a
             URL to which the Pledge can retrieve additional
             configuration information.
             The contents of this URL are manufacturer specific.
             This is intended to do things like configure
             a VoIP phone to point to the correct hosted
             PBX, for example.";
      }
    } // end voucher
  } // end voucher-grouping
}