dtbootstrap-anima-keyinfra.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC7030 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7030.xml">
<!ENTITY RFC5280 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5280.xml">
<!ENTITY RFC5652 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5652.xml">
<!ENTITY RFC7575 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7575.xml">
<!ENTITY RFC7950 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7950.xml">
<!ENTITY RFC7951 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7951.xml">
<!ENTITY RFC3748 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3748.xml">
]>

<rfc category="std" docName="draft-ietf-anima-bootstrapping-keyinfra-45"
    ipr="trust200902">
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

  <?rfc toc="yes" ?>

  <?rfc compact="yes" ?>
  <?rfc consensus="true" ?>
  <?rfc symrefs="yes" ?>

  <?rfc sortrefs="yes"?>

  <?rfc iprnotified="no" ?>

  <?rfc strict="yes" ?>

  <front>
    <title abbrev="BRSKI">Bootstrapping Remote Secure Key Infrastructures
    (BRSKI)</title>

    <author fullname="Max Pritikin" initials="M." surname="Pritikin">
      <organization>Cisco</organization>
      <address>
        <email>pritikin@cisco.com</email>
      </address>
    </author>

    <author fullname="Michael C. Richardson" initials="M."
            surname="Richardson">
      <organization abbrev="Sandelman">Sandelman Software Works</organization>

      <address>
        <email>mcr+ietf@sandelman.ca</email>

        <uri>http://www.sandelman.ca/</uri>
      </address>
    </author>

    <author fullname="Toerless Eckert" initials="T.T.E." surname="Eckert">
        <organization abbrev="Futurewei USA">
                Futurewei Technologies Inc.  USA</organization>
        <address>
                <postal>
                    <street>2330 Central Expy</street>
                    <city>Santa Clara</city>
                    <region>CA</region>
                    <code>95050</code>
                    <country>USA</country>
                </postal>
                <email>tte+ietf@cs.fau.de</email>
        </address>
    </author>

    <author fullname="Michael H. Behringer" initials="M.H."
            surname="Behringer">

      <address>
        <email>Michael.H.Behringer@gmail.com</email>
      </address>
    </author>

    <author fullname="Kent Watsen" initials="K.W." surname="Watsen">
      <organization>Watsen Networks</organization>

      <address>
        <email>kent+ietf@watsen.net</email>
      </address>
    </author>

    <date year="2021" />

    <area>Operations and Management</area>

    <workgroup>ANIMA WG</workgroup>

    <abstract>
      <t>
        This document specifies automated bootstrapping of an Autonomic
        Control Plane.  To do this a Secure Key Infrastructure is
        bootstrapped.  This is done using manufacturer-installed
        X.509 certificates, in combination with a manufacturer's authorizing
        service, both online and offline.  We call this process the
        Bootstrapping Remote Secure Key Infrastructure (BRSKI) protocol.
        Bootstrapping a new device can occur using a routable address and a
        cloud service, or using only link-local connectivity, or on
        limited/disconnected networks. Support for deployment models
        with less stringent security requirements is included.
        Bootstrapping is complete when the cryptographic identity of the new
        key infrastructure is successfully deployed to the device.  The
        established secure connection can be used to deploy a locally issued
        certificate to the device as well.
      </t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>
        The Bootstrapping Remote Secure Key Infrastructure (BRSKI) protocol
        provides a solution for secure zero-touch (automated) bootstrap of
        new (unconfigured) devices that are called pledges in this
        document.  Pledges have an IDevID installed in them at the factory.
      </t>
      <t>
        "BRSKI" is pronounced like "brewski", a colloquial term for beer in
        Canada and parts of the US-midwest. <xref target="brewski" />
      </t>

      <t>
        This document primarily provides for the needs of
        the ISP and Enterprise focused ANIMA
        <xref target="I-D.ietf-anima-autonomic-control-plane">Autonomic
        Control Plane (ACP)</xref>.  This bootstrap process satisfies
        the <xref target="RFC7575" /> requirements of section 3.3 of making all operations
        secure by default.  Other users of the BRSKI protocol
        will need to provide separate applicability statements that
        include privacy and security considerations appropriate to that
        deployment.  <xref target="acpapplicability" /> explains the detailed
        applicability for this the ACP usage.
      </t>
      <t>
        The BRSKI protocol requires a significant amount of communication
        between manufacturer and owner: in its default modes it provides a
        cryptographic transfer of control to the initial owner.  In its
        strongest modes, it leverages sales channel information to identify
        the owner in advance.  Resale of devices is possible, provided that
        the manufacturer is willing to authorize the transfer.  Mechanisms
        to enable transfers of ownership without manufacturer authorization
        are not included in this version of the protocol, but could be
        designed into future versions.
      </t>

      <t>
        This document describes how pledges discover (or are discovered by) an
        element of the network domain to which the pledge belongs that will perform
        the bootstrap.  This element (device) is called the
        registrar.  Before any other operation, pledge and registrar need to
        establish mutual trust:
      </t>

      <t><list style="numbers">
          <t>Registrar authenticating the pledge: "Who is this device? What is
          its identity?"</t>

          <t>Registrar authorizing the pledge: "Is it mine? Do I want it?
          What are the chances it has been compromised?"</t>

          <t>Pledge authenticating the registrar: "What is this
          registrar's identity?"</t>

          <t>Pledge authorizing the registrar: "Should I join this network?"</t>
        </list></t>

        <t>
          This document details protocols and messages to answer the above questions.
          It uses a TLS connection and an PKIX-shaped (X.509v3) certificate (an IEEE
          802.1AR <xref target="IDevID" /> IDevID) of the pledge to answer
          points 1 and 2.
          It uses a new artifact called a "voucher" that the registrar
          receives from a "Manufacturer Authorized Signing Authority" (MASA) and
          passes to the pledge to answer points 3 and 4.
        </t>
        <t>
          A proxy provides very limited connectivity between the pledge and
          the registrar.
        </t>


      <t>The syntactic details of vouchers are described in detail in <xref
      target="RFC8366" />. This document details automated
      protocol mechanisms to obtain vouchers, including the definition
      of a 'voucher-request' message that is a minor extension
      to the voucher format (see <xref target="voucher-request" />) defined
      by <xref target="RFC8366" />.</t>

     <t>BRSKI results in the pledge storing an X.509 root
    certificate sufficient for verifying the registrar identity. In the
    process a TLS connection is established that can be directly used for
    Enrollment over Secure Transport (EST). In effect BRSKI provides
    an automated mechanism for the "Bootstrap Distribution of CA Certificates"
    described in <xref target="RFC7030"></xref> Section 4.1.1 wherein
    the pledge "MUST [...] engage a human user to authorize the CA certificate using
    out-of-band" information. With BRSKI the pledge now can automate
    this process using the voucher. Integration with a complete EST
    enrollment is optional but trivial.</t>

      <t>BRSKI is agile enough to support
      bootstrapping alternative key infrastructures, such as a symmetric key
      solutions, but no such system is described in this document.</t>

      <section title="Prior Bootstrapping Approaches">

         <t>To literally "pull yourself up by the bootstraps" is an impossible
        action. Similarly the secure establishment of a key infrastructure
        without external help is also an impossibility. Today it is commonly
        accepted that the initial connections between nodes are insecure, until
        key distribution is complete, or that domain-specific keying material
        (often pre-shared keys, including mechanisms like SIM cards)
        is pre-provisioned on each new device in a costly and non-scalable
        manner. Existing automated mechanisms are known as non-secured 'Trust on
        First Use' (TOFU) <xref target="RFC7435" />, 'resurrecting duckling'
        <xref target="Stajano99theresurrecting" /> or 'pre-staging'.</t>

        <t>Another prior approach has been to try and
        minimize user actions during bootstrapping, but not eliminate all
        user-actions.
        The original EST protocol <xref
        target="RFC7030"></xref> does reduce user actions during bootstrap
        but does not provide solutions for how the following protocol steps
        can be made autonomic (not involving user actions):
        </t>

          <t><list style="symbols">
              <t>using the Implicit Trust Anchor <xref target="RFC7030" /> database to authenticate
                an owner specific service (not an autonomic solution because
                the URL must be securely distributed),</t>

              <t>engaging a human user to authorize the CA certificate using
                  out-of-band data (not an autonomic solution because the human user
                  is involved),</t>

              <t>using a configured Explicit TA database (not an autonomic
                  solution because the distribution of an explicit TA database is
                  not autonomic),</t>

              <t>and using a Certificate-Less TLS mutual authentication method
                  (not an autonomic solution because the distribution of symmetric
                  key material is not autonomic).
              </t>
            </list>
            These "touch" methods do not meet the requirements for
            zero-touch.
          </t>

          <t>There are "call home" technologies where the pledge first
              establishes a connection to a well known manufacturer service using a common
              client-server authentication model. After mutual authentication,
              appropriate credentials to authenticate the target domain are
              transferred to the pledge. This creates several problems and
              limitations:</t>

          <t><list style="symbols">
              <t>the pledge requires realtime connectivity to the manufacturer
                  service,</t>

              <t>the domain identity is exposed to the manufacturer service (this is a
                  privacy concern),</t>

              <t>the manufacturer is responsible for making the authorization
                  decisions (this is a liability concern),</t>
          </list></t>

         <t>BRSKI addresses these issues by defining extensions to the EST protocol
             for the automated distribution of vouchers.
         </t>
      </section>

      <section title="Terminology">
        <t>
          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 <xref target="RFC2119"></xref>
          <xref target="RFC8174"></xref> when, and only when, they
          appear in all capitals, as shown here.
        </t>

        <t>The following terms are defined for clarity:</t>

        <t><list style="hanging">
            <t hangText="ANI:">The Autonomic Network Infrastructure as
            defined by <xref target="I-D.ietf-anima-reference-model" />.
            <xref target="acpapplicability" /> details specific requirements for pledges,
            proxies and registrars when they are part of an ANI.</t>

            <t hangText="Circuit Proxy:">A stateful implementation
              of the join proxy. This is the assumed type of proxy.</t>

            <t hangText="drop-ship:">The physical distribution of equipment
            containing the "factory default" configuration to a final
            destination. In zero-touch scenarios there is no staging or
            pre-configuration during drop-ship.</t>

            <t hangText="Domain:">The set of entities that share a common local
            trust anchor. This includes the proxy, registrar,
            Domain Certificate Authority, Management components and any
            existing entity that is already a member of the domain.</t>

            <t hangText="domainID:">The domain IDentity is a unique value
            based upon the Registrar CA's certificate.
            <xref target="domainID" /> specifies how it is calculated.
            </t>

            <t hangText="Domain CA:">The domain Certification Authority (CA)
            provides certification functionalities to the domain. At a minimum
            it provides certification functionalities to a registrar and
            manages the private key that defines the domain. Optionally, it
            certifies all elements.</t>

            <t hangText="enrollment:">The process where a device presents key
            material to a network and acquires a network-specific identity.
            For example when a certificate signing request is presented to a
            certification authority and a certificate is obtained in
            response.</t>

            <t hangText="imprint:">The process where a device obtains the
            cryptographic key material to identify and trust future
            interactions with a network. This term is taken from Konrad
            Lorenz's work in biology with new ducklings: during a critical
            period, the duckling would assume that anything that looks like a
            mother duck is in fact their mother. An equivalent for a device is
            to obtain the fingerprint of the network's root certification
            authority certificate. A device that imprints on an attacker
            suffers a similar fate to a duckling that imprints on a hungry
            wolf. Securely imprinting is a primary focus of this
            document <xref target="imprinting"></xref>. The analogy to
            Lorenz's work was first noted in <xref
            target="Stajano99theresurrecting"></xref>.</t>

            <t hangText="IDevID:">An Initial Device Identity X.509 certificate
            installed by the vendor on new equipment. This is a term from
            802.1AR <xref target="IDevID" /></t>

            <t hangText="IPIP Proxy:">A stateless proxy alternative.</t>

            <t hangText="Join Proxy:">A domain entity that helps the pledge join
            the domain. A join proxy facilitates communication for devices that
            find themselves in an environment where they are not provided
            connectivity until after they are validated as members of the
            domain. For simplicity this document sometimes uses the
            term of 'proxy' to indicate the join proxy. The pledge
            is unaware that they are communicating with a
            proxy rather than directly with a registrar.</t>

            <t hangText="Join Registrar (and Coordinator):">A representative of the domain that is
            configured, perhaps autonomically, to decide whether a new device
            is allowed to join the domain. The administrator of the domain
            interfaces with a "join registrar (and coordinator)" to control this process. Typically a
            join registrar is "inside" its domain. For simplicity this document
            often refers to this as just "registrar". Within <xref target="I-D.ietf-anima-reference-model" /> this is
            referred to as the "join registrar autonomic service agent".
            Other communities use the abbreviation "JRC".
            </t>

            <t hangText="LDevID:">A Local Device Identity X.509 certificate
            installed by the owner of the equipment. This is a term from
            802.1AR <xref target="IDevID" /></t>

            <t hangText="manufacturer:">the term manufacturer is used
            throughout this document to be the entity that created the
            device.  This is typically the "original equipment manufacturer"
            or OEM, but in more complex situations it could be a "value added
            retailer" (VAR), or possibly even a systems integrator.  In
            general, it a goal of BRSKI to eliminate small distinctions
            between different sales channels.  The reason for this is
            that it permits a single device, with a uniform firmware load, to
            be shipped directly to all customers.  This eliminates costs
            for the manufacturer.  This also reduces the number of products
            supported in the field increasing the chance that firmware will
            be more up to date.
            </t>

            <t hangText="MASA Audit-Log:">An anonymized list of previous owners
            maintained by the MASA on a per device (per pledge)
            basis. Described in <xref target="MASAauditlog" />.
            </t>

            <t hangText="MASA Service:">A third-party Manufacturer Authorized
            Signing Authority (MASA) service on the global Internet. The MASA
            signs vouchers. It also provides a repository for audit-log
            information of privacy protected bootstrapping events. It does
            not track ownership. </t>

            <t hangText="nonced:">a voucher (or request) that contains a nonce (the normal
            case).</t>

            <t hangText="nonceless:">a voucher (or request) that does not
            contain a nonce, relying upon accurate clocks for expiration, or
            which does not expire.</t>

            <t hangText="offline:">When an architectural component cannot
              perform realtime communications with a peer, either due to
              network connectivity or because the peer is turned off, the
              operation is said to be occurring offline.</t>

            <t hangText="Ownership Tracker:">An Ownership Tracker service on
            the global Internet. The Ownership Tracker uses business processes
            to accurately track ownership of all devices shipped against
            domains that have purchased them. Although optional, this component
            allows vendors to provide additional value in cases where their
            sales and distribution channels allow for accurate tracking of
            such ownership. Ownership tracking information is indicated in
            vouchers as described in <xref target="RFC8366"/></t>

            <t hangText="Pledge:">The prospective (unconfigured) device, which has an
            identity installed at the factory.</t>

            <t hangText="(Public) Key Infrastructure:"> The collection of systems and
            processes that sustain the activities of a public key system.
            The registrar acts as an
            <xref target="RFC5280" /> and <xref target="RFC5272" /> (see
              section 7) "Registration Authority".</t>

            <t hangText="TOFU:">Trust on First Use. Used similarly to <xref
            target="RFC7435" />. This is where a pledge
            device makes no security decisions but rather simply trusts the
            first registrar it is contacted by. This is also known as the
            "resurrecting duckling" model.</t>

            <t hangText="Voucher:">A signed artifact from the MASA
            that indicates to a pledge the cryptographic identity of the
            registrar it should trust. There are different types of vouchers
            depending on how that trust is asserted. Multiple voucher types are
            defined in <xref target="RFC8366" /></t>

          </list>
          </t>
      </section>

      <section title="Scope of solution">
        <section title="Support environment">
        <t>
          This solution (BRSKI) can support large router
        platforms with multi-gigabit inter-connections, mounted in controlled
        access data centers. But this solution is not exclusive to large equipment:
        it is intended to scale to thousands of devices located in hostile
        environments, such as ISP provided CPE devices which are drop-shipped
        to the end user. The situation where an order is fulfilled from
        distributed warehouse from a common stock and shipped directly to the
        target location at the request of a domain owner is explicitly
        supported. That stock ("SKU") could be provided to a number of
        potential domain owners, and the eventual domain owner will not know
        a-priori which device will go to which location.
        </t>

        <t>
          The bootstrapping process can take minutes to complete depending on
          the network infrastructure and device processing speed. The network
          communication itself is not optimized for speed; for privacy reasons,
          the discovery process allows for the pledge to avoid announcing its
          presence through broadcasting.
        </t>
        <t>
          Nomadic or mobile devices often need to acquire credentials to
          access the network at the new location.  An example of this is
          mobile phone roaming among network operators, or even between
          cell towers.  This is usually called handoff.
          BRSKI does not provide a low-latency handoff which is usually a
          requirement in such situations.
          For these solutions BRSKI can be used to create a relationship
          (an LDevID) with the "home" domain owner. The resulting credentials
          are then used to provide credentials more appropriate for a
          low-latency handoff.
        </t>
        </section>

        <section title="Constrained environments">
        <t>Questions have been posed as to whether this solution is suitable
        in general for Internet of Things (IoT) networks. This depends on the
        capabilities of the devices in question. The terminology of <xref
        target="RFC7228"></xref> is best used to describe the boundaries.</t>

        <t>The solution described in this document is aimed in general at
        non-constrained (i.e., class 2+ <xref target="RFC7228" />) devices operating on a non-Challenged
        network. The entire solution as described here is not intended to be
        useable as-is by constrained devices operating on challenged networks
        (such as 802.15.4 Low-power Lossy Networks (LLN)s).</t>


        <t>Specifically, there are protocol aspects described here that might
        result in congestion collapse or energy-exhaustion of intermediate
        battery powered routers in an LLN. Those types of networks should not
        use this solution. These limitations are predominately related to the
        large credential and key sizes required for device authentication.
        Defining symmetric key techniques that meet the operational
        requirements is out-of-scope but the underlying protocol operations
        (TLS handshake and signing structures) have sufficient algorithm
        agility to support such techniques when defined.</t>

        <t>The imprint protocol described here could, however, be used by
        non-energy constrained devices joining a non-constrained network (for
        instance, smart light bulbs are usually mains powered, and speak
        802.11). It could also be used by non-constrained devices across a
        non-energy constrained, but challenged network (such as 802.15.4). The
        certificate contents, and the process by which the four
        questions above are resolved do apply to constrained devices. It is
        simply the actual on-the-wire imprint protocol that could be
        inappropriate.</t>

        </section>

        <section title="Network Access Controls">
        <t>This document presumes that network access control has either
        already occurred, is not required, or is integrated by the proxy
        and registrar in such a way that the device itself does not need to
        be aware of the details. Although the use of an X.509 Initial
        Device Identity is consistent with IEEE 802.1AR <xref
        target="IDevID"></xref>, and allows for alignment with 802.1X
        network access control methods, its use here is for pledge
        authentication rather than network access control. Integrating
        this protocol with network access control, perhaps as an
        Extensible Authentication Protocol (EAP) method
        (see <xref target="RFC3748"></xref>), is out-of-scope.</t>
        </section>

        <section title="Bootstrapping is not Booting">
        <t>This document describes "bootstrapping" as the protocol
        used to obtain a local trust anchor. It is expected that this
        trust anchor, along with any additional configuration
        information subsequently installed, is persisted on the device
        across system restarts ("booting"). Bootstrapping occurs only
        infrequently such as when a device is transferred to a new
        owner or has been reset to factory default settings.</t>
        </section>
      </section>

      <section anchor="PostEnrollment"
               title="Leveraging the new key infrastructure / next steps">

        <t>
          As a result of the protocol described herein, the bootstrapped devices
          have the Domain CA trust anchor in common. An end entity certificate has
          optionally been issued from the Domain CA. This makes it possible
          to securely deploy functionalities across the domain, e.g:<list style="symbols">
            <t>Device management.</t>
            <t>Routing authentication.</t>
            <t>Service discovery.</t>
          </list>
        </t>

        <t>
          The major intended benefit is that it possible to use the credentials
          deployed by this protocol to secure the Autonomic Control Plane
          (ACP) (<xref target="I-D.ietf-anima-autonomic-control-plane" />).
        </t>
      </section>

      <section anchor="ANIrequirements"
               title="Requirements for Autonomic Network Infrastructure (ANI) devices">
        <t>
          The BRSKI protocol can be used in a number of environments. Some of
          the options in this document are the result of requirements that
          are out of the ANI scope.  This section defines the base
          requirements for ANI devices.
        </t>
        <t>
          For devices that intend to become part of an Autonomic Network
          Infrastructure (ANI)
          (<xref target="I-D.ietf-anima-reference-model" />) that includes an
          Autonomic Control Plane
          (<xref target="I-D.ietf-anima-autonomic-control-plane" />), the
          BRSKI protocol MUST be implemented.
        </t>
        <t>
          The pledge must perform discovery of the proxy as described in
          <xref target="discovery" /> using Generic Autonomic Signaling
          Protocol (GRASP)'s DULL <xref target="I-D.ietf-anima-grasp" />
          M_FLOOD announcements.
        </t>
        <t>
          Upon successfully validating a voucher artifact, a status telemetry
          MUST be returned. See <xref target="pledgestatus" />.
        </t>
        <t>
          An ANIMA ANI pledge MUST implement the EST automation
          extensions described in <xref target="ESTintegration" />.
          They supplement the <xref target="RFC7030" /> EST to better
          support automated devices that do not have an end user.
        </t>
        <t>
          The ANI Join Registrar Autonomic Service Agent (ASA) MUST support all the BRSKI and above listed
          EST operations.
        </t>
        <t>
          All ANI devices SHOULD support the BRSKI proxy function, using
          circuit proxies over the ACP. (See <xref target="JRCgrasp" />)
        </t>

      </section>

    </section>

    <section title="Architectural Overview">
      <t>The logical elements of the bootstrapping framework are described in
      this section. <xref target="architecturefigure" /> provides a simplified overview of the components.
      </t>

      <figure anchor="architecturefigure" title="Architecture Overview">
INSERT_FIG_FROM_FILE component-diagram.txt END
      </figure>

      <t>We assume a multi-vendor network. In such an environment there could
      be a Manufacturer Service for each manufacturer that supports devices following this
      document's specification, or an integrator could provide a generic
      service authorized by multiple manufacturers. It is unlikely that an
      integrator could provide Ownership Tracking services for multiple
      manufacturers due to the required sales channel integrations necessary to
      track ownership.</t>

      <t>The domain is the managed network infrastructure with a Key Infrastructure the pledge is
      joining. The domain provides initial device connectivity
      sufficient for bootstrapping through a proxy. The domain
      registrar authenticates the pledge, makes authorization decisions, and distributes
      vouchers obtained from the Manufacturer Service. Optionally the registrar
      also acts as a PKI Certification Authority.</t>

      <section title="Behavior of a Pledge">
        <t>The pledge goes through a series of steps, which are outlined here
        at a high level.</t>

      <figure anchor="pledgestatusfigure" title="Pledge State Diagram">
<artwork><![CDATA[
               ------------
              /  Factory   \
              \  default   /
               -----+------
                    |
             +------v-------+
             | (1) Discover |
+------------>              |
|            +------+-------+
|                   |
|            +------v-------+
|            | (2) Identify |
^------------+              |
| rejected   +------+-------+
|                   |
|            +------v-------+
|            | (3) Request  |
|            |     Join     |
|            +------+-------+
|                   |
|            +------v-------+
|            | (4) Imprint  |
^------------+              |
| Bad MASA   +------+-------+
| response          |  send Voucher Status Telemetry
|            +------v-------+
|            | (5) Enroll   |<---+ (non-error HTTP codes  )
^------------+              |\___/ (e.g. 202 'Retry-After')
| Enroll     +------+-------+
| Failure           |
|              -----v------
|             /  Enrolled  \
^------------+             |
 Factory      \------------/
 reset

]]></artwork>
        </figure>

        <t>State descriptions for the pledge are as follows:</t>

        <t><list style="numbers">
            <t>Discover a communication channel to a registrar.</t>

            <t>Identify itself. This is done by presenting an X.509 IDevID
                credential to the discovered registrar (via the proxy) in a TLS
                handshake. (The registrar credentials are only provisionally
                accepted at this time).</t>

            <t>Request to join the discovered registrar. A unique nonce is
                included ensuring that any responses can be associated with this
                particular bootstrapping attempt.</t>

            <t>Imprint on the registrar. This requires verification of the
                manufacturer-service-provided voucher. A voucher contains sufficient
                information for the pledge to complete authentication of a
                registrar.  This document details this step in depth.
            </t>

            <t>Enroll. After imprint an authenticated TLS (HTTPS) connection exists
            between pledge and registrar.
            Enrollment over Secure Transport (EST) <xref
            target="RFC7030"></xref> can then be used to obtain a domain
            certificate from a registrar.</t>

        </list></t>

        <t>
          The pledge is now a member of, and can be managed by, the
          domain and will only repeat the discovery aspects of bootstrapping
          if it is returned to factory default settings.
        </t>

        <t>
          This specification details integration with EST enrollment so that pledges can
          optionally obtain a locally issued certificate, although any
          Representational State Transfer (REST) (see <xref target="REST" />)
          interface could be integrated in future work.
        </t>

      </section>

      <section title="Secure Imprinting using Vouchers">
        <t>A voucher is a cryptographically protected artifact (using a digital signature) to the pledge
        device authorizing a zero-touch imprint on the registrar
        domain. </t>

        <t>The format and cryptographic mechanism of vouchers is described in
        detail in <xref target="RFC8366" />.</t>

        <t>Vouchers provide a flexible mechanism to secure imprinting: the
        pledge device only imprints when a voucher can be validated.
        At the lowest security levels the MASA can indiscriminately issue
        vouchers and log claims of ownership by domains.  At the highest security
        levels issuance of vouchers can be integrated with complex sales channel
        integrations that are beyond the scope of this document. The sales
        channel integration would verify actual (legal) ownership of the
        pledge by the domain.
            This
            provides the flexibility for a number of use cases via a single
            common protocol mechanism on the pledge and registrar devices that
            are to be widely deployed in the field. The MASA services have
            the flexibility to leverage either the currently defined claim
            mechanisms or to experiment with higher or lower security levels.
        </t>

        <t>
          Vouchers provide a signed but non-encrypted communication channel among
          the pledge, the MASA, and the registrar. The registrar maintains
          control over the transport and policy decisions, allowing the
          local security policy of the domain network to be enforced.
        </t>

      </section>

      <section anchor="IDevIDextension" title="Initial Device Identifier">
        <t>
          Pledge authentication and pledge voucher-request signing is via
          a PKIX-shaped certificate installed
          during the manufacturing process. This is the 802.1AR Initial
          Device Identifier (IDevID), and it
          provides a basis for authenticating the pledge during
          the protocol exchanges described here.
          There is no requirement for a common root PKI hierarchy.
          Each device manufacturer can generate its own root certificate.
          Specifically, the IDevID enables:
          <list style="numbers">
            <t>
              Uniquely identifying the pledge by the Distinguished Name (DN)
              and subjectAltName (SAN) parameters in the IDevID. The
              unique identification of a pledge in the voucher objects are derived
              from those parameters as described below. <xref
              target="idevidprivacy" /> discusses privacy implications of the identifier.
            </t>
            <t>
              Provides a cryptographic authentication of the pledge to the
              Registrar (see <xref target="pledgeauthorization" />).
            </t>
            <t>
              Secure auto-discovery of the pledge's MASA by the registrar
              (see <xref target="obtainmasaurl" />).
            </t>
            <t>
              Signing of voucher-request by the pledge's IDevID
              (see <xref target="voucher-request" />).
            </t>
            <t>
              Provides a cryptographic authentication of the pledge to the
              MASA (see <xref target="MASAassertion" />).
            </t>
          </list>
        </t>
        <t>
          Section 7.2.13 (2009 edition) and section 8.10.3 (2018 edition) of
          <xref target="IDevID" /> discusses keyUsage and
          extendedKeyUsage extensions in the IDevID certificate.
          <xref target="IDevID" /> acknowledges that adding restrictions
          in the certificate limits applicability of these long-lived
          certificates.  This specification emphasizes this point, and
          therefore RECOMMENDS that no key usage restrictions be included.
          This is consistent with <xref target="RFC5280" /> section 4.2.1.3,
          which does not
          require key usage restrictions for end entity certificates.
        </t>

        <section anchor="PledgeIdentification"
                 title="Identification of the Pledge">
          <t>
            In the context of BRSKI, pledges have a 1:1 relationship
            with a "serial-number".
            This serial-number is used both in the "serial-number"
            field of voucher or voucher-requests (see <xref target="voucher-request" />)
            and in local policies on registrar or MASA
            (see <xref target="ProtocolDetails" />).
          </t>

          <t>
            There is a (certificate) serialNumber field is defined in <xref
            target="RFC5280" /> section 4.1.2.2.  In the ASN.1, this is
            referred to as the CertificateSerialNumber.  This field is NOT
            relevant to this specification.  Do not confuse this field with
            the "serial-number" defined by this document, or by
            <xref target="IDevID" /> and <xref target="RFC4519" /> section
            2.31.
          </t>

          <t>
            The device serial number is defined in <xref target="RFC5280" />
            section A.1 and A.2 as the X520SerialNumber, with the OID tag
            id-at-serialNumber.
          </t>
          <t>
            The device serial number field (X520SerialNumber) is used as
            follows by the pledge to build the "serial-number" that is placed
            in the voucher-request.
            In order to build it, the fields need to be converted into a
            serial-number of "type string".
          </t>
          <t>
            An example of a printable form of the "serialNumber" field
            is provided in <xref target="RFC4519" /> section 2.31 ("WI-3005").
            That section further provides equality and syntax attributes.
          </t>
          <t>
            Due to the reality of existing device identity provisioning
            processes, some manufacturers have stored serial-numbers in other
            fields. Registrar's SHOULD be configurable, on a per-manufacturer
            basis, to look for serial-number equivalents in other fields.
          </t>
          <t>
            As explained in <xref target="RequestVoucherFromMASA" /> the Registrar MUST extract the
            serial-number again itself from the pledge's TLS certificate.  It
            can consult the serial-number in the pledge-request if there are
            any possible confusion about the source of the serial-number.
          </t>

        </section>

        <section anchor="MASAURL"
                 title="MASA URI extension">

          <t>
            This document defines a new PKIX non-critical certificate
            extension to carry the MASA URI.
            This extension is intended to be used in the IDevID certificate.
            The URI is represented as described in Section 7.4 of <xref target="RFC5280" />.
          </t>

          <t>
            The URI provides the authority information.
            The BRSKI "/.well-known" tree (<xref target="RFC5785" />) is
            described in <xref target="ProtocolDetails"></xref>.
          </t>

          <t>
            A complete URI MAY be in this extension, including the 'scheme', 'authority', and 'path',
            The complete URI will typically be used in diagnostic or
            experimental situations.
            Typically, (and in consideration to constrained systems), this
            SHOULD be reduced to only the 'authority', in which
            case a scheme of "https://"
            (<xref target="RFC7230" /> section 2.7.3)
            and 'path' of "/.well-known/brski" is to be
            assumed.
          </t>
          <t>
            The registrar can assume that only the 'authority' is present in
            the extension, if there are no slash ("/") characters in the
            extension.
          </t>
          <t>
            Section 7.4 of <xref target="RFC5280" /> calls out various
            schemes that MUST be supported, including LDAP, HTTP and FTP.
            However, the registrar MUST use HTTPS for the BRSKI-MASA connection.
          </t>

          <t>The new extension is identified as follows:</t>

      <figure anchor="masaurlmodule" title="MASAURL ASN.1 Module">
            <artwork><![CDATA[
<CODE BEGINS>

MASAURLExtnModule-2016 { iso(1) identified-organization(3) dod(6)
internet(1) security(5) mechanisms(5) pkix(7)
id-mod(0) id-mod-MASAURLExtn2016(TBD) }

DEFINITIONS IMPLICIT TAGS ::= BEGIN

-- EXPORTS ALL --

IMPORTS
EXTENSION
FROM PKIX-CommonTypes-2009
  { iso(1) identified-organization(3) dod(6) internet(1)
    security(5) mechanisms(5) pkix(7) id-mod(0)
    id-mod-pkixCommon-02(57) }

id-pe FROM PKIX1Explicit-2009
  { iso(1) identified-organization(3) dod(6) internet(1)
     security(5) mechanisms(5) pkix(7) id-mod(0)
     id-mod-pkix1-explicit-02(51) } ;

MASACertExtensions EXTENSION ::= { ext-MASAURL, ... }
ext-MASAURL EXTENSION ::= { SYNTAX MASAURLSyntax
IDENTIFIED BY id-pe-masa-url }

id-pe-masa-url OBJECT IDENTIFIER ::= { id-pe TBD }

MASAURLSyntax ::= IA5String

END

<CODE ENDS>
]]></artwork>
          </figure>

          <t>The choice of id-pe is based on guidance found in Section 4.2.2 of
          [RFC5280], "These extensions may be used to direct applications to on-line
          information about the issuer or the subject". The MASA URL is precisely
          that: online information about the particular subject. </t>
        </section>

      </section>

    <section anchor="flow" title="Protocol Flow">
        <t>A representative flow is shown in
        <xref target="protocoltimesequencefigure" /></t>

        <figure anchor="protocoltimesequencefigure" title="Protocol Time Sequence Diagram">
INSERT_FIG_FROM_FILE time-sequence-diagram.txt END
        </figure>

        <t>
          On initial bootstrap, a new device (the pledge) uses a local service
          autodiscovery (GRASP or mDNS) to locate a join proxy.  The
          join proxy connects the pledge to a local registrar (the JRC).
        </t>
        <t>
          Having found a candidate registrar, the fledgling pledge sends
          some information about itself to the registrar, including its
          serial number in the form of a voucher request and its device identity
          certificate (IDevID) as part of the TLS session.
        </t>
        <t>
          The registrar can determine whether it expected such a device to
          appear, and locates a MASA.  The location of the MASA is usually found in
          an extension in the IDevID.  Having determined that the MASA is
          suitable, the entire information from the initial voucher request
          (including device serial number) is transmitted over the internet in a
          TLS protected channel to the manufacturer, along with information about
          the registrar/owner.
        </t>
        <t>
          The manufacturer can then apply policy based on the provided
          information, as well as other sources of information (such as sales
          records), to decide whether
          to approve the claim  by the registrar to own the device; if the claim
          is accepted, a voucher is issued that directs the device to accept its
          new owner.
        </t>
        <t>
          The voucher is returned to the registrar, but not immediately to
          the device -- the registrar has an opportunity to examine the
          voucher, the MASA's audit-logs, and other sources of information to
          determine whether the device has been tampered with, and whether
          the bootstrap should be accepted.
        </t>
        <t>
          No filtering of information is possible in the signed voucher, so
          this is a binary yes-or-no decision.  If the registrar accepts
          the voucher as a proper one for its device, the voucher is returned
          to the pledge for imprinting.
        </t>
        <t>
          The voucher also includes a trust anchor that the pledge uses as
          representing the owner.  This is used to successfully bootstrap from an environment
          where only the manufacturer has built-in trust by the
          device into an environment where the owner now has a PKI footprint on the
          device.
        </t>
        <t>
          When BRSKI is followed with EST this single footprint is further
          leveraged into the full owner's PKI and a LDevID for the
          device. Subsequent reporting steps provide flows of  information to
          indicate success/failure of the process.
        </t>

    </section>
    <section title="Architectural Components">
        <section anchor="pledge-overview" title="Pledge">
          <t>
            The pledge is the device that is attempting to join.
            The pledge is assumed to talk to the Join Proxy using link-local network
            connectivity.  In most cases, the pledge has no other
            connectivity until the pledge completes the enrollment process
            and receives some kind of network credential.
          </t>
        </section>
        <section anchor="proxy-overview" title="Join Proxy">
          <t>
            The join proxy provides HTTPS connectivity between the
            pledge and the registrar. A circuit proxy mechanism is
            described in <xref target="proxydetails" />. Additional
            mechanisms, including a CoAP mechanism and a stateless
            IPIP mechanism are the subject of future work.
          </t>
        </section>
        <section anchor="registrar-overview" title="Domain Registrar">
          <t>
            The domain's registrar operates as the BRSKI-MASA client when
            requesting vouchers from the MASA (see <xref
            target="brskimasatls" />). The registrar
            operates as the BRSKI-EST server when pledges request
            vouchers (see <xref target="brskiesttls" />). The registrar operates as the BRSKI-EST server
            "Registration Authority" if the pledge requests an end entity certificate
          over the BRSKI-EST connection (see <xref target="ESTintegration"
          />).
          </t>
          <t>
            The registrar uses an Implicit Trust Anchor database for
            authenticating the BRSKI-MASA connection's MASA TLS Server Certificate.
            Configuration or distribution of trust anchors is out-of-scope
            for this specification.
          </t>

          <t>
            The registrar uses a different Implicit Trust Anchor database for
            authenticating the BRSKI-EST connection's Pledge TLS Client Certificate.
            Configuration or distribution of the BRSKI-EST client trust
            anchors is out-of-scope of this specification.  Note that the
            trust anchors
            in/excluded from the database will affect which manufacturers' devices are
            acceptable to the registrar as pledges, and can also be used to limit the
            set of MASAs that are trusted for enrollment.
          </t>
        </section>
        <section anchor="masa-overview" title="Manufacturer Service">
          <t>
            The Manufacturer Service provides two logically separate functions:
            the Manufacturer Authorized Signing Authority (MASA) described in
            <xref target="RequestVoucherFromMASA" /> and
            <xref target="VoucherResponse" />,
            and an ownership tracking/auditing function described
            in <xref target="pledgestatus" />
            and <xref target="authzLogRequest" />.
          </t>
        </section>

        <section anchor="pki-overview"
                 title="Public Key Infrastructure (PKI)">
          <t>
            The Public Key Infrastructure (PKI) administers certificates for the
            domain of concern, providing the trust anchor(s) for it and
            allowing enrollment of pledges with domain certificates.
          </t>
          <t>
            The voucher provides a method for the distribution of a
            single PKI trust anchor (as the "pinned-domain-cert"). A distribution
            of the full set of current trust anchors is possible using the
            optional EST integration.
          </t>
          <t>
            The domain's registrar acts as an <xref target="RFC5272" />
            Registration Authority, requesting certificates for pledges from
            the Key Infrastructure.
          </t>
          <t>
            The expectations of the PKI are unchanged from EST <xref target="RFC7030" />.  This document does
            not place any additional architectural requirements on the Public Key
            Infrastructure.
          </t>
        </section>
      </section>

      <section anchor="certificatevalidaty" title="Certificate Time Validation">
        <section anchor="timeunknown" title="Lack of realtime clock">
          <t>
            Many devices when bootstrapping do not have knowledge of the
            current time. Mechanisms such as Network Time Protocols cannot be
            secured until bootstrapping is complete. Therefore bootstrapping is
            defined with a framework that does not require knowledge of the current
            time.  A pledge MAY ignore all time stamps in the voucher and
            in the certificate validity periods if it does not know
            the current time.
          </t>

          <t>
            The pledge is exposed to dates in the following five places:
            registrar certificate notBefore, registrar certificate
            notAfter,
            voucher created-on, and voucher expires-on.
            Additionally, CMS signatures contain a signingTime.
          </t>

          <t>
            A pledge with a real time clock in which it has confidence,
            MUST check the above time fields in all certificates and
            signatures that it processes.
          </t>

          <t>
            If the voucher contains a nonce
            then the pledge MUST confirm the nonce matches the original
            pledge voucher-request. This ensures the voucher is fresh.
            See <xref target="RequestVoucherFromRegistrar" />.
          </t>
        </section>
        <section anchor="infinitelifetime"
                 title="Infinite Lifetime of IDevID">
          <t>
            <xref target="RFC5280" /> explains that
            long lived pledge certificates "SHOULD be assigned the
            GeneralizedTime value of 99991231235959Z" for the notAfter field.
          </t>
          <t>
            Some deployed IDevID management systems are not compliant
            with the 802.1AR requirement for infinite lifetimes, and
            put in typical &lt;= 3 year certificate lifetimes.
            Registrars SHOULD be configurable on a per-manufacturer basis
            to ignore pledge lifetimes when the pledge did not follow the RFC5280
            recommendations.
          </t>
        </section>
      </section>
      <section anchor="cloudregistrar" title="Cloud Registrar">
        <t>
          There exist operationally open networks wherein devices gain
          unauthenticated access to the Internet at large.
          In these use cases the
          management domain for the device needs to be discovered within the
          larger Internet. The case where a device can boot and get access to
          larger Internet are less likely within the ANIMA ACP scope but may
          be more important in the future.  In the ANIMA ACP scope, new
          devices will be quarantined behind a Join Proxy.
        </t>

        <t>
          There are additionally some greenfield situations involving an
          entirely new installation where a device may have some kind of
          management uplink that it can use (such as via 3G network for
          instance).   In such a future situation, the device might use
          this management interface to learn that it should
          configure itself to become the local registrar.
        </t>
        <t>
          In order to support these scenarios, the pledge MAY contact a well
          known URI of a cloud registrar if a
              local registrar cannot be discovered or if the pledge's target use
              cases do not include a local registrar.</t>
          <t>If the pledge uses a well known URI for contacting a cloud registrar
              a manufacturer-assigned Implicit Trust Anchor database (see <xref target="RFC7030"/>) MUST
              be used to authenticate that service as described in <xref
              target="RFC6125" />.  The use of a DNS-ID for validation is
              appropriate, and it may include wildcard components on the
              left-mode side. This is
              consistent with the human user configuration of an EST server URI in
              <xref target="RFC7030"/> which also depends on RFC6125.</t>
      </section>
      <section title="Determining the MASA to contact" anchor="obtainmasaurl">
          <t>The registrar needs to be able to contact a MASA that is trusted by the pledge in order to obtain vouchers. There are three mechanisms described:</t>

        <t>The device's Initial Device Identifier (IDevID) will normally contain the MASA URL as detailed in <xref target="IDevIDextension"></xref>. This is the RECOMMENDED
            mechanism.</t>

        <t>It can be operationally difficult to ensure the necessary X.509 extensions are in the pledge's IDevID due to the difficulty of aligning current pledge manufacturing with software releases and development. As a final fallback the registrar MAY be manually configured or distributed with a MASA URL for each manufacturer. Note that the registrar can only select the configured MASA URL based on the trust anchor -- so manufacturers can only leverage this approach if they ensure a single MASA URL works for all pledges associated with each trust anchor.</t>

      </section>
    </section>

    <section title="Voucher-Request artifact" anchor="voucher-request">

      <t>
        Voucher-requests are how vouchers are requested.
        The semantics of the voucher-request are described below, in the YANG model.
      </t>

      <t>
        A pledge forms the "pledge voucher-request", signs it with it's
        IDevID and submits it to the registrar.
      </t>

      <t>
        The registrar in turn forms the "registrar voucher-request",
        signs it with it's Registrar keypair and submits it to the MASA.
      </t>

      <t>
        The "proximity-registrar-cert" leaf is used in the pledge
        voucher-requests. This provides a method for the pledge to
        assert the registrar's proximity.
      </t>
      <t>
        This network proximity results from the following properties in the
        ACP context:  the pledge is connected to the Join Proxy
        (<xref target="proxydetails" />) using a Link-Local IPv6 connection.
        While the Join Proxy does not participate in any meaningful sense in
        the cryptography of the TLS connection (such as via a Channel
        Binding), the Registrar can observe that the connection is via the
        private ACP (ULA) address of the join proxy, and could not come from
        outside the ACP.  The Pledge must therefore be at most one IPv6
        Link-Local hop away from an existing node on the ACP.
      </t>
      <t>
        Other users of BRSKI will need to define other kinds of assertions if
        the network proximity described above does not match their needs.
      </t>
      <t>
        The "prior-signed-voucher-request" leaf is used in registrar
        voucher-requests. If present, it is the signed pledge voucher-request
        artifact. This provides a method for
        the registrar to forward the pledge's signed request to the
        MASA. This completes transmission of the signed
        "proximity-registrar-cert" leaf.
      </t>
      <t>
        Unless otherwise signaled (outside the voucher-request artifact), the
        signing structure is as defined for vouchers, see
        <xref target="RFC8366"/>.
      </t>

        <section title="Nonceless Voucher Requests" anchor="noncelessVoucherRequest">
          <t>
            A registrar MAY also retrieve nonceless vouchers by sending
            nonceless voucher-requests to the MASA in order to obtain
            vouchers for use when the registrar does not have connectivity to the
            MASA.
            No "prior-signed-voucher-request" leaf
            would be included.  The registrar will also need to know the serial number of
            the pledge. This document does not provide a mechanism for the
            registrar to learn that in an automated fashion. Typically this will
            be done via scanning of bar-code or QR-code on packaging, or via
            some sales channel integration.
          </t>
        </section>

        <section title="Tree Diagram" anchor="voucher-request-tree-diagram">
            <t>The following tree diagram illustrates a high-level view of a
                voucher-request document.  The voucher-request builds upon
                the voucher artifact described in <xref target="RFC8366" />.
                The tree diagram is described in <xref target="RFC8340" />.
                Each node in the diagram is
                fully described by the YANG module in <xref target="voucher-request-yang-module"/>.
                Please review the YANG module for a detailed description of the
                voucher-request format.</t>

<figure anchor="voucherrequest_tree" title="YANG Tree diagram for Voucher-Request">
INSERT_CODE_FROM_FILE ietf-voucher-request-tree.txt END
</figure>

        </section> <!-- tree diagram -->

        <section title="Examples" anchor="voucher-request-examples">
            <t>This section provides voucher-request examples for illustration
                purposes.
                These examples show the JSON prior to CMS wrapping.
                JSON encoding rules specify that any binary
                content be base64 encoded (<xref target="RFC4648" /> section 4).
                The contents of the (base64) encoded certificates have been elided
                to save space. For detailed examples, see <xref
                target="exampleprocess" />. These examples conform to the encoding rules
                defined in <xref target="RFC7951"/>.</t>

            <t><list style="format Example (%d)" counter="examples"><t>The following example illustrates a pledge voucher-request. The
            assertion leaf is indicated as 'proximity' and the registrar's TLS server
            certificate is included in the 'proximity-registrar-cert' leaf. See
            <xref target="RequestVoucherFromRegistrar"/>.</t></list></t>

<figure anchor="voucherrequest_example1"
        title="JSON representation of example Voucher-Request">
INSERT_CODE_FROM_FILE refs/ex-file-voucher-request-proximity.json END
</figure>

            <t><list style="format Example (%d)" counter="examples"><t>The following example illustrates a registrar voucher-request.
                The 'prior-signed-voucher-request' leaf is populated with the pledge's
                voucher-request (such as the prior example).  The pledge's
                voucher-request is a binary CMS signed object.  In the JSON encoding used
                here it must be base64 encoded. The nonce and
                assertion have been carried forward from the pledge request to
                the registrar request.
                The serial-number is extracted from
                the pledge's Client Certificate from the TLS connection. See
                <xref target="RequestVoucherFromMASA"/>.</t></list></t>
<figure anchor="voucherrequest_prior_example1"
        title="JSON representation of example Prior-Signed Voucher-Request">
INSERT_CODE_FROM_FILE refs/ex-file-voucher-request-prior.json END
</figure>

            <t><list style="format Example (%d)" counter="examples"><t>The following example illustrates a registrar voucher-request.
                The 'prior-signed-voucher-request' leaf is not populated with the pledge's
                voucher-request nor is the nonce leaf. This form might be used by a
                registrar requesting a voucher when the pledge can not
                communicate with the registrar (such as when it is powered
                down, or still in packaging),
                and therefore could not submit a nonce.
                This scenario is most useful when the registrar is aware that
                it will not be able to reach the MASA during deployment.
                See
                <xref target="RequestVoucherFromMASA"/>.</t></list></t>
<figure anchor="voucherrequest_offline_example1"
        title="JSON representation of Offline Voucher-Request">
INSERT_CODE_FROM_FILE refs/ex-file-voucher-request-offline.json END
</figure>
        </section>  <!-- examples -->

        <section title="YANG Module" anchor="voucher-request-yang-module">

          <t>Following is a YANG <xref target="RFC7950"/> module formally
          extending the <xref target="RFC8366" /> voucher into
          a voucher-request.</t>

<figure anchor="voucherrequest_yang"
        title="YANG module for Voucher-Request">
INSERT_CODE_FROM_FILE ietf-voucher-request@DATE.yang END
</figure>

</section>  <!-- yang module -->
    </section>   <!-- voucher-request artifact -->
    <section anchor="proxydetails" title="Proxying details (Pledge - Proxy -
                                          Registrar)">
      <t>
        This section is normative for uses with an ANIMA ACP.
        The use of the GRASP mechanism is part of the ACP.
        Other users of BRSKI will need to define an equivalent proxy
        mechanism, and an equivalent mechanism to configure the proxy.
      </t>
      <t>
        The role of the proxy is to facilitate communications. The proxy
        forwards packets between the pledge and a registrar that has been
        provisioned to the proxy via full GRASP ACP discovery.
      </t>
      <t>
        This section defines a stateful proxy mechanism which is referred
        to as a "circuit" proxy.  This is a form of Application Level Gateway
        (<xref target="RFC2663" /> section 2.9).
      </t>

      <t>
        The proxy does not terminate the TLS handshake: it passes streams
        of bytes onward without examination.
        A proxy MUST NOT assume any specific TLS version.  Please see
        <xref target="RFC8446" /> section 9.3 for details on TLS invariants.
      </t>

      <t>
        A Registrar can directly provide the proxy announcements
        described below, in which case the
        announced port can point directly to the Registrar itself.  In this
        scenario the pledge is unaware that there is no proxying occurring.
        This is useful for Registrars which are servicing pledges on directly
        connected networks.
      </t>


      <t>
        As a result of the proxy Discovery process in <xref target="brskigrasp" />,
        the port number exposed by the proxy
        does not need to be well known, or require an IANA allocation.
      </t>

      <t>
        During the discovery of the Registrar by the Join Proxy, the
        Join Proxy will also learn which kinds of proxy mechanisms are
        available.  This will allow the Join Proxy to use the lowest impact
        mechanism which the Join Proxy and Registrar have in common.
      </t>

      <t>
        In order to permit the proxy functionality to be implemented on the
        maximum variety of devices the chosen mechanism should use the minimum
        amount of state on the proxy device. While many devices in the ANIMA
        target space will be rather large routers, the proxy function is
        likely to be implemented in the control plane CPU of such a device,
        with available capabilities for the proxy function similar to many
        class 2 IoT devices.
      </t>

      <t>
        The document <xref
        target="I-D.richardson-anima-state-for-joinrouter"></xref> provides a
        more extensive analysis and background of the alternative proxy methods.
      </t>
        <section anchor="discovery" title="Pledge discovery of Proxy">
            <t>
              The result of discovery is a logical communication with a
              registrar, through a proxy.
              The proxy is transparent to the pledge.  The communication
              between the pledge and Join Proxy is over IPv6 Link-Local addresses.
            </t>

            <t>To discover the proxy the pledge performs the following
                actions:</t>

            <t><list style="numbers">
                <t>MUST: Obtains a local address using IPv6
                    methods as described in <xref target="RFC4862"></xref> IPv6
                    Stateless Address AutoConfiguration.
                    Use of <xref target="RFC4941" /> temporary addresses is
                    encouraged.  To limit pervasive monitoring (
                    <xref target="RFC7258" />), a new temporary address MAY
                    use a short lifetime (that is, set TEMP_PREFERRED_LIFETIME
                    to be short).
                    Pledges will generally prefer use of IPv6 Link-Local
                    addresses, and discovery of proxy will be by Link-Local
                    mechanisms.
                    IPv4 methods are described in <xref target="IPv4operations" /></t>

                <t>MUST: Listen for GRASP M_FLOOD
                    (<xref target="I-D.ietf-anima-grasp" />)
                    announcements of the objective: "AN_Proxy".
                    See section <xref target="brskigrasp" /> for the details of
                    the objective.  The pledge MAY listen concurrently for
                    other sources of information, see <xref target="mdnsmethods" />.
                </t>
            </list>

            Once a proxy is
            discovered the pledge communicates with a registrar through the
            proxy using the bootstrapping protocol defined in <xref
                target="ProtocolDetails"></xref>.
            </t>

            <t>
              While the GRASP M_FLOOD mechanism is passive for the pledge, the
              non-normative other methods (mDNS, and IPv4 methods) described in
              <xref target="mdnsmethods" /> are active.
              The pledge SHOULD run those methods in parallel with listening
              to for the M_FLOOD.  The active methods SHOULD
              back-off by doubling to a maximum of one hour to avoid overloading the
              network with discovery attempts.  Detection of change of
              physical link status (Ethernet carrier for instance) SHOULD
              reset the back off timers.
            </t>

            <t>
              The pledge could discover more than one proxy on a given physical
              interface.  The pledge can have a multitude of physical
              interfaces as well: a layer-2/3 Ethernet switch may have
              hundreds of physical ports.
            </t>

            <t>
              Each possible proxy offer SHOULD be attempted up to the point
              where a valid voucher is received: while there are many ways in which
              the attempt may fail, it does not succeed until the voucher has
              been validated.
            </t>

            <t>
              The connection attempts via a single proxy SHOULD exponentially
              back-off to a maximum of one hour to avoid overloading the network
              infrastructure.   The back-off timer for each  MUST be
              independent of other connection attempts.
            </t>

            <t>
                Connection attempts SHOULD be run in
                parallel to avoid head of queue problems wherein an attacker
                running a fake proxy or registrar could perform protocol
                actions intentionally slowly.  Connection attempts to
                different proxies SHOULD be sent with an interval of 3 to
                5s. The pledge SHOULD continue to
                listen to for additional GRASP M_FLOOD messages during
                the connection attempts.
            </t>
            <t>
              Each connection attempt through a distinct Join Proxy MUST
              have a unique nonce in the voucher-request.
            </t>
            <t>
              Once a connection to a
              registrar is established (e.g. establishment of a TLS session key)
              there are expectations of more timely responses, see <xref
              target="RequestVoucherFromRegistrar"></xref>.
            </t>

            <t>
              Once all discovered services are attempted (assuming that none
              succeeded) the device MUST return to listening for GRASP M_FLOOD.
              It SHOULD periodically retry any manufacturer-specific mechanisms.
              The pledge MAY prioritize selection order as
              appropriate for the anticipated environment.
            </t>

            <section anchor="brskigrasp" title="Proxy GRASP announcements">
              <t>
               A proxy uses the DULL GRASP M_FLOOD mechanism to announce
               itself.
               This announcement can be within the same message as the ACP
               announcement detailed in
               <xref target="I-D.ietf-anima-autonomic-control-plane" />.

             </t>

             <t>
               The formal Concise Data Definition Language (CDDL) <xref target="RFC8610"/> definition is:
<figure anchor="proxy_discovery_cddl"
        title="CDDL definition of Proxy Discovery message">
INSERT_CODE_FROM_FILE proxygrasp.cddl END
</figure>
             </t>

             <t>
               Here is an example M_FLOOD announcing a proxy at fe80::1,
               on TCP port 4443.
<figure anchor="proxy_discovery_mflood"
        title="Example of Proxy Discovery message">
INSERT_CODE_FROM_FILE proxygrasp-example.txt END
</figure>
            </t>
             <t>
               On a small network the Registrar MAY include the GRASP
               M_FLOOD announcements to locally connected networks.
             </t>

             <t>
               The $transport-proto above indicates the method that the
               pledge-proxy-registrar will use.  The TCP method described
               here is mandatory, and other proxy methods, such as CoAP
               methods not defined in this document are optional. Other
               methods MUST NOT be enabled unless the Join Registrar ASA
               indicates support for them in it's own announcement.
             </t>

            </section>

        </section>
      <section anchor="coapconnection" title="CoAP connection to Registrar">
        <t>
          The use of CoAP to connect from pledge to registrar
          is out of scope for this document, and is described in future
          work. See <xref target="I-D.ietf-anima-constrained-voucher" />.
        </t>
      </section>


      <section title="Proxy discovery and communication of Registrar" anchor="JRCgrasp">
        <t> The registrar SHOULD announce itself so that proxies can find it
        and determine what kind of connections can be terminated.
        </t>
        <t>
          The registrar announces itself using ACP instance of GRASP using
          M_FLOOD messages, with the "AN_join_registrar" objective.
          A registrar may announce any convenient port
          number, including using a stock port 443.
          ANI proxies MUST support GRASP discovery of registrars.
        </t>
        <t>
          The M_FLOOD is formatted as follows:
<figure anchor="registrar_discovery_example1"
        title="An example of a Registrar announcement message">
INSERT_CODE_FROM_FILE jrcgrasp-example.txt END
        </figure>
        </t>
        <t>
          The formal CDDL definition is:
<figure anchor="registrar_discovery_cddl"
        title="CDDL definition for Registrar announcement message">
INSERT_CODE_FROM_FILE jrcgrasp.cddl END
</figure>
        </t>

        <t>
          The M_FLOOD message MUST be sent periodically.  The default period SHOULD be
          60 seconds, the value SHOULD be operator configurable but SHOULD
          NOT be smaller than 60 seconds.  The frequency of sending MUST be such
          that the aggregate amount of periodic M_FLOODs from all flooding
          sources cause only negligible traffic across the ACP.
        </t>
             <t>
               Here are some examples of locators for illustrative purposes.
               Only the first one ($transport-protocol = 6, TCP) is defined in
               this document and is mandatory to implement.
               <figure>
                 <artwork><![CDATA[
locator1  = [O_IPv6_LOCATOR, fd45:1345::6789, 6,  443]
locator2  = [O_IPv6_LOCATOR, fd45:1345::6789, 17, 5683]
locator3  = [O_IPv6_LOCATOR, fe80::1234, 41, nil]]]></artwork>
                 </figure>
             </t>
             <t>
               A protocol of 6 indicates that TCP proxying on the
               indicated port is desired.
             </t>
             <t>
               Registrars MUST announce the set of protocols that they
               support.  They MUST support TCP traffic.
             </t>
             <t>
               Registrars MUST accept HTTPS/EST traffic on the TCP ports
               indicated.
             </t>

             <t>
               Registrars MUST support ANI TLS circuit proxy and
               therefore BRSKI across HTTPS/TLS native across the ACP.
             </t>

             <t>
               In the ANI, the Autonomic Control Plane (ACP) secured instance of
               GRASP (<xref target="I-D.ietf-anima-grasp" />) MUST be used for
               discovery of ANI registrar ACP addresses
               and ports by ANI proxies.  The TCP leg of the proxy connection between
               ANI proxy and ANI registrar therefore also runs across the ACP.
             </t>

        </section>
    </section>

    <section anchor="ProtocolDetails"
             title="Protocol Details (Pledge - Registrar - MASA)">

        <t>The pledge MUST initiate BRSKI after boot if it is unconfigured.
        The pledge MUST NOT automatically initiate BRSKI if it has been
        configured or is in the process of being configured.</t>

        <t>
          BRSKI is described as extensions to EST <xref target="RFC7030"/>.
          The goal of these extensions is to reduce the number of TLS
          connections and crypto operations required on the pledge.

          The registrar implements the BRSKI REST interface within
          the "/.well-known/brski" URI tree, as well as implementing the existing EST URIs as
          described in
          EST <xref target="RFC7030"/> section 3.2.2. The communication channel
          between the pledge and the registrar is referred to as "BRSKI-EST"
          (see <xref target="architecturefigure" />).
        </t>

        <t>The communication channel between the registrar and MASA is
           a new communication channel, similar to EST, within the newly
           registred "/.well-known/brski" tree.
           For clarity this channel is referred to as "BRSKI-MASA". (See <xref target="architecturefigure" />).
        </t>

        <t>The MASA URI is "https://" authority "/.well-known/brski".</t>

        <t>
          BRSKI uses existing CMS message formats for existing EST
          operations.  BRSKI uses JSON
          <xref target="RFC8259" /> for all new operations defined here, and
          voucher formats. In all places where a binary value must be carried
          in a JSON string, the use of base64 format (<xref
          target="RFC4648" /> section 4) is to be used, as per
          <xref target="RFC7951" /> section 6.6.
        </t>

        <t>
          While EST section 3.2 does not insist upon use of HTTP
          persistent connections
          (<xref target="RFC7230" /> section 6.3),
          BRSKI-EST connections SHOULD use persistent
          connections.  The intention of this guidance is to ensure the
          provisional TLS state occurs only once, and that the subsequent
          resolution of the provision state is not subject to a MITM attack
          during a critical phase.
        </t>
        <t>
          If non-persistent connections are used, then both the pledge and
          the registrar MUST remember the certificates seen, and also sent
          for the first connection.  They MUST check each subsequent
          connections for the same certificates, and each end MUST use
          the same certificates as well.  This places a difficult restriction
          on rolling certificates on the Registrar.
        </t>


        <t>Summarized automation extensions for the BRSKI-EST flow are:</t>

        <t><list style="symbols">
            <t>
              The pledge either attempts concurrent connections via each
              discovered proxy, or it times out quickly and tries connections
              in series, as explained at the end of <xref target="brskiesttls" />.
            </t>

            <t>
              The pledge provisionally accepts the registrar certificate during
              the TLS handshake as detailed in <xref target="brskiesttls"></xref>.
            </t>

            <t>
              The pledge requests a voucher using
              the new REST calls described below.  This voucher is then validated.
            </t>

            <t>
              The pledge completes authentication of the server certificate as
              detailed in <xref target="CompletingAuthenticationBootstrapping"></xref>. This
              moves the BRSKI-EST TLS connection out of the provisional
              state.
            </t>
            <t>
              Mandatory bootstrap steps conclude with voucher status
              telemetry (see <xref target="pledgestatus" />).
            </t>

        </list></t>

        <t>
          The BRSKI-EST TLS connection can now be used for EST enrollment.
        </t>

        <t>The extensions for a registrar (equivalent to EST server) are:</t>
        <t><list style="symbols">
          <t>
            Client authentication is automated using Initial Device Identity
            (IDevID) as per the EST certificate based client authentication.
            The subject field's DN encoding MUST include the "serialNumber"
            attribute   with the device's unique serial number
            as explained in <xref target="PledgeIdentification" />
          </t>

          <t>The registrar requests and validates the voucher from the MASA.</t>

          <t>The registrar forwards the voucher to the pledge when
          requested.</t>

          <t>
            The registrar performs log verifications (described in
            <xref target="auditLogVerification" />) in addition to local
            authorization checks before accepting optional pledge device
            enrollment requests.
          </t>
        </list></t>

        <section anchor="brskiesttls" title="BRSKI-EST TLS establishment details">
            <t>The pledge establishes the TLS connection with the registrar through
                the circuit proxy (see <xref target="proxydetails"></xref>)
                but the TLS handshake is with the registrar. The BRSKI-EST pledge
                is the TLS client and the BRSKI-EST registrar is the TLS server.
                All security associations established are
                between the pledge and the registrar regardless of proxy
                operations.
            </t>
            <t>
              Use of TLS 1.3 (or newer) is encouraged.
              TLS 1.2 or newer is REQUIRED on the Pledge side.
              TLS 1.3 (or newer) SHOULD be available on the Registrar server interface,
              and the Registrar client interface, but TLS 1.2 MAY be used.
              TLS 1.3 (or newer) SHOULD be available on the MASA server interface, but TLS
              1.2 MAY be used.
            </t>
            <t>
              Establishment of the BRSKI-EST TLS connection is as
              specified in EST <xref target="RFC7030"/> section 4.1.1 "Bootstrap
              Distribution of CA Certificates" <xref target="RFC7030"/> wherein
              the client is authenticated with the IDevID certificate, and the
              EST server (the registrar) is provisionally authenticated with an unverified
              server certificate.

              Configuration or distribution of the trust anchor database
              used for validating the IDevID certificate is out-of-scope of
              this specification.  Note that the trust anchors
              in/excluded from the database will affect which manufacturers'
              devices are acceptable to the registrar as pledges, and can
              also be used to limit the set of MASAs that are trusted for
              enrollment.
            </t>
            <t>
              The signature in the certificate MUST be validated even if a
              signing key can not (yet) be validated.  The certificate (or
              chain) MUST be retained for later validation.
            </t>
            <t>
              A self-signed
              certificate for the Registrar is acceptable as the voucher
              can validate it upon successful enrollment.
            </t>

            <t>The pledge performs input validation of all data received
               until a voucher is verified as specified in <xref
               target="CompletingAuthenticationBootstrapping"></xref> and
               the TLS connection leaves the provisional state. Until these
               operations are complete the pledge could be communicating
               with an attacker.
            </t>
            <t>
              The pledge code needs to be written with the assumption that
              all data is being transmitted at this point to an
              unauthenticated peer, and that received data, while inside a
              TLS connection, MUST be considered untrusted.  This
              particularly applies to HTTP headers and CMS structures that
              make up the voucher.
            </t>
            <t>
              A pledge that can connect to multiple Registrars concurrently
              SHOULD do so.  Some devices may be unable to do so for lack of
              threading, or resource issues.   Concurrent connections defeat
              attempts by a malicious proxy from causing a TCP Slowloris-like
              attack (see <xref target="slowloris" />).
            </t>
            <t>
              A pledge that can not maintain as many connections as there are
              eligible proxies will need to rotate among the various choices,
              terminating connections that do not appear to be making
              progress.
              If no connection is making progress after 5 seconds then the
              pledge SHOULD drop the oldest connection and go on to a
              different proxy: the proxy that has been
              communicated with least recently.
              If there were no
              other proxies discovered, the pledge MAY continue to wait,
              as long as it is concurrently listening for new proxy
              announcements.
            </t>


        </section>
        <section anchor="RequestVoucherFromRegistrar"
               title="Pledge Requests Voucher from the Registrar">
        <t>When the pledge bootstraps it makes a request for a voucher from a
        registrar.</t>

        <t>This is done with an HTTPS POST using the operation path value of
        "/.well-known/brski/requestvoucher".</t>

        <t>The pledge voucher-request Content-Type is:</t>
        <t><list style="hanging">
          <t hangText="application/voucher-cms+json">
            <xref target="RFC8366" /> defines a
           "YANG-defined JSON document that has been signed using a CMS
           structure", and the voucher-request described in
           <xref target="voucher-request"/> is created in the same way.
           The media type is the same as defined in <xref target="RFC8366" />.
           This is also used for the pledge voucher-request.
           The pledge MUST sign the request using the
           <xref target="IDevIDextension"/> credential.
          </t>
        </list></t>

        <t>Registrar
        implementations SHOULD anticipate future media types but of course will simply fail the request if those
        types are not yet known.</t>

        <t>
          The pledge SHOULD include an <xref target="RFC7231" /> section 5.3.2
          "Accept" header field indicating the acceptable media type for the voucher
          response. The  "application/voucher-cms+json" media type is defined
          in <xref target="RFC8366" /> but constrained voucher formats are
          expected in the future. Registrars and MASA are expected to be
          flexible in what they accept.
        </t>

        <t>The pledge populates the voucher-request fields as follows:</t>

        <t><list style="hanging">
            <t hangText="created-on:">Pledges that have a realtime clock are
            RECOMMENDED to populate this field with the current date and
            time in yang:date-and-time format. This provides additional
            information to the MASA.
            Pledges that have no real-time clocks MAY omit this field.
            </t>

            <t hangText="nonce:">The pledge voucher-request MUST contain a
            cryptographically strong random or pseudo-random number
            nonce (see <xref target="RFC4086" /> section 6.2).
            As the nonce is usually generated very early in the boot sequence
            there is a concern that the same nonce might generated across
            multiple boots, or after a factory reset.
            Different nonces MUST be generated for each bootstrapping
            attempt, whether in series or concurrently.
            The freshness of this nonce mitigates against the lack of real-time
            clock as explained in <xref target="timeunknown"/>.
            </t>

            <t hangText="assertion:">
              The pledge indicates support for the mechanism
              described in this document, by putting the value "proximity" in the
              voucher-request, MUST include the
              "proximity-registrar-cert" field (below).
            </t>

            <t hangText="proximity-registrar-cert:">In a pledge
            voucher-request this is the first certificate in the TLS server
            'certificate_list' sequence (see [RFC5246]) presented by the
            registrar to the pledge. That is, it is the end-entity
            certificate. This MUST be populated in a pledge voucher-request.
            </t>

            <t hangText="serial-number">The serial number of the pledge
            is included in the voucher-request from the Pledge. This value is
            included as a sanity check only, but it is not to be forwarded
            by the Registrar as described in <xref target="RequestVoucherFromMASA" />.
            </t>

        </list></t>
        <t>All other fields MAY be omitted in the pledge voucher-request.</t>

        <t>An example JSON payload of a pledge voucher-request is in
            <xref target="voucher-request-examples"/> Example 1.</t>

        <t>
          The registrar confirms that the
          assertion is 'proximity' and that pinned
          'proximity-registrar-cert' is the Registrar's certificate.
          If this validation fails, then there is an On-Path Attacker (MITM),
          and the connection MUST be closed after the returning an
          HTTP 401 error code.
        </t>
      </section>

      <section anchor="pledgeauthorization" title="Registrar Authorization of
                                                   Pledge">
        <t>
          In a fully automated network all devices must be securely identified
          and authorized to join the domain.
        </t>

        <t>
          A Registrar accepts or declines a request to join the domain, based
          on the authenticated identity presented.  For different networks,
          examples of automated acceptance may include:<list style="symbols">
          <t>allow any device of a specific type (as determined by the X.509
          IDevID),</t>
          <t>allow any device from a specific vendor (as determined by the
          X.509 IDevID),</t>
          <t>allow a specific device from a vendor (as determined by the X.509
          IDevID) against a domain white list.  (The mechanism for checking
          a shared white list potentially used by multiple Registrars is out
          of scope).</t>
        </list>
        </t>

        <t>
          If validation fails the registrar SHOULD respond with the
          HTTP 404 error code.  If the voucher-request is in an unknown
          format, then an HTTP 406 error code is more appropriate.
          A situation that could be resolved with administrative action
          (such as adding a vendor to a whitelist) MAY be responded with an
          403 HTTP error code.
        </t>

        <t>If authorization is successful the registrar obtains a voucher from the MASA service (see
            <xref target="RequestVoucherFromMASA"/>) and returns that MASA signed voucher to the pledge
        as described in <xref target="VoucherResponse"/>.</t>

      </section>
    <section anchor="brskimasatls" title="BRSKI-MASA TLS establishment details">
        <t>
          The BRSKI-MASA TLS connection is a 'normal' TLS connection
          appropriate for HTTPS REST interfaces. The registrar initiates the
          connection and uses the MASA URL obtained as described in
          <xref target="obtainmasaurl" />. The mechanisms in
          <xref target="RFC6125" /> SHOULD be used in authentication of the
          MASA using a DNS-ID that matches that which is found in the IDevID.
          Registrars MAY include a mechanism to override the MASA URL on a
          manufacturer-by-manufacturer basis, and within that override it is
          appropriate to provide alternate anchors.
          This will typically used by some vendors to establish explicit
          (or private) trust
          anchors for validating their MASA that is part of a sales channel
          integration.
        </t>

        <t>
          Use of TLS 1.3 (or newer) is encouraged. TLS 1.2 or newer is
          REQUIRED.  TLS 1.3 (or newer) SHOULD be available.
        </t>

        <t>
          As described in <xref target="RFC7030" />, the MASA and the
          registrars SHOULD be prepared to support TLS client
          certificate authentication and/or HTTP Basic, Digest, or SCRAM authentication.
          This connection MAY also have no client authentication at all.
        </t>
        <t>
          Registrars SHOULD permit
          trust anchors to be pre-configured on a per-vendor(MASA) basis.
          Registrars SHOULD include the ability to configure a TLS
          ClientCertificate on a per-MASA basis, or to use no client
          certificate.  Registrars SHOULD also permit HTTP Basic and
          Digest authentication to be configured.
        </t>
        <t>
          The authentication of the BRSKI-MASA
          connection does not change the voucher-request process, as
          voucher-requests are already signed by the registrar.
          Instead, this authentication provides access control to the
          audit-log as described in <xref target="authzLogRequest" />.
        </t>
        <t>
          Implementors are advised that
          contacting the MASA is to establish a secured API connection with a
          web service and that there are a number of authentication models
          being explored within the industry. Registrars are RECOMMENDED to
          fail gracefully and generate useful administrative notifications or
          logs in the advent of unexpected HTTP 401 (Unauthorized) responses
          from the MASA.
        </t>

        <section anchor="masaauthentication" title="MASA authentication of
                                                    customer Registrar">
          <t>
            Providing per-customer options requires that the customer's
            registrar be uniquely identified.  This can be done by any stateless
            method that HTTPS supports such as with HTTP Basic
            or Digest authentication (that is using a password), but the use
            of TLS Client Certificate authentication is RECOMMENDED.
          </t>
          <t>
            Stateful methods involving API tokens, or HTTP Cookies, are not
            recommended.
          </t>
          <t>
            It is expected that the setup and configuration of per-customer
            Client Certificates is done as part of a sales ordering process.
          </t>
          <t>
            The use of public PKI (i.e. WebPKI) End-Entity Certificates to
            identify the Registrar is reasonable, and if done universally
            this would permit a MASA to identify a customers' Registrar simply by a
            FQDN.
          </t>
          <t>
            The use of DANE records in DNSSEC signed zones would also permit use of
            a FQDN to identify customer Registrars.
          </t>
          <t>
            A third (and simplest, but least flexible) mechanism would be for
            the MASA to simply store the Registrar's certificate pinned in a
            database.
          </t>
          <t>
            A MASA without any supply chain integration can simply accept
            Registrars without any authentication, or can accept them on a
            blind Trust-on-First-Use basis as described in <xref target="masasecurityreduction_tofu" />.
          </t>
          <t>
            This document does not make a specific recommendation on how the
            MASA authenticates the Registrar as there are
            likely different tradeoffs in different environments and product
            values. Even within the ANIMA ACP applicability, there is a
            significant difference between supply chain logistics for $100
            CPE devices and $100,000 core routers.
          </t>
        </section>

    </section>

    <section anchor="RequestVoucherFromMASA" title="Registrar Requests Voucher from MASA">
        <t>
          When a registrar receives a pledge voucher-request it in turn
          submits a registrar voucher-request to the MASA service via an
          HTTPS interface (<xref target="RFC7231" />).
        </t>

        <t>This is done with an HTTP POST using the operation path value of
        "/.well-known/brski/requestvoucher".</t>

        <t>The voucher media type "application/voucher-cms+json" is defined in
          <xref target="RFC8366" /> and is also used for the registrar voucher-request. It is a JSON document that has been
          signed using a CMS structure.
          The registrar MUST sign the registrar voucher-request.
        </t>
        <t>
          MASA implementations SHOULD anticipate future media
          ntypes but of course will simply fail the request if those types are
          not yet known.
        </t>

        <t>
          The voucher-request CMS object includes some number of certificates
          that are input to the MASA as it populates the
          'pinned-domain-cert'. As the
          <xref target="RFC8366" /> is quite flexible in what may be put into
          the 'pinned-domain-cert', the MASA needs some signal as to what
          certificate would be effective to populate the field with: it may
          range from the End Entity (EE) Certificate that the Registrar uses,
          to the entire private Enterprise CA certificate.
          More specific certificates result in a tighter binding of the
          voucher to the domain, while less specific certificates result in
          more flexibility in how the domain is represented by certificates.
        </t>
        <t>
          A Registrar which is seeking a nonceless voucher for later offline use
          benefits from a less specific certificate, as it permits the actual
          keypair used by a future Registrar to be determined by the pinned
          certificate authority.
        </t>
        <t>
          In some cases, a less specific certificate, such a public WebPKI
          certificate authority, could be too open, and could permit any
          entity issued a certificate by that
          authority to assume ownership of a device
          that has a voucher pinned.
          Future work may provide a solution to pin both a certificate and a
          name that would reduce such risk of malicious ownership assertions.
        </t>
        <t>
          The Registrar SHOULD request a voucher with the most specificity
          consistent with the mode that it is operating in.
          In order to do this, when the Registrar prepares the CMS structure
          for the signed voucher-request, it SHOULD include only certificates
          which are part of the chain that it wishes the MASA to pin.
          This MAY be as small as only the End-Entity certificate (with id-kp-cmcRA set) that
          it uses as it's TLS Server Certificate, or it MAY be the entire
          chain, including the Domain CA.
        </t>

        <t>
          The Registrar SHOULD include an <xref target="RFC7231" /> section
          5.3.2 "Accept" header field indicating the response media types that are
          acceptable. This list SHOULD be the entire list presented to the
          Registrar in the Pledge's original request (see <xref
          target="RequestVoucherFromRegistrar" />) but MAY be a subset.
          The MASA is expected to be flexible in what it accepts.
        </t>

        <t>The registrar populates the voucher-request fields as follows:</t>

        <t><list style="hanging">
        <t hangText="created-on:">
          The Registrars SHOULD populate this field with the current date and
          time when the Registrar formed this voucher request. This field
          provides additional information to the MASA.
        </t>
        <t hangText="nonce:">This value, if present, is copied from the pledge
            voucher-request. The registrar voucher-request MAY omit
            the nonce as per <xref target="noncelessVoucherRequest" />.
        </t>
        <t hangText="serial-number:">The serial number of the pledge the registrar would like a voucher for. The registrar
        determines this value by parsing the authenticated pledge IDevID certificate. See <xref target="IDevIDextension"></xref>.
        The registrar MUST verify that the serial number field it parsed matches the serial number field the pledge
        provided in its voucher-request. This provides a sanity check useful for detecting error conditions and logging.
        The registrar MUST NOT simply copy the serial number field from a pledge voucher request as that field is claimed but
        not certified.</t>
        <t hangText="idevid-issuer:">The Issuer value from the
        pledge IDevID certificate is included to ensure unique interpretation of the
        serial-number. In the case of nonceless (offline) voucher-request, then an
        appropriate value needs to be configured from the same out-of-band source as the serial-number.
        </t>

        <t hangText="prior-signed-voucher-request:">The signed pledge
        voucher-request SHOULD be included in the registrar voucher-request.
        The entire CMS signed structure is to be included, base64 encoded for
        transport in the JSON structure.
        </t>
        </list></t>

        <t>
          A nonceless registrar voucher-request MAY be
          submitted to the MASA. Doing so allows
          the registrar to request a voucher when the pledge is offline, or
          when the registrar anticipates not being able to connect to the
          MASA
          while the pledge is being deployed. Some use cases require the
          registrar to learn the
          appropriate IDevID SerialNumber field and appropriate 'Accept header field' values from the physical device
          labeling or from the sales channel (out-of-scope for this
          document).
        </t>

        <t>All other fields MAY be omitted in the registrar
        voucher-request.</t>
        <t>
          The "proximity-registrar-cert" field MUST NOT be present in the
          registrar voucher-request.
        </t>

        <t>Example JSON payloads of registrar voucher-requests are in
            <xref target="voucher-request-examples"/> Examples 2 through 4.</t>

        <t>The MASA verifies that the registrar voucher-request is internally consistent
        but does not necessarily authenticate the registrar certificate since the
        registrar MAY be unknown to the MASA in advance. The MASA
        performs the actions and validation checks described in the following
        sub-sections before issuing a voucher.</t>
        <section title="MASA renewal of expired vouchers">
          <t>
            As described in
            <xref target="RFC8366"/> vouchers
            are normally short lived to avoid revocation issues. If the request
            is for a previous (expired) voucher using the same registrar
            (that is, a Registrar with the same Domain CA)
            then the request for
            a renewed voucher SHOULD be automatically authorized. The MASA has
            sufficient information to determine this by examining the request, the registrar
            authentication, and the existing audit-log. The issuance of a renewed voucher is
            logged as detailed in <xref target="VoucherResponse"/>.
            </t>
          <t>To inform the MASA that existing vouchers are not to be renewed one
            can update or revoke the registrar credentials used to authorize the request (see
            <xref target="MASAauthenticationOfRegistrar"/> and <xref target="revocationcheck"/>). More
            flexible methods will likely involve sales channel integration and
            authorizations (details are out-of-scope of this document).</t>
        </section>

        <section anchor="MASApinned" title="MASA pinning of registrar">
          <t>
            A certificate chain is extracted from the Registrar's signed CMS container.
            This chain may be as short as a single End-Entity Certificate, up
            to the entire registrar certificate chain, including the Domain
            CA certificate,
            as specified in <xref target="RequestVoucherFromMASA" />.
          </t>
          <t>
            If the domain's CA is unknown to the MASA, then it is to be
            considered a temporary trust anchor for the rest of the steps
            in this section.  The intention is not to authenticate the
            message as having come from a fully validated origin, but
            to establish the consistency of the domain PKI.
          </t>
          <t>
            The MASA MAY use the certificate farthest in the chain
            chain that it received from the Registrar from the
            end-entity, as determined by MASA policy.
            A MASA MAY have a local policy that it only pins the End-Entity
            certificate. This is consistent with <xref target="RFC8366" />.
            Details of the policy will typically depend upon the degree of
            Supply Chain Integration, and the mechanism used by the Registrar to
            authenticate.  Such a policy would also determine how
            the MASA will respond to a request for a nonceless voucher.
          </t>
        </section>

        <section anchor="revocationcheck"
                 title="MASA checking of voucher request signature">
          <t>
            As described in <xref target="MASApinned" />, the MASA has
            extracted Registrar's domain CA.  This is used to validate the
            CMS signature (<xref target="RFC5652" />) on the voucher-request.
          </t>
          <t>
            Normal PKIX revocation
            checking is assumed during voucher-request signature validation.
            This CA certificate MAY have
            Certificate Revocation List distribution points, or Online
            Certificate Status Protocol (OCSP) information (<xref
            target="RFC6960" />).  If they are present, the MASA MUST
            be able to reach the relevant servers belonging to the
            Registrar's domain CA to perform the revocation checks.
          </t>
          <t>
            The use of OCSP Stapling is preferred.
          </t>
        </section>

        <section anchor="MASAauthenticationOfRegistrar"
                 title="MASA verification of domain registrar">
          <t>
            The MASA MUST verify that the registrar voucher-request is signed
            by a registrar. This is confirmed by verifying that the
            id-kp-cmcRA extended key usage extension field (as detailed in
            EST RFC7030 section 3.6.1) exists in the certificate of the
            entity that signed the registrar voucher-request. This
            verification is only a consistency check that the unauthenticated
            domain CA intended the voucher-request signer to be a registrar. Performing this check
            provides value to the domain PKI by assuring the domain administrator
            that the MASA service will only respect claims from authorized
            Registration Authorities of the domain.
          </t>

          <t>
            Even when a domain CA is authenticated to the MASA, and there is
            strong sales channel integration to understand who the legitimate
            owner is, the above id-kp-cmcRA check prevents arbitrary End-Entity
            certificates (such as an LDevID certificate) from
            having vouchers issued against them.
          </t>
          <t>
            Other cases of inappropriate voucher issuance are detected
            by examination of the audit log.
          </t>

          <t>
            If a nonceless voucher-request is submitted the MASA MUST
            authenticate the registrar as described in either
            EST <xref target="RFC7030"/> section 3.2.3, section 3.3.2,
            or by validating the registrar's certificate used to
            sign the registrar voucher-request using a configured trust anchor.
            Any of these methods reduce the risk of DDoS attacks
            and provide an authenticated identity as an input to
            sales channel integration and authorizations
            (details are out-of-scope of this document).
          </t>

          <t>
            In the nonced case, validation of the Registrar's identity (via
            TLS Client Certificate or HTTP authentication) MAY be omitted
            if the device policy is to accept audit-only vouchers.
          </t>
        </section>

        <section anchor="MASAassertion" title="MASA verification of pledge prior-signed-voucher-request">
          <t>
            The MASA MAY verify that the registrar voucher-request
            includes the 'prior-signed-voucher-request' field. If so the
            prior-signed-voucher-request MUST include a
            'proximity-registrar-cert' that is consistent with the
            certificate used to sign the registrar voucher-request.
            Additionally the
            voucher-request serial-number leaf MUST match the pledge
            serial-number that the MASA extracts from the signing certificate
            of the prior-signed-voucher-request.
            The consistency check described above is checking that the
            'proximity-registrar-cert' SPKI fingerprint exists within the
            registrar voucher-request CMS signature's certificate chain.
            This is substantially the same as the pin validation described in
            in <xref target="RFC7469" /> section 2.6, paragraph three.
          </t>
          <t>
            If these checks succeed the MASA updates
            the voucher and audit-log assertion leafs with the "proximity"
            assertion, as defined by <xref target="RFC8366" /> section 5.3.
          </t>
        </section>

        <section anchor="MASAnoncehandling" title="MASA nonce handling">
          <t>
            The MASA does not verify the nonce itself.
            If the registrar voucher-request contains a nonce, and the
            prior-signed-voucher-request exists, then the MASA MUST
            verify that the nonce is consistent.
            (Recall from above that the
            voucher-request might not contain a nonce, see
            <xref target="RequestVoucherFromMASA"/> and
            <xref target="MASAauthenticationOfRegistrar"/>).
          </t>
          <t>
            The MASA populates the audit-log with the nonce that was
            verified. If a nonceless voucher is issued, then the
            audit-log is to be populated with the JSON value "null".
          </t>
        </section>
      </section>

      <section anchor="VoucherResponse" title="MASA and Registrar Voucher Response">
        <t>The MASA voucher response to the registrar is forwarded
          without changes to the pledge; therefore this section applies
          to both the MASA and the registrar. The HTTP signaling described
          applies to both the MASA and registrar responses.
        </t>

        <t>
          When a voucher request arrives at the registrar, if it has a cached
          response from the MASA for the corresponding registrar
          voucher-request, that cached response can be used according to
          local policy; otherwise the registrar constructs a new registrar
          voucher-request and sends it to the MASA.
        </t>

        <t>
          Registrar evaluation of the voucher itself is purely for
          transparency and audit purposes to further inform log verification
          (see <xref target="auditLogVerification" />) and therefore a
          registrar could accept future voucher formats that are opaque to
          the registrar.
        </t>

        <t>
          If the voucher-request is successful, the server (MASA responding
          to registrar or registrar responding to pledge) response MUST
          contain an HTTP 200 response code. The server MUST answer with a
          suitable 4xx or 5xx HTTP <xref target="RFC7230" /> error code when a problem occurs.
          In this case, the response data from the MASA MUST be a plaintext
          human-readable (UTF-8) error message containing explanatory
          information describing why the request was rejected.
        </t>

        <t>
          The registrar MAY respond with an HTTP 202 ("the request has been
          accepted for processing, but the processing has not been completed") as
          described in EST <xref target="RFC7030"/> section 4.2.3 wherein the
          client "MUST wait at least the specified 'Retry-After' time before
          repeating the same request".
          (see <xref target="RFC7231" /> section 6.6.4)
          The pledge is RECOMMENDED to provide local
          feedback (blinked LED etc) during this wait cycle if mechanisms for this
          are available. To prevent an attacker registrar from significantly
          delaying bootstrapping the pledge MUST limit the 'Retry-After' time to
          60 seconds. Ideally the pledge would keep track of the
          appropriate Retry-After header field values for any number of
          outstanding registrars but this would involve a state table
          on the pledge.  Instead the
          pledge MAY ignore the exact Retry-After value in favor of a single hard
          coded value (a registrar that is unable
          to complete the transaction after the first 60 seconds has another chance a minute later). A pledge SHOULD only maintain a 202 retry-state
          for up to 4 days, which is longer than a long weekend, after which
          time the enrollment attempt fails and the pledge returns to discovery state.
        </t>

        <t>
          A pledge that retries a request after receiving a 202 message MUST
          resend the same voucher-request.  It MUST NOT sign a new
          voucher-request each time, and in particular, it MUST NOT change
          the nonce value.
        </t>

        <t>
          In order to avoid infinite redirect loops, which a malicious
          registrar might do in order to keep the pledge from
          discovering the correct registrar, the pledge MUST NOT
          follow more than one redirection (3xx code) to another web
          origin. EST supports redirection but requires user
          input; this change allows the pledge to follow a single
          redirection without a user interaction.
        </t>

        <t>A 403 (Forbidden) response is appropriate if the voucher-request
        is not signed correctly, stale, or if the pledge has another
        outstanding voucher that cannot be overridden.</t>
        <t>A 404 (Not Found) response is appropriate when the request is for a
        device that is not known to the MASA.</t>
        <t>A 406 (Not Acceptable) response is appropriate if a voucher of the
        desired type or using the desired algorithms (as indicated by the
        Accept: header fields, and algorithms used in the signature) cannot be
        issued such as because the MASA knows the pledge cannot process
        that type. The registrar SHOULD use this response if it determines
        the pledge is unacceptable due to inventory control, MASA audit-logs, or
        any other reason.</t>
        <t>
          A 415 (Unsupported Media Type) response is appropriate
          for a request that has a voucher-request or Accept: value that is
          not understood.
        </t>

        <t>The voucher response format is as indicated in the submitted
        Accept header fields or based on the MASA's prior understanding of proper
        format for this Pledge. Only the <xref target="RFC8366"/>
        "application/voucher-cms+json" media type is defined at this
        time. The syntactic details of vouchers are described in detail in
        <xref target="RFC8366"/>. <xref target="voucherjsonexample" /> shows
        a sample of the contents of a voucher.
        </t>

        <figure anchor="voucherjsonexample" title="An example voucher">
INSERT_CODE_FROM_FILE example-voucher.json END
        </figure>

        <t>The MASA populates the voucher fields as follows:</t>

        <t><list style="hanging">
        <t hangText="nonce:">The nonce from the pledge if available. See <xref
          target="MASAnoncehandling"/>.</t>
        <t hangText="assertion:">The method used to verify the relationship
        between pledge and registrar. See <xref
          target="MASAassertion"/>.</t>
        <t hangText="pinned-domain-cert:">A certificate. See <xref
          target="MASApinned"/>. This figure is illustrative, for an example,
        see <xref target="exampleprocess" /> where an End Entity certificate
        is used. </t>
        <t hangText="serial-number:">The serial-number as provided in the
          voucher-request. Also see <xref target="MASAassertion"/>.</t>
        <t hangText="domain-cert-revocation-checks:">Set as appropriate for the
          pledge's capabilities and as documented in <xref target="RFC8366"/>.
          The MASA MAY set this field to 'false' since setting it to 'true' would
          require that revocation information be available to the pledge and this
          document does not make normative requirements for
          <xref target="RFC6961"/> or equivalent integrations.</t>
        <t hangText="expires-on:">This is set for nonceless vouchers. The MASA
          ensures the voucher lifetime is consistent with any revocation or
          pinned-domain-cert consistency checks the pledge might perform.
          See section <xref target="timeunknown" />. There are three times to consider:
          (a) a configured voucher lifetime in the MASA, (b) the expiry time for the
          registrar's certificate, (c) any certificate revocation
          information (CRL) lifetime. The expires-on field SHOULD be before
          the earliest of these three values.
          Typically (b) will be some significant time in the future,
          but (c) will typically be short (on the order of a week or
          less).  The RECOMMENDED period for (a) is on the order of
          20 minutes, so it will typically determine the lifespan
          of the resulting voucher.

          20 minutes is sufficient time to reach the post-provisional state
          in the pledge, at which point there is an established trust
          relationship between pledge and registrar.  The subsequent
          operations can take as long as required from that point onwards.
          The lifetime of the voucher has no impact on the lifespan of the
          ownership relationship.
        </t>
        </list></t>

        <t>
          Whenever a voucher is issued the MASA MUST update the
          audit-log sufficiently to generate the response as described in
          <xref target="MASAauditlog" />.
          The internal state requirements to maintain the audit-log
          are out-of-scope.
        </t>

        <section anchor="CompletingAuthenticationBootstrapping"
                 title="Pledge voucher verification">

        <t>
          The pledge MUST verify the voucher signature using the
          manufacturer-installed
          trust anchor(s) associated with the manufacturer's MASA (this is
          likely included in the pledge's firmware). Management of the
          manufacturer-installed
          trust anchor(s) is out-of-scope of this document; this protocol
          does not update these trust anchor(s).
        </t>

        <t>
          The pledge MUST verify the serial-number field of the signed voucher
          matches the pledge's own serial-number.
        </t>

        <t>
          The pledge MUST
          verify the nonce information in the voucher.  If present, the nonce in
          the voucher must match the nonce the pledge submitted to the
          registrar; vouchers with no nonce can also be accepted (according
          to local policy, see <xref target="pledgeReductions"/>)
        </t>

        <t>
          The pledge MUST be prepared to parse and fail gracefully from
          a voucher response that does not contain a 'pinned-domain-cert'
          field.
          Such a thing indicates a failure to enroll in this domain,
          and the pledge MUST attempt joining with other available Join Proxy.
        </t>
        <t>
          The pledge MUST be prepared to ignore additional fields that it does not recognize.
        </t>
        </section>
        <section anchor="PledgeAuthenticationOfProvisionalTLS"
                 title="Pledge authentication of provisional TLS connection">
          <t>
            Following the process described in <xref target="RFC8366" />,
            the pledge should consider the public key from the
            pinned-domain-cert as the sole temporary trust anchor.
          </t>
          <t>
            The pledge then evaluates the TLS Server Certificate chain that it
            received when the TLS connection was formed using this trust
            anchor.
            It is possible that the pinned-domain-cert matches the End-Entity
            Certificate provided in the TLS Server.
          </t>
          <t>
            If a registrar's credentials cannot be verified using the
            pinned-domain-cert trust anchor from the voucher then the TLS
            connection is immediately
            discarded and the pledge abandons attempts to bootstrap with this
            discovered registrar. The pledge SHOULD send voucher status
            telemetry (described below) before closing the TLS connection.
            The pledge MUST attempt to enroll using any other proxies
            it has found.  It SHOULD return to the same proxy again after
            unsuccessful attempts with other proxies.  Attempts should be
            made repeated at intervals according to the backoff timer
            described earlier.
            Attempts SHOULD be repeated as failure may be the result of a
            temporary inconsistency (an inconsistently rolled registrar key,
            or some other mis-configuration).  The inconsistency could also
            be the result an active MITM attack on the EST connection.
          </t>
          <t> The registrar MUST use a certificate that chains to the pinned-domain-cert
            as its TLS server certificate.
          </t>
          <t>The pledge's PKIX path validation of a registrar certificate's validity
            period information is as described in <xref target="timeunknown"></xref>.
            Once the PKIX path validation is successful the TLS connection is
            no longer provisional.</t>
          <t>The pinned-domain-cert MAY be installed as a
            trust anchor for future operations such as enrollment (e.g. <xref target="RFC7030"></xref> as recommended) or trust anchor management or raw protocols that do not need full PKI based key management. It can be used to authenticate any dynamically
            discovered EST server that contain the id-kp-cmcRA extended key
            usage extension as detailed in EST RFC7030 section 3.6.1; but to
            reduce system complexity the pledge SHOULD avoid additional
            discovery operations. Instead the pledge SHOULD communicate directly
            with the registrar as the EST server. The 'pinned-domain-cert'
            is not a complete
            distribution of the <xref target="RFC7030" /> section 4.1.3 CA Certificate Response,
            which is
            an additional justification for the recommendation to proceed with EST
            key management operations. Once a full CA Certificate Response is
            obtained it is more authoritative for the domain than the limited
            'pinned-domain-cert' response.</t>
        </section>
      </section>

      <section anchor="pledgestatus" title="Pledge BRSKI Status Telemetry ">
        <t>The domain is expected to provide indications to the system
        administrators concerning device lifecycle status. To facilitate this
        it needs telemetry information concerning the device's
        status.</t>

        <t>The pledge MUST indicate its pledge status regarding the voucher.
        It does this by sending a status message to the Registrar.</t>

        <t>The posted data media type: application/json</t>

        <t>The client sends an HTTP POST to the server at the URI ".well-known/brski/voucher_status".</t>

        <t>
          The format and semantics described below are for version 1.
          A version field is included to permit significant changes to this
          feedback in the future.  A Registrar that receives a status
          message with a version larger than it knows about SHOULD log the
          contents and alert a human.
        </t>

        <t>The Status field indicates if the voucher was acceptable.
        Boolean values are acceptable, where "true" indicates the voucher was
        acceptable.
        </t>

        <t>
          If the voucher was not acceptable the Reason string indicates
          why. In the failure case this message may be sent to an
          unauthenticated, potentially malicious registrar and therefore the
          Reason string SHOULD NOT provide information beneficial to an
          attacker. The operational benefit of this telemetry information is
          balanced against the operational costs of not recording that an
          voucher was ignored by a client the registrar expected to continue
          joining the domain.
        </t>

        <t>
          The reason-context attribute is an arbitrary JSON object (literal
          value or hash of values) which provides additional information
          specific to this pledge.  The contents of this field are not
          subject to standardization.
        </t>

        <t>
          The version and status fields MUST be present.
          The Reason field SHOULD be present whenever the status field
          is false.  The Reason-Context field is optional.
          In the case of a SUCCESS the Reason string MAY be omitted.
        </t>
        <t>
          The keys to this JSON object are case-sensitive and MUST be lowercase.
          <xref target="telemetryexample" /> shows an example JSON.
        </t>

          <t><figure anchor="cddl-voucherstatus" title="CDDL for voucher status POST">
INSERT_CODE_FROM_FILE voucherstatus.cddl END
          </figure></t>

        <t><figure anchor="telemetryexample" title="Example Status Telemetry">
INSERT_CODE_FROM_FILE example-telemetry.json END
          </figure>
          The server SHOULD respond with an HTTP 200 but MAY simply
          fail with an HTTP 404 error. The client ignores any response. Within
          the server logs the server SHOULD capture this telemetry
          information.
        </t>
        <t>
          Additional standard JSON fields in this POST MAY be added, see
          <xref target="pledgestatustelemetryregistry" />.  A server that
          sees unknown fields should log them, but otherwise ignore them.
        </t>
      </section>

      <section anchor="authzLogRequest" title="Registrar audit-log request ">
         <t>
           After receiving the pledge status telemetry <xref target="pledgestatus" />,
           the registrar SHOULD request the MASA audit-log from the MASA
           service.</t>

        <t>
          This is done with an HTTP POST using the operation path value of
          "/.well-known/brski/requestauditlog".
        </t>

        <t>
          The registrar SHOULD HTTP POST the same registrar voucher-request
          as it did when requesting a
          voucher (using the same Content-Type). It is posted to the /requestauditlog URI instead.
          The "idevid-issuer" and "serial-number" informs the MASA
          which log is requested so the appropriate log can be prepared
          for the response.
          Using the same media type and message minimizes
          cryptographic and message operations although it results in additional
          network traffic.
          The relying MASA implementation MAY leverage internal state
          to associate this request with the original, and by now already
          validated, voucher-request so as to avoid an extra crypto
          validation.
        </t>
        <t>
          A registrar MAY request logs at future times. If the registrar
          generates a new request then the MASA is forced to perform
          the additional cryptographic operations to verify the new request.
        </t>
        <t>
          A MASA that receives a request for a device that does not exist,
          or for which the requesting owner was never an owner returns an
          HTTP 404 ("Not found") code.
        </t>
        <t>
          It is reasonable for a Registrar, that the MASA does not believe
          to be the current owner, to request the audit-log.  There are
          probably reasons for this which are hard to predict in advance.
          For instance, such a registrar may not be aware that the device has
          been resold; it may be that the device has been resold
          inappropriately, and this is how the original owner will learn of
          the occurance.  It is also possible that the device legitimately
          spends time in two different networks.
        </t>
        <t>
          Rather than returning the audit-log as a response to the POST (with
          a return code 200), the MASA MAY instead return a 201 ("Created")
          response (<xref target="RFC7231" /> sections 6.3.2 and 7.1), with
          the URL to the prepared (and idempotent, therefore cachable) audit
          response in the Location: header field.
        </t>
        <t>
          In order to avoid enumeration of device audit-logs,
          MASA that return URLs SHOULD take care to make the returned
          URL unguessable.
          <xref target="W3C.WD-capability-urls-20140218" /> provides very good additional guidance.
          For instance, rather than returning URLs containing a database number
          such as https://example.com/auditlog/1234 or the EUI of the device
          such https://example.com/auditlog/10-00-00-11-22-33,
          the MASA SHOULD return a randomly generated value (a "slug" in
          web parlance).  The value is used to find the relevant database
          entry.
        </t>
        <t>
          A MASA that returns a code 200 MAY also include a Location: header
          for future reference by the registrar.
        </t>

        <section anchor="MASAauditlog" title="MASA audit log response">
          <t>A log data file is returned consisting of all log entries
          associated with the device selected by the IDevID presented in
          the request.  The audit log may be abridged by removal of old or repeated
          values as explained below.
          The returned data is in JSON format (<xref target="RFC8259"/>),
          and the Content-Type SHOULD be "application/json".

          </t>
          <t>
            The following CDDL (<xref target="RFC8610" />) explains the
            structure of the JSON format audit-log response:
            <figure anchor="cddl-auditlog" title="CDDL for audit-log response">
INSERT_CODE_FROM_FILE auditlog.cddl END
            </figure>
          </t>



          <t>An example:
          <figure anchor="example-auditlog" title="Example of audit-log response">
INSERT_CODE_FROM_FILE example-auditlog.json END
          </figure>
          </t>

          <t>
            The domainID is a binary SubjectKeyIdentifier value calculated
            according to <xref target="domainID" />.
            It is encoded once in base64 in order to be transported in this
            JSON container.
          </t>

          <t>
            The date is in <xref target="RFC3339" /> format, which is
            consistent with typical JavaScript usage of JSON.
          </t>

          <t>
            The truncation structure MAY be omitted if all values are zero.
            Any counter missing from the truncation structure is the be
            assumed to be zero.
          </t>

          <t>
            The nonce is a string, as provided in the voucher-request, and
            used in the voucher.   If no nonce was placed in the resulting
            voucher, then a value of null SHOULD be used in preference to
            omitting the entry.
            While the nonce is often created as a base64 encoded random
            series of bytes, this should not be assumed.
          </t>

          <t>
            Distribution of a large log is less than ideal. This structure can
            be optimized as follows: Nonced or Nonceless entries for the
            same domainID MAY be abridged from the log leaving only the single
            most recent nonced or nonceless entry for that domainID. In the case of
            truncation the 'event' truncation value SHOULD contain a count of the number of events for this
            domainID that were omitted. The log SHOULD NOT be further
            reduced but there could exist operational situation where maintaining
            the full log is not possible. In such situations the log MAY be
            arbitrarily abridged for length, with the number of removed
            entries indicated as 'arbitrary'.
          </t>

          <t>
            If the truncation count exceeds 1024 then the MASA
            MAY use this value without further incrementing it.
          </t>

          <t>
            A log where duplicate entries for the same domain have
            been omitted ("nonced duplicates" and/or "nonceless duplicates)
            could still be acceptable for informed decisions. A log that
            has had "arbitrary" truncations is less acceptable but manufacturer
            transparency is better than hidden truncations.
          </t>

          <t>
            A registrar that sees a version value greater than 1 indicates
            an audit log format that has been enhanced with additional
            information.   No information will be removed in future
            versions; should an incompatible change be desired in the future,
            then a new HTTP end point will be used.
          </t>

          <t>This document
            specifies a simple log format as provided by the
            MASA service to the registrar. This format could be improved by
            distributed consensus technologies that integrate vouchers
            with technologies such as block-chain or hash trees or optimized
            logging approaches. Doing so is out of the scope of this document
            but is an
            anticipated improvement for future work.  As such, the
            registrar SHOULD anticipate new kinds of responses, and
            SHOULD provide operator controls to indicate how to process
            unknown responses.
          </t>
        </section>

        <section anchor="domainID" title="Calculation of domainID">
          <t>
            The domainID is a binary value (a BIT STRING) that uniquely
            identifies a Registrar by the "pinned-domain-cert".
          </t>
          <t>
            If the "pinned-domain-cert" certificate
            includes the SubjectKeyIdentifier (<xref target="RFC5280">Section
            4.2.1.2</xref>), then it is to be used as the domainID.  If not,
            the SPKI Fingerprint as described in
            <xref target="RFC7469" /> section 2.4 is to be used.
            This value needs to be calculated by both MASA (to
            populate the audit-log), and by the Registrar (to recognize
            itself in the audit log).
          </t>

          <t>
            <xref target="RFC5280" /> section 4.2.1.2 does not mandate that the
            SubjectKeyIdentifier extension be present in non-CA certificates.
            It is RECOMMENDED that Registrar certificates (even if
            self-signed), always include the SubjectKeyIdentifier to be
            used as a domainID.
          </t>

          <t>
            The domainID is determined
            from the certificate chain associated with the
            pinned-domain-cert and is used to update the audit-log.
          </t>
      </section>

        <section anchor="auditLogVerification" title="Registrar audit log verification">
          <t>
            Each time the Manufacturer Authorized Signing Authority (MASA)
            issues a voucher, it appends details of the assignment to
            an internal audit log for that device.
            The internal audit log is processed when responding to
            requests for details as described in <xref
            target="authzLogRequest" />.
            The contents of the audit log can express a variety of trust
            levels, and this section explains what kind of trust a
            registrar can derive from the entries.
          </t>
          <t>
            While the audit log provides a list of vouchers that were issued
            by the MASA, the vouchers are issued in response to
            voucher-requests, and it is the contents of the voucher-requests
            which determines how meaningful the audit log entries are.
          </t>
          <t>A registrar SHOULD use the log information to make an informed decision
          regarding the continued bootstrapping of the pledge. The exact policy is
          out of scope of this document as it depends on the security requirements
          within the registrar domain. Equipment that is purchased pre-owned can be
          expected to have an extensive history.  The following discussion is provided to help
          explain the value of each log element:</t>
          <t><list style="hanging">
            <t hangText="date:">The date field provides the registrar an
              opportunity to divide the log around known events such as
              the purchase date. Depending on context known to the registrar
              or administrator events before/after certain dates can
              have different levels of importance. For example for equipment
              that is expected to be new, and thus have no history, it
              would be a surprise to find prior entries.</t>
            <t hangText="domainID:"> If the log includes an unexpected domainID
              then the pledge could have imprinted on an unexpected domain. The
              registrar can be expected to use a variety of techniques to
              define "unexpected" ranging from white lists of prior
              domains to anomaly detection (e.g. "this device was previously
              bound to a different domain than any other device deployed"). Log
              entries can also be compared against local history logs in search of
              discrepancies (e.g. "this device was re-deployed some number of times
              internally but the external audit log shows additional re-deployments
              our internal logs are unaware of").</t>
            <t hangText="nonce:">Nonceless entries mean the logged domainID could
              theoretically trigger a reset of the pledge and then take over management
              by using the existing nonceless voucher.</t>
            <t hangText="assertion:">The assertion leaf in the voucher and
            audit log indicates why the MASA issued the voucher.
              A "verified" entry means that
              the MASA issued the associated voucher as a result of positive
              verification of ownership.
              However, this entry does not indicate whether the pledge was
              actually deployed in the prior domain, or not.
              A "logged" assertion informs
              the registrar that the prior vouchers were issued with
              minimal verification. A "proximity" assertion
              assures the registrar that the pledge was truly communicating
              with the prior domain and thus provides assurance that the
              prior domain really has deployed the pledge.</t>
          </list></t>
          <t>
            A relatively simple policy is to white list known (internal or
            external) domainIDs, and require all vouchers to have a nonce.
            An alternative is to require that all nonceless vouchers be from a
            subset (e.g. only internal) of domainIDs.
            If the policy is violated a simple action is to revoke any
            locally issued credentials for the pledge in question or to
            refuse to forward the voucher.  The Registrar MUST then refuse
            any EST actions, and SHOULD inform a human via a log.
            A registrar MAY be configured to ignore (i.e. override the above
            policy) the
            history of the device but it is RECOMMENDED that this only be
            configured if hardware assisted (i.e. TPM anchored) Network
            Endpoint Assessment (NEA) <xref target="RFC5209" /> is supported.
          </t>
        </section>
      </section>

      <section anchor="ESTintegration" title="EST Integration for PKI bootstrapping">
        <t>The pledge SHOULD follow the BRSKI operations with EST enrollment operations
        including "CA Certificates Request", "CSR Attributes" and "Client Certificate Request"
        or "Server-Side Key Generation", etc. This is a relatively seamless integration
        since BRSKI API calls provide an automated alternative to the manual bootstrapping method
        described in <xref target="RFC7030"></xref>. As noted above, use of HTTP persistent
        connections simplifies the pledge state machine.</t>

        <!-- dealing with: https://github.com/anima-wg/anima-bootstrap/issues/24 -->
        <t>
          Although EST allows clients to obtain multiple certificates by sending
          multiple Certificate Signing Requests (CSR) requests, BRSKI does not support this mechanism directly.
          This is because BRSKI pledges MUST use the CSR Attributes request
          (<xref target="RFC7030" /> section 4.5).
          The registrar MUST validate the CSR against the expected
          attributes. This implies that client requests will "look the same"
          and therefore result in a single logical certificate being issued
          even if the client were to make multiple requests. Registrars MAY
          contain more complex logic but doing so is out-of-scope of this
          specification.
          BRSKI does not signal any enhancement or restriction to this
          capability.
        </t>

        <section title="EST Distribution of CA Certificates">
          <t>The pledge SHOULD request the full EST Distribution of CA
          Certificates message. See RFC7030, section 4.1.</t>

          <t>This ensures that the pledge has the complete set of current CA
          certificates beyond the pinned-domain-cert (see <xref
          target="PledgeAuthenticationOfProvisionalTLS" /> for a discussion of the
          limitations inherent in having a single certificate instead of a full
          CA Certificates response.) Although these limitations are acceptable during initial bootstrapping, they are not appropriate for ongoing PKIX end entity certificate validation.</t>
        </section>

        <section anchor="csrattributes" title="EST CSR Attributes">
          <t>Automated bootstrapping occurs without local administrative
          configuration of the pledge. In some deployments it is plausible that
          the pledge generates a certificate request containing only identity
          information known to the pledge (essentially the X.509 IDevID information)
          and ultimately receives a certificate containing domain specific
          identity information. Conceptually the CA has complete control over
          all fields issued in the end entity certificate. Realistically this
          is operationally difficult with the current status of PKI
          certificate authority deployments, where the CSR is submitted to the
          CA via a number of non-standard protocols. Even with all
          standardized protocols used, it could operationally be problematic
          to expect that service specific certificate fields can be created
          by a CA that is likely operated by a group that has no insight
          into different network services/protocols used. For example, the
          CA could even be outsourced.</t>

          <t>To alleviate these operational difficulties, the pledge MUST
          request the
          EST "CSR Attributes" from the EST server and the EST server needs
          to be able to reply with the attributes necessary for use of
          the certificate in its intended protocols/services. This approach
          allows for minimal CA integrations and instead
          the local infrastructure (EST server) informs the pledge of the proper
          fields to include in the generated CSR (such as rfc822Name).
          This approach is beneficial
          to automated bootstrapping in the widest number of environments.</t>

          <t>
            In networks using the BRSKI enrolled certificate to authenticate
            the ACP (Autonomic Control Plane), the EST CSR attributes MUST include
            the ACP Domain Information Fields defined in
            <xref target="I-D.ietf-anima-autonomic-control-plane" /> section 6.1.1.
          </t>

          <t>The registrar MUST also confirm that the resulting CSR is formatted as
          indicated before forwarding the request to a CA. If the registrar is
          communicating with the CA using a protocol such as full CMC, which
          provides mechanisms to override the CSR attributes, then these
          mechanisms MAY be used even if the client ignores CSR Attribute
          guidance.</t>
        </section>

        <section title="EST Client Certificate Request">
          <t>The pledge MUST request a new client certificate. See RFC7030,
          section 4.2.</t>
        </section>

        <section title="Enrollment Status Telemetry">
          <t>
            For automated bootstrapping of devices, the administrative elements
            providing bootstrapping also provide indications to the system
            administrators concerning device lifecycle status.
            This might include information concerning attempted bootstrapping
            messages seen by the client.
            The MASA provides logs and status of credential
            enrollment.
            <xref target="RFC7030" /> assumes an end user and therefore does
            not include a final success indication back to the server. This is
            insufficient for automated use cases.
          </t>

          <t>
            The client MUST send an indicator to the Registrar about its
            enrollment status.  It does this by using an HTTP POST of
            a JSON dictionary with the of attributes described below to
            the new EST endpoint at "/.well-known/brski/enrollstatus". (XXX ?)
          </t>

          <t>
            When indicating a successful enrollment the client SHOULD first
            re-establish the EST TLS session using the newly obtained
            credentials. TLS 1.2 supports doing this in-band, but
            TLS 1.3 does not.  The client SHOULD therefore always close the existing
            TLS connection, and start a new one.
          </t>

          <t>
            In the case of a failed enrollment, the client MUST send the
            telemetry information over the same TLS
            connection that was used for the enrollment attempt, with a
            Reason string indicating why the most recent enrollment failed.
            (For failed attempts, the TLS connection is the most reliable way
            to correlate server-side information with what the client provides.)
          </t>
          <t>
            The version and status fields MUST be present.  The Reason field SHOULD be present
            whenever the status field is false.
            In the case of a SUCCESS the Reason string MAY be omitted.
          </t>
          <t>
            The reason-context attribute is an arbitrary JSON object (literal
            value or hash of values) which provides additional information
            specific to the failure to unroll from this pledge.
            The contents of this field are not subject to
            standardization. This is represented by the group-socket
            "$$arbitrary-map" in the CDDL.
          </t>

          <t>
            In the case of a SUCCESS the Reason string is omitted.
          </t>

          <t><figure anchor="cddl-enrollstatus" title="CDDL for enrollment status POST">
INSERT_CODE_FROM_FILE enrollstatus.cddl END
          </figure></t>


          <t>
            An example status report can be seen below.  It is sent with
            with the media type: application/json
          </t>

          <t><figure anchor="example-enrollstatus" title="Example of
                                                          enrollment status POST">
INSERT_CODE_FROM_FILE example-enrollstatus.json END
          </figure></t>

          <t>The server SHOULD respond with an HTTP 200 but MAY simply fail
          with an HTTP 404 error.</t>

          <t>
            Within the server logs the server MUST capture if this message
            was received over an TLS session with a matching client
            certificate.
          </t>
        </section>

        <section title="Multiple certificates">
          <t>
            Pledges that require multiple certificates could establish
            direct EST connections to the registrar.
          </t>
        </section>

        <section title="EST over CoAP">
          <t>This document describes extensions to EST for the purposes
              of bootstrapping of remote key infrastructures.
              Bootstrapping is relevant for CoAP enrollment
              discussions as well. The definition of EST and BRSKI over CoAP is not
              discussed within this document beyond ensuring proxy support for
              CoAP operations. Instead it is anticipated that a definition of
              CoAP mappings will occur in subsequent documents such as
              <xref target="I-D.ietf-ace-coap-est"></xref> and that
              CoAP mappings for BRSKI will be discussed either there or
              in future work.</t>
        </section>
      </section>
    </section>

    <section anchor="estbase64"
             title="Clarification of transfer-encoding">
      <t>
        <xref target="RFC7030" /> defines its endpoints to include a
        "Content-Transfer-Encoding" heading, and the payloads to be
        <xref target="RFC4648" /> Base64 encoded DER.
      </t>
      <t>
        When used within BRSKI, the original RFC7030 EST endpoints remain
        Base64 encoded, but the new BRSKI end points which send and receive binary
        artifacts (specifically, "/.well-known/brski/requestvoucher") are
        binary. That is, no encoding is used.
      </t>
      <t>
        In the BRSKI context, the EST "Content-Transfer-Encoding" header
        field if present, SHOULD be ignored. This header field does not need
        to be included.
      </t>
    </section>

    <section anchor="reducedsecuritymodes"
             title="Reduced security operational modes">
      <t>
        A common requirement of bootstrapping is to support less secure operational
        modes for support specific use cases.  This section suggests a range of
        mechanisms that would alter the security assurance of BRSKI to accommodate
        alternative deployment architectures and mitigate lifecycle management issues
        identified in <xref target="privacyconsiderations" />.  They are presented here as informative
        (non-normative) design guidance for future standardization
        activities.
        <xref target="acpapplicability" /> provides standardization applicability statements
        for the ANIMA ACP.  Other users
        would be expected that subsets of these mechanisms could be profiled with an
        accompanying applicability statements similar to the one described in
        <xref target="acpapplicability" />.
      </t>
      <t>
        This section is considered non-normative in the generality of the
        protocol.  Use of the suggested mechanisms here MUST be detailed in
        specific profiles of BRSKI, such as in <xref target="acpapplicability" />.
      </t>

      <section title="Trust Model">
        <t>
        This section explains the trust relationships detailed in <xref
        target="flow" />:
        </t>
        <figure>
          <artwork><![CDATA[
+--------+         +---------+    +------------+     +------------+
| Pledge |         | Join    |    | Domain     |     |Manufacturer|
|        |         | Proxy   |    | Registrar  |     | Service    |
|        |         |         |    |            |     | (Internet) |
+--------+         +---------+    +------------+     +------------+
              ]]></artwork>

          <postamble>Figure 10</postamble>
        </figure>

        <t><list style="hanging">
            <t hangText="Pledge:">The pledge could be compromised and
            providing an attack vector for malware. The entity is trusted to
            only imprint using secure methods described in this document.
            Additional endpoint assessment techniques are RECOMMENDED but are
            out-of-scope of this document.</t>

            <t hangText="Join Proxy:">Provides proxy functionalities but is not
            involved in security considerations.</t>

            <t hangText="Registrar:">When interacting with a MASA a
            registrar makes all decisions. For Ownership Audit Vouchers (see <xref target="RFC8366" />) the registrar is provided an opportunity to
            accept MASA decisions.</t>

            <t hangText="Vendor Service, MASA:">This form of manufacturer service is
            trusted to accurately log all claim attempts and to provide
            authoritative log information to registrars. The MASA does not
            know which devices are associated with which domains. These claims
            could be strengthened by using cryptographic log techniques to
            provide append only, cryptographic assured, publicly auditable
            logs. </t>

            <t hangText="Vendor Service, Ownership Validation:">This form of
            manufacturer service is trusted to accurately know which device is owned
            by which domain.</t>
          </list></t>
      </section>

      <section anchor="pledgeReductions" title="Pledge security reductions">
        <t>
          The following is a list of alternative behaviours that the
          pledge can be programmed to implement.  These behaviours are not
          mutually exclusive, nor are they dependent upon each other.
          Some of these methods enable offline and emergency (touch based)
          deployment use cases.  Normative language is used as these behaviours
          are referenced in later sections in a normative fashion.

        <list style="numbers">
              <t>
                The pledge MUST accept nonceless vouchers. This allows for
                a use case where the registrar can not connect to the MASA
                at the deployment time.
                Logging and validity periods address the
                security considerations of supporting these use cases.
              </t>

              <t>
                Many devices already support "trust on first use" for
                physical interfaces such as console ports. This document does
                not change that reality. Devices supporting this protocol
                MUST NOT support "trust on first use" on network
                interfaces. This is because "trust on first use" over network
                interfaces would undermine the logging based security
                protections provided by this specification.
              </t>
              <t>
                The pledge MAY have an operational mode where it skips voucher
                validation one time. For example if a physical button is
                depressed during the bootstrapping operation. This can be
                useful if the manufacturer service is unavailable. This
                behavior SHOULD be available via local configuration or
                physical presence methods (such as use of a serial/craft
                console) to ensure new entities can always be deployed even
                when autonomic methods fail. This allows for unsecured
                imprint.
              </t>
              <t>
                A craft/serial console could include a command such as
                "est-enroll [2001:db8:0:1]:443" that begins the
                EST process from the point after the voucher is validated.
                This process SHOULD include server certificate verification using
                an on-screen fingerprint.
              </t>
            </list>
          </t>

        <t>It is RECOMMENDED that "trust on first use" or any method of skipping voucher
        validation (including use of craft serial console) only be available if hardware assisted Network Endpoint
        Assessment (NEA: <xref target="RFC5209" />)
        is supported. This recommendation ensures that domain network monitoring
        can detect inappropriate use of offline or emergency
        deployment procedures when voucher-based bootstrapping is not used.</t>
      </section>

      <section title="Registrar security reductions">
        <t>
          A registrar can choose to accept devices using less secure methods.
          They MUST NOT be the default behavior.
          These methods may be acceptable in situations where threat
          models indicate that low security is adequate.
          This includes situations where security decisions are being made by
          the local administrator:
          <list style="numbers">
            <t>A registrar MAY choose to accept all devices, or all devices of
            a particular type, at the administrator's discretion. This could
            occur when informing all registrars of unique identifiers of new
            entities might be operationally difficult.</t>

            <t>A registrar MAY choose to accept devices that claim a unique
            identity without the benefit of authenticating that claimed
            identity. This could occur when the pledge does not include an
            X.509 IDevID factory installed credential. New Entities without an
            X.509 IDevID credential MAY form the <xref
            target="RequestVoucherFromRegistrar"></xref> request using the
            <xref target="RequestVoucherFromMASA"></xref> format to ensure the
            pledge's serial number information is provided to the registrar
            (this includes the IDevID AuthorityKeyIdentifier value, which would
            be statically configured on the pledge.) The pledge MAY refuse to
            provide a TLS client certificate (as one is not available.) The
            pledge SHOULD support HTTP-based or certificate-less TLS
            authentication as described in EST RFC7030 section 3.3.2. A
            registrar MUST NOT accept unauthenticated New Entities unless it
            has been configured to do so by an administrator that has verified
            that only expected new entities can communicate with a registrar
            (presumably via a physically secured perimeter.)</t>

            <t>A registrar MAY submit a nonceless voucher-requests to the MASA
            service (by not including a nonce in the voucher-request.) The resulting
            vouchers can then be stored by the registrar until
            they are needed during bootstrapping operations. This is for use
            cases where the target network is protected by an air gap and
            therefore cannot contact the MASA service during pledge
            deployment.</t>

            <t>
              A registrar MAY ignore unrecognized nonceless log
              entries. This could occur when used equipment is purchased with a
              valid history being deployed in air gap networks that
              required offline vouchers.
            </t>

            <t>A registrar MAY accept voucher formats of future types that
              can not be parsed by the Registrar. This reduces the Registrar's
              visibility into the exact voucher contents but does not change
              the protocol operations.</t>
          </list></t>
      </section>

      <section anchor="masasecurityreductions" title="MASA security reductions">
        <t>
          Lower security modes chosen by the MASA service affect all device
          deployments unless the lower-security behavior is tied to specific
          device identities.
          The modes described below can be applied to specific devices
          via knowledge of what devices were sold.  They can also be
          bound to specific customers (independent of the device identity) by
          authenticating  the customer's Registrar.
        </t>

        <section anchor="masasecurityreduction_nonce" title="Issuing Nonceless vouchers">
          <t>
            A MASA has the option of not including a nonce in the voucher,
            and/or not requiring one to be present in the voucher-request. This
            results in distribution of a voucher that may never expire and in
            effect makes the specified Domain an always trusted entity to the
            pledge during any subsequent bootstrapping attempts. That a nonceless
            voucher was issued
            is captured in the log information so that the registrar
            can make appropriate security decisions when a pledge joins the
            Domain. Nonceless vouchers are useful to support use cases where registrars might
            not be online during actual device deployment.
          </t>
          <t>
            While a nonceless voucher may include an expiry date, a typical
            use for a nonceless voucher is for it to be long-lived.  If
            the device can be trusted to have an accurate clock (the MASA
            will know), then a nonceless voucher CAN be issued with a limited
            lifetime.
          </t>
          <t>
            A more typical case for a nonceless voucher is for use with
            offline onboarding scenarios where it is not possible to pass
            a fresh voucher-request to the MASA.  The use of a long-lived
            voucher also eliminates concern about the availability of the
            MASA many years in the future.  Thus many nonceless vouchers
            will have no expiry dates.
          </t>
          <t>
            Thus, the long lived nonceless voucher does not require the proof
            that the device is online.  Issuing such a thing is only accepted
            when the registrar is authenticated by the MASA and the
            MASA is authorized to provide this functionality to this
            customer.
            The MASA is RECOMMENDED to use this
            functionality only in concert with an enhanced level of ownership
            tracking, the details of which are out of scope for this document.
          </t>
          <t>
            If the pledge device is known to have
            a real-time-clock that is set from the factory, use of a voucher
            validity period is RECOMMENDED.
          </t>
        </section>

        <section anchor="masasecurityreduction_tofu" title="Trusting Owners on First Use">
          <t>
            A MASA has the option of not verifying ownership before
            responding with a voucher.
            This is expected to be a common operational model because
            doing so relieves the manufacturer providing MASA services from
            having
            to track ownership during shipping and supply chain and allows
            for a very low overhead MASA service. A registrar uses the audit
            log information as a defense in depth strategy to ensure that this
            does not occur unexpectedly (for example when purchasing new
            equipment the registrar would throw an error if any audit log
            information is reported.) The MASA SHOULD verify the
            'prior-signed-voucher-request' information for pledges that support
            that functionality. This provides a proof-of-proximity
            check that reduces the need for ownership verification.  The
            proof-of-proximity comes from the assumption that the pledge and
            Join Proxy are on the same link-local connection.
          </t>
          <t>
            A MASA that practices Trust-on-First-Use (TOFU) for Registrar
            identity may wish to annotate the origin of the connection
            by IP address or netblock, and restrict future use of that
            identity from other locations.  A MASA that does this SHOULD
            take care to not create nuisance situations for itself when
            a customer has multiple registrars, or uses outgoing IPv4 NAT44
            connections that change frequently.
          </t>
        </section>

        <section anchor="masasecurityreduction_newanchor"
                 title="Updating or extending voucher trust anchors">
          <t>
            This section deals with the problem of a MASA that is no longer
            available due to a failed business, or the situation where a
            MASA is uncooperative to a secondary sale.
          </t>
          <t>
            A manufacturer could offer a management mechanism that allows the
            list of voucher verification trust anchors to be extended.
            <xref target="I-D.ietf-netconf-keystore" /> is one such interface
            that could be implemented using YANG.  Pretty much any
            configuration mechanism used today could be extended to
            provide the needed additional update.
            A manufacturer could even decide to install the domain CA
            trust anchors received during the EST "cacerts" step as voucher
            verification anchors. Some additional signals will be needed to
            clearly identify which keys have voucher validation authority from
            among those signed by the domain CA. This is future work.
          </t>
          <t>
            With the above change to the list of anchors, vouchers can be
            issued by an alternate MASA.  This could be the previous owner
            (the seller), or some other trusted third party who is mediating
            the sale.  If it was a third party, then the seller would need
            to have taken steps to introduce the third party configuration to
            the device prior disconnection.  The third party
            (e.g. a wholesaler of used equipment) could however
            use a mechanism described in <xref target="pledgeReductions" />
            to take control of the device after receiving it physically.
            This would permit the third party to act as the MASA for future
            onboarding actions.  As the IDevID certificate probably can not
            be replaced, the new owner's Registrar would have to support
            an override of the MASA URL.
          </t>
          <t>
            To be useful for resale or other transfers of ownership one of
            two situations will need to occur.  The simplest is that the
            device is not put through any kind of factory default/reset
            before going through onboarding again.  Some other secure, physical
            signal would be needed to initiate it.  This is most suitable for
            redeploying a device within the same Enterprise.  This would
            entail having previous configuration in the system until entirely
            replaced by the new owner, and represents some level of risk.
          </t>
          <t>
            The second mechanism is that there would need to be two levels
            of factory reset.  One would take the system back entirely to
            manufacturer state, including removing any added trust anchors,
            and the second (more commonly used) one would just restore the
            configuration back to a known default without erasing trust
            anchors.  This weaker factory reset might leave valuable
            credentials on the device and this may be unacceptable to
            some owners.
          </t>
          <t>
            As a third option, the manufacturer's trust anchors could be
            entirely overwritten with local trust anchors.  A factory default
            would never restore those anchors.  This option comes with a lot
            of power, but also a lot of responsibility: if access to
            the private part of the new anchors
            are lost the manufacturer may be unable to help.
          </t>
        </section>
      </section>
    </section>

    <section title="IANA Considerations">
      <t>This document requires the following IANA actions:</t>

      <section title="The IETF XML Registry">
        <t>
          This document registers a URI in the "IETF XML
          Registry" <xref target="RFC3688"/>.
          IANA is asked to register the following:</t>
          <t>
            <figure>                                                                                            <artwork><![CDATA[
URI: urn:ietf:params:xml:ns:yang:ietf-voucher-request
Registrant Contact: The ANIMA WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
            ]]></artwork>
      </figure>
          </t>
      </section>

      <section title="YANG Module Names Registry">
        <t>
          This document registers a YANG module in the
          "YANG Module Names" registry <xref target="RFC6020"/>.
          IANA is asked to register the following:</t>
          <t>
            <figure>
              <artwork><![CDATA[
name:         ietf-voucher-request
namespace:    urn:ietf:params:xml:ns:yang:ietf-voucher-request
prefix:       vch
reference:    THIS DOCUMENT
              ]]></artwork>
            </figure>
          </t>
      </section>

      <section title="BRSKI well-known considerations">
        <section title="BRSKI .well-known registration">
          <t>
            To the Well-Known URIs Registry, at:
            "https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml",
            this document registers the well-known name "brski" with the
            following filled-in template from <xref target="RFC5785" />:
            <figure>
              <artwork><![CDATA[
                URI suffix: brski
                Change Controller: IETF
              ]]></artwork>
            </figure>
          </t>
          <t>
            IANA is asked to change the registration of "est" to now only
            include RFC7030 and no longer this document.
            Earlier versions of this document used "/.well-known/est" rather
            than "/.well-known/brski".
          </t>
         </section>

        <section title="BRSKI .well-known registry">
          <t>
            IANA is requested to create a new Registry entitled: "BRSKI well-known URIs".
            The registry shall have at least three columns:  URI, description, and reference.
            New items can be added using the Specification Required process.
            The initial contents of this registry shall be:

            <figure>
              <artwork><![CDATA[
URI               document  description
requestvoucher	[THISRFC] pledge to registrar, and registrar to MASA
voucher_status	[THISRFC] pledge to registrar
requestauditlog	[THISRFC] registrar to MASA
enrollstatus	[THISRFC] pledge to registrar
              ]]></artwork>
            </figure>
          </t>
        </section>
      </section>

      <section title="PKIX Registry">
        <t>IANA is requested to register the following:</t>
        <t>
          This document requests a number for id-mod-MASAURLExtn2016(TBD)
          from the pkix(7) id-mod(0) Registry.
        </t>
        <t>
          This document has received an early allocation from the id-pe registry
          (SMI Security for PKIX Certificate Extension) for id-pe-masa-url
          with the value 32, resulting in an OID of 1.3.6.1.5.5.7.1.32.
        <!-- https://www.iana.org/assignments/smi-numbers/smi-numbers.xml#smi-numbers-1.3.6.1.5.5.7.1 -->

        </t>
      </section>
      <section anchor="pledgestatustelemetryregistry" title="Pledge BRSKI Status Telemetry">
        <t>
          IANA is requested to create a new Registry entitled: "BRSKI
          Parameters", and within that Registry to create a table called:
          "Pledge BRSKI Status Telemetry Attributes".
          New items can be added using the Specification Required process.
          The following items are to be in the
          initial registration, with this document (<xref target="pledgestatus" />) as the reference:
          <list style="symbols">
          <t>version</t>
          <t>Status</t>
          <t>Reason</t>
          <t>reason-context</t>
        </list></t>
      </section>
      <section title="DNS Service Names">
        <t>IANA is requested to register the following Service Names:</t>
        <figure>
          <artwork><![CDATA[
Service Name: brski-proxy
Transport Protocol(s): tcp
Assignee: IESG <iesg@ietf.org>.
Contact: IESG <iesg@ietf.org>
Description: The Bootstrapping Remote Secure Key
             Infrastructures Proxy
Reference: [This document]

Service Name: brski-registrar
Transport Protocol(s): tcp
Assignee: IESG <iesg@ietf.org>.
Contact: IESG <iesg@ietf.org>
Description: The Bootstrapping Remote Secure Key
             Infrastructures Registrar
Reference: [This document]
          ]]></artwork>
        </figure>
      </section>

      <section title="GRASP Objective Names">
        <t>IANA is requested to register the following GRASP Objective
        Names:</t>

        <t>
          The IANA is requested to register the value "AN_Proxy" (without quotes)
          to the GRASP Objectives Names Table in the GRASP Parameter Registry.
          The specification for this value is this document, <xref
          target="brskigrasp" />.
        </t>
        <t>
          The IANA is requested to register the value "AN_join_registrar" (without quotes)
          to the GRASP Objectives Names Table in the GRASP Parameter Registry.
          The specification for this value is this document, <xref
          target="JRCgrasp" />.
        </t>
      </section>


    </section>
    <section anchor="acpapplicability"
             title="Applicability to the Autonomic Control Plane (ACP)">
      <t>
        This document provides a solution to the requirements for secure
        bootstrap set out in <xref target="RFC8368">Using an Autonomic Control Plane for
        Stable Connectivity of Network Operations, Administration, and
        Maintenance </xref>,
        <xref target="I-D.ietf-anima-reference-model" >A Reference Model for
        Autonomic Networking</xref> and specifically the
        <xref target="I-D.ietf-anima-autonomic-control-plane">An Autonomic
        Control Plane (ACP)</xref>, section 3.2 (Secure Bootstrap), and
        section 6.1 (ACP Domain, Certificate and Network).
      </t>
      <t>
        The protocol described in this document has appeal in a number of
        other non-ANIMA use cases.  Such uses of the protocol will be
        deploying into other environments with different tradeoffs of
        privacy, security, reliability and autonomy from manufacturers.
        As such those use cases will need to provide their own applicability
        statements, and will need to address unique privacy and security
        considerations for the environments in which they are used.
      </t>
      <t>
        The autonomic control plane (ACP) that is bootstrapped by
        the BRSKI protocol is typically used in medium to large Internet
        Service Provider organizations. Equivalent enterprises that have
        significant layer-3 router connectivity also will find significant
        benefit, particularly if the Enterprise has many sites.
        (A network consisting of primarily layer-2
        is not excluded, but the adjacencies that the ACP will create and
        maintain will not reflect the topology until all devices participate
        in the ACP).
      </t>
      <t>
        In the ACP, the Join Proxy is found to be proximal because
        communication between the pledge and the join proxy is exclusively
        on IPv6 Link-Local addresses.  The proximity of the
        Join Proxy to the Registrar is validated by the Registrar using ANI
        ACP IPv6 Unique Local Addresses (ULA).
        ULAs are not routable over the Internet, so as long as the Join
        Proxy is operating correctly the proximity asssertion is satisfied.
        Other uses of BRSKI will need make similar analysis if they
        use proximity assertions.
      </t>
      <t>
        As specified in the ANIMA charter, this work "..focuses on
        professionally-managed networks."  Such a network has an operator
        and can do things like install, configure and operate the
        Registrar function.  The operator makes purchasing decisions
        and is aware of what manufacturers it expects to see on its
        network.
      </t>
      <t>
        Such an operator is also capable of performing bootstrapping of a
        device using a serial-console (craft console). The zero-touch
        mechanism presented in this and the ACP document <xref target="I-D.ietf-anima-autonomic-control-plane" />
        represents a
        significiant efficiency: in particular it reduces the need to
        put senior experts on airplanes to configure devices in person.
      </t>
      <t>
        There is a recognition as the technology evolves that not every
        situation may work out, and occasionally a human may still have to
        visit.  In recognition of this, some mechanisms are presented in
        <xref target="pledgeReductions" />. The manufacturer MUST provide at
        least one of the one-touch mechanisms described that permit
        enrollment to be proceed without availability of any manufacturer
        server (such as the MASA).
      </t>
      <t>
        The BRSKI protocol is going into environments where there have
        already been quite a number of vendor proprietary management
        systems.  Those are not expected to go away quickly, but rather to
        leverage the secure credentials that are provisioned by BRSKI.  The
        connectivity requirements of said management systems are provided
        by the ACP.
      </t>
      <section anchor="operationalrequirements" title="Operational Requirements">
        <t>
          This section collects operational requirements based upon the three
          roles involved in BRSKI: The Manufacturer Authorized Signing
          Authority (MASA), the (Domain) Owner and the Device.
          It should be recognized that the manufacturer may be involved in two
          roles, as it creates the software/firmware for the device, and also
          may be the operator of the MASA.
        </t>
        <t>
          The requirements in this section are presented using BCP14
          (<xref target="RFC2119"></xref>, <xref target="RFC8174"></xref>)
          language.  These do not represent new normative statements, just a
          review of a few such things in one place by role.  They also apply
          specifically to the ANIMA ACP use case.  Other use cases likely
          have similar, but MAY have different requirements.
        </t>
        <section anchor="masarequirements" title="MASA Operational Requirements">
          <t>
            The manufacturer MUST arrange for an online service to be available
            called the MASA. It MUST be available at the URL which is encoded
            in the IDevID certificate extensions described in <xref target="MASAURL"/>.
          </t>
          <t>
            The online service MUST have access to a private key with which to
            sign <xref target="RFC8366"/> format voucher artifacts.  The public
            key, certificate, or certificate chain MUST be built in to the
            device as part of the firmware.
          </t>
          <t>
            It is RECOMMENDED that the manufacturer arrange for this signing
            key (or keys) to be escrowed according to typical software source
            code escrow practices <xref target="softwareescrow" />.
          </t>
          <t>
            The MASA accepts voucher requests from Domain Owners according to
            an operational practice appropriate for the device.  This can range
            from any domain owner (first-come first-served, on a TOFU-like
            basis), to full sales channel integration where Domain Owners need
            to be positively identified by TLS Client Certicate pinned, or HTTP
            Authentication process.  The MASA creates signed voucher artifacts
            according to its internally defined policies.
          </t>
          <t>
            The MASA MUST operate an audit log for devices that is accessible.
            The audit log is designed to be easily cacheable and the MASA MAY
            find it useful to put this content on a CDN.
          </t>
        </section>
        <section anchor="domainownerrequirements" title="Domain Owner Operational Requirements">
          <t>
            The domain owner MUST operate an EST (<xref target="RFC7030" />)
            server with the extensions described in this document.  This is
            the JRC or Registrar.  This JRC/EST
            server MUST announce itself using GRASP within the ACP.  This EST
            server will typically reside with the Network Operations Center for
            the organization.
          </t>
          <t>
            The domain owner MAY operate an internal certificate authority (CA) that
            is seperate from the EST server, or it MAY combine all activities
            into a single device.  The determination of the architecture
            depends upon the scale and resiliency requirements of the
            organization.  Multiple JRC instances MAY be announced into the ACP
            from multiple locations to achieve an appropriate level of
            redundancy.
          </t>
          <t>
            In order to recognize which devices and which manufacturers are
            welcome on the domain owner's network, the domain owner SHOULD
            maintain a white list of manufacturers.  This MAY extend to
            integration with purchasing departments to know the serial numbers
            of devices.
          </t>
          <t>
            The domain owner SHOULD use the resulting overlay ACP network to
            manage devices, replacing legacy out-of-band mechanisms.
          </t>
          <t>
            The domain owner SHOULD operate one or more EST servers which can
            be used to renew the domain certificates (LDevIDs) which are
            deployed to devices.  These servers MAY be the same as the JRC, or
            MAY be a distinct set of devices, as approriate for resiliency.
          </t>
          <t>
            The organization MUST take appropriate precautions against loss of
            access to the certificate authority private key.  Hardware security
            modules and/or secret splitting are appropriate.
          </t>
        </section>
        <section anchor="devicerequirements" title="Device Operational Requirements">
          <t>
            Devices MUST come with built-in trust anchors that permit the device to
            validate vouchers from the MASA.
          </t>
          <t>
            Device MUST come with (unique, per-device) IDevID certificates that
            include their serial numbers, and the MASA URL extension.
          </t>
          <t>
            Devices are expected to find Join Proxies using GRASP, and then connect
            to the JRC using the protocol described in this document.
          </t>
          <t>
            Once a domain owner has been validated with the voucher, devices
            are expected to enroll into the domain using EST.  Devices are then
            expected to form ACPs using IPsec over IPv6 Link-Local addresses as
            described in  <xref target="I-D.ietf-anima-autonomic-control-plane" />.
          </t>
          <t>
            Once a device has been enrolled it SHOULD listen for the address
            of the JRC using GRASP, and it SHOULD enable itself as a Join
            Proxy, and announce itself on all links/interfaces using GRASP DULL.
          </t>
          <t>
            Devices are expected to renew their certificates before they
            expire.
          </t>
        </section>
      </section>
    </section>
    <section anchor="privacyconsiderations" title="Privacy Considerations">
      <section title="MASA audit log">
      <t>
        The MASA audit log includes the domainID for each
        domain a voucher has been issued to. This information is closely
        related to the actual domain identity.  A MASA may need additional
        defenses against Denial of Service attacks (<xref target="dosmasa" />),
        and this may involve collecting additional (unspecified here)
        information. This could provide sufficient information for the MASA
        service to build a detailed understanding the devices that have been
        provisioned within a domain.
      </t>

      <t>
        There are a number of design choices that mitigate this
        risk. The domain can maintain some privacy since it has not necessarily
        been authenticated and is not authoritatively bound to the supply
        chain.
      </t>
      <t>
        Additionally the domainID captures only the unauthenticated
        subject key identifier of the domain. A privacy sensitive domain could
        theoretically generate a new domainID for each device being
        deployed. Similarly a privacy sensitive domain would likely purchase
        devices that support proximity assertions from a manufacturer that does
        not require sales channel integrations. This would result in a
        significant level of privacy while maintaining the security
        characteristics provided by Registrar based audit log inspection.
      </t>
      </section>

        <section anchor="idevidregistrar"
                 title="What BRSKI-EST reveals">
          <t>
            During the provisional phase of the BRSKI-EST connection between
            the Pledge and the Registrar, each party reveals its
            certificates to each other.  For the Pledge, this includes the
            serialNumber attribute, the MASA URL, and the identity that
            signed the IDevID certificate.
          </t>
          <t>
            TLS 1.2 reveals the certificate identities to on-path observers,
            including the Join Proxy.
          </t>
          <t>
            TLS 1.3 reveals the certificate identities only to the end
            parties, but as the connection is provisional, an on-path
            attacker (MTIM) can see the certificates.  This includes not just
            malicious attackers, but also Registrars that are visible
            to the Pledge, but which are not part of the intended domain.
          </t>
          <t>
            The certificate of the Registrar is rather arbitrary from the
            point of view of the BRSKI protocol. As no <xref target="RFC6125" />
            validations are expected to be done, the contents could be easily
            pseudonymized.  Any device that can see a join proxy would be
            able to connect to the Registrar and learn the identity of the
            network in question.  Even if the contents of the certificate
            are pseudonymized, it would be possible to correlate different
            connections in different locations belong to the same
            entity. This is unlikely to present a significant privacy concern
            to ANIMA ACP uses of BRSKI, but may be a concern to other users
            of BRSKI.
          </t>
          <t>
            The certificate of the Pledge could be revealed by a malicious
            Join Proxy that performed a MITM attack on the provisional TLS
            connection.   Such an attacker would be able to reveal the
            identity of the Pledge to third parties if it chose to so.
          </t>
          <t>
            Research into a mechanism to do multi-step, multi-party authenticated
            key agreement, incorporating some kind of zero-knowledge proof
            would be valuable.  Such a mechanism would ideally avoid
            disclosing identities until pledge, registrar and MASA agree to
            the transaction.  Such a mechanism would need to discover the
            location of the MASA without knowing the identity of the pledge,
            or the identity of the MASA.  This part of the problem may be unsolveable.
          </t>
        </section>

        <section anchor="idevidprivacy" title="What BRSKI-MASA reveals to the manufacturer">
          <t>
            With consumer-oriented devices, the "call-home" mechanism in IoT
            devices raises significant privacy concerns.  See
            <xref target="livingwithIoT" /> and <xref
            target="IoTstrangeThings" /> for exemplars.  The Autonomic Control
            Plane (ACP) usage of BRSKI is not targeted at individual usage of
            IoT devices, but rather at the Enterprise and ISP creation of
            networks in a zero-touch fashion where the "call-home" represents
            a different class of privacy and lifecycle management concerns.
          </t>
          <t>
            It needs to be re-iterated that the BRSKI-MASA mechanism
            only occurs once during the commissioning of the device.  It is
            well defined, and although encrypted with TLS, it could in theory
            be made auditable as the contents are well defined.
            This connection does not occur when the device powers on or is
            restarted for normal routines.
            (It is conceivable, but remarkably unusual, that a device could
            be forced to go through a full factory reset during an exceptional firmware update
            situation, after which enrollment would have be repeated, and a
            new connection would occur)
          </t>
          <t>
            The BRSKI call-home mechanism is mediated via the owner's
            Registrar, and the information that is transmitted is directly
            auditable by the device owner.    This is in stark contrast to
            many "call-home" protocols where the device autonomously calls
            home and uses an undocumented protocol.
          </t>
          <t>
            While the contents of the signed part of the pledge voucher request
            can not be changed, they are not encrypted at the registrar.
            The ability to audit the messages by the owner of the network
            is a mechanism to defend against exfiltration of data by a nefarious
            pledge. Both are, to re-iterate, encrypted by TLS while in transit.
          </t>
          <t>
            The BRSKI-MASA exchange reveals the following information to the
            manufacturer:
            <list style="symbols">
              <t>
                the identity of the device being enrolled.  This is revealed
                by transmission of a signed voucher-request containing the
                serial-number.  The manufacturer can usually link the serial
                number to a device model.
              </t>
              <t>
                an identity of the domain owner in the form of the domain
                trust anchor.  However, this is not a global PKI anchored
                name within the WebPKI, so this identity could be
                pseudonymous.  If there is sales channel integration, then
                the MASA will have authenticated the domain owner, either via
                pinned certificate, or perhaps another HTTP authentication
                method, as per <xref target="MASAauthenticationOfRegistrar" />.
              </t>
              <t>
                the time the device is activated,
              </t>
              <t>
                the IP address of the domain Owner's Registrar.
                For ISPs and Enterprises, the IP address provides very clear
                geolocation of the owner.  No amount of IP address privacy
                extensions (<xref target="RFC4941"/>) can do anything about
                this, as a simple whois lookup likely identifies the ISP or
                Enterprise from the upper bits anyway.  A passive attacker
                who observes the connection definitely may conclude that the
                given enterprise/ISP is a customer of the particular
                equipment vendor.  The precise model that is being enrolled
                will remain private.
              </t>
            </list>
          </t>
          <t>
            Based upon the above information, the manufacturer is able to
            track a specific device from pseudonymous domain identity to the
            next pseudonymous domain identity.  If there is sales-channel
            integration, then the identities are not pseudonymous.
          </t>
          <t>
            The manufacturer knows the IP address of the Registrar, but it
            can not see the IP address of the device itself.  The
            manufacturer can not track the device to a detailed physical
            or network location, only to the location of the Registrar.
            That is likely to be at the Enterprise or ISPs headquarters.
          </t>
          <t>
            The above situation is to be distinguished from a
            residential/individual person who registers a device from a
            manufacturer.  Individuals do not tend to have multiple offices,
            and their registrar is likely on the same network as the device.
            A manufacturer that sells switching/routing products to enterprises
            should hardly be surprised if additional purchases
            switching/routing products are made.
            Deviations from a historical trend or
            an establish baseline would, however, be notable.
          </t>
          <t>
            The situation is not improved by the enterprise/ISP using
            anonymization services such as
            <xref target="Dingledine2004">ToR</xref>, as a TLS 1.2 connection
            will reveal the ClientCertificate used, clearly identifying
            the enterprise/ISP involved.  TLS 1.3 is better in this regard,
            but an active attacker can still discover the parties involved by
            performing a Man-In-The-Middle-Attack on the first attempt
            (breaking/killing it with a TCP RST), and then letting subsequent
            connection pass through.
          </t>
          <t>
            A manufacturer could attempt to mix the BRSKI-MASA traffic in
            with general traffic their site by hosting the MASA behind the
            same (set) of load balancers that the companies normal marketing
            site is hosted behind.  This makes lots of sense from a straight
            capacity planning point of view as the same set of services
            (and the same set of Distributed Denial of Service mitigations)
            may be used.  Unfortunately, as the BRSKI-MASA connections
            include TLS ClientCertificate exchanges, this may easily be
            observed in TLS 1.2, and a traffic analysis may reveal it even in
            TLS 1.3.  This does not make such a plan irrelevant.  There may
            be other organizational reasons to keep the marketing site (which
            is often subject to frequent re-designs, outsourcing, etc.)
            separate from the MASA, which may need to operate reliably for
            decades.
          </t>
        </section>
        <section title="Manufacturers and Used or Stolen Equipment">
          <t>
            As explained above, the manufacturer receives information each
            time that a device which is in factory-default mode does a
            zero-touch bootstrap, and attempts to enroll into a domain
            owner's registrar.
          </t>
          <t>
            The manufacturer is therefore in a position to decline to
            issue a voucher if it detects that the new owner is not the
            same as the previous owner.
            <list style="numbers">
              <t>
                This can be seen as a feature if the equipment is believed to
                have been stolen.  If the legitimate owner notifies the
                manufacturer of the theft, then when the new owner brings the
                device up, if they use the zero-touch mechanism, the new
                (illegitimate) owner reveals their location and identity.
              </t>
              <t>
                In the case of Used equipment, the initial owner could inform
                the manufacturer of the sale, or the manufacturer may just
                permit resales unless told otherwise.  In which case, the
                transfer of ownership simply occurs.
              </t>
              <t>
                A manufacturer could however decide not to issue a new
                voucher in response to a transfer of ownership.
                This is essentially the same as the stolen case, with the
                manufacturer having decided that the sale was not legitimate.
              </t>
              <t>
                There is a fourth case, if the manufacturer is providing
                protection against stolen devices.  The manufacturer then
                has a responsibility to protect the legitimate owner against
                fraudulent claims that the equipment was stolen.
                In the absence of such manufacturer protection,
                such a claim would cause the manufacturer to refuse
                to issue a new voucher. Should the device go through
                a deep factory reset (for instance, replacement of a damaged
                main board component, the device would not bootstrap.
              </t>
              <t>
                Finally, there is a fifth case: the manufacturer has decided to
                end-of-line the device, or the owner has not paid a yearly
                support amount, and the manufacturer refuses to issue new
                vouchers at that point.  This last case is not new to the
                industry: many license systems are already deployed that have
                significantly worse effect.
              </t>
            </list>
          </t>
          <t>
            This section has outlined five situations in which a manufacturer
            could use the voucher system to enforce what are clearly
            license terms.
            A manufacturer that attempted to
            enforce license terms via vouchers would find it rather
            ineffective as the terms would only be enforced when the device
            is enrolled, and this is not (to repeat), a daily or even monthly
            occurrence.
          </t>
        </section>
        <section title="Manufacturers and Grey market equipment">
          <t>
            Manufacturers of devices often sell different products into
            different regional markets.  Which product is available in which
            market can be driven by price differentials, support issues (some
            markets may require manuals and tech-support to be done in the
            local language), government export regulation (such as whether
            strong crypto is permitted to be exported, or permitted to be
            used in a particular market).  When an domain owner obtains a
            device from a different market (they can be new) and transfers it
            to a different location, this is called a Grey Market.
          </t>
          <t>
            A manufacturer could decide not to issue a voucher to an
            enterprise/ISP based upon their location.  There are a number of
            ways which this could be determined: from the geolocation of the
            registrar, from sales channel knowledge about the customer, and
            what products are (un-)available in that market.  If the device
            has a GPS the coordinates of the device could even be placed into
            an extension of the voucher.
          </t>
          <t>
            The above actions are not illegal, and not new.  Many
            manufacturers have shipped crypto-weak (exportable) versions of
            firmware as the default on equipment for decades.  The first task
            of an enterprise/ISP has always been to login to a manufacturer
            system, show one's "entitlement" (country information, proof that
            support payments have been made), and receive either a new
            updated firmware, or a license key that will activate the correct
            firmware.
          </t>
          <t>
            BRSKI permits the above process to automated (in an autonomic
            fashion), and therefore perhaps encourages this kind of
            differentiation by reducing the cost of doing it.
          </t>
          <t>
            An issue that manufacturers will need to deal with in the above
            automated process is when a device is shipped to one country
            with one set of rules (or laws or entitlements), but the domain
            registry is in another one.  Which rules apply is something
            will have to be worked out: the manufacturer could come to
            believe they are dealing with Grey market equipment, when it
            is simply dealing with a global enterprise.
          </t>
        </section>
        <section title="Some mitigations for meddling by manufacturers">
          <t>
            The most obvious mitigation is not to buy the product.
            Pick manufacturers that are up-front about their policies, who do
            not change them gratuitously.
          </t>
          <t>
            <xref target="masasecurityreduction_newanchor" />
            describes some ways in which a manufacturer could provide a
            mechanism to manage the trust
            anchors and built-in certificates (IDevID) as an extension.
            There are a variety of mechanism, and some may take a substantial
            amount of work to get exactly correct.  These mechanisms do
            not change the flow of the protocol described here, but rather
            allow the starting trust assumptions to be changed.
            This is an area for
            future standardization work.
          </t>
          <t>
            Replacement of the voucher validation anchors (usually pointing
            to the original manufacturer's MASA) with those of the new
            owner permits the new owner to issue vouchers to subsequent
            owners. This would be done by having the selling (old) owner
            to run a MASA.
          </t>
          <t>
            The BRSKI protocol depends upon a trust anchor on the device
            and an identity on the device.  Management of these
            entities facilitates a few new operational modes without
            making any changes to the BRSKI protocol.  Those modes include:
            offline modes where the domain owner operates an internal
            MASA for all devices, resell modes where the first domain owner
            becomes the MASA for the next (resold-to) domain owner,
            and services where an aggregator acquires a large variety
            of devices, and then acts as a pseudonymized MASA for a variety
            of devices from a variety of manufacturers.
          </t>
          <t>
            Although replacement of the IDevID is not required for all
            modes described above, a manufacturers could support such a
            thing.   Some may wish to consider replacement of the IDevID
            as an indication that the device's warrantee is terminated.
            For others, the privacy requirements of some deployments might
            consider this a standard operating practice.
          </t>
          <t>
            As discussed at the end of <xref target="MASAauditlog" />,
            new work could be done to use a
            distributed consensus technology for the audit log.
            This would permit the audit log to continue to be useful,
            even when there is a chain of MASA due to changes of ownership.
          </t>

        </section>
        <section title="Death of a manufacturer">
          <t>
            A common concern has been that a manufacturer could go out of
            business, leaving owners of devices unable to get new vouchers
            for existing products.  Said products might have been previously
            deployed, but need to be re-initialized, they might have been
            purchased used, or they might have kept in a warehouse as
            long-term spares.
          </t>
          <t>
            The MASA was named the Manufacturer *Authorized* Signing
            Authority to emphasize that it need not be the manufacturer
            itself that performs this.  It is anticipated that specialist
            service providers will come to exist that deal with the creation
            of vouchers in much the same way that many companies have
            outsourced email, advertising and janitorial services.
          </t>
          <t>
            Further, it is expected that as part of any service agreement
            that the manufacturer would arrange to escrow appropriate private
            keys such that a MASA service could be provided by a third
            party.  This has routinely been done for source code for decades.
          </t>
        </section>
    </section>

    <section anchor="securityconsiderations" title="Security Considerations">
      <t>
        This document details a protocol for bootstrapping that balances
        operational concerns against security concerns. As detailed in the introduction,
        and touched on again in <xref target="reducedsecuritymodes"></xref>,
        the protocol allows for reduced security modes.
        These attempt to deliver additional
        control to the local administrator and owner in cases where
        less security provides operational benefits. This
        section goes into more detail about a variety of specific
        considerations.
      </t>
      <t>
        To facilitate logging and administrative oversight, in addition
        to triggering Registrar verification of MASA logs, the pledge reports
      on voucher parsing status to the registrar. In the case of a
      failure, this information is informative to a potentially malicious
      registrar. This is mandated anyway because of the operational
      benefits of an informed administrator in cases where the failure is
      indicative of a problem. The registrar is RECOMMENDED to verify MASA logs
      if voucher status telemetry is not received.</t>

      <t>To facilitate truly limited clients EST RFC7030 section 3.3.2
      requirements that the client MUST support a client authentication model
      have been reduced in <xref target="reducedsecuritymodes"></xref> to a
      statement that the registrar "MAY" choose to accept devices
      that fail cryptographic authentication. This reflects
      current (poor) practices in shipping devices without a cryptographic
      identity that are NOT RECOMMENDED.</t>

        <t>During the provisional period of the connection the pledge MUST treat all HTTP header and
        content data as untrusted data. HTTP libraries are
        regularly exposed to non-secured HTTP traffic: mature libraries
        should not have any problems.
        </t>

      <t>Pledges might chose to engage in protocol operations with
      multiple discovered registrars in parallel. As noted above they
      will only do so with distinct nonce values, but the end result
      could be multiple vouchers issued from the MASA if all registrars
      attempt to claim the device. This is not a failure and the pledge
      choses whichever voucher to accept based on internal logic. The
      registrars verifying log information will see multiple entries
      and take this into account for their analytics purposes.</t>
      <section anchor="dosmasa" title="Denial of Service (DoS) against MASA">
        <t>There are uses cases where the MASA could be unavailable or
        uncooperative to the Registrar. They include active DoS attacks, planned and unplanned
        network partitions, changes to MASA policy, or other instances where
        MASA policy rejects a claim. These introduce an operational risk to the
        Registrar owner in that MASA behavior might limit the ability to
        bootstrap a pledge device. For example this might be an issue during
        disaster recovery. This risk can be mitigated by Registrars that
        request and maintain long term copies of "nonceless" vouchers. In
        that way they are guaranteed to be able to bootstrap their devices.</t>

        <t>The issuance of nonceless vouchers themselves creates a security
        concern. If the Registrar of a previous domain can intercept protocol
        communications then it can use a previously issued nonceless voucher to
        establish management control of a pledge device even after having sold
        it. This risk is mitigated by recording the issuance of such vouchers
        in the MASA audit log that is verified by the subsequent Registrar
        and by Pledges only bootstrapping when in a factory default state. This
        reflects a balance between enabling MASA independence during
        future bootstrapping and the security of bootstrapping itself.
        Registrar control over requesting and auditing nonceless vouchers
        allows device owners to choose an appropriate balance.</t>

        <t>The MASA is exposed to DoS attacks wherein attackers claim
        an unbounded number of devices. Ensuring a registrar is
        representative of a valid manufacturer customer, even without validating
        ownership of specific pledge devices, helps to mitigate this. Pledge
        signatures on the pledge voucher-request, as forwarded by the
        registrar in the prior-signed-voucher-request field of the registrar voucher-request, significantly
        reduce this risk by ensuring the MASA can confirm proximity
        between the pledge and the registrar making the request. Supply
        chain integration ("know your customer") is an additional
        step that MASA providers and device vendors can explore.</t>
      </section>
      <section title="DomainID must be resistant to second-preimage attacks">
        <t>
          The domainID is used as the reference in the audit log to the
          domain.  The domainID is expected to be calculated by a hash that
          is resistant to a second-preimage attack.
          Such an attack would allow a second registrar to create audit log
          entries that are fake.
        </t>
      </section>
      <section title="Availability of good random numbers">
        <t>
          The nonce used by the Pledge in the voucher-request SHOULD be
          generated by a Strong Cryptographic Sequence (<xref
          target="RFC4086" /> section 6.2).  TLS has a similar requirement.
        </t>
        <t>
          In particular implementations should pay attention to the advance
          in <xref target="RFC4086" /> section 3, particularly section 3.4.
          The random seed used by a device at boot MUST be
          unique across all devices and all bootstraps.  Resetting a device to
          factory default state does not obviate this requirement.
        </t>
      </section>
      <section title="Freshness in Voucher-Requests">
        <t>
          A concern has been raised that the pledge voucher-request should contain some content (a nonce) provided by the registrar and/or MASA
          in order for those actors to verify that the pledge voucher-request is fresh.
        </t>
        <t>
          There are a number of operational problems with getting a nonce
          from the MASA to the pledge. It is somewhat easier to collect a
          random value from the registrar, but as the registrar is not yet
          vouched for, such a registrar nonce has little value.
          There are privacy and logistical challenges to addressing these
          operational issues, so if
          such a thing were to be considered, it would have to provide some
          clear value.  This section examines the impacts of not having a
          fresh pledge voucher-request.
        </t>
        <t>
          Because the registrar authenticates the pledge, a full Man-in-the-Middle
          attack is not possible, despite the provisional TLS authentication
          by the pledge (see <xref target="ProtocolDetails"></xref>.)
          Instead we examine the case of a fake registrar (Rm)
          that communicates with the pledge in parallel or in close time proximity
          with the intended registrar. (This scenario is intentionally supported as
          described in <xref target="discovery"></xref>.)
        </t>
        <t>
          The fake registrar (Rm) can obtain a voucher signed by the MASA
          either directly or through arbitrary intermediaries.
          Assuming that the MASA accepts the registrar voucher-request (either because
          Rm is collaborating with a legitimate registrar according to supply chain
          information, or because the MASA is in audit-log only mode), then
          a voucher linking the pledge to the registrar Rm is issued.
        </t>
        <t>
          Such a voucher, when passed back to the pledge, would link the
          pledge to registrar Rm, and would permit the pledge to
          end the provisional state. It now trusts Rm and, if it has any
          security vulnerabilities leveragable by an Rm with full
          administrative control, can be assumed to be a
          threat against the intended registrar.
        </t>
        <t>
          This flow is mitigated by the intended registrar verifying the audit
          logs available from the MASA as described in
          <xref target="authzLogRequest" ></xref>. Rm might chose to collect
          a voucher-request but wait until after the intended registrar completes the authorization process before submitting it. This pledge voucher-request would be 'stale' in that it has a nonce that no longer matches the internal state of the pledge. In order to successfully use any resulting voucher the Rm would need to remove the stale nonce or anticipate the pledge's future nonce state. Reducing the possibility of this is why the pledge is mandated to generate a strong random or pseudo-random number nonce.</t>
        <t>
          Additionally, in order to successfully use the resulting voucher the Rm
          would have to attack the pledge and return it to a bootstrapping
          enabled state. This would require wiping the pledge of current
          configuration and triggering a re-bootstrapping of the pledge.
          This is no more likely than simply taking control of the pledge
          directly but if this is a consideration the target network is
          RECOMMENDED to take the following steps:
        </t>
        <t><list style="symbols">
          <t>Ongoing network monitoring for unexpected bootstrapping attempts by pledges.</t>
          <t>Retrieval and examination of MASA log information upon the occurrence
              of any such unexpected events. Rm will be listed in the logs along with nonce information for analysis.</t>
        </list></t>
      </section>
      <section title="Trusting manufacturers">
        <t>
          The BRSKI extensions to EST permit a new pledge to be completely
          configured with domain specific trust anchors.  The link from
          built-in manufacturer-provided trust anchors to domain-specific
          trust anchors is mediated by the signed voucher artifact.
        </t>
        <t>
          If the manufacturer's IDevID signing key is not properly validated,
          then there is a risk that the network will accept a pledge that
          should not be a member of the network.  As the address of the
          manufacturer's MASA is provided in the IDevID using the extension
          from <xref target="IDevIDextension" />, the malicious pledge will have no problem
          collaborating with it's MASA to produce a completely valid voucher.
        </t>
        <t>
          BRSKI does not, however, fundamentally change the trust model from
          domain owner to manufacturer.  Assuming that the pledge used
          its IDevID with RFC7030 EST and BRSKI, the domain (registrar) still needs to
          trust the manufacturer.
        </t>
        <t>
          Establishing this trust between domain and manufacturer is outside
          the scope of BRSKI.  There are a number of mechanisms that can
          adopted including:
          <list style="symbols">
            <t>
              Manually configuring each manufacturer's trust anchor.
            </t>
            <t>
              A Trust-On-First-Use (TOFU) mechanism. A human would be queried upon
              seeing a manufacturer's trust anchor for the first time, and
              then the trust anchor would be installed to the trusted store.
              There are risks with this; even if the key to name mapping is validated
              using something like the WebPKI, there remains the possibility
              that the name is a look alike: e.g, dem0.example. vs
              demO.example.
            </t>
            <t>
              scanning the trust anchor from a QR code that came with the
              packaging (this is really a manual TOFU mechanism)
            </t>
            <t>
              some sales integration process where trust anchors are provided
              as part of the sales process, probably included in a digital
              packing "slip", or a sales invoice.
            </t>
            <t>
              consortium membership, where all manufacturers of a particular
              device category (e.g, a light bulb, or a cable-modem) are
              signed by an certificate authority specifically for this.
              This is done by CableLabs today. It is used for authentication
              and authorization as part of TR-79: <xref target="docsisroot"
              /> and <xref target="TR069" />.
            </t>
          </list>
        </t>
        <t>
          The existing WebPKI provides a reasonable anchor between manufacturer
          name and public key. It authenticates the key.  It does not provide a
          reasonable authorization for the manufacturer, so it is not directly
          useable on it's own.
        </t>
      </section>
      <section title="Manufacturer Maintenance of trust anchors">
        <t>
          BRSKI depends upon the manufacturer building in trust anchors
          to the pledge device.  The voucher artifact which is signed by the
          MASA will be validated by the pledge using that anchor.  This
          implies that the manufacturer needs to maintain access to a signing
          key that the pledge can validate.
        </t>
        <t>
          The manufacturer will need to
          maintain the ability to make signatures that can be validated for
          the lifetime that the device could be onboarded. Whether
          this onboarding lifetime is less than the device lifetime depends
          upon how the device is used.  An inventory of devices kept in a
          warehouse as spares might not be onboarded for many decades.
        </t>
        <t>
          There are good cryptographic hygiene reasons why a manufacturer
          would not want to maintain access to a private key for many
          decades.  A manufacturer in that situation can leverage a long-term
          certificate authority anchor, built-in to the pledge, and then
          a certificate chain may be incorporated using the normal CMS
          certificate set.  This may increase the size of the voucher
          artifacts, but that is not a significant issues in non-constrained
          environments.
        </t>
        <t>
          There are a few other operational variations that manufacturers
          could consider. For instance, there is no reason that every device
          need have the same
          set of trust anchors pre-installed.  Devices built in different
          factories, or on different days, or any other consideration could
          have different trust anchors built in, and the record of which
          batch the device is in would be recorded in the asset database.
          The manufacturer would then know which anchor to sign an artifact
          against.
        </t>
        <t>
          Aside from the concern about long-term access to private keys, a
          major limiting factor for the shelf-life of many devices will be
          the age of the cryptographic algorithms included.  A device
          produced in 2019 will have hardware and software capable of
          validating algorithms common in 2019, and will have no defense
          against attacks (both quantum and von-neuman brute force attacks)
          which have not yet been invented.  This concern is orthogonal to
          the concern about access to private keys, but this concern likely
          dominates and limits the lifespan of a device in a warehouse.
          If any update to firmware to support new cryptographic mechanism
          were possible (while the device was in a warehouse), updates to
          trust anchors would also be done at the same time.
        </t>
        <t>
          The set of standard operating procedures for maintaining
          high value private keys is well documented. For instance,
          the WebPKI provides a number of options for audits at
          <xref target="cabforumaudit" />, and the DNSSEC root operations are well
          documented at <xref target="dnssecroot" />.
        </t>
        <t>
          It is not clear if Manufacturers will take this level of
          precaution, or how strong the economic incentives are to maintain
          an appropriate level of security.
        </t>
        <t>
          This next section examines the risk due to a compromised
          manufacturer IDevID signing key. This is followed by examination of
          the risk due to a compromised MASA key. The third section
          sections below examines the situation where MASA web server itself
          is under attacker control, but that the MASA signing key itself
          is safe in a not-directly connected hardware module.
        </t>

        <section title="Compromise of Manufacturer IDevID signing keys">
          <t>
            An attacker that has access to the key that the manufacturer uses
            to sign IDevID certificates can create counterfeit devices.
            Such devices can claim to be from a particular manufacturer,
            but be entirely different devices: Trojan horses in effect.
          </t>
          <t>
            As the attacker controls the MASA URL in the certificate,
            the registrar can be convinced to talk to the attackers' MASA.
            The Registrar does not need to be in any kind of promiscuous mode
            to be vulnerable.
          </t>
          <t>
            In addition to creating fake devices, the attacker may also
            be able to issue revocations for existing certificates if the
            IDevID certificate process relies upon CRL lists that are
            distributed.
          </t>
          <t>
            There does not otherwise seem to be any risk from this compromise
            to devices which are already deployed, or which are sitting
            locally in boxes waiting for deployment (local spares).
            The issue is that operators will be unable to trust devices
            which have been in an uncontrolled warehouse as they do not know
            if those are real devices.
          </t>
        </section>

        <section title="Compromise of MASA signing keys">
          <t>
            There are two periods of time in which to consider: when the MASA
            key has fallen into the hands of an attacker, and after the MASA
            recognizes that the key has been compromised.
          </t>
          <section title="Attacker opportunties with compromised MASA key">
            <t>
              An attacker that has access to the MASA signing key could create
              vouchers.  These vouchers could be for existing deployed
              devices, or for devices which are still in a warehouse.
              In order to exploit these vouchers two things need to occur:
              the device has to go through a factory default boot cycle, and the
              registrar has to be convinced to contact the attacker's MASA.
            </t>
            <t>
              If the attacker controls a Registrar which is visible to the
              device, then there is no difficulty in delivery of the false
              voucher.  A possible practical example of an attack like this
              would be in a data center, at an ISP peering point (whether a
              public IX, or a private peering point).  In such a situation,
              there are already cables attached to the equipment that lead
              to other devices (the peers at the IX), and through those
              links, the false voucher could be delivered.  The difficult
              part would be get the device put through a factory reset.
              This might be accomplished through social engineering of data
              center staff.  Most locked cages have ventilation holes, and
              possibly a long "paperclip" could reach through to depress a
              factory reset button.  Once such a piece of ISP equipment has
              been compromised, it could be used to compromise equipment that
              was connected to (through long haul links even), assuming that
              those pieces of equipment could also be forced through a
              factory reset.
            </t>
            <t>
              The above scenario seems rather unlikely as it requires some
              element of physical access; but were there a remote exploit
              that did not cause a direct breach, but rather a fault that
              resulted in a factory reset, this could provide a reasonable
              path.
            </t>
            <t>
              The above deals with ANI uses of BRSKI.  For cases where 802.11
              or 802.15.4 is involved, the need to connect directly to the
              device is eliminated, but the need to do a factory reset is
              not.  Physical possession of the device is not required as
              above, provided that there is some way to force a factory
              reset.  With some consumers devices with low overall
              implementation quality, the end users might be familiar with
              needing to reset the device regularly.
            </t>
            <t>
              The authors are unable to come up with an attack scenario where
              a compromised voucher signature enables an attacker to
              introduce a compromised pledge into an existing operator's
              network.  This is the case because the operator controls the
              communication between Registrar and MASA, and there is no
              opportunity to introduce the fake voucher through that conduit.
            </t>
          </section>

          <section title="Risks after key compromise is known">
            <t>
              Once the operator of the MASA realizes that the voucher signing
              key has been compromised it has to do a few things.
            </t>
            <t>
              First, it MUST issue a firmware update to all devices that
              had that key as a trust anchor, such that they will no longer
              trust vouchers from that key.  This will affect devices in the
              field which are operating, but those devices, being in
              operation, are not performing onboarding operations, so this
              is not a critical patch.
            </t>
            <t>
              Devices in boxes (in warehouses) are vulnerable, and remain
              vulnerable until patched.   An operator would be prudent to
              unbox the devices, onboard them in a safe environment, and
              then perform firmware updates.  This does not have to be
              done by the end-operator; it could be done by a distributor
              that stores the spares.  A recommended practice for high value
              devices (which typically have a &lt;4hr service window) may be to
              validate the device operation on a regular basis anyway.
            </t>
            <t>
              If the onboarding process includes attestations about firmware
              versions, then through that process the operator would be
              advised to upgrade the firmware before going into production.
              Unfortunately, this does not help against situations where the
              attacker operates their own Registrar (as listed above).
            </t>
            <t>
              <xref target="RFC8366" /> section 6.1 explains the need
              for short-lived vouchers.  The nonce guarantees freshness,
              and the short-lived nature of the voucher means that the window
              to deliver a fake voucher is very short.  A nonceless,
              long-lived voucher would be the only option for the attacker,
              and devices in the warehouse would be vulnerable to such a
              thing.
            </t>
            <t>
              A key operational recommendation is for manufacturers to sign
              nonceless, long-lived vouchers with a different key that they
              sign short-lived vouchers. That key needs significantly better
              protection.  If both keys come from a common trust-anchor
              (the manufacturer's CA), then a compromise of the
              manufacturer's CA would compromise both keys.  Such a
              compromise of the manufacturer's CA likely compromises
              all keys outlined in this section.
            </t>
          </section>
        </section>
        <section title="Compromise of MASA web service">
          <t>
            An attacker that takes over the MASA web service has a number of
            attacks.  The most obvious one is simply to take the database
            listing customers and devices and to sell this data to other
            attackers who will now know where to find potentially vulnerable
            devices.
          </t>
          <t>
            The second most obvious thing that the attacker can do is to
            kill the service, or make it operate unreliably, making
            customers frustrated.  This could have a serious affect on
            ability to deploy new services by customers, and would be a
            significant issue during disaster recovery.
          </t>
          <t>
            While the compromise of the MASA web service may lead to the
            compromise of the MASA voucher signing key, if the signing occurs
            offboard (such as in a hardware signing module, HSM), then the
            key may well be safe, but control over it resides with the attacker.
          </t>
          <t>
            Such an attacker can issue vouchers for any device presently in
            service.  Said device still needs to be convinced to do through a
            factory reset process before an attack.
          </t>
          <t>
            If the attacker has access to a key that is trusted for
            long-lived nonceless vouchers, then they could issue vouchers for
            devices which are not yet in service.  This attack may be very
            hard to verify and as it would involve doing firmware updates
            on every device in warehouses (a potentially ruinously expensive
            process), a manufacturer might be reluctant to admit this
            possibility.
          </t>
        </section>
      </section>
      <section title="YANG Module Security Considerations">
        <t>
          As described in the Security Considerations section of <xref
          target="RFC8366" /> (section 7.4), the YANG module specified
          in this document defines the schema for data that is subsequently
          encapsulated by a CMS signed-data content type, as described in
          Section 5 of <xref target="RFC5652" />.
          As such, all of the YANG modeled data is protected from modification.
        </t>
        <t>
           The use of YANG to define data structures, via the 'yang-data'
           statement, is relatively new and distinct from the traditional use
           of YANG to define an API accessed by network management protocols
           such as NETCONF <xref target="RFC6241" /> and RESTCONF <xref target="RFC8040"/>.  For this
           reason, these guidelines do not follow template described by
           Section 3.7 of <xref target="RFC8407" />.
        </t>
      </section>
    </section>

    <section title="Acknowledgements">
      <t>We would like to thank the various reviewers for their input, in
      particular
      William Atwood,
      Brian Carpenter,
      Fuyu Eleven,
      Eliot Lear,
      Sergey Kasatkin,
      Anoop Kumar,
      Tom Petch,
      Markus Stenberg,
      Peter van der Stok,
      and
      Thomas Werner
      </t>
      <t>
        Significant reviews were done by Jari Arko, Christian Huitema and
        Russ Housley.
      </t>
      <t>
        Henk Birkholz contributed the CDDL for the audit log response.
      </t>
      <t>
        This document started it's life as a two-page idea from Steinthor
        Bjarnason.
      </t>
      <t>
        In addition, significant review comments were received by many IESG
        members, including Adam Roach, Alexey Melnikov, Alissa Cooper, Benjamin Kaduk, Éric Vyncke, Roman
        Danyliw, and Magnus Westerlund.
      </t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      &RFC2119;
      <?rfc include="reference.RFC.8174" ?>
      <?rfc include="reference.RFC.4648" ?>

      &RFC7030;

      &RFC5652;

      <?rfc include="reference.RFC.8446" ?>

      &RFC5280;

      <?rfc include="reference.RFC.5272" ?>
      <?rfc include="reference.RFC.8259" ?>;

      &RFC7950;
      &RFC7951;

      <?rfc include="reference.RFC.4519" ?>

      <?rfc include="reference.RFC.6762" ?>

      <?rfc include="reference.RFC.6763" ?>

      <?rfc include="reference.RFC.3927" ?>

      <?rfc include="reference.RFC.3339" ?>

      <?rfc include="reference.RFC.4086" ?>
      <?rfc include="reference.RFC.4862" ?>
      <?rfc include="reference.RFC.4941" ?>

      <?rfc include="reference.RFC.3748" ?>

      <?rfc include="reference.RFC.6125" ?>
      <?rfc include="reference.RFC.7230" ?>
      <?rfc include="reference.RFC.7231" ?>
      <?rfc include="reference.RFC.7469" ?>

      <?rfc include="reference.I-D.ietf-anima-autonomic-control-plane" ?>
      <?rfc include="reference.RFC.8366" ?>
      <?rfc include="reference.RFC.8368" ?>
      <?rfc include="reference.I-D.ietf-anima-grasp" ?>
      <?rfc include="reference.RFC.8610" ?>
      <?rfc include="reference.RFC.8040" ?>
      <?rfc include="reference.RFC.6020" ?>
      <?rfc include="reference.RFC.6241" ?>
      <?rfc include="reference.RFC.8407" ?>
      <?rfc include="reference.ITU.X690.1994" ?>

      <?rfc include="reference.RFC.3688" ?>
      <reference anchor="IDevID"
                 target="http://standards.ieee.org/findstds/standard/802.1AR-2009.html">
        <front>
          <title>IEEE 802.1AR Secure Device Identifier</title>

          <author surname="IEEE Standard"></author>

          <date month="December" year="2009" />
        </front>
      </reference>

       <reference anchor="REST" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">
        <front>
            <title>Architectural Styles and the Design of Network-based Software Architectures</title>
            <author initials="R.F." surname="Fielding" fullname="Roy Fielding">
                <organization>University of California, Irvine</organization>
            </author>
            <date year="2000" />
        </front>
       </reference>

    </references>

    <references title="Informative References">
      <?rfc include="reference.I-D.ietf-anima-reference-model" ?>

      <?rfc include="reference.RFC.7435" ?>
      &RFC7575;
      <?rfc include="reference.RFC.7228" ?>
      <?rfc include="reference.RFC.7258" ?>
      <?rfc include="reference.RFC.5785" ?>
      <?rfc include="reference.RFC.2663" ?>
      <?rfc include="reference.RFC.6960" ?>
      <?rfc include="reference.RFC.6961" ?>
      <?rfc include="reference.RFC.8340" ?>
      <?rfc include="reference.I-D.ietf-ace-coap-est" ?>
      <!-- not referenced anymore: <?rfc
           include="reference.I-D.ietf-anima-stable-connectivity" ?> -->
      <?rfc include="reference.I-D.richardson-anima-state-for-joinrouter" ?>
      <?rfc include="reference.I-D.ietf-anima-constrained-voucher" ?>
      <?rfc include="reference.I-D.ietf-netconf-keystore" ?>
      <!-- not referenced anywhere: <?rfc include="reference.RFC.8572" ?> -->

      <?rfc include="reference.W3C.WD-capability-urls-20140218" ?>

      <?rfc include="reference.RFC.5209" ?>

      <reference anchor="docsisroot"
                 target="https://www.cablelabs.com/resources/digital-certificate-issuance-service/">
        <front>
          <title>CableLabs Digital Certificate Issuance Service</title>

          <author surname="CableLabs"></author>

          <date month="February" year="2018" />
        </front>
      </reference>

      <reference anchor="slowloris"
                 target="https://en.wikipedia.org/wiki/Slowloris_(computer_security)/">
        <front>
          <title>Slowloris (computer security)</title>
          <author surname="Wikipedia" />
          <date month="February" year="2019" />
        </front>
      </reference>

      <reference anchor="openssl"
                 target="https://www.openssl.org/docs/man1.1.1/man1/openssl-x509.html/">
        <front>
          <title>OpenSSL X509 utility</title>
          <author surname="Openssl" />
          <date month="September" year="2019" />
        </front>
      </reference>

      <reference anchor="TR069"
                 target="https://www.broadband-forum.org/standards-and-software/technical-specifications/tr-069-files-tools">
        <front>
          <title>TR-69: CPE WAN Management Protocol</title>

          <author surname="Broadband Forum"></author>

          <date month="February" year="2018" />
        </front>
      </reference>


      <reference anchor="imprinting"
                 target="https://en.wikipedia.org/wiki/Imprinting_(psychology)">
        <front>
          <title>Wikipedia article: Imprinting</title>

          <author surname="Wikipedia"></author>

          <date month="July" year="2015" />
        </front>
      </reference>

      <reference anchor="softwareescrow"
                 target="https://en.wikipedia.org/wiki/Source_code_escrow">
        <front>
          <title>Wikipedia article: Software Escrow</title>

          <author surname="Wikipedia"></author>

          <date month="October" year="2019" />
        </front>
      </reference>

      <reference anchor="IoTstrangeThings"
                 target="https://www.welivesecurity.com/2017/03/03/internet-of-things-security-privacy-iot-update/">
        <front>
          <title>IoT of toys stranger than fiction: Cybersecurity and data
          privacy update (accessed 2018-12-02)</title>

          <author surname="Internet"></author>
          <date month="March" year="2017" />
        </front>
      </reference>

      <reference anchor="livingwithIoT"
                 target="https://www.siliconrepublic.com/machines/iot-smart-devices-reality">
        <front>
          <title>What is it actually like to live in a house filled with IoT
          devices? (accessed 2018-12-02)</title>

          <author surname="Internet"></author>
          <date month="February" year="2018" />
        </front>
      </reference>

      <reference anchor="brewski"
                 target="https://www.urbandictionary.com/define.php?term=brewski">
        <front>
          <title>Urban Dictionary: Brewski</title>

          <author surname="Internet"></author>
          <date month="October" year="2019" />
        </front>
      </reference>

      <reference anchor="cabforumaudit"
                 target="https://cabforum.org/information-for-auditors-and-assessors/">
        <front>
          <title>Information for Auditors and Assessors</title>
          <author surname="CA/Browser Forum"></author>
          <date month="August" year="2019" />
        </front>
      </reference>

      <reference anchor="dnssecroot"
                 target="https://www.iana.org/dnssec/dps/zsk-operator/dps-zsk-operator-v2.0.pdf">
        <front>
          <title>DNSSEC Practice Statement for the Root Zone ZSK Operator</title>
          <author surname="Verisign"></author>
          <date month="December" year="2017" />
        </front>
      </reference>

      <reference anchor="Stajano99theresurrecting"
                 target="https://www.cl.cam.ac.uk/~fms27/papers/1999-StajanoAnd-duckling.pdf">
        <front>
          <title>The resurrecting duckling: security issues for ad-hoc
          wireless networks</title>

          <author fullname="Frank Stajano" initials="F." surname="Stajano"></author>

          <author fullname="Ross Anderson" initials="R." surname="Anderson"></author>

          <date year="1999" />
        </front>
      </reference>

      <reference anchor="minerva"
                 target="https://minerva.sandelman.ca/">
        <front>
          <title>Minerva reference implementation for BRSKI</title>

          <author fullname="Michael Richardson" initials="M." surname="Richardsdon"></author>
          <date year="2020" />
        </front>
      </reference>

      <reference anchor="minervagithub"
                 target="https://github.com/ANIMAgus-minerva">
        <front>
          <title>GITHUB hosting of Minerva reference code</title>

          <author fullname="Michael Richardson" initials="M." surname="Richardsdon"></author>
          <date year="2020" />
        </front>
      </reference>

<reference anchor="Dingledine2004" target="https://spec.torproject.org/tor-spec">
  <front>
    <title>Tor: the second-generation onion router</title>
    <author initials="R." surname="Dingledine">
      <organization></organization>
    </author>
    <author initials="N." surname="Mathewson">
      <organization></organization>
    </author>
    <author initials="P." surname="Syverson">
      <organization></organization>
    </author>
    <date year="2004"/>
  </front>
</reference>

    </references>

    <section anchor="IPv4operations" title="IPv4 and non-ANI operations">

      <t>
        The specification of BRSKI in <xref target="proxydetails" />
        intentionally only covers the mechanisms for an IPv6 pledge using
        Link-Local addresses.  This section describes non-normative
        extensions that can be used in other environments.
      </t>

      <section title="IPv4 Link Local addresses">
      <t>Instead of an IPv6 link-local address, an IPv4 address may be
      generated using <xref target="RFC3927" />  Dynamic Configuration of
      IPv4 Link-Local Addresses.
      </t>
      <t> In the case that an IPv4 Link-Local address is formed, then the
      bootstrap process would continue as in the IPv6 case by looking for
      a (circuit) proxy.
      </t>
      </section>

      <section title="Use of DHCPv4" anchor="IPv4dhcp">
      <t>
        The Pledge MAY obtain an IP address via
        DHCP [RFC2131]. The DHCP provided parameters for the Domain Name
        System can be used to perform DNS operations if all
        local discovery attempts fail.
      </t>
      </section>
    </section>

    <section anchor="mdnsmethods" title="mDNS / DNSSD proxy discovery options">
      <t>Pledge discovery of the proxy (<xref target="discovery"></xref>) MAY be performed with DNS-based Service Discovery <xref
      target="RFC6763"></xref> over Multicast DNS <xref
      target="RFC6762"></xref> to discover the proxy at
      "_brski-proxy._tcp.local.". </t>

      <t>Proxy discovery of the registrar (<xref target="JRCgrasp"></xref>) MAY be performed with DNS-based Service Discovery over Multicast DNS to discover registrars by searching for the service
        "_brski-registrar._tcp.local.".</t>

      <t>
        To prevent unaccceptable levels of
        network traffic, when using mDNS, the congestion avoidance mechanisms
        specified in
        <xref target="RFC6762"></xref> section 7 MUST be followed. The
        pledge SHOULD listen for an unsolicited broadcast response as
        described in <xref target="RFC6762"></xref>. This allows devices
        to avoid announcing their presence via mDNS broadcasts and
        instead silently join a network by watching for periodic
        unsolicited broadcast responses.
      </t>

      <t>
        Discovery of registrar MAY also be performed with DNS-based
        service discovery by searching for the service "_brski-registrar._tcp.example.com".
        In this case the domain
        "example.com" is discovered as described in <xref
        target="RFC6763"></xref> section 11 (<xref target="IPv4dhcp" />
        suggests the use of DHCP parameters).
      </t>

      <t>
        If no local proxy or registrar service is located using the GRASP
        mechanisms or the above mentioned DNS-based Service Discovery
        methods, the pledge MAY contact a well
        known manufacturer provided bootstrapping server by performing a DNS
        lookup using a well known URI such as
        "brski-registrar.manufacturer.example.com". The details of the URI are
        manufacturer specific. Manufacturers that leverage this method on the
        pledge
        are responsible for providing the registrar service.
        Also see <xref target="cloudregistrar" />.
      </t>

      <t>
        The current DNS services returned
          during each query are maintained until bootstrapping is completed. If
          bootstrapping fails and the pledge returns to the Discovery state, it
          picks up where it left off and continues attempting bootstrapping.
          For example, if the first Multicast DNS _bootstrapks._tcp.local
          response doesn't work then the second and third responses are tried.
          If these fail the pledge moves on to normal DNS-based Service
          Discovery.
      </t>
    </section>

    <section title="Example Vouchers">
      <t>
        Three entities are involved in a voucher: the MASA issues (signs)
        it, the registrar's public key is mentioned in the voucher, and the
        pledge validates it.  In order to provide reproduceable examples
        the public and private keys for an example MASA and registrar are
        first listed.
      </t>
      <t>
        The keys come from an open source reference implementation of BRSKI,
        called "Minerva" <xref target="minerva" />.
        It is available on github <xref target="minervagithub" />.
        The keys presented here are used in the unit and integration tests.
        The MASA code is called "highway", the Registrar code is called
        "fountain", and the example client is called "reach".
      </t>
      <t>
        The public key components of each are presented as both base64
        certificates, as well as being decoded by openssl's x509
        utility so that the extensions can be seen.  This was version
        1.1.1c of the <xref target="openssl" /> library and utility.
      </t>
      <section title="Keys involved">
        <t>
          The Manufacturer has a Certificate Authority that signs the
          pledge's IDevID.  In addition the Manufacturer's signing authority
          (the MASA) signs the vouchers, and that certificate must
          distributed to the devices at manufacturing time so that vouchers
          can be validated.
        </t>
        <section title="Manufacturer Certificate Authority for IDevID signatures">
          <t>
            This private key is Certificate Authority that signs IDevID certificates:
            <figure>
              INSERT_CODE_FROM_FILE examples/vendor.key END
              <postamble>file: examples/vendor.key</postamble>
            </figure>
            This public key validates IDevID certificates:
            <figure>
              INSERT_CODE_FROM_FILE examples/vendor.cert END
            </figure>
          </t>
        </section>
        <section title="MASA key pair for voucher signatures">
          <t>
            The MASA is the Manufacturer Authorized Signing Authority.  This
            keypair signs vouchers.  An example TLS certificate
            <xref target="brskimasatls" /> HTTP authentication is not provided as it is a
            common form.
          </t>
          <t>
            This private key signs the vouchers which are presented below:
            <figure>
              INSERT_CODE_FROM_FILE examples/masa.key END
              <postamble>file: examples/masa.key</postamble>
            </figure>
            This public key validates vouchers, and it has been signed by the
            CA above:
            <figure>
              INSERT_CODE_FROM_FILE examples/masa.cert END
            </figure>
          </t>
        </section>
        <section title="Registrar Certificate Authority">
          <t>
            This Certificate Authority enrolls the pledge once it is
            authorized, and it also signs the Registrar's certificate.
            <figure>
              INSERT_CODE_FROM_FILE examples/ownerca_secp384r1.key END
              <postamble>file: examples/ownerca_secp384r1.key</postamble>
            </figure>
            The public key is indicated in a pledge voucher-request to show proximity.
            <figure>
              INSERT_CODE_FROM_FILE examples/ownerca_secp384r1.cert END
            </figure>
          </t>
        </section>
        <section title="Registrar key pair">
          <t>
            The Registrar is the representative of the domain owner.
            This key signs registrar voucher-requests, and terminates
            the TLS connection from the pledge.
            <figure>
              INSERT_CODE_FROM_FILE examples/jrc_prime256v1.key END
            </figure>
            The public key is indicated in a pledge voucher-request to show proximity.
            <figure>
              INSERT_CODE_FROM_FILE examples/jrc_prime256v1.cert END
            </figure>
          </t>
        </section>
        <section title="Pledge key pair">
          <t>
            The pledge has an IDevID key pair built in at manufacturing time:
            <figure>
              INSERT_CODE_FROM_FILE examples/idevid_00-D0-E5-F2-00-02.key END
            </figure>
            The certificate is used by the registrar to find the MASA.
            <figure>
              INSERT_CODE_FROM_FILE examples/idevid_00-D0-E5-F2-00-02.cert END
            </figure>
          </t>
        </section>
      </section>

      <section anchor="exampleprocess" title="Example process">
        <t>
          The JSON examples below are wrapped at 60 columns.
          This results in strings that have newlines in them, which
          makes them invalid JSON as is.  The strings would otherwise
          be too long, so they need to be unwrapped before processing.
        </t>
        <t>
          For readability, the output of the asn1parse has been truncated at
          72 columns rather than wrapped.
        </t>
        <section title="Pledge to Registrar">
          <t>
            As described in <xref target="RequestVoucherFromRegistrar" />,
            the pledge will sign a pledge voucher-request containing the
            registrar's public key in the proximity-registrar-cert field.
            The base64 has been wrapped at 60 characters for presentation reasons.
            <figure>
              INSERT_CODE_FROM_FILE examples/vr_00-D0-E5-F2-00-02.b64 END
              <postamble>file: examples/vr_00-D0-E5-F2-00-02.b64</postamble>
            </figure>
            The ASN1 decoding of the artifact:
            <figure>
              INSERT_CODE_FROM_FILE examples/vr_00-D0-E5-F2-00-02.asn1.txt END
            </figure>
            The JSON contained in the voucher request:
            <figure>
              INSERT_CODE_FROM_FILE examples/vr_00-D0-E5-F2-00-02.json END
            </figure>
          </t>
        </section>

        <section title="Registrar to MASA">
          <t>
            As described in <xref target="RequestVoucherFromMASA" />
            the registrar will sign a registrar voucher-request, and will
            include pledge's voucher request in the prior-signed-voucher-request.
            <figure>
              INSERT_CODE_FROM_FILE examples/parboiled_vr_00-D0-E5-F2-00-02.b64 END
              <postamble>file: examples/parboiled_vr_00_D0-E5-02-00-2D.b64</postamble>
            </figure>
            The ASN1 decoding of the artifact:
            <figure>
              INSERT_CODE_FROM_FILE examples/parboiled_vr_00-D0-E5-F2-00-02.asn1.txt END
            </figure>
            The JSON contained in the voucher request. Note that the previous
            voucher request is in the prior-signed-voucher-request attribute.
            <figure>
              INSERT_CODE_FROM_FILE examples/parboiled_vr_00-D0-E5-F2-00-02.json END
            </figure>
          </t>
        </section>

        <section title="MASA to Registrar">
          <t>
            The MASA will return a voucher to the registrar, to be relayed to
            the pledge.
            <figure>
              INSERT_CODE_FROM_FILE examples/voucher_00-D0-E5-F2-00-02.b64 END
              <postamble>file: examples/voucher_00-D0-E5-F2-00-02.b64</postamble>
            </figure>
            The ASN1 decoding of the artifact:
            <figure>
              INSERT_CODE_FROM_FILE examples/voucher_00-D0-E5-F2-00-02.asn1.txt END
            </figure>
          </t>
        </section>
      </section>
    </section>
    <section title="Additional References">
      <t>
        RFC EDITOR Please remove this section before publication.
        It exists just to include
        references to the things in the YANG descriptions which are not
        otherwise referenced in the text so that xml2rfc will not complain.
      </t>
      <t>
        <xref target="ITU.X690.1994" />
      </t>
    </section>
  </back>
</rfc>
<!--
    Local Variables:
    mode: xml
    End:
-->