Draft: dtbootstrap-anima-keyinfra

Commentary: after mcr 's review calling this good enough to merge into master
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, if a signed artifact with a CMS format
signature is a binary object.  In the JSON encoding used here it
must be base64 encoded.  The nonce, created-on and assertion is
carried forward. serial-number is extracted from the pledge's
Client Certificate from the TLS connection.  See
RequestVoucherFromMASA.
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, if a signed artifact with a CMS format
signature is a binary object.  In the JSON encoding used here it
must be base64 encoded.  The nonce, created-on and assertion is
carried forward.  The serial-number is extracted from the pledge's
Client Certificate from the TLS connection.  See
RequestVoucherFromMASA.
As described in I-D.ietf-anima-voucher vouchers are normally short
lived to avoid revocation issues.  If the request is for a previous
(expired) voucher using the same registrar (as determined by the
registrar pinned-domain-cert) and the MASA has not been informed that
the claim is invalid then the request for a renewed voucher SHOULD be
automatically authorized.
As described in I-D.ietf-anima-voucher vouchers are normally short
lived to avoid revocation issues.  If the request is for a previous
(expired) voucher using the same registrar 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
VoucherResponse.
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 MASAauthenticationOfRegistrar and revocationcheck).
More flexible methods will likely involve sales channel integration
and authorizations (details are out-of-scope of this document).
If a nonceless voucher-request is submitted the MASA server MUST
authenticate the registrar as described in either EST RFC7030 section
3.2, section 3.3, or by validating the registrar's certificate used
to sign the registrar voucher-request.  Any of these methods reduce
the risk of DDoS attacks and provide an authenticated identity as an
input to sales channel integration and authorizations (the actual
sale-channel integration is also out-of-scope of this document).
Note that this section is about ensuring consistency of the
registrar.  These checks are not equivalent to RFC5280 Certificate
Revocation Checks that the pledge would ideally do if it had a real
time clock.
If the registrar uses a CA for which the MASA is able to obtain
revocation information, then the MASA SHOULD check for the maximum
validity period of the registrar's certificate.
A registrar which has done these checks may set the "domain-cert-
revocation-checks" attribute in the voucher to false (or omit it).
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 resulting voucher should have a lifetime (expires-on field) which
is 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.
By limiting the voucher lifetime in this way, the MASA is ensuring
the voucher is consistent with any CRL and lifetime checks.  See
section timeunknown.
If a nonceless voucher-request is submitted the MASA server MUST
authenticate the registrar as described in either EST RFC7030 section
3.2, section 3.3, or by validating the registrar's certificate used
to sign the registrar voucher-request.  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).
As noted in MASAauthenticationOfRegistrar the MASA performs registrar
authentication in a subset of situations (e.g. nonceless voucher
requests).  Normal PKIX revocation checking is assumed during either
EST client authentication or voucher-request signature validation.
Similarly, as noted in MASAsignatureconsistency, the MASA performs
normal PKIX revocation checking during signature consistency checks
(a signature by a registrar certificate that has been revoked is an
inconsistency).
If this check succeeds the MASA updates the voucher and audit log
assertion leafs with the "proximity" assertion.
The voucher-request serial-number leaf and the pledge serial-number
the MASA extracts from the prior-signed-voucher-request signing
certificate MUST match.  If this check succeeds the MASA updates the
voucher and audit log assertion leafs with the "proximity" assertion.
The voucher response to requests from the pledge and requests from a
registrar are in the same format.  A registrar either caches prior
MASA responses or dynamically requests a new voucher based on local
policy.
If the join operation is successful, the server (MASA responding to
registrar, and registrar responding to pledge) response MUST contain
an HTTP 200 response code.  The server MUST answer with a suitable
4xx or 5xx HTTP [RFC2616] error code when a problem occurs.  In this
case, the response data from the MASA server MUST be a plaintext
human-readable (ASCII, English) error message containing explanatory
information describing why the request was rejected.
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.  A registrar either caches prior
MASA responses or dynamically requests a new voucher based on local
policy (it does not generate or sign a voucher).
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 [RFC2616] error code when a problem occurs.  In this
case, the response data from the MASA server MUST be a plaintext
human-readable (ASCII, English) error message containing explanatory
information describing why the request was rejected.
The response is a "YANG-defined JSON document that has been signed
using a CMS structure" as described in I-D.ietf-anima-voucher
using the JSON encoded described in RFC7951.  The MASA MUST sign
the request.
The response is a "YANG-defined JSON document that has been signed
using a CMS structure" as described in I-D.ietf-anima-voucher
using the JSON encoded described in RFC7951.  The MASA MUST sign
the response.
The nonce from the pledge if available.  See MASAnoncehandling.
The method used to verify assertion.  See MASAassertion.
The domain CA cert.  See MASApinned.
The serial-number as provided in the voucher-request.  Also see
MASAassertion.
Set as appropriate for the pledge's capabilities and as documented
in I-D.ietf-anima-voucher.  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 RFC6961 or equivalent
integrations.
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
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.
Whenever a voucher is issued the MASA MUST update the audit log
appropriately.  The internal state requirements to maintain the audit
log are out-of-scope.  See MASAauditlog for a discussion of reporting
the log to a registrar.