RFC 8295
EST (Enrollment over Secure Transport) Extensions
RFC 8295: EST (Enrollment over Secure Transport) Extensions 🎀
Part 1 of 12 💅
okay bestie, let's start with the basics 🦋 this is an Internet Standards Track doc, so it's the real deal and not just a suggestion ✨ It's from January 2018 and was written by S. Turner (listed alongside sn3rd). It has ISSN 2070-1721 and gets its own RFC number, 8295 🌸 The title block doesn't list anything it obsoletes or updates, so it's standing on its own. iconic 👑
Abstract
okay so the EST (Enrollment over Secure Transport) protocol already gives you the Well-Known URI /.well-known/est 🧚 along with a bunch of other path components that clients use for PKI (Public Key Infrastructure) services. the big one is certificate enrollment, like /simpleenroll 💜
this doc adds more PKI services as extra path components 🍓 we're talking firmware, trust anchors, and symmetric, asymmetric, and encrypted keys 🔥
it also specifies the PAL (Package Availability List) 📦 which is an XML (Extensible Markup Language) file or a JSON (JavaScript Object Notation) object. clients use it to grab the packages that are available and authorized for them. main character energy 💅
and lastly, this doc extends the EST server path components so all of this can actually happen ✨
Status of This Memo
ngl this part is the official paperwork 🙈 but here's the tea:
This is an Internet Standards Track document.
It's a product of the Internet Engineering Task Force (IETF) 🌈 and it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 🫶 for more on Internet Standards, check out Section 2 of RFC 7841.
Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8295 🎀
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. 💖
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. please review these documents carefully, because they describe your rights and restrictions with respect to this document ✨
Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Simplified BSD License 🦋
Table of Contents
here's the full map so you can see where everything is 🗺️🧚
1. Introduction ....................................................4
1.1. Definitions ................................................6
1.2. Authentication and Authorization ...........................7
1.3. TLS Cipher Suites ..........................................7
1.4. URI Configuration ..........................................7
1.5. Message Types ..............................................8
1.6. Key Words .................................................10
2. Locate Available Packages ......................................10
2.1. PAL Format ................................................12
2.1.1. PAL Package Types ..................................14
2.1.2. PAL XML Schema .....................................19
2.1.3. PAL JSON Object ....................................23
2.2. Request PAL ...............................................23
2.3. Provide PAL ...............................................24
3. Distribute EE Certificates .....................................25
3.1. EE Certificate Request ....................................25
3.2. EE Certificate Response ...................................26
4. Distribute CRLs and ARLs .......................................26
4.1. CRL Request ...............................................26
4.2. CRL Response ..............................................26
5. Symmetric Keys, Receipts, and Errors ...........................27
5.1. Symmetric Keys ............................................27
5.1.1. Distribute Symmetric Keys ..........................28
5.1.2. Symmetric Key Response .............................28
5.2. Symmetric Key Receipts and Errors .........................29
5.2.1. Provide Symmetric Key Receipt or Error .............30
5.2.2. Symmetric Key Receipt or Error Response ............31
6. Firmware, Receipts, and Errors .................................31
6.1. Firmware ..................................................31
6.1.1. Distribute Firmware ................................32
6.1.2. Firmware Response ..................................32
6.2. Firmware Receipts and Errors ..............................33
6.2.1. Provide Firmware Receipt or Error ..................33
6.2.2. Firmware Receipt or Error Response .................33
7. Trust Anchor Management Protocol ...............................34
7.1. TAMP Status Query, Trust Anchor Update,
Apex Trust Anchor Update, Community Update,
and Sequence Number Adjust ................................34
7.1.1. Request TAMP Packages ..............................34
7.1.2. Return TAMP Packages ...............................35
7.2. TAMP Responses, Confirms, and Errors ......................35
7.2.1. Provide TAMP Responses, Confirms, or Errors ........36
7.2.2. TAMP Responses, Confirms, and Error Responses ......36
8. Asymmetric Keys, Receipts, and Errors ..........................36
8.1. Asymmetric Key Encapsulation ..............................37
8.2. Asymmetric Key Package Receipts and Errors ................38
8.3. PKCS #12 ..................................................39
8.3.1. Server-Side Key Generation Request .................39
8.3.2. Server-Side Key Generation Response ................39
9. PAL and Certificate Enrollment .................................40
10. Security Considerations .......................................43
11. IANA Considerations ...........................................44
11.1. PAL Name Space ...........................................44
11.2. PAL XML Schema ...........................................44
11.3. PAL Package Types ........................................44
12. References ....................................................45
12.1. Normative References .....................................45
12.2. Informative References ...................................50
Appendix A. Example Use of PAL ....................................51
Appendix B. Additional CSR Attributes .............................53
Acknowledgements ..................................................54
Author's Address ..................................................541. Introduction ✨
okay so bestie, the EST (Enrollment over Secure Transport) protocol [RFC7030] already defines a Well-Known URI, /.well-known/est 🌸, for a handful of PKI (Public Key Infrastructure) services. Those include simple enrollment with /simpleenroll and rekey or renew with /simplereenroll, and more. A server that wants to offer more PKI-related services and other security-related packages can reuse that same .well-known URI by defining extra PCs (path components). This document defines six of them, and they're honestly so iconic 💅
/pal- The PAL (Package Availability List) is a list of every known package that's available and authorized for a client 📋. A client hits this PC first, then walks through the PAL and downloads everything it needs to start operating securely 🔐. The PAL basically points to other PCs, including the ones defined here and the ones in [RFC7030] (for example,/cacerts,/simpleenroll,/simplereenroll,/fullcmc,/serverkeygen, and/csrattrs) 🧚. The/palPC is described in Section 2./eecerts- EE (End-Entity) certificates [RFC5280] are what a client needs once it starts a security protocol to talk to a peer 🦋. Basically, they're what make it operational and actually doing something meaningful, instead of just chatting with the infrastructure. If the infrastructure already knows which certificates the client needs, it can hand over the peer's certificate so the client doesn't have to go hunting for it 🔍. This is NOT a general-purpose repository where clients ask and get answers back. It's purely a push mechanism, no cap 🙅♀️. The/eecertsPC is described in Section 3./crls- CRLs (Certificate Revocation Lists) and ARLs (Authority Revocation Lists) [RFC5280] are also things a client needs when it validates certificate paths 💀. CRLs (and ARLs) from TAs (Trust Anchors) and intermediate CAs (Certification Authorities) are needed to validate the certificates used for the client's certificate or the peer's certificate, which are provided through the/eecertsPC. Pushing them saves the client from having to "discover" them and then retrieve them 🫶. CRL "discovery" is a lot easier when the CRL Distribution Point certificate extension [RFC5280] is included, but that extension isn't always there, and then the client needs another connection to get the lists 😭. Just like/eecerts, this is a push mechanism and not a general-purpose repository where clients query and then get a response 💜. The/crlsPC is described in Section 4./symmetrickeys- Sometimes clients use symmetric keys [RFC6031] when they talk to their peers 🔑. If the server already knows the client's peers ahead of time, handing those keys over saves the client or an administrator from later having to find, retrieve, and install them 🙌. Like/eecertsand/crls, this is not a general-purpose repository. It's purely a push mechanism for the keys themselves 🎀. But things don't always go as planned, so clients need to tell the server about any errors ⚠️. And if things did go well, the client, if asked, needs to send back a receipt [RFC7191] 🧾. The/symmetrickeysand/symmetrickeys/returnPCs are described in Section 5./firmware- Some client firmware and software have automatic update mechanisms, and some don't 🛠️. For the ones that don't, the/firmwarePC gives the infrastructure a way to tell the client that firmware and software updates [RFC4108] are available 📣. Updates don't always go smoothly, and sometimes the server needs to know whether the firmware actually arrived and got processed. So this PC also includes a way to return errors and receipts 🧾✨. The/firmwareand/firmware/returnPCs are defined in Section 6./tamp- To manage the TAs in client TA databases, servers use the/tampPC to ask clients to retrieve TAMP (Trust Anchor Management Protocol) query, update, and adjust packages [RFC5934] 👑. Clients then use the/tamp/returnPC to send back TAMP responses, confirms, and errors [RFC5934] 🌈. The/tampand/tamp/returnPCs are defined in Section 7.
This document also extends the /est/serverkeygen PC [RFC7030] to support the following (see Section 8) 🍓:
- Returning asymmetric key package receipts and errors [RFC7191].
- Encapsulating returned asymmetric keys in additional CMS (Cryptographic Message Syntax) content types [RFC7193].
- Returning server-generated public key pairs encapsulated in PKCS #12 (Public Key Cryptography Standard #12) [RFC7292].
Okay so the whole motivation is getting packages to clients during enrollment, so they can stay secure after enrollment 🥹. But the services in this specification can also be used after enrollment, which is lowkey a bonus 💖.
1.1. Definitions
Familiarity with the following specifications is assumed 📚:
- "Using Cryptographic Message Syntax (CMS) to Protect Firmware Packages" [RFC4108]
- "Certificate Management over CMS (CMC)" [RFC5272]
- "Cryptographic Message Syntax (CMS) Encrypted Key Package Content Type" [RFC6032]
- "Cryptographic Message Syntax (CMS)" [RFC5652]
- "Additional New ASN.1 Modules for the Cryptographic Message Syntax (CMS) and the Public Key Infrastructure Using X.509 (PKIX)" [RFC6268]
- "Trust Anchor Management Protocol (TAMP)" [RFC5934]
- "Cryptographic Message Syntax (CMS) Content Constraints Extension" [RFC6010]
- "Cryptographic Message Syntax (CMS) Symmetric Key Package Content Type" [RFC6031]
- "Enrollment over Secure Transport" [RFC7030]
- "Cryptographic Message Syntax (CMS) Key Package Receipt and Error Content Types" [RFC7191]
Also, familiarity with the CMS protecting content types signed-data and encrypted-data [RFC5652] is assumed 🧠. The CMS encrypted key package is defined in [RFC6032].
In addition to the definitions found in [RFC7030], the following definitions are used in this document 💅:
Agent: An entity that performs functions on behalf of a client. Agents can service a) one or more clients on the same network as the server, b) clients on non-IP-based networks, or c) clients that have a non-electronic air gap [RFC4949] between themselves and the server. Interactions between the agent and client in the last two cases are beyond the scope of this document 🚧. Before an agent can service clients, the agent must have a trust relationship with the server (i.e., be authorized to act on behalf of clients) 🤝.
Client: A device that ultimately consumes and uses the packages to enable communications. In other words, the client is the endpoint for the packages, and an agent may have one or more clients 🎯. To avoid confusion, this document henceforth uses the term "client" to refer to both agents and clients 🫠.
Package: An object that contains one or more content types. There are numerous types of packages, e.g., packages for asymmetric keys, symmetric keys, encrypted keys, CRLs, firmware, and TAMP. See Section 2.1.1 📦. All of these packages are digitally signed by their creator and encapsulated in a CMS signed-data [RFC5652] [RFC6268] (except the public key certificates and CRLs that are already digitally signed by a CA): firmware receipts and errors; TAMP responses, confirms, and errors; and "key package" receipts and errors that can be optionally signed ✍️. Certificates and CRLs are included in a package that uses signed-data, which is often referred to as a "degenerate CMS", or as a "certs-only" [RFC5751] [RFC6268] or "crls-only" message (see Section 4.2), but no signature or content is present -- hence the names "certs-only" and "crls-only" 🥺.
Note: As per [RFC7030], the creator may or may not be the EST server or the EST CA 👀.
1.2. Authentication and Authorization
Client and server authentication as well as client and server authorization are as defined in [RFC7030] 🔐. The requirements for each are discussed in the "request" and "response" sections (e.g., Sections 3.1 and 3.2 of this document) of each of the PCs defined herein 📝.
The requirements for the TA databases are as specified in [RFC7030] as well 🗂️.
1.3. TLS Cipher Suites
TLS (Transport Layer Security) cipher suites and issues associated with them are as defined in [RFC7030] 🔒.
1.4. URI Configuration
As specified in Section 3.1 of [RFC7030], the client is configured with sufficient information to form the server URI [RFC3986] 🧭. Like EST, this configuration mechanism is beyond the scope of this document 🌷.
1.5. Message Types 💅
okay so this doc is literally borrowing existing media types for its messages, like the ones from "Internet X.509 Public Key Infrastructure Operational Protocols: FTP and HTTP" [RFC2585], "The application/pkcs10 Media Type" [RFC5967], and "Certificate Management over CMS (CMC)" [RFC5272]. no need to reinvent the wheel 🫶
for consistency with [RFC5273], every distinct EST message type uses an HTTP Content-Type header with its own specific media type 🎀
here's the big table of every EST message, its media type for each operation, and which sections explain the request and response. it's giving organized chaos 🌈
+-------------------+---------------------------------+---------------+
| Message type | Request media type | Request |
| | Response media type(s) | Response |
| (per operation) | Source(s) of types | |
+===================+=================================+===============+
| Locate Available | N/A | Section 2.2 |
| Packages | application/xml or | Section 2.3 |
| | application/json | |
| | [RFC7303] [RFC8259] | |
| /pal | | |
+===================+=================================+===============+
| Distribute EE | N/A | Section 3.1 |
| Certificates | application/pkcs7-mime | Section 3.2 |
| | [RFC5751] | |
| /eecerts | | |
+===================+=================================+===============+
| Distribute CRLs | N/A | Section 4.1 |
| | application/pkcs7-mime | Section 4.2 |
| | [RFC5751] | |
| /crls | | |
+===================+=================================+===============+
| Symmetric Key | N/A | Section 5.1.1 |
| Distribution | application/cms | Section 5.1.2 |
| | [RFC7193] | |
| /symmetrickeys | | |
+===================+=================================+===============+
| Return Symmetric | application/cms | Section 5.2.1 |
| Key | N/A | Section 5.2.2 |
| Receipts/Errors | [RFC7193] | |
| | | |
| /symmetrickeys/ | | |
| return | | |
+===================+=================================+===============+
| Firmware | N/A | Section 6.1.1 |
| Distribution | application/cms | Section 6.1.2 |
| | [RFC7193] | |
| /firmware | | |
+===================+=================================+===============+
| Return Firmware | application/cms | Section 6.2.1 |
| Receipts/Errors | N/A | Section 6.2.2 |
| | [RFC7193] | |
| /firmware/return | | |
+===================+=================================+===============+
| Trust Anchor | N/A | Section 7.1.1 |
| Management | application/ | Section 7.1.2 |
| | tamp-status-query | |
| | tamp-update | |
| | tamp-apex-update | |
| | tamp-community-update | |
| | tamp-sequence-adjust | |
| | [RFC5934] | |
| /tamp | | |
+===================+=================================+===============+
| Return TAMP | application/ | Section 7.2.1 |
| Responses/ | tamp-status-response | |
| Confirms/ | tamp-update-confirm | |
| Errors | tamp-apex-update-confirm | |
| | tamp-community-update-confirm | |
| | tamp-sequence-adjust-confirm | |
| | tamp-error | |
| | N/A | Section 7.2.2 |
| | [RFC5934] | |
| /tamp/return | | |
+===================+=================================+===============+
| Server-Side Key | application/pkcs10 with | Section 8.1 |
| Generation | content type attribute | |
| | CSR* | |
| | application/cms | Section 8.1 |
| /serverkeygen | [RFC5967] [RFC7193] [RFC7030] | |
+===================+=================================+===============+
| Return Asymmetric | application/cms | Section 8.2 |
| Key | N/A | Section 8.2 |
| Receipts/Errors | [RFC7193] | |
| | | |
| /serverkeygen/ | | |
| return | | |
+===================+=================================+===============+
| Server-Side Key | application/pkcs10 | Section 8.3.1 |
| Generation: | application/pkcs12 | Section 8.3.2 |
| PKCS #12 | [RFC5967] [RFC7193] [RFC7030] | |
| | | |
| /serverkeygen | | |
+===================+=================================+===============+
* Certificate Signing Request1.6. Key Words 🔑
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. so watch the caps, bestie 👀
2. Locate Available Packages 📦
okay so the PAL (Package Availability List) is either an XML (Extensible Markup Language) [XML] or JSON (JavaScript Object Notation) [RFC8259] object that lives at the /pal PC. it hands clients the following info:
- Advertisements for available packages that can be retrieved from the server;
- Notifications to begin public key certificate management or to return package receipts and errors; and
- Advertisement for another PAL.
once a client is configured (see Section 1.4), it can grab its PAL (see Section 2.1). if the PAL is properly constructed (see Section 2.3), the client can figure out some or all of the security-related packages it needs for bootstrapping. it's giving main character energy ✨
each PAL entry points 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 start public key certificate enrollment. PAL entries can also tell clients to return receipts or errors for certain packages (see Section 2.1.1). putting these entries after the ones clients used to retrieve the packages is the same as asking for receipts in the originally distributed package 🧾 figure 1 is a ladder diagram of the /pal PC protocol flow, and Appendix A has 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 is 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 it's present, the 0001 package type is always last, because other entries after it are ignored. also, to avoid needlessly dereferencing URIs, the 0001 package type cannot be the only PAL entry. 🙈 besides using the PAL during bootstrapping, clients can be configured to poll the server periodically to see 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, some services do 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 comes in two variants: XML and JSON. when clients connect to the server, they include the HTTP Accept header [RFC7231] to say 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]. no skipping this one, periodt 🫶
the server MUST authenticate the client as specified in [RFC7030], and the server MUST check the client's authorization as specified in [RFC7030]. same energy on both sides 💜
PAL support is OPTIONAL. it shows up in figures throughout this document, but clients need not support the PAL to access services offered by the server 🌸
2.1. PAL Format ✨
okay so bestie, each PAL is made up of zero or more entries 🎀 and every entry has four fields: type, date, size, and info. let's break them down 💅
Quick heads up before we dive in: XML elements show up in angle brackets (<>) and JSON values show up in single quotes (''). when we talk about both at once, they get wrapped in square brackets ([]) and separated by a vertical bar (|). so [<type> | 'type'] means the XML version or the JSON version, no cap 🦋
[<type> | 'type']uniquely identifies each package a client can grab from the server, using a 4-digit string 🧚[<type> | 'type']MUST be present. the PAL package types are defined in Section 2.1.1 💜[<date> | 'date']can mean one of two things 🌸- it's the date and time the client last successfully downloaded the identified package from the server. this one is written as Generalized Time with 20 characters,
YYYY-MM-DDTHH:MM:SSZ⏰[<date> | 'date']MUST be represented that way.<date>matches the dateTime production in "canonical representation" [XMLSCHEMA], and'date'is a string. implementations SHOULD NOT rely on time resolution finer than seconds 🙈 and they MUST NOT generate time instants that specify leap seconds 🚫 - or the date is just omitted, and that omission means one of two things 👀
- there's no indication that the client has successfully downloaded the identified package, or
- the PAL entry is a pointer to the next PAL, or the server is requesting a package from the client (for example a certification request, a receipt, or an error) 💌
- it's the date and time the client last successfully downloaded the identified package from the server. this one is written as Generalized Time with 20 characters,
[<size> | 'size']tells you the size in bytes of the package 📦<size>is a nonNegativeInteger, and'size'is a number. a package size of zero (that's "0", no quotes) means the client needs to begin a transaction, return an error, or return a receipt 🧾[<size> | 'size']MUST be present.[<info> | 'info']gives you one of four things: an SKI (Subject Key Identifier), a DN (Distinguished Name), an Issuer and Serial Number tuple, or a URI 💖 it's a choice between these four, and all of them are defined in [RFC5280] 📜 when a URI [RFC3986] shows up,[<uri> | 'uri']tells you where the package can be retrieved from 🗺️ when a DN, an SKI, or an Issuer and Serial Number tuple shows up, it points to a certificate that's the subject of the notification (so, the certificate that's about to be rekeyed or renewed) 🔑[<dn> | 'dn']is encoded as a string using the format defined in [RFC4514] 🎀<ski>is a hexBinary, and'ski'is a string of hex digits (that means 0-9, a-f, and A-F) 🌈[<iasn> | 'iasn']includes both[<issuer> | 'issuer']and[<serial> | 'serial'], as a complexType in XML and as an object in JSON 🧁[<issuer> | 'issuer']is a DN encoded as a string using the format defined in [RFC4514] 🦄<serial>is a positiveInteger, and'serial'is a number.[<info> | 'info']MUST be present, and it MUST include exactly one of[<dn> | 'dn'],[<ski> | 'ski'],[<iasn> | 'iasn'], or[<uri> | 'uri']👑
Real talk though, clients are often limited by how big of an object they can consume, and the PAL is not immune to that 😭 instead of picking one limit for every client, the spec defines a special package type (0001) that just says "another PAL is available" (see Section 2.1.1) ✨ that way servers can use this value to limit how big the PALs they hand out are 💅 how servers actually learn each client's PAL size limit is beyond the scope of this document, and one possible solution is provisioned information 🫶
2.1.1. PAL Package Types ✨
okay so bestie, here's the big table of every PAL package type this document defines 💖 Each row is a little code number paired with what the package is about.
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 TypesQuick decoder ring 🔑: "CSR" is Certificate Signing Request, "DS" is Digital Signature, and "KE" is Key Establishment.
PAL package types are basically hints 🦋 They tell the client what kind of package it's about to grab, or what it's being asked to send back. Smart clients can parse a package to figure out what's inside, but sometimes it's way better to know before you download it. Still, the hint does NOT let clients skip checking the package type before storing it. Some clients keep things in special spots, like storing Root ARLs apart from intermediate CRLs 🌸 For packages the client sends up, the server is basically saying "hey, I need an enrollment package, receipt, response, confirm, or error from you."
Here's what each package type means 👑
Note: the semantics behind codes 0002 and 0006-0021 come from [RFC7030] 📚
0000Reserved: Set aside for future use 🧚0001Additional PAL value present: This entry points to another PAL through a/palURI (defined in this section). The whole point is to keep PALs from getting too huge for clients to handle 💅 If this type shows up, it MUST be the last entry in the PAL.
Also, to avoid pointless URI dereferencing 🙈, this package type MUST NOT be the only entry.
0002X.509 CA certificate: One or more CA certificates [RFC5280] are available. The client finds them at a/cacertsURI, defined in [RFC7030] ✨0003X.509 EE certificate: One or more EE certificates [RFC5280] are available at an/eecertsURI, defined in Section 3 🎀0004X.509 ARL: One or more ARLs (Authority Revocation Lists) [RFC5280] are available at a/crlsURI, defined in Section 4 🌈0005X.509 CRL: One or more CRLs (Certificate Revocation Lists) [RFC5280] are available at a/crlsURI, defined in Section 4 💜
Note: check out Section 9 for more on how PAL and certificate enrollment work together 💖 And Appendix B has extra informative stuff if you want the deep dive 🤓
0006Start DS certificate enrollment with CSR: The client needs to start enrolling its DS certificate (that's any certificate whose key usage extension has a digital signature set) 🔥 It uses a template the server provides along with a CSR (Certificate Signing Request) attribute (see Appendix B). The PAL entry points to a/csrattrsURI, defined in [RFC7030] 💅0007Start DS certificate enrollment: The client needs to start enrolling its DS certificate. The PAL entry points to a/simpleenrollURI, defined in [RFC7030] 🦋0008DS certificate enrollment (success): The client needs to fetch a successful certification response. The PAL entry points to a/simpleenrollor a/fullcmcURI, both defined in [RFC7030] 🫶0009DS certificate enrollment (failure): The client needs to fetch a failed certification response for a DS certificate. This PAL entry points to a/simpleenrollor a/fullcmcURI 😭0010Start DS certificate re-enrollment: The client needs to rekey or renew a DS certificate. The PAL entry points to a/simplereenrollor a/fullcmcURI 🌸0011DS certificate re-enrollment (success): See PAL package type 0008 ✨0012DS certificate re-enrollment (failure): See PAL package type 0009 💀
Note: the KE (Key Establishment) responses below use the same URIs as DS certificates. The only difference is that the certificate's key usage extension is set to key agreement or key transport only 🔑
0013Start KE certificate enrollment with CSR: See PAL package type 0006 🧚0014Start KE certificate enrollment: See PAL package type 0007 🍓0015KE certificate enrollment (success): See PAL package type 0008 👑0016KE certificate enrollment (failure): See PAL package type 0009 🙈0017Start KE certificate re-enrollment: See PAL package type 0010 🌈0018KE certificate re-enrollment (success): See PAL package type 0008 💜0019KE certificate re-enrollment (failure): See PAL package type 0009 ⭐
Note: the asymmetric key packages come in different flavours because of how many CMS content types can protect the asymmetric key. The syntax for the key itself is the same. The extra ASN.1 is only needed to wrap it in a signed-data (meaning the ASN.1 has to be a CMS content type and not the private key info type) 🎀 See Section 8 of this document for more 💖
0020Asymmetric Key Package (PKCS #8): An asymmetric key generated by the server is ready for the client. The package is an asymmetric key with no additional encryption, as specified in Section 4.4.2 of [RFC7030]. The PAL entry points to a/serverkeygenor a/fullcmcURI, both defined in [RFC7030] 🦋0021Asymmetric Key Package (CMS): See PAL package type 0020. The difference is that the package is an asymmetric key package [RFC5958] that's signed and wrapped in a signed-data content type, as specified in Section 4.4.2 of [RFC7030]. Also check out Section 8.1 of this document 🫶0022Asymmetric Key Package (PKCS #12): See PAL package type 0020. The difference is that the package is the PKCS #12 [RFC7292] content type. See Section 8.3 of this document 🌈0023Asymmetric Key Package Receipt or Error: The server wants the client to send back a key package receipt or error [RFC7191] to the/serverkeygen/returnURI, defined in Section 8 💅0024Symmetric Key Package: A symmetric key package [RFC6031] is available for the client at a/symmetrickeysURI, defined in Section 5 ✨0025Symmetric Key Package Receipt or Error: The server wants the client to send back a key package receipt or error [RFC7191] to the/symmetrickeys/returnURI, defined in Section 5 🌸0026Firmware Package: A firmware package [RFC4108] is available for the client through the/firmwareURI, defined in Section 6 🔥0027Firmware Package Receipt or Error: The server wants the client to send back a firmware package load receipt or error [RFC4108] to the/firmware/returnURI, defined in Section 6 🍓
Note: the /tamp and /tamp/return URIs are defined in Section 7 🧚
0028TAMP Status Query: A TAMP Status Query package [RFC5934] is available for the client through the/tampURI 💜0029TAMP Status Query Response or Error: The server wants the client to send back a TAMP Status Query Response or Error [RFC5934] to the/tamp/returnURI 🌈0030Trust Anchor Update: A Trust Anchor Update package [RFC5934] is available for the client through the/tampURI 👑0031Trust Anchor Update Confirm or Error: The server wants the client to send back a Trust Anchor Update Confirm or Error [RFC5934] to the/tamp/returnURI 💀0032Apex Trust Anchor Update: An Apex Trust Anchor Update package [RFC5934] is available for the client through the/tampURI ⭐0033Apex Trust Anchor Update Confirm or Error: The server wants the client to send back an Apex Trust Anchor Update Confirm or Error [RFC5934] to the/tamp/returnURI 🎀0034Community Update: A Community Update package [RFC5934] is available for the client through the/tampURI 🦋0035Community Update Confirm or Error: The server wants the client to send back a Community Update Confirm or Error [RFC5934] to the/tamp/returnURI 🫶0036Sequence Number Adjust: A Sequence Number Adjust package [RFC5934] is available for the client through the/tampURI 🌸0037Sequence Number Adjust Confirm or Error: The server wants the client to send back a Sequence Number Adjust Confirm or Error [RFC5934] to the/tamp/returnURI 💖
2.1.2. PAL XML Schema 💅
okay so the namespace lives in Section 11.1 🎀, and all the fields in this schema were already explained back in Sections 2.1 and 2.1.1, so we're not doing that again bestie ✨
<?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 🧚
here's an example PAL JSON object, and yes the fields were covered 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 ask for their PAL with an HTTP GET [RFC7231], using the operation path "/pal". to say which format they'd prefer, clients put the HTTP Accept header [RFC7231] on the request with either "application/xml" or "application/json", respectively. XML or JSON, your choice bestie 💖
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, there's an order of precedence for PAL offerings, and it's based on this rationale 👑
/cacertsand/crlspackages are the most important because they support validation decisions on certificates used to sign and encrypt other listed PAL items. no notes, they're the VIPs 💅/csrattrsis next in importance, since it gives info the server would like the client to include in its certificate enrollment request. 🎀/simpleenroll,/simplereenroll, and/fullcmcpackages come next, since they can impact a certificate the client uses 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. 😭
/symmetrickeys,/firmware,/tamp, and/eecertspackages 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, and that can happen 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) 🧚
3. Distribute EE Certificates 🌈
okay so numerous mechanisms exist for clients to query repositories for certificates, but the service provided by the /eecerts PC is different. it's not a general-purpose query for client certificates. instead, it lets the server hand peer certificates to a client that the server knows, through an out-of-band mechanism, 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. main character energy 👑
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 looks like Figure 1, except 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 the operation path "/eecerts" 🎀
3.2. EE Certificate Response 💜
the response and the processing of the returned error codes are identical to what's in Section 4.1.3 of [RFC7030], except the certificate provided isn't the one issued to the client. instead, one or more of the client's peer certificates come back in the certs-only message 🫶
Clients MUST reject EE certificates that do not validate to an authorized TA. 🔥
4. Distribute CRLs and ARLs 💖
okay so CRLs (and ARLs) are needed in lots of situations to do certificate path validation [RFC5280] 🧐 ngl that's a big deal. Normally a client can grab them from a repository if the certificate tells it where to look, but then the client has to parse the certificate AND make an extra round trip just to get them 😩. Handing out CRLs during bootstrapping means the client doesn't have to parse the certificate at all, and it helps clients who might otherwise be unable to retrieve the CRL 🫶. Clients are totally free to get the CRLs they rely on from other places too, like a local directory 📁. The /crls PC lets servers distribute CRLs at the same time the client grabs its certificate(s), CA certificate(s), and peer certificates ✨ iconic multitasking.
The server doesn't need to authenticate or authorize the client to distribute a CRL, because the package contents are already signed by a CA (the CRLs in a crls-only message have already been signed by a CA) 🔐 it's giving "already vetted." The message flow looks like Figure 2, just with "CRL(s)" in place 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 how you process it, are the same as what's described in Section 4.1.3 of [RFC7030], except that instead of an issued certificate, one or more CRLs come back in the crls-only message 🧚
Clients MUST reject CRLs that do not validate to an authorized TA. 🚫 this one is non-negotiable, bestie.
5. Symmetric Keys, Receipts, and Errors 🔑
okay so in addition to public keys, clients often need one or more symmetric keys to talk to their peers 🗝️ The /symmetrickeys PC lets the server hand those out 💜
Distribution doesn't always go to plan 😭 so clients need a way to tell the server when something went wrong. They also need a way to tell the server, if asked, that the distribution finished successfully. That's what the /symmetrickeys/return PC is for 📬
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 give symmetric keys to clients. The symmetric key package is defined in [RFC6031] ✨
Just like the /serverkeygen PC defined in [RFC7030], the default way to distribute 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 encrypting the symmetric key beyond what TLS gives you is OPTIONAL 🙈 So the cipher suite used to return the symmetric key MUST offer cryptographic strength that's commensurate with the symmetric key being delivered to the client 💪 The cipher suite used MUST NOT have the NULL encryption algorithm, because that would expose the unprotected symmetric key 💀 It is strongly RECOMMENDED that servers always return encrypted symmetric keys 🔥
Here's 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:
- If additional encryption is not being employed, the content associated with application/cms is a DER-encoded [X.690] symmetric key package 📦
- 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 🎀
- 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 🧁
- 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. 😭 the bad guy can just delete the signature, so it's only catching honest mistakes.
[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 🚩
Here's the protocol flow for this bit 👇
| |
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:
- 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 🧾
- 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 🧸
okay so 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 ✨
Okay so if the request goes through, 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 so everyone knows how much protection the returned firmware has. What comes back depends on the situation:
- If the firmware is unprotected, then the Content-Type is
application/cmsand the content is the DER-encoded [X.690] firmware package. - If the firmware is compressed, then the Content-Type is
application/cmsand the content is the DER-encoded [X.690] compressed data that encapsulates the firmware package. - If the firmware is encrypted, then the Content-Type is
application/cmsand the content is the DER-encoded [X.690] encrypted-data that encapsulates the firmware package (which might be compressed prior to encryption). - If the firmware is signed, then the Content-Type is
application/cmsand 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? Totally 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. No exceptions, bestie 💅.
[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 (aka "same thing, except...") 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:
- If the firmware receipt is not digitally signed, the Content-Type is
application/cms[RFC7193] and the content is the DER-encoded firmware receipt. - If the firmware receipt is digitally signed, the Content-Type is
application/cmsand the content is the DER-encoded signed-data encapsulating the firmware receipt. - If the firmware error is not digitally signed, the Content-Type is
application/cmsand the content is the DER-encoded firmware error. - If the firmware error is digitally signed, the Content-Type is
application/cmsand 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). Empty body, big vibes 🫧.
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, and 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. Automation queen behavior 🦋.
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:
application/tamp-status-queryfor TAMP Status Queryapplication/tamp-updatefor Trust Anchor Updateapplication/tamp-apex-updatefor Apex Trust Anchor Updateapplication/tamp-community-updatefor Community Updateapplication/tamp-sequence-adjustfor 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. Certificates or bust 🧾✨.
[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:
application/tamp-status-responsefor TAMP Status Query Responseapplication/tamp-update-confirmfor Trust Anchor Update Confirmapplication/tamp-apex-update-confirmfor Apex Trust Anchor Update Confirmapplication/tamp-community-update-confirmfor Community Update Confirmapplication/tamp-sequence-adjust-confirmfor Sequence Number Adjust Confirmapplication/tamp-errorfor 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. Bye bye bad signatures 👋.
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 ✨
Okay so CMS supports a bunch of content types for wrapping other CMS content types 🎀, and [RFC7030] is one of those possibilities. Heads up though: when you're only relying on TLS, the returned key is not a CMS content type 🙈. This doc extends the list of CMS content types that can be returned 🦋.
If the client supports CCC [RFC6010], it can say it's cool with encapsulated asymmetric keys in the encrypted key package [RFC5958] by putting the encrypted key package's OID in a content type attribute [RFC2985] inside the CSR (Certificate Signing Request), aka the certification request, that it sends to the server 💌. And if the client already knows a priori that the server supports the encrypted key package content type, it doesn't need to include the content type attribute in the CSR 🧚.
In all instances defined here, 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 extra encryption and origin authentication are in play, the content for application/cms is a DER-encoded signed-data wrapping an enveloped-data, which wraps another signed-data that holds the asymmetric key package 🎁.
If CCC is supported and extra encryption is in play, the content for application/cms is a DER-encoded encrypted key package [RFC6032] content type that wraps a signed-data, which holds the asymmetric key package 💜.
If CCC is supported and extra encryption and extra origin authentication are both in play, the content for application/cms is a DER-encoded signed-data wrapping an encrypted key package content type, which wraps a signed-data that holds the asymmetric key package ✨.
The encrypted key package [RFC6032] gives you three ways to wrap keys: EncryptedData, EnvelopedData, and AuthEnvelopedData. EnvelopedData is the mandatory-to-implement one 👑.
When the server says no 🙅, it 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. They can also 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 what Figure 4 shows, modulo the fact that 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 hugely deployed 🌍. It protects keys in the same fashion as CMS, but it does so differently 🤷.
8.3.1. Server-Side Key Generation Request
Just like the other server-generated asymmetric keys that come through the /serverkeygen PC:
- The certificate request is HTTPS POSTed and is the same format as for the
/simpleenrolland/simplereenrollpath extensions, with the same content type. - 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]. The body consists of a base64-encoded DER-encoded [X.690] PFX [RFC7292] 🎉.
This response is different from 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 💬.
9. PAL and Certificate Enrollment 🧚
The /fullcmc PC is defined in [RFC7030]. The CMC (Certificate Management over Cryptographic Message Syntax) requirements and packages are defined in [RFC5272], [RFC5273], [RFC5274], and [RFC6402]. This section describes PAL interactions 🌈.
Under normal circumstances, the client-server interactions for PKI enrollment look like this:
Client Server
--------------------->
POST req: PKIRequest
Content-Type: application/pkcs10
or
POST req: PKIRequest
Content-Type: application/pkcs7-mime
smime-type=CMC-request
<--------------------
POST res: PKIResponse
Content-Type: application/pkcs7-mime
smime-type=certs-only
or
POST res: PKIResponse
Content-Type: application/pkcs7-mime
smime-type=CMC-responseIf the response is rejected during the same session:
Client Server
--------------------->
POST req: PKIRequest
Content-Type: application/pkcs10
or
POST req: PKIRequest
Content-Type: application/pkcs7-mime
smime-type=CMC-request
<--------------------
POST res: empty
HTTPS Status Code
or
POST res: PKIResponse
Content-Type: application/pkcs7-mime
smime-type=CMC-responseIf the request is to be filled later:
Client Server
--------------------->
POST req: PKIRequest
Content-Type: application/pkcs10
or
POST req: PKIRequest
Content-Type: application/pkcs7-mime
smime-type=CMC-request
<--------------------
POST res: empty
HTTPS Status Code
+ Retry-After
or
POST res: PKIResponse (pending)
Content-Type: application/pkcs7-mime
smime-type=CMC-response
--------------------->
POST req: PKIRequest (same request)
Content-Type: application/pkcs10
or
POST req: PKIRequest (CMC Status Info only)
Content-Type: application/pkcs7-mime
smime-type=CMC-request
<--------------------
POST res: PKIResponse
Content-Type: application/pkcs7-mime
smime-type=certs-only
or
POST res: PKIResponse
Content-Type: application/pkcs7-mime
smime-type=CMC-responseWith the PAL, the client begins after pulling the PAL and a Start Issuance PAL package type. Essentially, that adds the following before the request:
Client Server
--------------------->
GET req: PAL
<--------------------
GET res: PAL
Content-Type: application/xmlThe client then proceeds as above with a simple PKI enrollment or a full CMC enrollment. Or it begins enrollment assisted by a CSR:
Client Server
--------------------->
GET req: DS certificate with CSR
<--------------------
GET res: PAL
Content-Type: application/csrattrsFor immediately rejected requests, CMC works well. If the server prematurely closes the connection, then the procedures in Section 6.3.1 of [RFC7230] apply. But this might leave the client and server in a different state 😬. The client could merely resubmit the request. Another option, documented herein, is for the client to instead download the PAL to see if the server has processed the request. Clients might also use this process when they are unable to remain connected to the server for the entire enrollment process. If the server does not or is not able to return a PKIData indicating a status of pending, then the client will not know whether the request was received. If a client uses the PAL and reconnects to determine if the certification or rekey or renew request was processed:
- 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.
- Clients retrieve the PAL, using the
/palURI. - Clients and servers use the operation path of
"/simpleenroll","simplereenroll", or"/fullcmc", based on the PAL entry, with an HTTP GET [RFC7231] to get the success or failure response.
Responses are as specified in [RFC7030] 💖.
10. Security Considerations 🔐
This document relies on many other specifications. However, all of the security considerations in [RFC7030] apply. Refer also to the following 🚨:
- For HTTP, HTTPS, and TLS security considerations, see [RFC7231], [RFC2818], and [RFC5246].
- For URI security considerations, see [RFC3986].
- For content type security considerations, see [RFC4073], [RFC4108], [RFC5272], [RFC5652], [RFC5751], [RFC5934], [RFC5958], [RFC6031], [RFC6032], [RFC6268], [RFC6402], [RFC7191], and [RFC7292].
- For algorithms used to protect packages, see [RFC3370], [RFC5649], [RFC5753], [RFC5754], [RFC5959], [RFC6033], [RFC6160], [RFC6161], [RFC6162], and [RFC7192].
- For random numbers, see [RFC4086].
- For server-generated asymmetric key pairs, see [RFC7030].
11. IANA Considerations 🎀
okay so IANA (the folks who keep the official registries) made a brand new registry called "PAL Package Types" 🦋 and did three registrations: PAL Name Space, PAL XML Schema, and PAL Package Types. literally iconic bookkeeping ✨
11.1. PAL Name Space
this section registers a new XML namespace [XMLNS], urn:ietf:params:xml:ns:pal, following the guidelines in [RFC3688] 💅
URI: urn:ietf:params:xml:ns:pal
Registrant Contact: Sean Turner (sean@sn3rd.com)
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Package Availability List</title>
</head>
<body>
<h1>Namespace for Package Availability List</h1>
<h2>urn:ietf:params:xml:ns:pal</h2>
<p>See RFC 8295</p>
</body>
</html>
END11.2. PAL XML Schema
this one registers an XML schema, also following [RFC3688] 🌸 the registrant is the same, and the XML part just points you to Section 2.1.2 💖
URI: urn:ietf:params:xml:schema:pal
Registrant Contact: Sean Turner (sean@sn3rd.com)
XML: See Section 2.1.2.11.3. PAL Package Types
IANA made a new registry called "PAL Package Types" 🧚 its starting values are the ones in Section 2.1.1. future registrations go through Expert Review, as defined in RFC 8126 [RFC8126] 🫶
the big rule here: package types MUST be paired with a media type 🔥 package types spell out the path components, and those path components are what pin down the media type that gets used. so it's basically a whole matching system and you can't skip the pairing, periodt 💅
12. References 📚
12.1. Normative References 📚
Okay, these are the reference docs the spec leans on, the ones you actually need to read alongside it 💜
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996,
<https://www.rfc-editor.org/info/rfc2046>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key
Infrastructure Operational Protocols: FTP and HTTP",
RFC 2585, DOI 10.17487/RFC2585, May 1999,
<https://www.rfc-editor.org/info/rfc2585>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000,
<https://www.rfc-editor.org/info/rfc2818>.
[RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object
Classes and Attribute Types Version 2.0", RFC 2985,
DOI 10.17487/RFC2985, November 2000,
<https://www.rfc-editor.org/info/rfc2985>.
[RFC3370] Housley, R., "Cryptographic Message Syntax (CMS)
Algorithms", RFC 3370, DOI 10.17487/RFC3370, August 2002,
<https://www.rfc-editor.org/info/rfc3370>.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394,
September 2002, <https://www.rfc-editor.org/info/rfc3394>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC4073] Housley, R., "Protecting Multiple Contents with the
Cryptographic Message Syntax (CMS)", RFC 4073,
DOI 10.17487/RFC4073, May 2005,
<https://www.rfc-editor.org/info/rfc4073>.
[RFC4108] Housley, R., "Using Cryptographic Message Syntax (CMS) to
Protect Firmware Packages", RFC 4108,
DOI 10.17487/RFC4108, August 2005,
<https://www.rfc-editor.org/info/rfc4108>.
[RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
(LDAP): String Representation of Distinguished Names",
RFC 4514, DOI 10.17487/RFC4514, June 2006,
<https://www.rfc-editor.org/info/rfc4514>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS
(CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008,
<https://www.rfc-editor.org/info/rfc5272>.
[RFC5273] Schaad, J. and M. Myers, "Certificate Management over CMS
(CMC): Transport Protocols", RFC 5273,
DOI 10.17487/RFC5273, June 2008,
<https://www.rfc-editor.org/info/rfc5273>.
[RFC5274] Schaad, J. and M. Myers, "Certificate Management Messages
over CMS (CMC): Compliance Requirements", RFC 5274,
DOI 10.17487/RFC5274, June 2008,
<https://www.rfc-editor.org/info/rfc5274>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>.
[RFC5649] Housley, R. and M. Dworkin, "Advanced Encryption Standard
(AES) Key Wrap with Padding Algorithm", RFC 5649,
DOI 10.17487/RFC5649, September 2009,
<https://www.rfc-editor.org/info/rfc5649>.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, DOI 10.17487/RFC5652, September 2009,
<https://www.rfc-editor.org/info/rfc5652>.
[RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
Mail Extensions (S/MIME) Version 3.2 Message
Specification", RFC 5751, DOI 10.17487/RFC5751,
January 2010, <https://www.rfc-editor.org/info/rfc5751>.
[RFC5753] Turner, S. and D. Brown, "Use of Elliptic Curve
Cryptography (ECC) Algorithms in Cryptographic Message
Syntax (CMS)", RFC 5753, DOI 10.17487/RFC5753,
January 2010, <https://www.rfc-editor.org/info/rfc5753>.
[RFC5754] Turner, S., "Using SHA2 Algorithms with Cryptographic
Message Syntax", RFC 5754, DOI 10.17487/RFC5754,
January 2010, <https://www.rfc-editor.org/info/rfc5754>.
[RFC5934] Housley, R., Ashmore, S., and C. Wallace, "Trust Anchor
Management Protocol (TAMP)", RFC 5934,
DOI 10.17487/RFC5934, August 2010,
<https://www.rfc-editor.org/info/rfc5934>.
[RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958,
DOI 10.17487/RFC5958, August 2010,
<https://www.rfc-editor.org/info/rfc5958>.
[RFC5959] Turner, S., "Algorithms for Asymmetric Key Package Content
Type", RFC 5959, DOI 10.17487/RFC5959, August 2010,
<https://www.rfc-editor.org/info/rfc5959>.
[RFC5967] Turner, S., "The application/pkcs10 Media Type", RFC 5967,
DOI 10.17487/RFC5967, August 2010,
<https://www.rfc-editor.org/info/rfc5967>.
[RFC6010] Housley, R., Ashmore, S., and C. Wallace, "Cryptographic
Message Syntax (CMS) Content Constraints Extension",
RFC 6010, DOI 10.17487/RFC6010, September 2010,
<https://www.rfc-editor.org/info/rfc6010>.
[RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax
(CMS) Symmetric Key Package Content Type", RFC 6031,
DOI 10.17487/RFC6031, December 2010,
<https://www.rfc-editor.org/info/rfc6031>.
[RFC6032] Turner, S. and R. Housley, "Cryptographic Message Syntax
(CMS) Encrypted Key Package Content Type", RFC 6032,
DOI 10.17487/RFC6032, December 2010,
<https://www.rfc-editor.org/info/rfc6032>.
[RFC6033] Turner, S., "Algorithms for Cryptographic Message Syntax
(CMS) Encrypted Key Package Content Type", RFC 6033,
DOI 10.17487/RFC6033, December 2010,
<https://www.rfc-editor.org/info/rfc6033>.
[RFC6160] Turner, S., "Algorithms for Cryptographic Message Syntax
(CMS) Protection of Symmetric Key Package Content Types",
RFC 6160, DOI 10.17487/RFC6160, April 2011,
<https://www.rfc-editor.org/info/rfc6160>.
[RFC6161] Turner, S., "Elliptic Curve Algorithms for Cryptographic
Message Syntax (CMS) Encrypted Key Package Content Type",
RFC 6161, DOI 10.17487/RFC6161, April 2011,
<https://www.rfc-editor.org/info/rfc6161>.
[RFC6162] Turner, S., "Elliptic Curve Algorithms for Cryptographic
Message Syntax (CMS) Asymmetric Key Package Content Type",
RFC 6162, DOI 10.17487/RFC6162, April 2011,
<https://www.rfc-editor.org/info/rfc6162>.
[RFC6268] Schaad, J. and S. Turner, "Additional New ASN.1 Modules
for the Cryptographic Message Syntax (CMS) and the Public
Key Infrastructure Using X.509 (PKIX)", RFC 6268,
DOI 10.17487/RFC6268, July 2011,
<https://www.rfc-editor.org/info/rfc6268>.
[RFC6402] Schaad, J., "Certificate Management over CMS (CMC)
Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011,
<https://www.rfc-editor.org/info/rfc6402>.
[RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed.,
"Enrollment over Secure Transport", RFC 7030,
DOI 10.17487/RFC7030, October 2013,
<https://www.rfc-editor.org/info/rfc7030>.
[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
DOI 10.17487/RFC7303, July 2014,
<https://www.rfc-editor.org/info/rfc7303>.
[RFC7191] Housley, R., "Cryptographic Message Syntax (CMS) Key
Package Receipt and Error Content Types", RFC 7191,
DOI 10.17487/RFC7191, April 2014,
<https://www.rfc-editor.org/info/rfc7191>.
[RFC7192] Turner, S., "Algorithms for Cryptographic Message Syntax
(CMS) Key Package Receipt and Error Content Types",
RFC 7192, DOI 10.17487/RFC7192, April 2014,
<https://www.rfc-editor.org/info/rfc7192>.
[RFC7193] Turner, S., Housley, R., and J. Schaad, "The
application/cms Media Type", RFC 7193,
DOI 10.17487/RFC7193, April 2014,
<https://www.rfc-editor.org/info/rfc7193>.
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Semantics and Content",
RFC 7231, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7292] Moriarty, K., Ed., Nystrom, M., Parkinson, S., Rusch, A.,
and M. Scott, "PKCS #12: Personal Information Exchange
Syntax v1.1", RFC 7292, DOI 10.17487/RFC7292, July 2014,
<https://www.rfc-editor.org/info/rfc7292>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in
RFC 2119 Key Words", BCP 14, RFC 8174,
DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0
(Fifth Edition)", World Wide Web Consortium
Recommendation REC-xml-20081126, November 2008,
<https://www.w3.org/TR/2008/REC-xml-20081126/>.
[XMLSCHEMA]
Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004,
<https://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[X.690] ITU-T, "Information technology - ASN.1 encoding rules:
Specification of Basic Encoding Rules (BER), Canonical
Encoding Rules (CER) and Distinguished Encoding Rules
(DER)", ITU-T Recommendation X.690, ISO/IEC 8825-1,
August 2015, <https://www.itu.int/rec/T-REC-X.690/en>.12.2. Informative References ✨
Okay, bestie, the informative refs are the "go read this if you want the backstory" stuff 📚💖 Here's the lineup:
[PKCS12]IANA, "PKCS #12",https://www.iana.org/assignments/media-types/application/pkcs12.[RFC4086]Eastlake 3rd, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, DOI 10.17487/RFC4086, June 2005,https://www.rfc-editor.org/info/rfc4086.[RFC4949]Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,https://www.rfc-editor.org/info/rfc4949.[XMLNS]Bray, T., Hollander, D., Layman, A., Tobin, R., and H. Thompson, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208/, December 2009,https://www.w3.org/TR/2009/REC-xml-names-20091208/.
Appendix A. Example Use of PAL 🧚
This is an informative appendix, so it's all examples and protocol flows, no cap 💅 It shows the vibe of a full PAL session, start to finish.
Steps for using a PAL go like this:
- Access PAL
- Process PAL entries
- 2.1. Get CA certificates
- 2.2. Get CRLs
- 2.3. Get CSR attributes
- 2.4. Enroll: simple enrollment, re-enrollment, or full CMC
- 2.5. Get Firmware, TAMP, Symmetric Keys, or EE certificates
Here's the whole flow in one picture, bestie 🦋
Client Server
---------------------> -+
GET req: | /pal
<--------------------- |
GET res: PAL |
Content-Type: application/xml |
|
---------------------> -+
GET req: | /cacerts
<--------------------- |
GET res: CA Certificates |
Content-Type: application/pkcs7-smime |
smime-type=certs-only |
|
---------------------> -+
GET req: | /crls
<--------------------- |
GET res: CRLs |
Content-Type: application/pkcs7-smime |
smime-type=crls-only |
|
---------------------> -+
GET req: | /csrattrs
<--------------------- |
GET res: attributes |
---------------------> -+
POST req: PKIRequest | /simpleenroll and
Content-Type: application/pkcs10 | /simplereenroll
|
Content-Type: application/pkcs7-mime | /fullcmc
smime-type=CMC-request |
|
<-------------------- |
(success or failure) |
POST res: PKIResponse | /simpleenroll
Content-Type: application/pkcs7-mime | /simplereenroll
smime-type=certs-only | /fullcmc
|
Content-Type: application/pkcs7-mime | /fullcmc
smime-type=CMC-response |
|
--------------------> -+
GET req: | /firmware
<-------------------- | /tamp
GET res: Firmware, TAMP Query | /symmetrickeys
+ Updates, Symmetric Keys |
Content-Type: application/cms |
|
---------------------> -+
POST res: Firmware Receipts or Errors, | /firmware/return
TAMP Response or Confirms or Errors, | /tamp/return
Symmetric Key Receipts or Errors | /symmetrickeys/
| return
|
Content-Type: application/cms |
<-------------------- |
POST res: empty |
(success or failure) |
--------------------> -+
GET req: | /eecerts
<-------------------- |
GET res: Other EE certificates |
Content-Type: application/pkcs7-mime |
smime-type=certs-only |The figure above shows /eecerts after /*/return, but this is for illustrative purposes only.
Appendix B. Additional CSR Attributes 🎀
This is an informative appendix, so it's extra-credit reading 🤓
In some cases, the client is severely limited in its ability to encode and decode ASN.1 objects. If the client knows that a "csr" template is being provided during enrollment, then it can peel the returned CSR attribute, generate its keys, place the public key in the certification request, and then sign the request. To accomplish this, the server returns a pKCS7PDU attribute [RFC2985] in the /csrattrs (the following is "pseudo ASN.1" and is only meant to show the fields needed to accomplish returning a template certification request):
pKCS7PDU ATTRIBUTE ::= {
WITH SYNTAX ContentInfo
ID pkcs-9-at-pkcs7PDU
}
pkcs-9-at-pkcs7PDU OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs9(9)
pkcs-9-at(25) 5
}The ContentInfo is a PKIData:
PKIData ::= SEQUENCE {
reqSequence SEQUENCE SIZE(0..MAX) OF TaggedRequest
}Where TaggedRequest is a choice between the PKCS #10 or Certificate Request Message Format (CRMF) requests.
TaggedRequest ::= CHOICE {
tcr [0] TaggedCertificationRequest,
crm [1] CertReqMsg
}Or, the ContentInfo can be a signed-data content type that further encapsulates a PKIData.
Acknowledgements 🫶
Thanks in no particular order go to Alexey Melnikov, Paul Hoffman, Brad McInnis, Max Pritikin, Francois Rousseau, Chris Bonatti, and Russ Housley for taking time to provide comments. Iconic squad 👑✨
Author's Address 🌈
Sean Turner sn3rd
Email: sean@sn3rd.com
📦 where this page comes from
- ietf: rfc8295 2018-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms