RFC 8295
EST (Enrollment over Secure Transport) Extensions
3. Distribute EE Certificates
Numerous mechanisms exist for clients to query repositories for certificates. The service provided by the /eecerts PC is different in that it is not a general-purpose query for client certificates; instead, it allows the server to provide peer certificates to a client that the server knows through an out-of-band mechanism that the client will be communicating with. For example, a router being provisioned that connects to two peers can be provisioned with not only its certificate but also with the peers' certificates. The server need not authenticate or authorize the client for distributing an EE certificate, because the package contents are already signed by a CA (i.e., the certificate(s) in a certs-only message has already been signed by a CA). The message flow is similar to Figure 1, except that the connection need not be HTTPS: | | Client | Establish TLS | Server | Session | |<-------------------->| | | | Request PAL | | (HTTP GET Request) | |--------------------->| |<---------------------| | Deliver PAL | | (HTTP GET Response) | | | | Request EE Cert(s) | | (HTTP GET Request) | |--------------------->| |<---------------------| | Deliver EE Cert(s) | | (HTTP GET Response) | | | Figure 2: /eecerts Message Sequence3.1. EE Certificate Request
Clients request EE certificates with an HTTP GET [RFC7231], using an operation path of "/eecerts".
3.2. EE Certificate Response
The response and processing of the returned error codes are identical to what is described in Section 4.1.3 of [RFC7030], except that the certificate provided is not the one issued to the client; instead, one or more client's peer certificates are returned in the certs-only message. Clients MUST reject EE certificates that do not validate to an authorized TA.4. Distribute CRLs and ARLs
CRLs (and ARLs) are needed in many instances to perform certificate path validation [RFC5280]. They can be obtained from repositories if their location is provided in the certificate. However, the client needs to parse the certificate and perform an additional round trip to retrieve them. Providing CRLs during bootstrapping obviates the need for the client to parse the certificate and aids those clients who might be unable to retrieve the CRL. Clients are free to obtain CRLs on which they rely from sources other than the server (e.g., a local directory). The /crls PC allows servers to distribute CRLs at the same time that clients retrieve their certificate(s) and CA certificate(s) as well as peer certificates. The server need not authenticate or authorize the client for distributing a CRL, because the package contents are already signed by a CA (i.e., the CRLs in a crls-only message have already been signed by a CA). The message flow is as depicted in Figure 2 but with "CRL(s)" instead of "EE Cert(s)".4.1. CRL Request
Clients request CRLs with an HTTP GET [RFC7231], using an operation path of "/crls".4.2. CRL Response
The response, and the processing of that response, are identical to what is described in Section 4.1.3 of [RFC7030], except that instead of providing the issued certificate one of more CRLs are returned in the crls-only message. Clients MUST reject CRLs that do not validate to an authorized TA.
5. Symmetric Keys, Receipts, and Errors
In addition to public keys, clients often need one or more symmetric keys to communicate with their peers. The /symmetrickeys PC allows the server to distribute symmetric keys to clients. Distribution of keys does not always work as planned, and clients need a way to inform the server that something has gone wrong; they also need a way to inform the server, if asked, that the distribution process has successfully completed. The /symmetrickeys/return PC allows clients to provide errors and receipts. Clients MUST authenticate the server, and clients MUST check the server's authorization. The server MUST authenticate clients, and the server MUST check the client's authorization. HTTP GET [RFC7231] is used when the server provides the key to the client (see Section 5.1), using the /symmetrickeys PC; HTTP POST [RFC7231] is used when the client provides a receipt (see Section 5.2) or an error (see Section 5.2) to the server with the /symmetrickeys/return PC.5.1. Symmetric Keys
Servers use /symmetrickeys to provide symmetric keys to clients; the symmetric key package is defined in [RFC6031]. As with the /serverkeygen PC defined in [RFC7030], the default method for distributing the symmetric key uses the encryption mode of the negotiated TLS cipher suite. Keys are not protected by preferred key-wrapping methods such as AES Key Wrap [RFC3394] or AES Key Wrap with Padding [RFC5649], because encryption of the symmetric key beyond that provided by TLS is OPTIONAL. Therefore, the cipher suite used to return the symmetric key MUST offer cryptographic strength that is commensurate with the symmetric key being delivered to the client. The cipher suite used MUST NOT have the NULL encryption algorithm, as this will disclose the unprotected symmetric key. It is strongly RECOMMENDED that servers always return encrypted symmetric keys.
The following depicts the protocol flow: | | Client | Establish TLS | Server | Session | |<--------------------->| | | | Request PAL | | (HTTP GET Request) | |---------------------->| |<----------------------| | Deliver PAL | | (HTTP GET Response) | | | | Req Symmetric Key | | (HTTP GET Request) | |---------------------->| |<----------------------| | Deliver Symmetric Key | | (HTTP GET Response) | | | Figure 3: /symmetrickeys Message Sequence5.1.1. Distribute Symmetric Keys
Clients request the symmetric key from the server with an HTTP GET [RFC7231], using an operation path of "/symmetrickeys".5.1.2. Symmetric Key Response
If the request is successful, the server response MUST have an HTTP 200 response code with a Content-Type of "application/cms" [RFC7193]. The optional application/cms encapsulatingContent and innerContent parameters SHOULD be included with the Content-Type to indicate the protection afforded to the returned symmetric key. The returned content varies: o If additional encryption is not being employed, the content associated with application/cms is a DER-encoded [X.690] symmetric key package. o If additional encryption is employed, the content associated with application/cms is DER-encoded enveloped-data that encapsulates a signed-data that further encapsulates a symmetric key package.
o If additional encryption and origin authentication are employed,
the content associated with application/cms is a DER-encoded
signed-data that encapsulates an enveloped-data that encapsulates
a signed-data that further encapsulates a symmetric key package.
o If CCC (CMS Content Constraints) [RFC6010] is supported, the
content associated with application/cms is a DER-encoded encrypted
key package [RFC6032]. The encrypted key package provides three
choices to encapsulate keys: EncryptedData, EnvelopedData, and
AuthEnvelopedData. Prior to employing one of these three
encryption choices, the key package can be encapsulated in a
signed-data.
How the server knows whether the client supports the encrypted key
package is beyond the scope of this document.
When rejecting a request, the server specifies either an HTTP 4xx
error or an HTTP 5xx error.
If a symmetric key package (which might be signed) or an encrypted
key package (which might be signed before and after encryption) is
digitally signed, the client MUST reject it if the digital signature
does not validate back to an authorized TA.
Note: Absent a policy on the client side requiring a signature, a
malicious EST server can simply strip the signature, thus bypassing
that check. In that case, this requirement is merely a sanity check,
serving to detect mis-signed packages or misconfigured clients.
[RFC3370], [RFC5753], [RFC5754], [RFC6033], [RFC6160], and [RFC6161]
provide algorithm details for use when protecting the symmetric key
package and encrypted key package.
5.2. Symmetric Key Receipts and Errors
Clients use /symmetrickeys/return to provide symmetric key package
receipts; the key package receipt content type is defined in
[RFC7191]. Clients can be configured to automatically return
receipts after processing a symmetric key package, return receipts
based on processing of the key-package-identifier-and-receipt-request
attribute [RFC7191], or return receipts when prompted by a PAL entry.
Servers can indicate that clients return a receipt by including the
key-package-identifier-and-receipt-request attribute in a signed-data
as a signed attribute. However, this attribute only appears when
additional encryption is employed (see Section 5.1.2).
Clients also use /symmetrickeys/return to return symmetric key package errors; the key package error content type is defined in [RFC7191]. Clients can be configured to automatically return errors after processing a symmetric key package or based on a PAL entry. The following depicts the protocol flow: | | Client | Establish TLS | Server | Session | |<-------------------->| | | | Request PAL | | (HTTP GET Request) | |--------------------->| |<---------------------| | Deliver PAL | | (HTTP GET Response) | | | | Return Receipt/Error | | (HTTP POST Request) | |--------------------->| |<---------------------| | (HTTP POST Response) | | status code only | | no content | | | Figure 4: /symmetrickeys/return Message Sequence5.2.1. Provide Symmetric Key Receipt or Error
Clients return symmetric key receipts and errors to the server with an HTTP POST [RFC7231], using an operation path of "/symmetrickeys/return". The returned content varies: o The key package receipt is digitally signed [RFC7191]; the Content-Type is "application/cms" [RFC7193]; and the associated content is signed-data, which encapsulates a key package receipt. o If the key package error is not digitally signed, the Content-Type is "application/cms" and the associated content is a key package error. If the key package error is digitally signed, the Content-Type is "application/cms" and the associated content is signed-data, which encapsulates a key package error.
The optional application/cms encapsulatingContent and innerContent parameters SHOULD be included with the Content-Type to indicate the protection afforded to the receipt or error. [RFC3370], [RFC5753], [RFC5754], and [RFC7192] provide algorithm details for use when protecting the key package receipt or key package error.5.2.2. Symmetric Key Receipt or Error Response
If the client successfully provides a receipt or error, the server response has an HTTP 204 response code (i.e., no content is returned). When rejecting a request, the server specifies either an HTTP 4xx error or an HTTP 5xx error. If a key package receipt or key package error is digitally signed, the server MUST reject it if the digital signature does not validate back to an authorized TA.6. Firmware, Receipts, and Errors
Servers can distribute object code for cryptographic algorithms and software with the firmware package [RFC4108]. Clients MUST authenticate the server, and clients MUST check the server's authorization. The server MUST authenticate the client, and the server MUST check the client's authorization. The /firmware PC uses an HTTP GET [RFC7231], and the /firmware/return PC uses an HTTP POST [RFC7231]. GET is used when the client retrieves firmware from the server (see Section 6.1); POST is used when the client provides a receipt (see Section 6.2) or an error (see Section 6.2).6.1. Firmware
The /firmware URI is used by servers to provide firmware packages to clients. The message flow is as depicted in Figure 3 modulo replacing "Symmetric Key" with "Firmware Package".
6.1.1. Distribute Firmware
Clients request firmware from the server with an HTTP GET [RFC7231], using an operation path of "/firmware".6.1.2. Firmware Response
If the request is successful, the server response MUST have an HTTP 200 response code with a Content-Type of "application/cms" [RFC7193]. The optional encapsulatingContent and innerContent parameters SHOULD be included with the Content-Type to indicate the protection afforded to the returned firmware. The returned content varies: o If the firmware is unprotected, then the Content-Type is "application/cms" and the content is the DER-encoded [X.690] firmware package. o If the firmware is compressed, then the Content-Type is "application/cms" and the content is the DER-encoded [X.690] compressed data that encapsulates the firmware package. o If the firmware is encrypted, then the Content-Type is "application/cms" and the content is the DER-encoded [X.690] encrypted-data that encapsulates the firmware package (which might be compressed prior to encryption). o If the firmware is signed, then the Content-Type is "application/cms" and the content is the DER-encoded [X.690] signed-data that encapsulates the firmware package (which might be compressed, encrypted, or compressed and then encrypted prior to signature). How the server knows whether the client supports the unprotected, signed, compressed, and/or encrypted firmware package is beyond the scope of this document. When rejecting a request, the server specifies either an HTTP 4xx error or an HTTP 5xx error. If a firmware package is digitally signed, the client MUST reject it if the digital signature does not validate back to an authorized TA. [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use when protecting the firmware package.
6.2. Firmware Receipts and Errors
Clients use the /firmware/return PC to provide firmware package load receipts and errors [RFC4108]. Clients can be configured to automatically return receipts and errors after processing a firmware package or based on a PAL entry. The message flow is as depicted in Figure 4 modulo the receipt or error is for a firmware package.6.2.1. Provide Firmware Receipt or Error
Clients return firmware receipts and errors to the server with an HTTP POST [RFC7231], using an operation path of "/firmware/return". The optional encapsulatingContent and innerContent parameters SHOULD be included with the Content-Type to indicate the protection afforded to the returned firmware receipt or error. The returned content varies: o If the firmware receipt is not digitally signed, the Content-Type is "application/cms" [RFC7193] and the content is the DER-encoded firmware receipt. o If the firmware receipt is digitally signed, the Content-Type is "application/cms" and the content is the DER-encoded signed-data encapsulating the firmware receipt. o If the firmware error is not digitally signed, the Content-Type is "application/cms" and the content is the DER-encoded firmware error. o If the firmware error is digitally signed, the Content-Type is "application/cms" and the content is the DER-encoded signed-data encapsulating the firmware error. [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use when protecting the firmware receipt or firmware error.6.2.2. Firmware Receipt or Error Response
If the request is successful, the server response MUST have an HTTP 204 response code (i.e., no content is returned). When rejecting a request, the server MUST specify either an HTTP 4xx error or an HTTP 5xx error.
If a firmware receipt or firmware error is digitally signed, the server MUST reject it if the digital signature does not validate back to an authorized TA.7. Trust Anchor Management Protocol
Servers distribute TAMP packages to manage TAs in a client's trust anchor databases; TAMP packages are defined in [RFC5934]. TAMP will allow the flexibility for a device to load TAs while maintaining an operational state. Unlike other systems that require new software loads when new PKI Roots are authorized for use, TAMP allows for automated management of roots for provisioning or replacement as needed. Clients MUST authenticate the server, and clients MUST check the server's authorization. The server MUST authenticate the client, and the server MUST check the client's authorization. The /tamp PC uses an HTTP GET [RFC7231], and the tamp/return PC uses an HTTP POST [RFC7231]. GET is used when the server requests that the client retrieve a TAMP package (see Section 7.1); POST is used when the client provides a confirm (see Section 7.2), provides a response (see Section 7.2), or provides an error (see Section 7.2) for the TAMP package.7.1. TAMP Status Query, Trust Anchor Update, Apex Trust Anchor Update, Community Update, and Sequence Number Adjust
Clients use the /tamp PC to retrieve the TAMP packages: TAMP Status Query, Trust Anchor Update, Apex Trust Anchor Update, Community Update, and Sequence Number Adjust. Clients can be configured to periodically poll the server for these packages or contact the server based on a PAL entry. The message flow is as depicted in Figure 3 modulo replacing "Symmetric Key" with the appropriate TAMP message.7.1.1. Request TAMP Packages
Clients request the TAMP packages from the server with an HTTP GET [RFC7231], using an operation path of "/tamp".
7.1.2. Return TAMP Packages
If the request is successful, the server response MUST have an HTTP 200 response code and a Content-Type of: o application/tamp-status-query for TAMP Status Query o application/tamp-update for Trust Anchor Update o application/tamp-apex-update for Apex Trust Anchor Update o application/tamp-community-update for Community Update o application/tamp-sequence-adjust for Sequence Number Adjust As specified in [RFC5934], these content types are digitally signed and clients must support validating the packages directly signed by TAs. For this specification, clients MUST support validation with a certificate and clients MUST reject it if the digital signature does not validate back to an authorized TA. [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use when protecting the TAMP packages.7.2. TAMP Responses, Confirms, and Errors
Clients return the TAMP Status Query Response, Trust Anchor Update Confirm, Apex Trust Anchor Update Confirm, Community Update Confirm, Sequence Number Adjust Confirm, and TAMP Error to servers, using the /tamp/return PC. Clients can be configured to automatically return responses, confirms, and errors after processing a TAMP package or based on a PAL entry. The message flow is as depicted in Figure 4 modulo replacing "Receipt/Error" with the appropriate TAMP response, confirm, or error.
7.2.1. Provide TAMP Responses, Confirms, or Errors
Clients provide the TAMP responses, confirms, and errors to the server with an HTTP POST, using an operation path of "/tamp/return". The Content-Type is: o application/tamp-status-response for TAMP Status Query Response o application/tamp-update-confirm for Trust Anchor Update Confirm o application/tamp-apex-update-confirm for Apex Trust Anchor Update Confirm o application/tamp-community-update-confirm for Community Update Confirm o application/tamp-sequence-adjust-confirm for Sequence Number Adjust Confirm o application/tamp-error for TAMP Error As specified in [RFC5934], these content types should be signed. If signed, a signed-data encapsulates the TAMP content. [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use when protecting the TAMP packages.7.2.2. TAMP Responses, Confirms, and Error Responses
If the request is successful, the server response MUST have an HTTP 204 response code (i.e., no content is returned). When rejecting a request, the server MUST specify either an HTTP 4xx error or an HTTP 5xx error. If the package is digitally signed, the server MUST reject it if the digital signature does not validate back to an authorized TA.8. Asymmetric Keys, Receipts, and Errors
[RFC7030] defines the /serverkeygen PC to support server-side generation of asymmetric keys. Keys are returned as either a) an unprotected PKCS #8 when additional security beyond TLS is not employed or b) a CMS asymmetric key package content type that is encapsulated in a signed-data content type that is further encapsulated in an enveloped-data content type when additional security beyond TLS is requested.
Some implementations prefer the use of other CMS content types to encapsulate the asymmetric key package. This document extends the content types that can be returned; see Section 8.1. [RFC7191] defines content types for key package receipts and errors. This document defines the /serverkeygen/return PC to add support for returning receipts and errors for asymmetric key packages; see Section 8.2. PKCS #12 [RFC7292] (sometimes referred to as "PFX" (Personal Information Exchange) or "P12") is often used to distribute asymmetric private keys and associated certificates. This document extends the /serverkeygen PC to allow servers to distribute server-generated asymmetric private keys and the associated certificate to clients using PKCS #12; see Section 8.3.8.1. Asymmetric Key Encapsulation
CMS supports a number of content types to encapsulate other CMS content types; [RFC7030] includes one such possibility. Note that when only relying on TLS the returned key is not a CMS content type. This document extends the CMS content types that can be returned. If the client supports CCC [RFC6010], then the client can indicate that it supports encapsulated asymmetric keys in the encrypted key package [RFC5958] by including the encrypted key package's OID in a content type attribute [RFC2985] in the CSR (Certificate Signing Request) -- aka the certification request -- that it provides to the server. If the client knows a priori that the server supports the encrypted key package content type, then the client need not include the content type attribute in the CSR. In all instances defined herein, the Content-Type is "application/cms" [RFC7193]. The optional encapsulatingContent and innerContent parameters SHOULD be included with the Content-Type to indicate the protection afforded to the returned asymmetric key package. If additional encryption and origin authentication are employed, the content associated with application/cms is a DER-encoded signed-data that encapsulates an enveloped-data that encapsulates a signed-data that further encapsulates an asymmetric key package. If CCC is supported and additional encryption is employed, the content associated with application/cms is a DER-encoded encrypted key package [RFC6032] content type that encapsulates a signed-data that further encapsulates an asymmetric key package.
If CCC is supported and if additional encryption and additional origin authentication are employed, the content associated with application/cms is a DER-encoded signed-data that encapsulates an encrypted key package content type that encapsulates a signed-data that further encapsulates an asymmetric key package. The encrypted key package [RFC6032] provides three choices to encapsulate keys: EncryptedData, EnvelopedData, and AuthEnvelopedData, with EnvelopedData being the mandatory-to-implement choice. When rejecting a request, the server specifies either an HTTP 4xx error or an HTTP 5xx error. If an asymmetric key package or an encrypted key package is digitally signed, the client MUST reject it if the digital signature does not validate back to an authorized TA. Note: Absent a policy on the client side requiring a signature, a malicious EST server can simply strip the signature, thus bypassing that check. In that case, this requirement is merely a sanity check, serving to detect mis-signed packages or misconfigured clients. [RFC3370], [RFC5753], [RFC5754], [RFC6033], [RFC6161], and [RFC6162] provide algorithm details for use when protecting the asymmetric key package and encrypted key package.8.2. Asymmetric Key Package Receipts and Errors
Clients can be configured to automatically return receipts after processing an asymmetric key package, return receipts based on processing of the key-package-identifier-and-receipt-request attribute [RFC7191], or return receipts when prompted by a PAL entry. Servers can indicate that clients return a receipt by including the key-package-identifier-and-receipt-request attribute [RFC7191] in a signed-data as a signed attribute. The protocol flow is identical to that depicted in Figure 4 modulo the receipt or error is for asymmetric keys. The server and client processing is as described in Sections 5.2.1 and 5.2.2 modulo the PC, which, for Asymmetric Key Packages, is "/serverkeygen/return".
8.3. PKCS #12
PFX is widely deployed and supports protecting keys in the same fashion as CMS, but it does so differently.8.3.1. Server-Side Key Generation Request
Similar to the other server-generated asymmetric keys provided through the /serverkeygen PC: o The certificate request is HTTPS POSTed and is the same format as for the "/simpleenroll" and "/simplereenroll" path extensions with the same content type. o In all respects, the server SHOULD treat the CSR as it would any enroll or re-enroll CSR; the only distinction here is that the server MUST ignore the public key values and signature in the CSR. These are included in the request only to allow the reuse of existing codebases for generating and parsing such requests. PBE (password-based encryption) shrouding of PKCS #12 is supported, and this specification makes no attempt to alter this de facto standard. As such, there is no support of the DecryptKeyIdentifier specified in [RFC7030] for use with PKCS #12 (i.e., "enveloping" is not supported). Note: The use of PBE requires that the password be distributed to the client; methods to distribute this password are beyond the scope of this document.8.3.2. Server-Side Key Generation Response
If the request is successful, the server response MUST have an HTTP 200 response code with a Content-Type of "application/pkcs12" [PKCS12] that consists of a base64-encoded DER-encoded [X.690] PFX [RFC7292]. Note that this response is different than the response returned as described in Section 4.4.2 of [RFC7030], because here the private key and the certificate are included in the same PFX. When rejecting a request, the server MUST specify either an HTTP 4xx error or an HTTP 5xx error. The response data's Content-Type MAY be "text/plain" [RFC2046] to convey human-readable error messages.
(next page on part 4)
