BRSKI with Pledge in Responder Mode (BRSKI-PRM)

3.1.1. Building Automation

In building automation a typical use case exists where a detached building or the basement is equipped with sensors, actuators, and controllers, but with only limited or no connection to the central building management system. This limited connectivity may exist during installation time or also during operation time.¶

During the installation, for instance, a service technician collects the device-specific information from the basement network and provides them to the central building management system. This could be done using a laptop, common mobile device, or dedicated commissioning tool to transport the information. The service technician may successively collect device-specific information in different parts of the building before connecting to the domain registrar for bulk bootstrapping.¶

A domain registrar may be part of the central building management system and already be operational in the installation network. The central building management system can then provide operational parameters for the specific devices in the basement or other detached areas. These operational parameters may comprise values and settings required in the operational phase of the sensors/actuators, among them a certificate issued by the operator to authenticate against other components and services. These operational parameters are then provided to the devices in the basement facilitated by the service technician's laptop. The Registrar-Agent, defined in this document, may be run on the technician's laptop to interact with pledges.¶

3.1.2. Infrastructure Isolation Policy

This refers to any case in which the network infrastructure is normally isolated from the Internet as a matter of policy, most likely for security reasons. In such a case, limited access to a domain registrar may be allowed in carefully controlled short periods of time, for example when a batch of new devices are deployed, but prohibited at other times.¶

3.1.3. Less Operational Security in the Target-Domain

The registration authority (RA) performing the authorization of a certificate request is a critical PKI component and therefore requires higher operational security than other components utilizing the issued certificates. CAs may also require higher security in the registration procedures. There may be situations in which the customer domain does not offer enough physical security to operate a RA/CA and therefore this service is transferred to a backend that offers a higher level of operational security.¶

6.1.1. Domain Registrar with Combined Functionality

A registrar with combined BRSKI and BRSKI-PRM functionality MAY detect if the bootstrapping is performed by the pledge directly (BRSKI case) or by a Registrar-Agent (BRSKI-PRM case) based on the utilized credential for client authentication during the TLS session establishment and switch switch the operational mode from BRSKI to BRSKI-PRM.¶

This may be supported by a specific naming in the SAN (subject alternative name) component of the EE certificate of the Registrar-Agent.¶

Alternatively, this may be supported by using an LDevID certificate signed by the domain owner for the client authentication of the Registrar-Agent. Using an LDevID certificate also allows the registrar to verify that a Registrar-Agent is authorized to perform the bootstrapping of a pledge. See also agent-proximity assertion in Section 5.4.¶

Using an LDevID certificate for TLS client authentication of the Registrar-Agent is a deviation from [RFC8995], in which the IDevID credential of the pledge is used to perform TLS client authentication.¶

6.2.1. Discovery of the Registrar

As a Registrar-Agent acts as representative of the domain registrar towards the pledge or may even be collocated with the domain registrar, a separate discovery of the registrar is likely not needed as Registrar-Agent and registrar are domain components and have a trust relation. Moreover, other communication (not part of this document) between the Registrar-Agent and the registrar is assumed, e.g., to exchange information about product-serial-number(s) of pledges to be discovered as outlined in Section 5.2. Moreover, as the standard discovery described in Section 4 of [RFC8995] and the Appendix A.2 of [RFC8995] does not support of registrars with an enhanced feature set (like the support of BRSKI-PRM), this standard discovery is not applicable.¶

As a more general solution, the BRSKI discovery mechanism can be extended to provide upfront information on the capabilities of registrars, such as the mode of operation (pledge-responder-mode or registrar-responder-mode). Defining discovery extensions is out of scope of this document. This may be provided in [I-D.eckert-anima-brski-discovery].¶

6.2.2. Discovery of the Pledge

The discovery of the pledge by Registrar-Agent in the context of this document describes the minimum discovery approach to be supported. A more general discovery mechanism, also supporting GRASP besides DNS-SD with mDNS may be provided in [I-D.eckert-anima-brski-discovery].¶

Discovery in BRSKI-PRM uses DNS-based Service Discovery [RFC6763] over Multicast DNS [RFC6762] to discover the pledge. Note that [RFC6762] Section 9 provides support for conflict resolution in situations when an DNS-SD with mDNS responder receives a mDNS response with inconsistent data. Note that [RFC8990] does not support conflict resolution of mDNS, which may be a limitation for its application.¶

The pledge constructs a local host name based on device local information (product-serial-number), which results in "product-serial-number._brski-pledge._tcp.local". The product-serial-number composition is manufacturer dependent and may contain information regarding the manufacturer, the product type, and further information specific to the product instance. To allow distinction of pledges, the product-serial-number therefore needs to be sufficiently unique.¶

In the absence of a more general discovery as defined in [I-D.eckert-anima-brski-discovery] the Registrar-Agent MUST use¶

• "<product-serial-number>._brski-pledge._tcp.local", to discover a specific pledge, e.g., when connected to a local network.¶

• "_brski-pledge._tcp.local" to get a list of pledges to be bootstrapped.¶

A manufacturer may allow the pledge to react on DNS-SD with mDNS discovery without his product-serial-number contained. This allows a commissioning tool to discover pledges to be bootstrapped in the domain. The manufacturer support this functionality as outlined in Section 10.4.¶

Establishing network connectivity of the pledge is out of scope of this document but necessary to apply DNS-SD with mDNS. For Ethernet it is provided by simply connecting the network cable. For WiFi networks, connectivity can be provided by using a pre-agreed SSID for bootstrapping, e.g., as proposed in [I-D.richardson-emu-eap-onboarding]. The same approach can be used by 6LoWPAN/mesh using a pre-agreed PAN ID. How to gain network connectivity is out of scope of this document.¶

6.3.1. Pledge with Combined Functionality

Pledges MAY support both initiator and responder mode.¶

A pledge in initiator mode should listen for announcement messages as described in Section 4.1 of [RFC8995]. Upon discovery of a potential registrar, it initiates the bootstrapping to that registrar. At the same time (so as to avoid the Slowloris-attack described in [RFC8995]), it SHOULD also respond to the triggers for responder mode described in this document.¶

Once a pledge with combined functionality has been bootstrapped, it MAY act as client for enrollment of further certificates needed, e.g., using the enrollment protocol of choice. If it still acts as server, the defined BRSKI-PRM endpoints to trigger a Pledge Enroll-Request (PER) or to provide an Enroll-Response can be used for further certificates.¶

7.1.1. Request Artifact: Pledge Voucher-Request Trigger (tPVR)

The Pledge Voucher-Request Trigger (tPVR) artifact is an unsigned JSON structure providing the trigger parameters. The following CDDL [RFC8610] explains the Pledge Voucher-Request Trigger structure.¶

<CODE BEGINS>
  pledgevoucherrequesttrigger = {
    "agent-provided-proximity-registrar-cert": bytes,
    "agent-signed-data": bytes
  }

<CODE ENDS>

The fields contained in the pledgevoucherrequesttrigger are:¶

• agent-provided-proximity-registrar-cert: X.509 v3 certificate structure of the domain registrar EE certificate (base64-encoded value); may be configured at the Registrar-Agent or may be fetched by the Registrar-Agent based on a prior TLS connection with this domain registrar¶

• agent-signed-data: base64-encoded JWS structure containing the SubjectKeyIdentifier of the EE (RegAgt) certificate and signing Data including the creation date and serial number of the pledge. Note that [I-D.ietf-anima-rfc8366bis] defines an opaque binary element for agent-signed data, for which the structure is defined in BRSKI-PRM.¶

{
  "payload": BASE64URL(UTF8(prmasd)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

The BRSKI-PRM Agent Signed Data structure MUST be encoded in JSON as defined in [RFC8259] following the CDDL definition Figure 8. The JWS Payload is further base64url-encoded to become the string value of the payload member as described in Section 3.2 of [RFC7515].¶

The following CDDL [RFC8610] explains the BRSKI-PRM Agent Signed Data structure.¶

<CODE BEGINS>
  prmasd = {
    "created": tdate,
    "serial-number": text
  }

<CODE ENDS>

The fields contained in the prmasd are:¶

• created-on: creation date and time as standard date/time string as defined in [RFC3339]¶

• serial-number: product-serial-number in the X520SerialNumber field of the IDevID certificate of the pledge as string as defined in Section 2.3.1 of [RFC8995]¶

Figure 9 below shows an example for unsigned BRSKI-PRM Agent Signed Data in JSON syntax.¶

{
  "created-on": "2021-04-16T00:00:01.000Z",
  "serial-number": "callee4711"
}

The JWS Protected Header of the agent-signed-data JWS structure MUST contain the following parameters (see Figure 10 for an example):¶

• alg: algorithm type used to create the signature, e.g., ES256 as defined in Section 4.1.1 of [RFC7515]¶

• kid: base64-encoded bytes of the SubjectKeyIdentifier (the "KeyIdentifier" OCTET STRING value) of the EE (RegAgt) certificate.¶

{
  "alg": "ES256",
  "kid": "base64encodedvalue=="
}

Note that at the time of receiving the PVR trigger, the pledge cannot verify the registrar LDevID certificate and has no proof-of-possession of the corresponding private key for the certificate. Hence, the tPVR is an unsigned artifact and the pledge only accepts the registrar LDevID certificate provisionally until it receives the voucher as described in Section 7.6.¶

The pledge will also be unable to verify the agent-signed-data itself as it does not possess the EE (RegAgt) certificate and the domain trust has not been established at this point of the communication. Verification SHOULD be done, after the voucher has been received.¶

The trigger for the pledge to create a PVR is depicted in the following figure:¶

{
  "agent-provided-proximity-registrar-cert": "base64encodedvalue==",
  "agent-signed-data": "base64encodedvalue=="
}

7.1.2. Response Artifact: Pledge Voucher-Request (PVR)

The Pledge Voucher-Request (PVR) artifact is a JWS Voucher Request as defined in [I-D.ietf-anima-jws-voucher]. Its unsigned data SHALL be constructed similar to the Voucher-Request artifact defined in [RFC8995]. It will contain additional data provided by the Registrar-Agent as specified in the following.¶

The payload of the PVR MUST contain the following parameters as part of the ietf-voucher-request:voucher as defined in [I-D.ietf-anima-rfc8366bis] and thus makes optional leaves in the YANG definition mandatory:¶

• created-on: SHALL contain the current date and time in yang:date-and-time format. If the pledge does not have synchronized time, it SHALL use the created-on time from the agent-signed-data, received in the trigger to create a PVR.¶

• nonce: SHALL contain a cryptographically strong pseudo-random number.¶

• serial-number: SHALL contain the pledge product-serial-number as X520SerialNumber.¶

• assertion: SHALL contain the requested voucher assertion "agent-proximity" (different value as in RFC 8995)..¶

The ietf-voucher-request:voucher data is extended with two additional parameters that MUST be included:¶

• agent-provided-proximity-registrar-cert: base64-encoded registrar EE certificate (provided in tPVR by the Registrar-Agent); enables the registrar to verify that it is the desired registrar for handling the PVR¶

• agent-signed-data: base64-encoded agent-signed-data (provided in tPVR by the Registrar-Agent); enables the registrar to verify and log, which Registrar-Agent was in contact with the pledge, when verifying the PVR¶

The enhancements of the YANG module for the ietf-voucher-request with these new leaves are defined in [I-D.ietf-anima-rfc8366bis].¶

The PVR is signed using the pledge's IDevID credential contained as x5c parameter of the JOSE header.¶

# The PVR in General JWS Serialization syntax
{
  "payload": BASE64URL(UTF8(ietf-voucher-request:voucher)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded Payload "ietf-voucher-request:voucher"
  representation in JSON syntax
{
  "ietf-voucher-request:voucher": {
     "created-on": "2021-04-16T00:00:02.000Z",
     "nonce": "eDs++/FuDHGUnRxN3E14CQ==",
     "serial-number": "callee4711",
     "assertion": "agent-proximity",
     "agent-provided-proximity-registrar-cert": "base64encodedvalue==",
     "agent-signed-data": "base64encodedvalue=="
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
    "alg": "ES256",
    "typ": "voucher-jws+json",
    "x5c": [
      "base64encodedvalue==",
      "base64encodedvalue=="
    ]
}

7.2.1. Request Artifact: Pledge Enroll-Request Trigger (tPER)

This document specifies the trigger for a generic certificate with no CSR attributes provided to the pledge. If specific attributes in the certificate are required, they have to be inserted by the issuing RA/CA.¶

The Pledge Enroll-Request Trigger (tPVR) artifact is an unsigned JSON structure providing the trigger parameters (tPER-data). The following CDDL [RFC8610] explains the Pledge Enroll-Request Trigger structure.¶

<CODE BEGINS>
pledgeenrollrequesttrigger = {
    "enroll-type": "enroll-generic-cert"
  }

<CODE ENDS>

The enroll-type field is an enum, identifying what is being enrolled. Currently only "enroll-generic-cert" for the LDevID certificate is defined.¶

Figure 15 below shows an example for unsigned Pledge Enroll-Request Trigger in JSON syntax.¶

{
  "enroll-type" : "enroll-generic-cert"
}

The Pledge Enroll-Request Trigger (tPER) artifact MUST be encoded in JSON as defined in [RFC8259] following the CDDL definition Figure 14.¶

The Pledge Enroll-Request Trigger (tPER) artifact MAY be used to provide additional data, like CSR attributes. How to provide and use such additional data is out of scope for this specification.¶

7.2.2. Response Artifact: Pledge Enroll-Request (PER)

The Pledge Enroll-Request (PER) artifact is a JWS-signed PKCS#10 Certificate Signing Request (CSR) utilizing the csr-grouping of the ietf-ztp-types YANG module as defined in [I-D.ietf-netconf-sztp-csr]. The CSR already assures POP of the private key corresponding to the contained public key. In addition, based on the PER signature using the IDevID, POI is provided.¶

The pledge constructs the Pledge Enroll-Request (PER) artifact as a JWS structure containing the PKCS#10 request wrapped in ietf-ztp-types YANG structrue as JWS payload. Note, [I-D.ietf-netconf-sztp-csr] also allows for inclusion of certification requests in different formats used by CMP or CMC.¶

The pledge MUST construct the PER as PKCS#10 and MUST sign it additionally with its IDevID credentials to provide proof-of-identity bound to the PKCS#10 as described below.¶

A successful enrollment will result in a generic LDevID certificate for the pledge in the new domain. This generic LDevID certificate can be used to request further (application specific) LDevID certificates if necessary for operation. The Registrar-Agent SHALL use the enrollment endpoint requestenroll specified in this document to provide the Pledge Enroll-Request artifact to the Registrar.¶

The JWS Protected Header of the PER MUST contain the following parameters as defined in [RFC7515]:¶

• alg: algorithm type used to create the signature, e.g., ES256 as defined in Section 4.1.1 of [RFC7515]¶

• x5c: base64-encoded pledge IDevID certificate; it MAY optionally contain the certificate chain for this certificate; if the certificate chain is not included, it MUST be available at the registrar for verification of the IDevID certificate¶

The body of the Pledge Enroll-Request SHOULD contain a P10 parameter (for PKCS#10) as defined for ietf-ztp-types:p10-csr in [I-D.ietf-netconf-sztp-csr]:¶

• p10-csr: base64-encoded PKCS#10 of the pledge.¶

The JOSE object is signed using the pledge's IDevID credential, which corresponds to the certificate signaled in the JOSE header.¶

While BRSKI-PRM targets the initial enrollment, re-enrollment SHOULD be supported as described in a similar way as for enrollment in this document, if no other re-enrollment mechanism is supported. Note that in this case the current LDevID credential is used instead of the IDevID credential to create the signature of the PKCS#10 request.¶

# The PER in General JWS Serialization syntax
{
  "payload": "BASE64URL(ietf-ztp-types)",
  "signatures": [
    {
      "protected": "BASE64URL(UTF8(JWS Protected Header))",
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded Payload "ietf-ztp-types" Representation
  in JSON Syntax
{
  "ietf-ztp-types": {
     "p10-csr": "base64encodedvalue=="
   }
}

# Example: Decoded "JWS Protected Header" Representation
  in JSON Syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ],
  "crit":["created-on"],
  "created-on": "2022-09-13T00:00:02.000Z"
}

With the collected PVR and PER, the Registrar-Agent starts the interaction with the domain registrar.¶

The new protected header field "created-on" is introduced to reflect freshness of the PER. The field is marked critical "crit" to ensure that it must be understood and validated by the receiver (here the domain registrar) according to Section 4.1.11 of [RFC7515]. It allows the registrar to verify the timely correlation between the PER and previously exchanged messages, i.e., created-on of PER >= created-on of PVR >= created-on of PVR trigger. The registrar MAY consider to ignore any but the newest PER from the same pledge in the case the registrar has at any point in time more than one pending PER from the pledge.¶

As the Registrar-Agent is intended to facilitate communication between the pledge and the domain registrar, a collection of requests from more than one pledge is possible. This allows bulk bootstrapping of several pledges using the same connection between the Registrar-Agent and the domain registrar.¶

7.3.1. Request Artifact: Pledge Voucher-Request (PVR)

For BRSKI-PRM, the Registrar-Agent sends the PVR by HTTP POST to the same registrar endpoint as introduced by BRSKI: "/.well- known/brski/requestvoucher", but with a Content-Type header field for JSON-in-JWS"¶

7.3.2. Supply RVR to MASA (backend interaction)

The registrar needs to convert the PVR to an RVR and supply it to the MASA.¶

If the MASA address/URI is learned from the IDevID MASA URI extension (Section 2.3 of [RFC8995]), then the MASA on that URI MUST support the procedures defined in this document if the PVR used JSON-JWS encoding. If the MASA is only configured on the registrar, then a registrar supporting BRKSI-PRM and other voucher encoding formats (such as those in [RFC8995]) SHOULD support per-message-format MASA address/URI configuration for the same IDevID trust anchor."¶

The registrar SHALL construct the payload of the RVR as defined in [RFC8995], Section 5.5. The RVR encoding SHALL be JSON-in-JWS as defined in [I-D.ietf-anima-jws-voucher].¶

The header of the RVR SHALL contain the following parameter as defined for JWS [RFC7515]:¶

• alg: algorithm used to create the object signature¶

• x5c: base64-encoded registrar LDevID certificate(s) (It optionally contains the certificate chain for this certificate)¶

The payload of the RVR MUST contain the following parameter as part of the voucher-request as defined in [RFC8995]:¶

• created-on: current date and time in yang:date-and-time format of RVR creation¶

• nonce: copied from the PVR¶

• serial-number: product-serial-number of pledge. The registrar MUST verify that the IDevID certificate subject serialNumber of the pledge (X520SerialNumber) matches the serial-number value in the PVR. In addition, it MUST be equal to the serial-number value contained in the agent-signed data of PVR.¶

• assertion: voucher assertion requested by the pledge (agent-proximity). The registrar provides this information to assure successful verification of Registrar-Agent proximity based on the agent-signed-data.¶

• prior-signed-voucher-request: PVR as received from Registrar-Agent, see Section 7.1¶

The RVR MUST be extended with the following parameter, when the assertion "agent-proximity" is requested, as defined in [I-D.ietf-anima-rfc8366bis]:¶

• agent-sign-cert: EE (RegAgt) certificate or the EE (RegAgt) certificate including certificate chain. In the context of this document it is a JSON array of base64encoded certificate information and handled in the same way as x5c header objects. If only a single object is contained in the x5c it MUST be the base64-encoded EE (RegAgt) certificate. If multiple certificates are included in the x5c, the first MUST be the base64-encoded EE (RegAgt) certificate.¶

The MASA uses this information for verification that the Registrar-Agent is in proximity to the registrar to state the corresponding assertion "agent-proximity".¶

The object is signed using the registrar LDevID credentials, which corresponds to the certificate referenced in the JOSE header.¶

# The RVR in General JWS Serialization syntax
{
  "payload": BASE64URL(UTF8(ietf-voucher-request:voucher)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "ietf-voucher-request:voucher"
  representation in JSON syntax
{
  "ietf-voucher-request:voucher": {
     "created-on": "2022-01-04T02:37:39.235Z",
     "nonce": "eDs++/FuDHGUnRxN3E14CQ==",
     "serial-number": "callee4711",
     "assertion": "agent-proximity",
     "prior-signed-voucher-request": "base64encodedvalue==",
     "agent-sign-cert": [
       "base64encodedvalue==",
       "base64encodedvalue==",
       "..."
     ]
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ],
  "typ": "voucher-jws+json"
}

The registrar SHALL send the RVR to the MASA endpoint by HTTP POST: "/.well-known/brski/requestvoucher"¶

The RVR Content-Type header field is defined in [I-D.ietf-anima-jws-voucher] as: application/voucher-jws+json¶

The registrar SHOULD set the Accept header of the RVR indicating the desired media type for the voucher-response. The media type is application/voucher-jws+json as defined in [I-D.ietf-anima-jws-voucher].¶

This document uses the JSON-in-JWS format throughout the definition of exchanges and in the examples. Nevertheless, alternative encodings of the voucher as used in BRSKI [RFC8995] with JSON-in-CMS or CBOR-in-COSE_Sign [RFC9052] for constraint environments are possible as well. The assumption is that a pledge typically supports a single encoding variant and creates the PVR in the supported format. To ensure that the pledge is able to process the voucher, the registrar MUST use the media type for Accept header in the RVR based on the media type used for the PVR.¶

Once the MASA receives the RVR it SHALL perform the verification as described in Section 5.5 of [RFC8995].¶

In addition, the following processing SHALL be performed for PVR contained in RVR "prior-signed-voucher-request" field:¶

• agent-provided-proximity-registrar-cert: The MASA MAY verify that this field contains the registrar LDevID certificate. If so, it MUST correspond to the registrar LDevID credentials used to sign the RVR. Note: Correspond here relates to the case that a single registrar LDevID certificate is used or that different registrar LDevID certificates are used, which are issued by the same CA.¶

• agent-signed-data: The MASA MAY verify this data to issue "agent-proximity" assertion. If so, the agent-signed-data MUST contain the pledge product-serial-number, contained in the "serial-number" field of the PVR (from "prior-signed-voucher-request" field) and also in "serial-number" field of the RVR. The EE (RegAgt) certificate to be used for signature verification is identified by the "kid" parameter of the JOSE header. If the assertion "agent-proximity" is requested, the RVR MUST contain the corresponding EE (RegAgt) certificate data in the "agent-sign-cert" field of the RVR. It MUST be verified by the MASA to the same domain CA as the registrar LDevID certificate. If the "agent-sign-cert" field is not set, the MASA MAY state a lower level assertion value, e.g.: "logged" or "verified". Note: Sub-CA certificate(s) MUST also be carried by "agent-sign-cert", in case the EE (RegAgt) certificate is issued by a sub-CA and not the domain CA known to the MASA. As the "agent-sign-cert" field is defined as array (x5c), it can handle multiple certificates.¶

If validation fails, the MASA SHOULD respond with an HTTP 4xx client error status code to the registrar. The HTTP error status codes are kept the same as defined in Section 5.6 of [RFC8995] and comprise the codes: 403, 404, 406, and 415.¶

The registrar provides the EE certificate of the Registrar-Agent identified by the SubjectKeyIdentifier (SKID) in the header of the "agent-signed-data" from the PVR in its RVR (see also Section 7.3.2).¶

The MASA in turn verifies the registrar LDevID certificate is included in the PVR (contained in the "prior-signed-voucher-request" field of RVR) in the "agent-provided-proximity-registrar-cert" leaf and may assert the PVR as "verified" or "logged".¶

In addition, the MASA may issue the assertion "agent-proximity" as follows: The MASA verifies the signature of the "agent-signed-data" contained in the "prior-signed-voucher-request", based on the provided EE certificate of the Registrar-Agent in the "agent-sign-cert" leaf of the RVR. If both can be verified successfully, the MASA can assert "agent-proximity" in the voucher. The assertion of "agent-proximity" is similar to the proximity assertion by the MASA when using BRSKI. Note that the different assertions do not provide a metric of strength as the security properties are not comparable.¶

Depending on the MASA verification policy, it may also respond with a suitable 4xx or 5xx response status codes as described in Section 5.6 of [RFC8995]. When successful, the Voucher will then be supplied via the registrar to the Registrar-Agent.¶

7.3.3. Issue Voucher by MASA (backend interaction)

The MASA creates a voucher with Media-Type of application/voucher-jws+json as defined in [I-D.ietf-anima-jws-voucher]. If the MASA detects that the Accept header of the PVR does not match application/voucher-jws+json it SHOULD respond with the HTTP status code "406 Not Acceptable" as the pledge will not be able to parse the response. The voucher is according to [I-D.ietf-anima-rfc8366bis] but uses the new assertion value specified Section 5.4.¶

Figure 19 shows an example of the contents of a voucher.¶

# The MASA issued voucher in General JWS Serialization syntax
{
  "payload": BASE64URL(UTF8(ietf-voucher:voucher)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "ietf-voucher:voucher" representation
  in JSON syntax
{
  "ietf-voucher:voucher": {
    "assertion": "agent-proximity",
    "serial-number": "callee4711",
    "nonce": "base64encodedvalue==",
    "created-on": "2022-01-04T00:00:02.000Z",
    "pinned-domain-cert": "base64encodedvalue=="
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ],
  "typ": "voucher-jws+json"
}

The pinned-domain certificate to be put into the voucher is determined by the MASA as described in Section 5.5 of [RFC8995]. The MASA returns the voucher-response (voucher) to the registrar.¶

7.3.4. Supply Voucher to Registrar (backend interaction)

After receiving the voucher the registrar SHOULD evaluate it for transparency and logging purposes as outlined in Section 5.6 of [RFC8995]. The registrar MUST add an additional signature to the MASA provided voucher using its registrar EE credentials.¶

The signature is created by signing the original "JWS Payload" produced by MASA and the registrar added "JWS Protected Header" using the registrar EE credentials (see [RFC7515], Section 5.2 point 8. The x5c component of the "JWS Protected Header" MUST contain the registrar EE certificate as well as potential subordinate CA certificates up to (but not including) the pinned domain certificate. The pinned domain certificate is already contained in the voucher payload ("pinned-domain-cert").¶

(For many installations, with a single registrar credential, the registrar credential is what is pinned)¶

In [RFC8995], the Registrar proved possession of the it's credential when the TLS session was setup. While the pledge could not, at the time, validate the certificate truly belonged the registrar, it did validate that the certificate it was provided was able to authenticate the TLS connection.¶

In the BRSKI-PRM mode, with the Registrar-Agent mediating all communication, the Pledge has not as yet been able to witness that the intended Registrar really does possess the relevant private key. This second signature provides for the same level of assurance to the pledge, and that it matches the public key that the pledge received in the trigger for the PVR (see Figure 11).¶

The registrar MUST use the same registrar EE credentials used for authentication in the TLS handshake to authenticate towards the Registrar-Agent. This has some operational implications when the registrar may be part of a scalable framework as described in [I-D.richardson-anima-registrar-considerations], Section 1.3.1.¶

The second signature MUST either be done with the private key associated with the registrar EE certificate provided to the Registrar-Agent, or the use of a certificate chain is necessary. This ensures that the same registrar EE certificate can be used to verify the signature as transmitted in the voucher-request as also transferred in the PVR in the "agent-provided-proximity-registrar-cert".¶

Figure 20 below provides an example of the voucher with two signatures.¶

# The MASA issued voucher with additional registrar signature in
  General JWS Serialization syntax
{
  "payload": BASE64URL(ietf-voucher:voucher),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header (MASA))),
      "signature": BASE64URL(JWS Signature)
    },
    {
      "protected": BASE64URL(UTF8(JWS Protected Header (Reg))),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "ietf-voucher:voucher" representation in
  JSON syntax
{
  "ietf-voucher:voucher": {
     "assertion": "agent-proximity",
     "serial-number": "callee4711",
     "nonce": "base64encodedvalue==",
     "created-on": "2022-01-04T00:00:02.000Z",
     "pinned-domain-cert": "base64encodedvalue=="
  }
}

# Example: Decoded "JWS Protected Header (MASA)" representation
  in JSON syntax
{
  "alg": "ES256",
  "typ": "voucher-jws+json",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}

# Example: Decoded "JWS Protected Header (Reg)" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}

Depending on the security policy of the operator, this signature can also be interpreted by the pledge as explicit authorization of the registrar to install the contained trust anchor. The registrar sends the voucher to the Registrar-Agent.¶

7.3.5. Response Artifact: Voucher

After receiving the PVR from Registrar-Agent, the registrar SHALL perform the verification as defined in Section 5.3 of [RFC8995]. In addition, the registrar SHALL verify the following parameters from the PVR:¶

• agent-provided-proximity-registrar-cert: MUST contain registrar's own registrar LDevID certificate to ensure the registrar in proximity of the Registrar-Agent is the desired registrar for this PVR.¶

• agent-signed-data: The registrar MUST verify that the Registrar-Agent provided data has been signed with the private key corresponding to the EE (RegAgt) certificate indicated in the "kid" JOSE header parameter. The registrar MUST verify that the LDevID(ReAgt) certificate, corresponding to the signature, is still valid. If the certificate is already expired, the registrar SHALL reject the request. Validity of used signing certificates at the time of signing the agent-signed-data is necessary to avoid that a rogue Registrar-Agent generates agent-signed-data objects to onboard arbitrary pledges at a later point in time, see also Section 10.3. The registrar MUST fetch the EE (RegAgt) certificate, based on the provided SubjectKeyIdentifier (SKID) contained in the "kid" header parameter of the agent-signed-data, and perform this verification. This requires, that the registrar has access to the EE (RegAgt) certificate data (including intermediate CA certificates if existent) based on the SKID. Note, the registrar may have stored the EE (RegAgt) certificate if used during TLS establishment between Registrar-Agent and registrar or it may be provided via a repository.¶

If the registrar is unable to validate the PVR, it SHOULD respond with a HTTP 4xx/5xx error code to the Registrar-Agent.¶

The following 4xx client error codes SHOULD be used:¶

• 403 Forbidden: if the registrar detected that one or more security related parameters are not valid or if the pledge-provided information could not be used with automated allowance.¶

• 406 Not Acceptable: if the Content-Type indicated by the Accept header is unknown or unsupported.¶

If the validation succeeds, the registrar performs pledge authorization according to Section 5.3 of [RFC8995] followed by obtaining a voucher from the pledge's MASA according to Section 5.4 of [RFC8995] with the modifications described below in Section 7.3.2.¶

7.4.1. Request Artifact: Pledge Enroll-Request (PER)

As specified in Section 7.2 deviating from BRSKI the PER is not a raw PKCS#10. As the Registrar-Agent is involved in the exchange, the PKCS#10 is wrapped in a JWS object by the pledge and signed with pledge's IDevID to ensure proof-of-identity as outlined in Figure 16.¶

EST [RFC7030] standard endpoints (/simpleenroll, /simplereenroll, /serverkeygen, /cacerts) on the registrar cannot be used for BRSKI-PRM. This is caused by the utilization of signature wrapped-objects in BRSKI-PRM. As EST requires to sent a raw PKCS#10 request to e.g., "/.well-known/est/simpleenroll" endpoint, this document makes an enhancement by utilizing EST but with the exception to transport a signature wrapped PKCS#10 request. Therefore a new endpoint for BRSKI-PRM on the registrar is defined as "/.well-known/brski/requestenroll"¶

The Registrar-Agent SHALL send the PER to the registrar by HTTP POST to the endpoint: "/.well-known/brski/requestenroll"¶

The Content-Type header of PER is: application/jose+json.¶

This is a deviation from the Content-Type header values used in [RFC7030] and results in additional processing at the domain registrar (as EST server). Note, the registrar is already aware that the bootstrapping is performed in a pledge-responder-mode due to the use of the EE (RegAgt) certificate for TLS and the provided PVR as JSON-in-JWS object.¶

• If the registrar receives a PER with Content-Type header: application/jose+json, it MUST verify the wrapping signature using the certificate indicated in the JOSE header.¶

• The registrar verifies that the pledge's certificate (here IDevID), carried in "x5c" header field, is accepted to join the domain after successful validation of the PVR.¶

7.4.2. Enroll Pledge by Domain CA (backend interaction)

If both succeed, the registrar utilizes the PKCS#10 request contained in the JWS object body as "P10" parameter of "ietf-sztp-csr:csr" for further processing of the Enroll-Request with the corresponding domain CA. It creates a Registrar Enroll-Request (RER) by utilizing the protocol expected by the domain CA.¶

The domain registrar may either directly forward the provided PKCS#10 request to the CA or provide additional information about attributes to be included by the CA into the requested LDevID certificate.¶

The approach of sending this information to the CA depends on the utilized certificate management protocol between the RA and the CA and is out of scope for this document.¶

7.4.3. Response Artifact: Enroll-Response (Enroll-Resp)

The registrar SHOULD respond with an HTTP 200 OK in the success case or fail with HTTP 4xx/5xx status codes as defined by the HTTP standard.¶

A successful interaction with the domain CA will result in a pledge LDevID certificate, which is then forwarded by the registrar to the Registrar-Agent using the Content-Type header: application/pkcs7-mime.¶

Note while BRSKI-PRM targets the initial enrollment, re-enrollment may be supported in a similar way with the exception that the current LDevID certificate is used instead of the IDevID certificate to verify the wrapping signature of the PKCS#10 request (see also Section 7.2).¶

7.5.1. Request Artifact: cACert-Request (cACert-Req)

To support Registrar-Agents requesting a signature wrapped CA certificate(s) object, a new endpoint for BRSKI-PRM is defined on the registrar: "/.well-known/brski/wrappedcacerts"¶

The Registrar-Agent SHALL requests the EST CA trust anchor database information (in form of CA certificates) by HTTP GET.¶

7.5.2. Response Artifact: cACert-Response (cACert-Resp)

The Content-Type header of the response SHALL be: application/jose+json.¶

This is a deviation from the Content-Type header values used in EST [RFC7030] and results in additional processing at the domain registrar (as EST server). The additional processing is to sign the CA certificate(s) information using the registrar LDevID credentials. This results in a signed CA certificate(s) object (JSON-in-JWS), the CA certificates are provided as base64-encoded "x5bag" (see definition in [RFC9360]) in the JWS payload.¶

# The CA certificates data with registrar signature in
# General JWS Serialization syntax
{
  "payload": BASE64URL(certs),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "certs" representation in JSON syntax
{
  "x5bag": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}


# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}

7.6.1. Request Artifact: Voucher

The Registrar-Agent SHALL send the voucher-response to the pledge by HTTP POST to the endpoint: "/.well-known/brski/svr".¶

The Registrar-Agent voucher-response Content-Type header is application/voucher-jws+json and contains the voucher as provided by the MASA. An example is given in Figure 19 for a MASA signed voucher and in Figure 20 for the voucher with the additional signature of the registrar.¶

A nonceless voucher may be accepted as in [RFC8995] and may be allowed by a manufacture's pledge implementation.¶

To perform the validation of several signatures on the voucher object, the pledge SHALL perform the signature verification in the following order:¶

1. Verify MASA signature as described in Section 5.6.1 of [RFC8995], against pre-installed manufacturer trust anchor (IDevID).¶

2. Install trust anchor contained in the voucher ("pinned-domain-cert") provisionally¶

3. Validate the LDevID(Reg) certificate received in the agent-provided-proximity-registrar-cert in the Pledge-Voucher-Request trigger request (in the field "agent-provided-proximity-registrar-cert")¶

4. Verify registrar signature of the voucher similar as described in Section 5.6.1 of [RFC8995], but take the registrar certificate instead of the MASA certificate for the verification¶

Step3 and step 4 have been introduced in BRSKI-PRM to enable verification of LDevID(Reg) certificate and also the proof-of-possession of the corresponding private key by the registrar, which is done in BRSKI based on the established TLS channel. If all steps stated above have been performed successfully, the pledge SHALL terminate the "PROVISIONAL accept" state for the domain trust anchor and the registrar LDevID certificate.¶

If an error occurs during the verification and validation of the voucher, this SHALL be reported in the reason field of the pledge voucher status.¶

7.6.2. Response Artifact: Voucher Status (vStatus)

After voucher verification and validation the pledge MUST reply with a status telemetry message as defined in Section 5.7 of [RFC8995]. The pledge generates the voucher-status and provides it as signed JSON-in-JWS object in response to the Registrar-Agent.¶

The response has the Content-Type application/jose+json and is signed using the IDevID of the pledge as shown in Figure 25. As the reason field is optional (see [RFC8995]), it MAY be omitted in case of success.¶

# The "pledge-voucher-status" telemetry in general JWS
  serialization syntax
{
  "payload": BASE64URL(pledge-voucher-status),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "pledge-voucher-status" representation
  in JSON syntax for success case
{
  "version": 1,
  "status": true,
  "reason": "Voucher successfully processed",
  "reason-context": {
    "pvs-details": "JSON"
  }
}

# Example: Decoded payload "pledge-voucher-status" representation
  in JSON syntax for error case
{
  "version": 1,
  "status": false,
  "reason": "Failed to authenticate MASA certificate because
  it starts in the future (1/1/2023).",
  "reason-context": {
    "pvs-details": "Current date: 1/1/1970"
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}

If the pledge did not did not provide voucher status telemetry information after processing the voucher, the Registrar-Agent MAY query the pledge status explicitly as described in Section 7.11 and MAY resent the voucher depending on the Pledge status following the procedure described in Section 7.6.¶

7.7.1. Request Artifact:

The Registrar-Agent SHALL provide the set of CA certificates requested from the registrar to the pledge by HTTP POST to the endpoint: "/.well-known/brski/scac".¶

As the CA certificate provisioning is crucial from a security perspective, this provisioning SHOULD only be done, if the voucher-response has been successfully processed by pledge as reflected in the voucher status telemetry.¶

The CA certificates message has the Content-Type application/jose+json and is signed using the credential of the registrar as shown in Figure 23.¶

The CA certificates are provided as base64-encoded "x5bag". The pledge SHALL install the received CA certificates as trust anchor after successful verification of the registrar's signature.¶

7.7.2. Response (no artifact)

The verification comprises the following steps the pledge MUST perform. Maintaining the order of versification steps as indicated allows to determine, which verification has already been passed:¶

1. Check content-type of the CA certificates message. If no Content-Type is contained in the HTTP header, the default Content-Type utilized in this document (JSON-in-JWS) is used. If the Content-Type of the response is in an unknown or unsupported format, the pledge SHOULD reply with a 415 Unsupported media type error code.¶

2. Check the encoding of the payload. If the pledge detects errors in the encoding of the payload, it SHOULD reply with 400 Bad Request error code.¶

3. Verify that the wrapped CA certificate object is signed using the registrar certificate against the pinned-domain certificate. This MAY be done by comparing the hash that is indicating the certificate used to sign the message is that of the pinned-domain certificate. If the validation against the pinned domain-certificate fails, the client SHOULD reply with a 401 Unauthorized error code. It signals that the authentication has failed and therefore the object was not accepted.¶

4. Verify signature of the received wrapped CA certificate object using the domain certificate contained in the voucher. If the validation of the signature fails, the pledge SHOULD reply with a 403 Forbidden. It signals that the object could not be verified and has not been accepted.¶

5. If the received CA certificates are not self-signed, i.e., an intermediate CA certificate, verify them against an already installed trust anchor, as described in section 4.1.3 of [RFC7030].¶

In case of success, the pledge SHOULD reply with HTTP 200 OK without a response body.¶

7.8.1. Request Artifact: Enroll-Response (Enroll-Resp)

The Registrar-Agent SHALL send the Enroll-Response to the pledge by HTTP(S) POST to the endpoint: "/.well-known/brski/ser".¶

The Content-Type header when using EST [RFC7030] as enrollment protocol between the Registrar-Agent and the infrastructure is application/pkcs7-mime. Note: It only contains the LDevID certificate for the pledge, not the certificate chain.¶

Upon reception, the pledge SHALL verify the received LDevID certificate. The pledge SHALL generate the enroll status and provide it in the response to the Registrar-Agent. If the verification of the LDevID certificate succeeds, the status property SHALL be set to "status": true, otherwise to "status": false¶

7.8.2. Response Artifact: Enroll Status (eStatus)

After enrollment processing the pledge MUST reply with a enrollment status telemetry message as defined in Section 5.9.4 of [RFC8995]. The enroll-status is also a signed object in BRSKI-PRM and results in form of JSON-in-JWS here. If the pledge verified the received LDevID certificate successfully it SHALL sign the enroll-status using its new LDevID credentials as shown in Figure 29. In failure case, the pledge SHALL use its IDevID credentials. Section 5.9.4 of [RFC8995] specifies the enrollment status telemetry message with two optional fields for "reason" and "reason-context". In BRSKI-PRM the optional fields are mandated to have a clear distinction between other status messages and MUST be provided therefore. This distinction is intended for better error handling on registrar side, as a status object could be send to a wrong status endpoint.¶

The following CDDL [RFC8610] explains enroll-status response structure. It is similar as defined in Section 5.9.4 of [RFC8995] with the optional fields set to mandatory as described above.¶

<CODE BEGINS>
enrollstatus-trigger = {
    "version": uint,
    "status": bool,
    "reason": text,
    "reason-context" : { $$arbitrary-map }
  }

<CODE ENDS>

The response has the Content-Type application/jose+json.¶

# The "pledge-enroll-status" telemetry in General JWS Serialization
  syntax
{
  "payload": BASE64URL(pledge-enroll-status),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "pledge-enroll-status" representation
  in JSON syntax for success case
{
  "version": 1,
  "status": true,
  "reason": "Enroll-Response successfully processed",
  "reason-context": {
    "pes-details": "JSON"
  }
}

# Example: Decoded payload "pledge-voucher-status" representation
  in JSON syntax for error case
{
  "version": 1,
  "status": false,
  "reason": "Enroll-Response could not be verified.",
  "reason-context": {
    "pes-details": "no matching trust anchor"
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ]
}

Once the Registrar-Agent has collected the information, it can connect to the registrar to provide it with the status responses.¶

7.9.1. Request Artifact: Voucher Status (vStatus)

The Registrar-Agent sends the pledge voucher status without modification to the registrar with an HTTP-over-TLS POST using the registrar endpoint "/.well-known/brski/voucher_status". The Content-Type header is kept as application/jose+json as depicted in the example in Figure 25.¶

The registrar SHOULD log the transaction provided for a pledge via Registrar-Agent and include the identity of the Registrar-Agent in these logs. For log analysis the following may be considered:¶

• The registrar knows the interacting Registrar-Agent from the authentication of the Registrar-Agent towards the registrar using LDevID (RegAgt) and can log it accordingly.¶

• The telemetry information from the pledge can be correlated to the voucher response provided from the registrar to the Registrar-Agent and further to the pledge.¶

• The telemetry information, when provided to the registrar is provided via the Registrar-Agent and can thus be correlated.¶

The registrar SHALL verify the signature of the pledge voucher status and validate that it belongs to an accepted device of the domain based on the contained "serial-number" in the IDevID certificate referenced in the header of the voucher status.¶

7.9.2. Response (no artifact)

According to Section 5.7 of [RFC8995], the registrar SHOULD respond with an HTTP 200 OK without a response body in the success case or fail with HTTP 4xx/5xx status codes. The Registrar-Agent may use the response status code to signal success/failure to the service technician operating the Registrar-Agent. Within the server logs the server SHOULD capture this telemetry information.¶

The registrar SHOULD proceed with collecting and logging status information by requesting the MASA audit-log from the MASA service as described in Section 5.8 of [RFC8995].¶

7.10.1. Request Artifact: Enroll Status (eStatus)

The Registrar-Agent sends the pledge enroll status without modification to the registrar with an HTTP-over-TLS POST using the registrar endpoint "/.well-known/brski/enrollstatus". The Content-Type header is kept as application/jose+json as depicted in the example in Figure 29.¶

The registrar MUST verify the signature of the pledge enroll status. Also, the registrar SHALL validate that the pledge is an accepted device of the domain based on the contained product-serial-number in the LDevID certificate referenced in the header of the enroll status. The registrar SHOULD log this event. In case the pledge enroll status indicates a failure, the pledge was unable to verify the received LDevID certificate and therefore signed the enroll status with its IDevID credential. Note that the signature verification of the status information is an addition to the described handling in Section 5.9.4 of [RFC8995], and is replacing the pledges TLS client authentication by DevID credentials in [RFC8995].¶

7.10.2. Response (no artifact)

According to Section 5.9.4 of [RFC8995], the registrar SHOULD respond with an HTTP 200 OK in the success case or fail with HTTP 4xx/5xx status codes.¶

Based on the failure case the registrar MAY decide that for security reasons the pledge is not allowed to reside in the domain. In this case the registrar MUST revoke the certificate. An example case for the registrar revoking the issued LDevID for the pledge is when the pledge was not able to verify the received LDevID certificate and therefore did send a 406 (Not Acceptable) response. In this case the registrar may revoke the LDevID certificate as the pledge did no accepted it for installation.¶

The Registrar-Agent may use the response to signal success / failure to the service technician operating the Registrar-Agent. Within the server log the registrar SHOULD capture this telemetry information.¶

7.11.1. Request Artifact: Status Trigger (tStatus)

The Status Query artifact is a JWS structure signing information on the requested status-type, the time and date the request is created, and the product serial-number of the pledge contacted as shown in Figure 32. The following Concise Data Definition Language (CDDL) [RFC8610] defines the structure of the unsigned Status Query data (i.e., JWS payload):¶

<CODE BEGINS>
  statustrigger = {
      "version": uint,
      "created-on": tdate,
      "serial-number": text,
      "status-type": text
  }

<CODE ENDS>

The version field is included to permit significant changes to the pledge status artifacts in the future. The format and semantics in this document follow the status telemetry definitions of [RFC8995]. Hence, the version MUST be set to 1. A pledge (or Registrar-Agent) that receives a version larger than it knows about SHOULD log the contents and alert a human.¶

The created-on field contains a standard date/time string following [RFC3339].¶

The serial-number field takes the product-serial-number corresponding to the X520SerialNumber field of the IDevID certificate of the pledge.¶

The status-type value defined for BRSKI-PRM Status Query is bootstrap. This indicates the pledge to provide current status information regarding the bootstrapping status (voucher processing and enrollment of the pledge into the new domain).¶

As the Status Query artifact is defined generic, it may be used by other specifications to request further status information using other status types, e.g., for onboarding to get further information about enrollment of application specific LDevIDs or other parameters. This is out of scope for this specification.¶

Figure 33 below shows an example for unsigned Status Query data in JSON syntax using status-type bootstrap.¶

{
  "version": 1,
  "created-on": "2022-08-12T02:37:39.235Z",
  "serial-number": "pledge-callee4711",
  "status-type": "bootstrap"
}

The Status Query data MUST be signed by the Registrar-Agent using its private key corresponding to the EE (RegAgt) certificate. When using a JWS signature, the Status Query artifact looks as shown in Figure 34 and the Content-Type response header MUST be set to application/jose+json:¶

{
  "payload": BASE64URL(UTF8(status-query)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

For details on JWS Protected Header and JWS Signature see [I-D.ietf-anima-jws-voucher] or [RFC7515].¶

7.11.2. Response Artifact: Pledge Status (pStatus)

When the pledge receives a Status Query with status-type bootstrap it SHALL respond with previously collected telemetry information (see Section 7.9 and Section 7.10) in a single Pledge Status artifact.¶

The pledge-status response message is signed with IDevID or LDevID, depending on bootstrapping state of the pledge.¶

The following CDDL defines the structure of the Pledge Status (pStatus) data:¶

<CODE BEGINS>
  pledgestatus = {
    "version": uint,
    "status":
      "factory-default" /
      "voucher-success" /
      "voucher-error" /
      "enroll-success" /
      "enroll-error" /
      "connect-success" /
      "connect-error",
    ?"reason" : text,
    ?"reason-context": { $$arbitrary-map }
  }

<CODE ENDS>

Different cases for pledge bootstrapping status may occur, which SHOULD be reflected using the status enumeration. This document specifies the status values in the context of the bootstrapping process and credential application. Other documents may enhance the above enumeration to reflect further status information.¶

• "factory-default": Pledge has not been bootstrapped. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its IDevID(Pledge).¶

• "voucher-success": Pledge processed the voucher exchange successfully. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its IDevID(Pledge).¶

• "voucher-error": Pledge voucher processing terminated with error. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its IDevID(Pledge).¶

• "enroll-success": Pledge has processed the enrollment exchange successfully. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its LDevID(Pledge).¶

• "enroll-error": Pledge enrollment-response processing terminated with error. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its IDevID(Pledge).¶

As the pledge is assumed to utilize its bootstrapped credentials (LDevID) in communication with other peers, additional status information is provided for the connectivity to other peers, which may be helpful in analyzing potential error cases.¶

• "connect-success": Pledge could successfully establish a connection to another peer. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its LDevID(Pledge).¶

• "connect-error": Pledge connection establishment terminated with error. Additional information may be provided in the reason or reason-context. The pledge signs the response message using its LDevID(Pledge).¶

The pledge-status responses are cumulative in the sense that connect-success implies enroll-success, which in turn implies voucher-success.¶

Figure 36 provides an example for the bootstrapping-status information.¶

# The pledge "status-response" in General JWS Serialization syntax
{
  "payload": BASE64URL(UTF8(status-response)),
  "signatures": [
    {
      "protected": BASE64URL(UTF8(JWS Protected Header)),
      "signature": BASE64URL(JWS Signature)
    }
  ]
}

# Example: Decoded payload "status-response" representation
  in JSON syntax
{
  "version": 1,
  "status": "enroll-success",
  "reason-context": {
    "additional" : "JSON"
  }
}

# Example: Decoded "JWS Protected Header" representation
  in JSON syntax
{
  "alg": "ES256",
  "x5c": [
    "base64encodedvalue==",
    "base64encodedvalue=="
  ],
  "typ": "jose+json
}

• In case "factory-default" the pledge does not possess the domain certificate resp. the domain trust-anchor. It will not be able to verify the signature of the Registrar-Agent in the bootstrapping-status request.¶

• In cases "vouchered" and "enrolled" the pledge already possesses the domain certificate (has domain trust-anchor) and can therefore validate the signature of the Registrar-Agent. If validation of the JWS signature fails, the pledge SHOULD respond with the HTTP 403 Forbidden status code.¶

• The HTTP 406 Not Acceptable status code SHOULD be used, if the Accept header in the request indicates an unknown or unsupported format.¶

• The HTTP 415 Unsupported Media Type status code SHOULD be used, if the Content-Type of the request is an unknown or unsupported format.¶

• The HTTP 400 Bad Request status code SHOULD be used, if the Accept/Content-Type headers are correct but nevertheless the status-request cannot be correctly parsed.¶

The pledge SHOULD by default only respond to requests from nodes it can authenticate (such as registrar agent), once the pledge is enrolled with CA certificates and a matching domain certificate.¶