RFC 8295
EST (Enrollment over Secure Transport) Extensions
2. Locate Available Packages
The PAL (Package Availability List) is either an XML (Extensible Markup Language) [XML] or JSON (JavaScript Object Notation) [RFC8259] object available through the /pal PC, which furnishes the following information to clients: o Advertisements for available packages that can be retrieved from the server; o Notifications to begin public key certificate management or to return package receipts and errors; and o Advertisement for another PAL. After being configured (see Section 1.4), the client can use this service to retrieve its PAL (see Section 2.1), which, if properly constructed (see Section 2.3), allows the client to determine some or all of the security-related packages needed for bootstrapping. Each PAL entry refers to other PCs (as defined in this document and in [RFC7030]) that clients use to a) retrieve packages that are available to them (e.g., CA certificates, firmware, trust anchors, symmetric keys, and asymmetric keys) or b) receive notifications to
initiate public key certificate enrollment. PAL entries can also be used to notify clients that they are to return receipts or errors for certain packages (see Section 2.1.1). Placing these entries after entries that clients used to retrieve the packages is the same as requesting receipts in the originally distributed package. Figure 1 provides a ladder diagram for the /pal PC protocol flow. Appendix A provides a detailed example. | | Client | Establish TLS | Server | Session | |<-------------------->| | | | Request PAL | | (HTTP GET Request) | |--------------------->| |<---------------------| | Deliver PAL | | (HTTP GET Response) | | | | Request package by | | specified URI | | (HTTP GET or POST | | Request) | |--------------------->| |<---------------------| | Deliver requested | | CMS package product | | (HTTP GET or POST | | Response) | | | Repeat as necessary. Figure 1: /pal Message Sequence PALs are designed to support an arbitrary number of entries, but for PALs that need to be divided for any reason, there is a special PAL entry type that constitutes a collection of "PAL package types". Package type 0001 ("Additional PAL value present") refers to another PAL. See Sections 2.1 and 2.1.1. If present, the 0001 package type is always last because other entries after it are ignored. Also, in order to avoid needlessly dereferencing URIs, the 0001 package type cannot be the only PAL entry. In addition to using the PAL during bootstrapping, clients can be configured to periodically poll the server to determine if updated packages are available for them. Note that the mechanism to configure how often clients poll the server is beyond the scope of this document. However, there are some services
that support indicating when a client should retry its request (e.g., simple enrollment and re-enroll responses include the Retry-After header [RFC7030]). As noted earlier, the PAL supports two variants: XML and JSON. Clients include the HTTP Accept header [RFC7231] when they connect to the server to indicate whether they support XML or JSON. The client MUST authenticate the server as specified in [RFC7030], and the client MUST check the server's authorization as specified in [RFC7030]. The server MUST authenticate the client as specified in [RFC7030], and the server MUST check the client's authorization as specified in [RFC7030]. PAL support is OPTIONAL. It is shown in figures throughout this document, but clients need not support the PAL to access services offered by the server.2.1. PAL Format
Each PAL is composed of zero or more entries. Each entry is composed of four fields -- type, date, size, and info -- whose semantics follow: Note: Both XML elements and JSON values are described below. XML elements are enclosed in angle brackets (<>), and JSON values are enclosed in single quotes (''). When described together, they are enclosed in square brackets ([]) separated by a vertical bar (|). o [<type> | 'type'] uniquely identifies each package that a client may retrieve from the server with a 4-digit string. [<type> | 'type'] MUST be present. The PAL package types are defined in Section 2.1.1. o [<date> | 'date'] indicates one of the following: * The date and time that the client last successfully downloaded the identified package from the server. [<date> | 'date'] MUST be represented as Generalized Time with 20 characters: YYYY-MM-DDTHH:MM:SSZ; <date> matches the dateTime production in "canonical representation" [XMLSCHEMA]; 'date' is a string. Implementations SHOULD NOT rely on time resolution finer than seconds and MUST NOT generate time instants that specify leap seconds.
* The omission of [<date> | 'date'] indicates the following:
- There is no indication that the client has successfully
downloaded the identified package, or
- The PAL entry corresponds to a pointer to the next PAL, or
the server is requesting a package from the client (e.g.,
certification request, receipt, error).
o [<size> | 'size'] indicates the size in bytes of the package;
<size> is a nonNegativeInteger, and 'size' is a number. A package
size of zero (i.e., "0" without the quotes) indicates that the
client needs to begin a transaction, return an error, or return a
receipt. [<size> | 'size'] MUST be present.
o [<info> | 'info'] provides an SKI (Subject Key Identifier), a DN
(Distinguished Name), an Issuer and Serial Number tuple, or a URI,
i.e., it is a choice between these four items, all of which are
defined in [RFC5280]. When a URI [RFC3986] is included,
[<uri> | 'uri'] indicates the location where the identified
package can be retrieved. When a DN, an SKI, or an Issuer Name
and Serial Number tuple is included, it points to a certificate
that is the subject of the notification (i.e., the certificate to
be rekeyed or renewed); [<dn> | 'dn'] is encoded as a string with
the format defined in [RFC4514]; <ski> is a hexBinary, and 'ski'
is a string of hex digits (i.e., 0-9, a-f, and A-F);
[<iasn> | 'iasn'] includes both [<issuer> | 'issuer'] and
[<serial> | 'serial'] as a complexType in XML and an object in
JSON. [<issuer> | 'issuer'] is a DN encoded as a string with the
format defined in [RFC4514]; <serial> is a positiveInteger, and
'serial' is a number. [<info> | 'info'] MUST be present, and
[<info> | 'info'] MUST include exactly one [<dn> | 'dn'],
[<ski> | 'ski'], [<iasn> | 'iasn'], or [<uri> | 'uri'].
Clients are often limited by the size of objects they can consume;
the PAL is not immune to these limitations. As opposed to picking a
limit for all clients, a special package type (0001) is defined (see
Section 2.1.1) to indicate that another PAL is available. Servers
can use this value to limit the size of the PALs provided to clients.
The mechanism for servers to know client PAL size limits is beyond
the scope of this document; one possible solution is through
provisioned information.
2.1.1. PAL Package Types
Table 1 lists the PAL package types that are defined by this document: Package Package Description Number -------- --------------------------------------------------- 0000 Reserved 0001 Additional PAL value present 0002 X.509 CA certificate 0003 X.509 EE certificate 0004 X.509 ARL 0005 X.509 CRL 0006 Start DS certificate enrollment with CSR attribute 0007 Start DS certificate enrollment 0008 DS certificate enrollment (success) 0009 DS certificate enrollment (failure) 0010 Start DS certificate re-enrollment 0011 DS certificate re-enrollment (success) 0012 DS certificate re-enrollment (failure) 0013 Start KE certificate enrollment with CSR attribute 0014 Start KE certificate enrollment 0015 KE certificate enrollment (success) 0016 KE certificate enrollment (failure) 0017 Start KE certificate re-enrollment 0018 KE certificate re-enrollment (success) 0019 KE certificate re-enrollment (failure) 0020 Asymmetric Key Package (PKCS #8) 0021 Asymmetric Key Package (CMS) 0022 Asymmetric Key Package (PKCS #12) 0023 Asymmetric Key Package Receipt or Error 0024 Symmetric Key Package 0025 Symmetric Key Package Receipt or Error 0026 Firmware Package 0027 Firmware Package Receipt or Error 0028 TAMP Status Query 0029 TAMP Status Query Response or Error 0030 Trust Anchor Update 0031 Trust Anchor Update Confirm or Error 0032 Apex Trust Anchor Update 0033 Apex Trust Anchor Update Confirm or Error 0034 Community Update 0035 Community Update Confirm or Error 0036 Sequence Number Adjust 0037 Sequence Number Adjust Confirm or Error Table 1: PAL Package Types
Note: "CSR" is Certificate Signing Request, "DS" is Digital Signature, and "KE" is Key Establishment. PAL package types are essentially hints about the type of package the client is about to retrieve or is asked to return. Savvy clients can parse the packages to determine what has been provided, but in some instances it is better to know before retrieving the package. The hint provided here does not obviate the need for clients to check the type of package provided before they store it, possibly in specially allocated locations (i.e., some clients might store Root ARLs separately from intermediate CRLs). For packages provided by the client, the server is asking the client to provide an enrollment package, receipt, response, confirm, or error. The PAL package types have the following meanings: Note: The semantics behind Codes 0002 and 0006-0021 are defined in [RFC7030]. 0000 Reserved: Reserved for future use. 0001 Additional PAL value present: Indicates that this PAL entry refers to another PAL by referring to another /pal URI, which is defined in this section. This PAL package type limits the size of PALs to a more manageable size for clients. If this PAL package type appears, it MUST be the last entry in the PAL. Additionally, in order to avoid needlessly dereferencing URIs, this PAL package type MUST NOT be the only entry. 0002 X.509 CA certificate: Indicates that one or more CA certificates [RFC5280] are available for the client by pointing to a /cacerts URI, which is defined in [RFC7030]. 0003 X.509 EE certificate: Indicates that one or more EE certificates [RFC5280] are available for the client by pointing to an /eecerts URI, which is defined in Section 3. 0004 X.509 ARL: Indicates that one or more ARLs (Authority Revocation Lists) [RFC5280] are available for the client by pointing to a /crls URI, which is defined in Section 4. 0005 X.509 CRL: Indicates that one or more CRLs (Certificate Revocation Lists) [RFC5280] are available for the client by pointing to a /crls URI, which is defined in Section 4.
Note: See Section 9 for additional information about PAL and certificate enrollment interaction. See Appendix B for additional informative information. 0006 Start DS certificate enrollment with CSR: Indicates that the client needs to begin enrolling its DS certificate (i.e., any certificate for which the key usage extension will have a digital signature set), using a template provided by the server with a CSR (Certificate Signing Request) attribute (see Appendix B). The PAL entry points to a /csrattrs URI, which is defined in [RFC7030]. 0007 Start DS certificate enrollment: Indicates that the client needs to begin enrolling its DS certificate. The PAL entry points to a /simpleenroll URI, which is defined in [RFC7030]. 0008 DS certificate enrollment (success): Indicates that the client needs to retrieve a successful certification response. The PAL entry points to a /simpleenroll or a /fullcmc URI, both of which are defined in [RFC7030]. 0009 DS certificate enrollment (failure): Indicates that the client needs to retrieve a failed certification response for a DS certificate. This PAL entry points to a /simpleenroll or a /fullcmc URI. 0010 Start DS certificate re-enrollment: Indicates that the client needs to rekey or renew a DS certificate. The PAL entry points to a /simplereenroll or a /fullcmc URI. 0011 DS certificate re-enrollment (success): See PAL package type 0008. 0012 DS certificate re-enrollment (failure): See PAL package type 0009. Note: The KE (Key Establishment) responses that follow use the same URIs as DS certificates, except that the certificates' key usage extension is set to only key agreement or key transport. 0013 Start KE certificate enrollment with CSR: See PAL package type 0006. 0014 Start KE certificate enrollment: See PAL package type 0007. 0015 KE certificate enrollment (success): See PAL package type 0008. 0016 KE certificate enrollment (failure): See PAL package type 0009.
0017 Start KE certificate re-enrollment: See PAL package type 0010.
0018 KE certificate re-enrollment (success): See PAL package
type 0008.
0019 KE certificate re-enrollment (failure): See PAL package
type 0009.
Note: The variations in the asymmetric key packages are due to the
number of CMS content types that can be used to protect the
asymmetric key; the syntax for the asymmetric key is the same, but
additional ASN.1 is needed to include it in a signed-data (i.e., the
ASN.1 needs to be a CMS content type and not the private key info
type). See Section 8 of this document for additional information.
0020 Asymmetric Key Package (PKCS #8): Indicates that an asymmetric
key generated by the server is available for the client; the
package is an asymmetric key without additional encryption as
specified in Section 4.4.2 of [RFC7030]. The PAL entry points
to a /serverkeygen or a /fullcmc URI, which are defined in
[RFC7030].
0021 Asymmetric Key Package (CMS): See PAL package type 0020 (the
difference being that the package available is an asymmetric key
package [RFC5958] that is signed and encapsulated in a
signed-data content type, as specified in Section 4.4.2 of
[RFC7030]). Also, see Section 8.1 of this document.
0022 Asymmetric Key Package (PKCS #12): See PAL package type 0020
(the difference being that the package available is the PKCS #12
[RFC7292] content type). See Section 8.3 of this document.
0023 Asymmetric Key Package Receipt or Error: Indicates that the
server wants the client to return a key package receipt or error
[RFC7191] to the /serverkeygen/return URI, which is defined in
Section 8.
0024 Symmetric Key Package: Indicates that a symmetric key package
[RFC6031] is available for the client by pointing to a
/symmetrickeys URI, which is defined in Section 5.
0025 Symmetric Key Package Receipt or Error: Indicates that the
server wants the client to return a key package receipt or error
[RFC7191] to the /symmetrickeys/return URI, which is defined in
Section 5.
0026 Firmware Package: Indicates that a firmware package [RFC4108] is available for the client, using the /firmware URI, which is defined in Section 6. 0027 Firmware Package Receipt or Error: Indicates that the server wants the client to return a firmware package load receipt or error [RFC4108] to the /firmware/return URI, which is defined in Section 6. Note: The /tamp and tamp/return URIs are defined in Section 7. 0028 TAMP Status Query: Indicates that a TAMP Status Query package [RFC5934] is available for the client, using the /tamp URI. 0029 TAMP Status Query Response or Error: Indicates that the server wants the client to return a TAMP Status Query Response or Error [RFC5934] to the /tamp/return URI. 0030 Trust Anchor Update: Indicates that a Trust Anchor Update package [RFC5934] is available for the client, using the /tamp URI. 0031 Trust Anchor Update Confirm or Error: Indicates that the server wants the client to return a Trust Anchor Update Confirm or Error [RFC5934] to the /tamp/return URI. 0032 Apex Trust Anchor Update: Indicates that an Apex Trust Anchor Update package [RFC5934] is available for the client, using the /tamp URI. 0033 Apex Trust Anchor Update Confirm or Error: Indicates that the server wants the client to return an Apex Trust Anchor Update Confirm or Error [RFC5934] to the /tamp/return URI. 0034 Community Update: Indicates that a Community Update package [RFC5934] is available for the client, using the /tamp URI. 0035 Community Update Confirm or Error: Indicates that the server wants the client to return a Community Update Confirm or Error [RFC5934] to the /tamp/return URI. 0036 Sequence Number Adjust: Indicates that a Sequence Number Adjust package [RFC5934] is available for the client, using the /tamp URI. 0037 Sequence Number Adjust Confirm or Error: Indicates that the server wants the client to return a Sequence Number Adjust Confirm or Error [RFC5934] to the /tamp/return URI.
2.1.2. PAL XML Schema
The namespace is specified in Section 11.1. The fields in the schema were discussed earlier, in Sections 2.1 and 2.1.1. <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:pal="urn:ietf:params:xml:ns:pal" targetNamespace="urn:ietf:params:xml:ns:pal" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0"> <xsd:annotation> <xsd:documentation> This schema defines the types and elements needed to retrieve client packages from the server or for the client to post packages to the server. </xsd:documentation> </xsd:annotation> <!-- ===== Element Declarations ===== --> <xsd:element name="pal" type="pal:PAL" /> <!-- ===== Complex Data Element Type Definitions ===== --> <xsd:complexType name="PAL"> <xsd:annotation> <xsd:documentation> This type defines the Package Availability List (PAL). </xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:element name="message" type="pal:PALEntry" minOccurs="0" maxOccurs="unbounded"> <xsd:annotation> <xsd:documentation> This item contains information about the package and a link that the client uses to download or post the package. </xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType>
<xsd:complexType name="PALEntry">
<xsd:annotation>
<xsd:documentation>
This type defines a product in the PAL.
</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="type" type="pal:PackageType" />
<xsd:element name="date" type="pal:GeneralizedTimeType"
minOccurs="0" />
<xsd:element name="size" type="xsd:nonNegativeInteger">
<xsd:annotation>
<xsd:documentation>
This item indicates the package's size.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="info" type="pal:PackageInfoType" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PackageInfoType">
<xsd:annotation>
<xsd:documentation>
This type allows a choice of X.500 Distinguished Name,
Subject Key Identifier, Issuer and Serial Number tuple,
or URI.
</xsd:documentation>
</xsd:annotation>
<xsd:choice>
<xsd:element name="dn" type="pal:DistinguishedName" />
<xsd:element name="ski" type="pal:SubjectKeyIdentifier" />
<xsd:element name="iasn" type="pal:IssuerAndSerialNumber" />
<xsd:element name="uri" type="pal:ThisURI" />
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="IssuerAndSerialNumber">
<xsd:annotation>
<xsd:documentation>
This type holds the issuer Distinguished Name and
serial number of a referenced certificate.
</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="issuer" type="pal:DistinguishedName" />
<xsd:element name="serial" type="xsd:positiveInteger" />
</xsd:sequence>
</xsd:complexType>
<!-- ===== Simple Data Element Type Definitions ===== -->
<xsd:simpleType name="PackageType">
<xsd:annotation>
<xsd:documentation>
This type identifies each package that a client may retrieve
from the server with a 4-digit string.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="d{4}" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="GeneralizedTimeType">
<xsd:annotation>
<xsd:documentation>
This type indicates the date and time (YYYY-MM-DDTHH:MM:SSZ)
that the client last acknowledged successful receipt of the
package; it is absent if a) there is no indication that the
package has been downloaded or b) the PAL entry corresponds
to a pointer to the next PAL.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:dateTime">
<xsd:pattern value=".*:d{2}Z" />
<xsd:minInclusive value="2013-05-23T00:00:00Z" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="DistinguishedName">
<xsd:annotation>
<xsd:documentation>
This type holds an X.500 Distinguished Name.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="1024" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="SubjectKeyIdentifier">
<xsd:annotation>
<xsd:documentation>
This type holds a hex string representing the value of a
certificate's SubjectKeyIdentifier.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:hexBinary">
<xsd:maxLength value="1024" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ThisURI">
<xsd:annotation>
<xsd:documentation>
This type holds a URI but is length limited.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:anyURI">
<xsd:maxLength value="1024" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
2.1.3. PAL JSON Object
The following is an example PAL JSON object. The fields in the object were discussed earlier, in Sections 2.1 and 2.1.1. [ { "type": "0003", "date": "2016-12-29T09:28:00Z", "size": 1234, "info": { "uri": "https://www.example.com/.well-known/est/eecerts/1234" } }, { "type": "0006", "date": "2016-12-29T09:28:00Z", "size": 1234, "info": { "iasn": { "issuer": "CN=Sean Turner,O=sn3rd,C=US", "serial": 0 } } } ]2.2. Request PAL
Clients request their PAL with an HTTP GET [RFC7231], using an operation path of "/pal". Clients indicate whether they would prefer XML or JSON by including the HTTP Accept header [RFC7231] with either "application/xml" or "application/json", respectively.
2.3. Provide PAL
If the server has a PAL for the client, the server response MUST contain an HTTP 200 response code with a Content-Type of "application/xml" [RFC7303] or "application/json" [RFC8259]. When the server constructs a PAL, an order of precedence for PAL offerings is based on the following rationale: o /cacerts and /crls packages are the most important because they support validation decisions on certificates used to sign and encrypt other listed PAL items. o /csrattrs are the next in importance, since they provide information that the server would like the client to include in its certificate enrollment request. o /simpleenroll, /simplereenroll, and /fullcmc packages are next in importance, since they can impact a certificate used by the client to sign CMS content or a certificate to establish keys for encrypting content exchanged with the client. * A client engaged in certificate management SHOULD accept and process CA-provided transactions as soon as possible to avoid undue delays that might lead to protocol failure. o /symmetrickeys, /firmware, /tamp, and /eecerts packages containing keys and other types of products are last. Precedence SHOULD be given to packages that the client has not previously downloaded. The items listed in a PAL may not identify all of the packages available for a device. This can be for any of the following reasons: * The server may temporarily withhold some outstanding PAL items to simplify client processing. * If a CA has more than one certificate ready for the client, the server will provide a notice for one at a time. Pending notices will be serviced in order, according to the date when the certificate will be used (earliest date first). When rejecting a request, the server specifies either an HTTP 4xx error or an HTTP 5xx error. All other return codes are handled as specified in Section 4.2.3 of [RFC7030] (i.e., 202 handling and all other HTTP response codes).
(next page on part 3)
