idnits 2.17.1 draft-turner-est-extensions-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 22, 2017) is 2651 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '1-9' is mentioned on line 866, but not defined == Missing Reference: '0-9' is mentioned on line 868, but not defined -- Looks like a reference, but probably isn't: '012' on line 866 -- Looks like a reference, but probably isn't: '12' on line 867 -- Looks like a reference, but probably isn't: '01' on line 867 == Missing Reference: '0-3' is mentioned on line 867, but not defined == Missing Reference: '0-5' is mentioned on line 868, but not defined -- Looks like a reference, but probably isn't: '0' on line 2210 -- Looks like a reference, but probably isn't: '1' on line 2211 ** Obsolete normative reference: RFC 7235 (ref. 'RFC2616') (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 2985 ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Obsolete normative reference: RFC 7159 (ref. 'RFC4627') (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 5649 ** Obsolete normative reference: RFC 5751 (Obsoleted by RFC 8551) ** Downref: Normative reference to an Informational RFC: RFC 5753 ** Downref: Normative reference to an Informational RFC: RFC 5967 ** Downref: Normative reference to an Informational RFC: RFC 6268 -- Duplicate reference: RFC7159, mentioned in 'RFC7159', was also mentioned in 'RFC4627'. ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Downref: Normative reference to an Informational RFC: RFC 7193 ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 7292 -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLSCHEMA' Summary: 16 errors (**), 0 flaws (~~), 5 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Sean Turner 3 Internet Draft sn3rd 4 Intended Status: Standards Track January 22, 2017 5 Expires: July 26, 2017 7 EST Extensions 8 draft-turner-est-extensions-08.txt 10 Abstract 12 The EST (Enrollment over Secure Transport) protocol defined a Well- 13 Known URI (Uniform Resource Identifier): /.well-known/est. EST also 14 defined several path components that clients use for PKI (Public Key 15 Infrastructure) services, namely certificate enrollment (e.g., 16 /simpleenroll). In some sense, the services provided by the path 17 components can be thought of as PKI management-related packages. 18 There are additional PKI-related packages a client might need as well 19 as other security-related packages, such as firmware, trust anchors, 20 and symmetric, asymmetric, and encrypted keys. This document also 21 specifies the PAL (Package Availability List), which is an XML 22 (Extensible Markup Language) file or JSON (Javascript Object 23 Notation) object that clients use to retrieve packages available and 24 authorized for them. This document extends the EST server path 25 components to provide these additional services. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5 61 1.2. Authentication and Authorization . . . . . . . . . . . . . 6 62 1.3. TLS Cipher Suites . . . . . . . . . . . . . . . . . . . . 6 63 1.4. URI Configuration . . . . . . . . . . . . . . . . . . . . 6 64 1.5. Content-Transfer-Encoding . . . . . . . . . . . . . . . . 6 65 1.6. Message Types . . . . . . . . . . . . . . . . . . . . . . 7 66 1.7. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 9 67 2. Locate Available Packages . . . . . . . . . . . . . . . . . . 9 68 2.1. PAL Format . . . . . . . . . . . . . . . . . . . . . . . . 10 69 2.1.1. PAL Package Types . . . . . . . . . . . . . . . . . . 11 70 2.1.2. PAL XML Schema . . . . . . . . . . . . . . . . . . . . 16 71 2.1.3. PAL JSON Object . . . . . . . . . . . . . . . . . . . 19 72 2.2. Request PAL . . . . . . . . . . . . . . . . . . . . . . . 20 73 2.3. Provide PAL . . . . . . . . . . . . . . . . . . . . . . . 20 74 3. Distribute EE Certificates . . . . . . . . . . . . . . . . . . 21 75 3.1. EE Certificate Request . . . . . . . . . . . . . . . . . . 22 76 3.2. EE Certificate Response . . . . . . . . . . . . . . . . . 22 77 4. Distribute CRLs and ARLs . . . . . . . . . . . . . . . . . . . 22 78 4.1. CRL Request . . . . . . . . . . . . . . . . . . . . . . . 23 79 4.2. CRL Response . . . . . . . . . . . . . . . . . . . . . . . 23 80 5. Symmetric Keys, Receipts, and Errors . . . . . . . . . . . . . 23 81 5.1. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . . 23 82 5.1.1. Distribute Symmetric Keys . . . . . . . . . . . . . . 24 83 5.1.2. Symmetric Key Response . . . . . . . . . . . . . . . . 24 84 5.2. Symmetric Key Receipts and Errors . . . . . . . . . . . . 25 85 5.2.1. Provide Symmetric Key Receipt or Error . . . . . . . . 26 86 5.2.2. Symmetric Key Receipt or Error Response . . . . . . . 27 87 6. Firmware, Receipts, and Errors . . . . . . . . . . . . . . . . 27 88 6.1. Firmware . . . . . . . . . . . . . . . . . . . . . . . . . 27 89 6.1.1. Distribute Firmware . . . . . . . . . . . . . . . . . 27 90 6.1.2. Firmware Response . . . . . . . . . . . . . . . . . . 28 91 6.2. Firmware Receipts and Errors . . . . . . . . . . . . . . . 28 92 6.2.1. Provide Firmware Receipt or Error . . . . . . . . . . 29 93 6.2.2. Firmware Receipt or Error Response . . . . . . . . . . 29 94 7. Trust Anchor Management Protocol . . . . . . . . . . . . . . . 29 95 7.1. TAMP Status Query, Trust Anchor Update, Apex Trust 96 Anchor Update, . . . . . . . . . . . . . . . . . . . . . . 30 98 Community Update, and Sequence Number Adjust . . . . . . . . 30 99 7.1.1. Request TAMP Packages . . . . . . . . . . . . . . . . 30 100 7.1.2. Return TAMP Packages . . . . . . . . . . . . . . . . . 30 101 7.2. TAMP Response, Confirm, and Errors . . . . . . . . . . . . 31 102 7.2.1. Provide TAMP Response, Confirm, or Error . . . . . . . 31 103 7.2.2. TAMP Response, Confirm, and Error Response . . . . . . 31 104 8. Asymmetric Keys, Receipts, and Errors . . . . . . . . . . . . 32 105 8.1. Asymmetric Key Encapsulation . . . . . . . . . . . . . . . 32 106 8.2. Asymmetric Key Package Receipts and Errors . . . . . . . . 33 107 8.3. PKCS#12 . . . . . . . . . . . . . . . . . . . . . . . . . 34 108 8.3.1. Server-Side Key Generation Request . . . . . . . . . . 34 109 8.3.2. Server-Side Key Generation Response . . . . . . . . . 34 110 9. PAL & Certificate Enrollment . . . . . . . . . . . . . . . . . 34 111 10. Security Considerations . . . . . . . . . . . . . . . . . . . 37 112 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 113 11.1. PAL Name Space . . . . . . . . . . . . . . . . . . . . . 38 114 11.2. PAL Schema . . . . . . . . . . . . . . . . . . . . . . . 38 115 11.3. PAL Package Types . . . . . . . . . . . . . . . . . . . . 38 116 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 117 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 118 13.1. Normative References . . . . . . . . . . . . . . . . . . 39 119 13.2. Informative References . . . . . . . . . . . . . . . . . 44 120 Appendix A. Example Use of PAL . . . . . . . . . . . . . . . . . 44 121 Appendix B. Additional CSR Attributes . . . . . . . . . . . . . . 46 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47 124 1. Introduction 126 The EST (Enrollment over Secure Transport) protocol [RFC7030] defines 127 the Well-Known URI (Uniform Resource Identifier) /.well-known/est to 128 support selected PKI (Public Key Infrastructure) related services 129 with path components (PCs) such as simple enrollment with 130 /simpleenroll, rekey/renew with /simplereenroll, etc. A server that 131 wishes to support additional PKI-related services and other security- 132 related packages could use the same .well-known URI by defining 133 additional PCs. This document defines six such PCs: 135 o /pal - The PAL (Package Availability List) provides a list of all 136 known packages available and authorized for a client. By 137 accessing the service provided by this PC first, the client can 138 walk through the PAL and download all the packages necessary to 139 begin operating securely. The PAL essentially points to other 140 PCs including the ones defined in this document as well as those 141 defined in [RFC7030], which include /cacerts, /simpleenroll, 142 /simplereenroll, /fullcmc, /serverkeygen, and /csrattrs. The 143 /pal PC is described in Section 2. 145 o /eecerts - EE (End-Entity) certificates are needed by the client 146 when they invoke a security protocol for communicating with a 147 peer (i.e., they become operational and do something meaningful 148 as opposed to just communicating with the infrastructure). If 149 the infrastructure knows the certificate(s) needed by the client, 150 then providing the peer's certificate avoids the client having to 151 discover the peer's certificate. This service is not meant to be 152 a general purpose repository to which clients query a 153 "repository" and then get a response; this is purely a push 154 mechanism. The /eecerts PC is described in Section 3. 156 o /crls - CRLs (Certificate Revocation Lists) and Authority 157 Revocation Lists (ARLs) are also needed by the client when they 158 validate certificate paths. CRLs (and ARLs) from TAs (Trust 159 Anchors) and intermediate CAs (Certification Authorities) are 160 needed to validate the certificates used to generate the client's 161 certificate or the peer's certificate, which is provided by the 162 /eecerts PC, and providing them saves the client from having to 163 "discover" them and then retrieve them. CRL "discovery" is 164 greatly aided by the inclusion of the CRL Distribution Point 165 certificate extension [RFC5280], but this extension is not always 166 present in certificates and requires another connection to 167 retrieve them. Like the /eecerts PC, this service is not meant 168 to be a general purpose repository to which clients query a 169 repository and then get a response; this is purely a push 170 mechanism. The /crls PC is described in Section 4. 172 o /symmetrickeys - In some cases, clients use symmetric keys when 173 communicating with their peers. If the client's peers are known 174 by the server a priori, then providing them saves the client or 175 an administrator from later having to find, retrieve and install 176 them. Like the /eecerts and /crls PCs, this service is not meant 177 to be a general purpose repository to which clients query a 178 repository and then get a response; this is purely a push 179 mechanism for the keys themselves. However, things do not always 180 go as planned and clients need to inform the server about any 181 errors. If things did go well, then the client, if requested, 182 needs to provide a receipt. The /symmetrickeys and 183 /symmetrickeys/return PCs are described in Section 5. 185 o /firmware - Some client firmware and software support automatic 186 updates mechanism and some do not. For those that do not, the 187 /firmware PC provides a mechanism for the infrastructure to 188 inform the client that a firmware and software updates are 189 available. Because updates do not always go as planned and 190 because sometimes the server needs to know whether the firmware 191 was received and processed, this PC also provides a mechanism to 192 return errors and receipts. The /firmware and /firmware/return 193 PCs are defined in Section 6. 195 o /tamp - To control the TAs in client TA databases, servers use 196 the /tamp PC to request that clients retrieve a TAMP query, 197 update, and adjust packages and clients use the /tamp/return PC 198 to return response, confirm, and error. The /tamp and 199 /tamp/return PCs are defined in Section 7. 201 This document also extends the /est/serverkeygen PC [RFC7030] to 202 support (see Section 8): 204 o Returning asymmetric key package receipts and errors. 206 o Encapsulating returned asymmetric keys in additional CMS content 207 types. 209 o Returning server-generated public key pairs encapsulated in 210 PKCS#12 [RFC7292]. 212 While the motivation is to provide packages to clients during 213 enrollment so that they can perform securely after enrollment, the 214 services defined in this specification can be used after enrollment. 216 1.1. Definitions 218 Familiarity with Using Cryptographic Message Syntax (CMS) to Protect 219 Firmware Packages [RFC4108], Certificate Management over CMS (CMC) 220 [RFC5272], Cryptographic Message Syntax (CMS) Encrypted Key Package 221 [RFC6032], Cryptographic Message Syntax (CMS) [RFC5652][RFC6268], 222 Trust Anchor Management Protocol (TAMP) [RFC5934], Cryptographic 223 Message Syntax (CMS) Content Constraints Extension [RFC6010], CMS 224 Symmetric Key Package Content Type [RFC6031], Enrollment over Secure 225 Transport protocol [RFC7030], CMS Key Package Receipt and Error 226 Content Types [RFC7191] is assumed. Also, familiarity with the CMS 227 protecting content types signed data and encrypted data is assumed; 228 CMS signed data and encrypted data are defined in [RFC5652] and 229 encrypted key package is defined in [RFC6032]. 231 In addition to the definitions found in [RFC7030], the following 232 definitions are used in this document: 234 Agent: An entity that performs functions on behalf of a client. 235 Agents can service a) one or more clients on the same network as the 236 server, b) clients on non-IP based networks, or c) clients that have 237 an air gap [RFC4949] between themselves and the server; interactions 238 between the agent and client in the last two cases are beyond the 239 scope of this document. Before an agent can service clients, the 240 agent must have a trust relationship with the server, be authorized 241 to act on behalf of clients. 243 Client: A device that ultimately consumes and uses the packages to 244 enable communications. In other words, the client is the end-point 245 for the packages and an agent may have one or more clients. To avoid 246 confusion, this document henceforth uses the term client to refer to 247 both agents and clients. 249 Package: An object that contains one or more content types. There 250 are numerous types of packages: Asymmetric Keys, Symmetric Keys, 251 Encrypted Keys, CRLs, Public Key Certificate Management, Firmware, 252 Public Key Certificates, and TAMP packages. All of these packages 253 are digitally signed and encapsulated in a CMS signed data 254 [RFC5652][RFC6268] (except the public key certificates and CRLs that 255 are already digitally signed); Firmware receipts and errors, TAMP 256 responses, confirms, and errors, as well as Key Package receipts and 257 errors can be optionally signed. Certificate and CRLs are included 258 in a package that uses signed data, which is often referred to as a 259 degenerate CMS or "certs-only" or "crls-only" message 260 [RFC5751][RFC6268], but no signature or content is present; hence the 261 name certs-only and crls-only. 263 1.2. Authentication and Authorization 265 Client and server authentication as well as client and server 266 authorization are as defined in [RFC7030]. The requirements for each 267 are discussed in the request and response sections of each of the PCs 268 defined by this document. 270 The requirements for the TA databases are as specified in [RFC7030] 271 as well. 273 1.3. TLS Cipher Suites 275 TLS cipher suite and issues associated with them are as defined in 276 [RFC7030]. 278 1.4. URI Configuration 280 As specified in Section 3.1 of [RFC7030], the client is configured 281 with sufficient information to form the server URI [RFC3986]. Like 282 EST, this configuration mechanism is beyond the scope of this 283 document. 285 1.5. Content-Transfer-Encoding 287 A Content-Transfer encoding of "base64" [RFC2045] is used for all 288 client server interactions. 290 1.6. Message Types 292 This document uses existing media types for the messages as specified 293 by FTP and HTTP [RFC2585], application/pkcs10 [RFC5967], and CMC 294 [RFC5272]. 296 For consistency with [RFC5273], each distinct EST message type uses 297 an HTTP Content-Type header with a specific media type. 299 The EST messages and their corresponding media types for each 300 operation are: 302 +--------------------+--------------------------+-------------------+ 303 | Message type | Request media type | Request section(s)| 304 | | Response media type(s) | Response section | 305 | (per operation) | Source(s) of types | | 306 +====================+==========================+===================+ 307 | Locate Available | N/A | Section 2.2 | 308 | Packages | application/xml or | Section 2.3 | 309 | | application/json | | 310 | | [RFC7303][RFC4627] | | 311 | /pal | | | 312 +====================+==========================+===================+ 313 | Distribute EE | N/A | Section 3.1 | 314 | Certificates | application/pkcs7-mime | Section 3.2 | 315 | | [RFC5751] | | 316 | /eecerts | | | 317 +====================+==========================+===================+ 318 | Distribute CRLs | N/A | Section 4.1 | 319 | | application/pkcs7-mime | Section 4.2 | 320 | | [RFC5751] | | 321 | /crls | | | 322 +====================+==========================+===================+ 323 | Symmetric Key | N/A | Section 5.1.1 | 324 | Distribution | application/cms | Section 5.1.2 | 325 | | [RFC7193] | | 326 | /symmetrickeys | | | 327 +====================+==========================+===================+ 328 | Return Symmetric | application/cms | Section 5.2.1 | 329 | Key | N/A | Section 5.2.2 | 330 | Receipts/Errors | [RFC7193] | | 331 | | | | 332 | /symmetrickeys/ | | | 333 | return | | | 334 +====================+==========================+===================+ 335 | Firmware | N/A | Section 6.1.1 | 336 | Distribution | application/cms | Section 6.1.2 | 337 | | [RFC7193] | | 338 | /firmware | | | 339 +====================+==========================+===================+ 340 | Return Firmware | application/cms | Section 6.2.1 | 341 | Receipts/Errors | N/A | Section 6.2.2 | 342 | | [RFC7193] | | 343 | /firmware/return | | | 344 +====================+==========================+===================+ 345 | Trust Anchor | N/A | Section 7.1.1 | 346 | Management | application/ | Section 7.1.2 | 347 | | tamp-status-query | | 348 | | tamp-update | | 349 | | tamp-apex-update | | 350 | | tamp-community-update | | 351 | | tamp-sequence-adjust | | 352 | | [RFC5934] | | 353 | /tamp | | | 354 +====================+==========================+===================+ 355 | Return TAMP | application/ | Section 7.2.1 | 356 | Responses/ | tamp-status-query-response | | 357 | Confirms/ | tamp-update-confirm | | 358 | Errors | tamp-apex-update-confirm | | 359 | | tamp-community-update-confirm | | 360 | | tamp-sequence-adjust-confirm | | 361 | | tamp-error | | 362 | | N/A | Section 7.2.2 | 363 | | [RFC5934] | | 364 | /tamp/return | | | 365 +====================+==========================+===================+ 366 | Server-Side Key | application/pkcs10 with | Section 8.1 | 367 | Generation | content type attribute | | 368 | | CSR | | 369 | | application/cms | Section 8.1 | 370 | /serverkeygen | [RFC7193] | | 371 +====================+==========================+===================+ 372 | Return Asymmetric | application/cms | Section 8.2 | 373 | Key | N/A | Section 8.2 | 374 | Receipts/Errors | [RFC7193] | | 375 | | | | 376 | /serverkeygen/ | | | 377 | return | | | 378 +====================+==========================+===================+ 379 | Server-Side Key | application/pkcs10 | Section 8.3.1 | 380 | Generation: | application/pkcs12 | Section 8.3.2 | 381 | PKCS#12 | | | 382 | | | | 383 | /serverkeygen | [RFC7193] | | 384 +====================+==========================+===================+ 386 1.7. Key Words 388 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 389 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 390 "OPTIONAL" in this document are to be interpreted as described in 391 [RFC2119]. 393 2. Locate Available Packages 395 The PAL (Package Availability List) is either an XML (Extensible 396 Markup Language) file [XML] or JSON (Javascript Object Notation) 397 [RFC7159] object that furnishes information for packages that are 398 currently available and authorized for retrieval by a client. It 399 provides client specific: 401 o Advertisements for available packages that can be retrieved from 402 the server; 403 o Notifications to begin public key certificate management or to 404 return package receipts and errors; and 405 o Advertisement for another PAL. 407 A client can use this service to determine all of the security- 408 related products for bootstrapping or to periodically poll the server 409 in order to determine if there are updated packages available for it. 411 To get the /pal PC, the client and server need to mutually 412 authenticate each other with TLS and authorize each other. Clients 413 retrieve their PAL and processes it to determine the packages 414 available for it. Clients include the HTTP Accept header [RFC2616] 415 to indicate whether they support XML or JSON. 417 | | 418 Client | Establish TLS | Server 419 | Session | 420 |<-------------------->| 421 | | 422 | Request PAL | 423 | (HTTP GET Request) | 424 |--------------------->| 425 |<---------------------| 426 | Deliver PAL | 427 | (HTTP GET Response) | 428 | | 429 | Request package by | 430 | specified URI | 431 | (HTTP GET or POST | 432 | Request) | 433 |--------------------->| 434 |<---------------------| 435 | Deliver requested | 436 | CMS package product | 437 | (HTTP GET or POST | 438 | Response) | 439 | | 441 repeat as necessary 443 Figure 1 - /pal Message Sequence 445 The client MUST authenticate the server as specified in [RFC7030] and 446 the client MUST verify server's authorization as specified in 447 [RFC7030]. 449 The server MUST authenticate the client as specified in [RFC7030] and 450 the server MUST verify client authorization as specified in 451 [RFC7030]. 453 PAL support is OPTIONAL. It is shown in figures throughout this 454 document but clients need not support the PAL to access services 455 offered by the server. 457 2.1. PAL Format 459 Each PAL is composed of zero (i.e., minOccurs=0) or more entries (an 460 array in JSON), each of which is composed of the following four 461 elements all of which MUST be present (i.e., minOccurs=1): 463 o The element uniquely identifies each package that a client 464 may retrieve from the server with a 4-digit field (a number in 465 JSON). The PAL Package Types are defined in Section 2.1.1. 467 o The element is a 20-character field (a string in JSON) 468 that contains either: 470 * The date and time (expressed as Generalized Time: YYYY-MM- 471 DDTHH:MM:SSZ) that the client last successfully downloaded the 472 identified package from the server, or 474 * 0001-01-01T00:00:00Z (i.e., 0), if: 476 - There is no indication the client has successfully downloaded 477 the identified package, or 479 - The PAL entry corresponds to a pointer to the next PAL or the 480 server is requesting a package from the client (e.g., 481 certification request, receipt, error). 483 o The element indicates the size in bytes of the package (a 484 number in JSON). A package size of zero (i.e., "0" without the 485 quotes) indicates that the client needs to begin a transaction or 486 return an error or receipt. 488 o The element provides either an SKI (Subject Key 489 Identifier), DN (Distinguished Name), Issuer and Serial Number 490 tuple or a URI (a string in JSON). When a URI [RFC3986] is 491 included it indicates the location where the identified package 492 can be retrieved. When a DN, SKI, or Issuer Name and Serial 493 Number tuple is included it points to a certificate that is the 494 subject of the notification (i.e., the certificate to be 495 rekeyed/renewed). 497 Clients are often limited by the size of objects they can consume, 498 the PAL is not immune to these limitations. As opposed to picking a 499 limit for all clients, a special package type is defined, see Section 500 2.1.1, to indicate that another PAL is available. Servers can use 501 this value to limit the size of the PALs provided to clients. 503 When the element is not zero (i.e., 0001-01-01T00:00:00Z) it 504 MUST be represented in a form that matches the dateTime production in 505 "canonical representation" [XMLSCHEMA]. Implementations SHOULD NOT 506 rely on time resolution finer than seconds and MUST NOT generate time 507 instants that specify leap seconds. 509 2.1.1. PAL Package Types 511 Table 1 lists the PAL package types that are defined by this 512 document: 514 NOTE: DS is Digital Signature and KE is Key Establishment. 516 Package Package Description 517 Number 518 -------- --------------------------------------------------- 519 0000: Reserved 520 0001: Additional PAL value present 521 0002: X.509 CA certificate 522 0003: X.509 EE certificate 523 0004: X.509 ARL 524 0005: X.509 CRL 525 0006: Start DS certificate enrollment with CSR attribute 526 0007: Start DS certificate enrollment 527 0008: DS certificate enrollment (success) 528 0009: DS certificate enrollment (failure) 529 0010: Start DS certificate re-enrollment 530 0011: DS certificate re-enrollment (success) 531 0012: DS certificate re-enrollment (failure) 532 0013: Start KE certificate enrollment with CSR attribute 533 0014: Start KE certificate enrollment 534 0015: KE certificate enrollment (success) 535 0016: KE certificate enrollment (failure) 536 0017: Start KE certificate re-enrollment 537 0018: KE certificate re-enrollment (success) 538 0019: KE certificate re-enrollment (failure) 539 0020: Asymmetric Key Package (PKCS#8) 540 0021: Asymmetric Key Package (CMS) 541 0022: Asymmetric Key Package (PKCS#12) 542 0023: Asymmetric Key Package Receipt or Error 543 0024: Symmetric Key Package 544 0025: Symmetric Key Package Receipt or Error 545 0026: Firmware Package 546 0027: Firmware Package Receipt or Error 547 0028: TAMP Status Query 548 0029: TAMP Status Query Response or Error 549 0030: Trust Anchor Update 550 0031: Trust Anchor Update Confirm or Error 551 0032: Apex Trust Anchor Update 552 0033: Apex Trust Anchor Update Confirm or Error 553 0034: Community Update 554 0035: Community Update Confirm or Error 555 0036: Sequence Number Adjust 556 0037: Sequence Number Adjust Confirm or Error 558 Table 1 - PAL Package Types 560 PAL package types are essentially hints about the type of package the 561 client is about to retrieve or is asked to return. Savvy clients can 562 parse the packages to determine what has been provided, but in some 563 instances it is better to know before retrieving the package. The 564 hint provided here does not obviate the need for clients to check the 565 type of package provided before they store it possibly in specially 566 allocated locations (i.e., some clients might store Root ARLs 567 separately from intermediate CRLs). For packages provided by the 568 client, the server is asking the client to provide an enrollment 569 package, receipt, response, confirm or error. 571 The PAL package types have the following meaning: 573 NOTE: The semantics behind Codes 0002 and 0006-0021 are defined in 574 [RFC7030]. 576 0000 Reserved: Reserved for future use. 578 0001 Additional PAL value present: Indicates that this PAL entry 579 refers to another PAL by referring to another /pal URI, which 580 is defined in this section. This PAL package type limits the 581 size of PALs to a more manageable size for clients. 583 0002 X.509 CA certificate: Indicates that one or more CA certificates 584 [RFC5280] are available for the client by pointing to a 585 /cacerts URI, which is defined in [RFC7030]. 587 0003 X.509 EE certificate: Indicates that one or more EE certificate 588 [RFC5280] is available for the client by pointing to an 589 /eecerts URI, which is defined in Section 3. 591 0004 X.509 ARL: Indicates that one or more ARL (Authority Revocation 592 List) [RFC5280] is available for the client by pointing to a 593 /crls URI, which is defined in Section 4. 595 0005 X.509 CRL: Indicates that one or more CRL (Certificate 596 Revocation List) [RFC5280] is available for the client by 597 pointing to a /crls URI, which is defined in Section 4. 599 NOTE: See Section 9 for additional information about PAL and 600 certificate enrollment interaction. See Appendix B for additional 601 informative information. 603 0006 Start DS (Digital Signature) certificate enrollment with CSR: 604 Indicates that the client begin enrolling their DS certificate 605 (i.e., those certificates for which the key usage extension 606 will have digital signature set) using a template provided by 607 the server with a CSR (Certificate Signing Request) attribute 608 (see Appendix B). The PAL entry points to a /csrattrs URI, 609 which is defined in [RFC7030]. 611 0007 Start DS (Digital Signature) certificate enrollment: Indicates 612 that the client begin enrolling their DS certificate. The PAL 613 entry points to a /simpleenroll URI, which is defined in 614 [RFC7030]. 616 0008 DS certificate enrollment (success): Indicates that the client 617 retrieve a successful certification response. The PAL entry 618 points to a /simpleenroll or a /fullcmc URI, which are both 619 defined in [RFC7030]. 621 0009 DS certificate enrollment (failure): Indicates that the client 622 retrieve a failed certification response for a DS certificate. 623 This PAL entry points to a /simpleenroll or a /fullcmc URI. 625 0010 Start DS certificate re-enrollment: Indicates that the client 626 rekey/renew a DS certificate. The PAL entry points to a 627 /simplereenroll or a /fullcmc URI. 629 0011 DS certificate re-enrollment (success): See PAL package type 630 0008. 632 0012 DS certificate re-enrollment (failure): See PAL package type 633 0009. 635 NOTE: The KE (Key Establishment) responses that follow use the same 636 URIs as DS certificates except in the requested certificates the key 637 usage extension request will have only either key agreement or key 638 transport set. 640 0013 Start KE certificate enrollment with CSR: See PAL package type 641 0006. 643 0014 Start KE certificate enrollment: See PAL package type 0007. 645 0015 KE certificate enrollment (success): See PAL package type 0008. 647 0016 KE certificate enrollment (failure): See PAL package type 0009. 649 0017 Start KE certificate re-enrollment: See PAL package type 0010. 651 0018 KE certificate re-enrollment (success): See PAL package type 652 0011. 654 0019 KE certificate re-enrollment (failure): See PAL package type 655 0012. 657 NOTE: The variations on the asymmetric key packages is due to the 658 number of CMS content types that can be used to protect the 659 asymmetric key; the syntax for the asymmetric key is the same but 660 additional ASN.1 is needed to include it in a signed data (i.e., the 661 ASN.1 needs to be a CMS content type not the private key info type). 662 See Section 8 of this document for additional information. 664 0020 Asymmetric Key Package (PKCS#8): Indicates that an asymmetric 665 key generated by the server is available for the client; the 666 package is an asymmetric key without additional encryption as 667 specified in Section 4.4.2 of [RFC7030]. The PAL entry points 668 to a /serverkeygen or a /fullcmc URI, which are defined in 669 [RFC7030]. 671 0021 Asymmetric Key Package (CMS): See PAL package type 0020. The 672 difference being that the package available is an asymmetric 673 key package [RFC5958] that is signed and encapsulated in a 674 signed data content type, as specified in Section 4.4.2 of 676 [RFC7030]. Also, see Section 8.1 of this document. 678 0022 Asymmetric Key Package (PKCS#12): See PAL package type 0020. 679 The difference being that the package available is PKCS12 680 [RFC7292] content type. See Section 8.3 of this document. 682 0023 Asymmetric Key Package Receipt or Error: Indicates that the 683 server wants the client to return a key package receipt or 684 error [RFC7191] to the /serverkeygen/return URI, which is 685 defined in Section 8. 687 0024 Symmetric Key Package: Indicates that a symmetric key package 688 [RFC6031] is available for the client by pointing to a 689 /symmetrickeys URI, which is defined in Section 5. 691 0025 Symmetric Key Package Receipt or Error: Indicates that the 692 server wants the client to return a key package receipt or an 693 error [RFC7191] to the /symmetrickeys/return URI, which is 694 defined in Section 5. 696 0026 Firmware Package: Indicates that a firmware package [RFC4108] is 697 available for the client using the /firmware URI, which is 698 defined in Section 6. 700 0027 Firmware Package Receipt or Error: Indicates that the server 701 wants the client to return a firmware package load receipt or 702 error [RFC4108] to the /firmware/return URI, which is defined 703 in Section 6. 705 NOTE: The /tamp and tamp/return URIs are defined in Section 7. 707 0028 TAMP Status Query: Indicates that a TAMP Status Query package 708 [RFC5934] is available for the client using the /tamp URI. 710 0029 TAMP Status Query Response or Error: Indicates that the server 711 wants the client to return a TAMP Status Query Response or 712 Error [RFC5934] to the /tamp/return URI. 714 0030 Trust Anchor Update: Indicates that a Trust Anchor Update 715 package [RFC5934] is available for the client using the /tamp 716 URI. 718 0031 Trust Anchor Update Confirm or Error: Indicates that the server 719 wants the client to return a Trust Anchor Update Confirm or 720 Error [RFC5934] to the /tamp/return URI. 722 0032 Apex Trust Anchor Update: Indicates that an Apex Trust Anchor 723 Update package [RFC5934] is available for the client using the 724 /tamp URI. 726 0033 Apex Trust Anchor Update Confirm or Error: Indicates that the 727 server wants the client to return an Apex Trust Anchor Update 728 Confirm or Error [RFC5934] to the /tamp/return URI. 730 0034 Community Update: Indicates that a Community Update package 731 [RFC5934] is available for the client using the /tamp URI. 733 0035 Community Update Confirm or Error: Indicates that the server 734 wants the client to return a Community Update Confirm or Error 735 [RFC5934] to the /tamp/return URI. 737 0036 Sequence Number Adjust: Indicates that a Sequence Number Adjust 738 package [RFC5934] is available for the client using the /tamp 739 URI. 741 0037 Sequence Number Adjust Confirm or Error: Indicates that the 742 server wants the client to return a Sequence Number Adjust 743 Confirm or Error [RFC5934] to the /tamp/return URI. 745 2.1.2. PAL XML Schema 747 The name space is specified in Section 11.1. The fields in the 748 schema were discussed earlier in Sections 2.1 and 2.1.1. 750 751 756 757 758 This schema defines the types and elements needed 759 to retrieve client packages from the server or for the 760 client to post packages to the server. 761 762 764 766 768 770 771 772 773 This type defines the Package Availability List (PAL). 774 775 776 777 778 779 780 Contains information about the package and a link that 781 the client uses to download or post the package. 782 783 784 785 786 788 789 790 791 This type defines a product in the PAL. 792 793 794 795 797 798 800 801 803 804 806 807 808 810 811 812 813 This type allows a choice of X.500 Distinguished Name, 814 Subject Key Identifier, Issuer and Serial Number tuple, 815 or URI. 816 817 818 819 820 821 822 823 824 826 827 828 829 This type holds the issuer Distinguished Name and 830 serial number of a referenced certificate. 831 832 833 834 835 836 837 839 841 842 843 844 Identifies each package that a client may retrieve from 845 the server with a 4-digit field. 846 847 848 849 850 851 853 854 855 856 Indicates the date and time (YYYY-MM-DDTHH:MM:SSZ) the 857 client last acknowledged successful receipt of the 858 package or 0001-01-01T00:00:00Z if there is no indication 859 the package has been downloaded or the PAL entry 860 corresponds to a pointer to the next PAL. 861 862 863 864 869 870 871 873 874 875 876 Indicates the package's size. 877 878 879 880 882 883 884 885 This type holds an X.500 Distinguished Name. 886 887 888 889 890 892 893 894 895 This type holds a hex string representing the value of a 896 certificate's SubjectKeyIdentifier. 897 898 899 900 901 903 904 905 906 This type holds a URI, but is length limited. 907 908 909 910 911 913 915 2.1.3. PAL JSON Object 916 The following is an example PAL JSON object. The fields in the 917 object were discussed earlier in Sections 2.1 and 2.1.1. 919 [ 920 { 921 "Type": 0003, 922 "Date": "2016-12-29T09:28:00Z", 923 "Size": 1234, 924 "Info": "https://www.example.com/.well-known/est/eecerts/1234" 925 } 926 { 927 "Type": 0003, 928 "Date": "2016-12-29T09:28:00Z", 929 "Size": 1234, 930 "Info": "https://www.example.com/.well-known/est/eecerts/9876" 931 } 932 ] 934 2.2. Request PAL 936 Clients request their PAL with an HTTP GET [RFC7231] using an 937 operation path of "/pal". Clients indicate whether they would prefer 938 XML or JSON by including the HTTP Accept header [RFC2616] with either 939 "application/xml" or "application/json", respectively. 941 2.3. Provide PAL 943 If the server has a PAL for the client, the server response MUST 944 contain an HTTP 200 response code with a content-type of 945 "application/xml" [RFC7303] or "application/json" [RFC4627] and a 946 Content-Transfer-Encoding of "base64". 948 When the server constructs a PAL, an order of precedence for PAL 949 offerings is based on the following rationale: 951 o /cacerts and /crls packages are the most important because they 952 support validation decisions on certificates used to sign and 953 encrypt other listed PAL items. 955 o /csrattrs are the next in importance, since they provide 956 information that the server would like the client to include in 957 its certificate enrollment request. 959 o /simpleenroll, /simplereenroll, and /fullcmc packages items are 960 next in importance, since they can impact a certificate used by 961 the client to sign CMS content or a certificate to establish keys 962 for encrypting content exchanged with the client. 964 * A client engaged in a certificate management SHOULD accept and 965 process CA-provided transactions as soon as possible to avoid 966 undue delays that might lead to protocol failure. 968 o /symmetrickeys, /firmware, /tamp, and /eecerts packages 969 containing keys and other types of products are last. Precedence 970 SHOULD be given to packages that the client has not previously 971 downloaded. The items listed in a PAL may not identify all of 972 the packages available for a device. This can be for any of the 973 following reasons: 975 The server may temporarily withhold some outstanding PAL items to 976 simplify client processing. 978 If a CA has more than one certificate ready to begin a certificate 979 management protocol with a client, the server will provide a notice 980 for one at a time. Pending notices will be serviced in order of the 981 earliest date when the certificate will be used. 983 When rejecting a request the server specifies either an HTTP 4xx 984 error, or an HTTP 5xx error. 986 All other return codes are handled as specified in Section 4.2.3 of 987 [RFC7030] (i.e., 202 handling and all other HTTP response codes). 989 3. Distribute EE Certificates 991 Numerous mechanisms exist for clients to query repositories for 992 certificates. The service provided by the /eecerts PC is different 993 in that it is not a general purpose query for client certificates 994 instead it allows the server to provide peer certificates to a client 995 that the server knows through an out-of-band mechanism that the 996 client will be communicating with. For example, a router being 997 provisioned that connects to two peers can be provisioned with not 998 only its certificate but also with the peers' certificates. 1000 The server need not authenticate or authorize the client for 1001 distributing an EE certificate because the package contents are 1002 already signed by a CA (i.e., the certificate(s) in a certs-only 1003 message are already signed by a CA). The message flow is similar to 1004 Figure 1 except that the connection need not be HTTPS: 1006 | | 1007 Client | Establish TLS | Server 1008 | Session | 1009 |<-------------------->| 1010 | | 1011 | Request PAL | 1012 | (HTTP GET Request) | 1013 |--------------------->| 1014 |<---------------------| 1015 | Deliver PAL | 1016 | (HTTP GET Response) | 1017 | | 1018 | Request EE Cert(s) | 1019 | (HTTP GET Request) | 1020 |--------------------->| 1021 |<---------------------| 1022 | Deliver EE Cert(s) | 1023 | (HTTP GET Response) | 1024 | | 1026 Figure 2 - /eecerts Message Sequence 1028 3.1. EE Certificate Request 1030 Clients request EE certificates with an HTTP GET [RFC7231] using an 1031 operation path of "/eecerts". 1033 3.2. EE Certificate Response 1035 The response and processing of the returned error codes is identical 1036 to that in Section 4.1.3 of [RFC7030] except that the certificate 1037 provided is not the one issued to the client but is instead one of 1038 more client's peer certificates is returned in the certs-only 1039 message. 1041 Clients MUST reject EE certificates that do not validate to an 1042 authorized TA. 1044 4. Distribute CRLs and ARLs 1046 CRLs (and ARLs) are needed in many instances to perform certificate 1047 path validation [RFC5280]. They can be obtained from repositories if 1048 their location is provided in the certificate. However, the client 1049 needs to parse the certificate and perform an additional round trip 1050 to retrieve them. Providing CRLs at the time of bootstrap would 1051 obviate the need for the client to parse certificate and aid those 1052 clients who might be unable to retrieve the CRL. Clients are free to 1053 obtain CRLs on which they rely from sources other than the server 1054 (e.g., a local directory). The /crls PC allows servers to distribute 1055 CRLs at the same time clients retrieve their certificate(s) and CA 1056 certificate(s) as well as peer certificates. 1058 The server need not authenticate or authorize the client for 1059 distributing a CRL because the package is already signed by a CA 1060 (i.e., the CRLs in a crls-only message are already signed by a CA). 1061 The message flow is as depicted in Figure 2 but with "CRL(s)" instead 1062 of "EE Cert(s)". 1064 4.1. CRL Request 1066 Clients request CRLs with an HTTP GET [RFC7231] using an operation 1067 path of "/crls". 1069 4.2. CRL Response 1071 The response and processing of the response is identical to that in 1072 Section 4.1.3 of [RFC7030] except that instead of providing the 1073 issued certificate one of more CRLs are returned in the crls-only 1074 message. 1076 Clients MUST reject CRLs that do not validate to an authorized TA. 1078 5. Symmetric Keys, Receipts, and Errors 1080 In addition to public keys, clients often need one or more symmetric 1081 keys to communicate with their peers. The /symmetrickeys PC allows 1082 the server to distribute symmetric keys to clients. 1084 Distribution of keys does not always work as planned and clients need 1085 a way to inform the server that something has gone wrong; they also 1086 need a way to inform the server, if asked, that the distribution 1087 process has successfully completed. The /symmetrickeys/return PC 1088 allows client to provide errors and receipts. 1090 Clients MUST authenticate the server and clients MUST check server's 1091 authorization. 1093 The server MUST authenticate clients and the server MUST check the 1094 client's authorization. 1096 HTTP GET [RFC7231] is used when the server provides the key to the 1097 client (see Section 5.1) using the /symmetrickeys PC; HTTP POST 1098 [RFC7231] is used when the client provides a receipt (see Section 1099 5.2) or an error (see Section 5.2) to the server with the 1100 /symmetrickeys/return PC. 1102 5.1. Symmetric Keys 1104 Servers use /symmetrickeys to provide clients symmetric keys; 1105 symmetric key package is defined in [RFC6031]. 1107 As with the /serverkeygen PC defined in [RFC7030], the default 1108 distribution method of the symmetric key uses the encryption mode of 1109 the negotiated TLS cipher suite. Keys are not protected by preferred 1110 key wrapping methods such as AES Key Wrap [RFC3394] or AES Key Wrap 1111 with Padding [RFC5649] because encryption of the symmetric key beyond 1112 that provided by TLS is OPTIONAL. Therefore, the cipher suite used 1113 to return the symmetric key MUST offer commensurate cryptographic 1114 strength with the symmetric key being delivered to the client. The 1115 cipher suite use MUST NOT have NULL encryption algorithm as this will 1116 disclose the unprotected symmetric key. It is strongly RECOMMENDED 1117 that servers always return encrypted symmetric keys. 1119 The following depicts the protocol flow: 1121 | | 1122 Client | Establish TLS | Server 1123 | Session | 1124 |<-------------------->| 1125 | | 1126 | Request PAL | 1127 | (HTTP GET Request) | 1128 |--------------------->| 1129 |<---------------------| 1130 | Deliver PAL | 1131 | (HTTP GET Response) | 1132 | | 1133 | Req Symmetric Key | 1134 | (HTTP GET Request) | 1135 |--------------------->| 1136 |<---------------------| 1137 | Res Symmetric Key | 1138 | (HTTP GET Response) | 1139 | | 1141 Figure 3 - /symmetrickeys Message Sequence 1143 5.1.1. Distribute Symmetric Keys 1145 Clients request the symmetric key from the server with an HTTP GET 1146 [RFC7231] using an operation path of "/symmetrickeys". 1148 5.1.2. Symmetric Key Response 1150 If the request is successful, the server response MUST have an HTTP 1151 200 response code with a Content-Type of application/cms [RFC7193] 1152 and a Content-Transfer-Encoding of "base64". The optional 1153 application/cms encapsulatingContent and innerContent parameters 1154 SHOULD be included with the Content-Type to indicate the protection 1155 afforded to the returned symmetric key. The returned content varies: 1157 o If additional encryption is not being employed, the content 1158 associated with application/cms is a DER-encoded [X.690] 1159 symmetric key package. 1161 o If additional encryption is employed, the content associated with 1162 application/cms is DER-encoded enveloped data that encapsulates a 1163 signed data that further encapsulates a symmetric key package. 1165 o If additional encryption and origin authentication is employed, 1166 the content associated with application/cms is a DER-encoded 1167 signed data that encapsulates an enveloped data that encapsulates 1168 a signed data that further encapsulates a symmetric key package. 1170 o If CCC (CMS Content Constraints) [RFC6010] is supported the 1171 content associated with application/cms is a DER-encoded 1172 encrypted key package [RFC6032]. Encrypted key package provides 1173 three choices to encapsulate keys: encrypted data, enveloped 1174 data, and authenticated enveloped data. Prior to employing one 1175 of these three encryption choices the key package can be 1176 encapsulated in a signed data. 1178 How the server knows whether the client supports the encrypted key 1179 package is beyond the scope of this document. 1181 When rejecting a request, the server specifies either an HTTP 4xx 1182 error, or an HTTP 5xx error. 1184 If a symmetric key package (which might be signed) or an encrypted 1185 key package (which might be signed before and after encryption) is 1186 digitally signed, the client MUST reject it if the digital signature 1187 does not validate back to an authorized TA. 1189 [RFC3370], [RFC5753], [RFC5754], [RFC6033], [RFC6160], and [RFC6161] 1190 provide algorithm details for use when protecting the symmetric key 1191 package and encrypted key package. 1193 5.2. Symmetric Key Receipts and Errors 1195 Clients use /symmetrickeys/return to provide symmetric key package 1196 receipts; the key package receipt content type is defined in 1197 [RFC7191]. Clients can be configured to automatically return 1198 receipts after processing a symmetric key package, return receipts 1199 based on processing of the key-package-identifier-and-receipt-request 1200 attribute [RFC7191], or return receipts when prompted by a PAL entry. 1202 Servers can indicate that clients return a receipt by including the 1203 key-package-identifier-and-receipt-request attribute in a signed data 1204 as a signed attribute. However, this attribute only appears when 1205 additional encryption is employed (see Section 5.1.2). 1207 Clients also use /symmetrickeys/return to return symmetric key 1208 package errors; the key package error content type is defined in 1209 [RFC7191]. Clients can be configured to automatically return errors 1210 after processing a symmetric key package or based on a PAL entry. 1212 The following depicts the protocol flow: 1214 | | 1215 Client | Establish TLS | Server 1216 | Session | 1217 |<-------------------->| 1218 | | 1219 | Request PAL | 1220 | (HTTP GET Request) | 1221 |--------------------->| 1222 |<---------------------| 1223 | Deliver PAL | 1224 | (HTTP GET Response) | 1225 | | 1226 | Return Receipt/Error | 1227 | (HTTP POST Request) | 1228 |--------------------->| 1229 |<---------------------| 1230 | (HTTP POST Response) | 1231 | status code only | 1232 | no content | 1233 | | 1235 Figure 4 - /symmetrickeys/return Message Sequence 1237 5.2.1. Provide Symmetric Key Receipt or Error 1239 Clients return symmetric key receipts and errors to the server with 1240 an HTTP POST [RFC7231] using an operation path of 1241 "/symmetrickeys/return" and a Content-Transfer-Encoding of "base64". 1242 The returned content varies: 1244 o The key package receipt is digitally signed [RFC7191], the 1245 Content-Type is application/cms [RFC7193] and the associated 1246 content is signed data, which encapsulates a key package receipt. 1248 o If the key package error is not digitally signed, the Content- 1249 Type is application/cms and the associated content is key package 1250 error. If the key package error is digitally signed, the 1251 Content-Type is application/cms and the associated content is 1252 signed data, which encapsulates a key package error. 1254 The optional application/cms encapsulatingContent and innerContent 1255 parameters SHOULD be included with the Content-Type to indicate the 1256 protection afforded to the receipt or error. 1258 [RFC3370], [RFC5753], [RFC5754], and [RFC7192] provide algorithm 1259 details for use when protecting the key package receipt or key 1260 package error. 1262 5.2.2. Symmetric Key Receipt or Error Response 1264 If the client successfully provides a receipt or error, the server 1265 response has an HTTP 200 response code with no content. 1267 When rejecting a request, the server specifies either an HTTP 4xx 1268 error, or an HTTP 5xx error. 1270 If a key package receipt or key package error is digitally signed, 1271 the server MUST reject it if the digital signature does not validate 1272 back to an authorized TA. 1274 6. Firmware, Receipts, and Errors 1276 Servers can distribute object code for cryptographic algorithms and 1277 software with the firmware package [RFC4108]. 1279 Clients MUST authenticate the server and clients MUST check server's 1280 authorization. 1282 Server MUST authenticate the client and the server MUST check the 1283 client's authorization. 1285 The /firmware PC uses an HTTP GET [RFC7231] and the /firmware/return 1286 PC uses an HTTP POST [RFC7231]. GET is used when the client 1287 retrieves firmware from the server (see Section 6.1); POST is used 1288 when the client provides a receipt (see Section 6.2) or an error (see 1289 Section 6.2). 1291 6.1. Firmware 1293 The /firmware URI is used by servers to provide firmware packages to 1294 clients. 1296 The message flow is as depicted in Figure 3 modulo replacing 1297 "Symmetric Key" with "Firmware Package". 1299 6.1.1. Distribute Firmware 1301 Clients request firmware from the server with an HTTP GET [RFC7231] 1302 using an operation path of "/firmware". 1304 6.1.2. Firmware Response 1306 If the request is successful, the server response MUST have an HTTP 1307 200 response code with a Content-Type of "application/cms" [RFC7193] 1308 and a Content-Transfer-Encoding of "base64". The optional 1309 encapsulatingContent and innerContent parameters SHOULD be included 1310 with Content-Type to indicate the protection afforded to the returned 1311 firmware. The returned content varies: 1313 o If the firmware is unprotected, then the Content-Type is 1314 application/cms and the content is the DER-encoded [X.690] 1315 firmware package. 1317 o If the firmware is compressed, then the Content-Type is 1318 application/cms and the content is the DER-encoded [X.690] 1319 compressed data that encapsulates the firmware package. 1321 o If the firmware is encrypted, then the Content-Type is 1322 application/cms and the content is the DER-encoded [X.690] 1323 encrypted data that encapsulates the firmware package (which 1324 might be compressed prior to encryption). 1326 o If the firmware is signed, then the Content-Type is 1327 application/cms and the content is the DER-encoded [X.690] signed 1328 data that encapsulates the firmware package (which might be 1329 compressed, encrypted, or compressed and then encrypted prior to 1330 signature). 1332 How the server knows whether the client supports the unprotected, 1333 signed, compressed and/or encrypted firmware package is beyond the 1334 scope of this document 1336 When rejecting a request, the server specifies either an HTTP 4xx 1337 error, or an HTTP 5xx error. 1339 If a firmware package is digitally signed, the client MUST reject it 1340 if the digital signature does not validate back to an authorized TA. 1342 [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use 1343 when protecting the firmware package. 1345 6.2. Firmware Receipts and Errors 1347 Clients use the /firmware/return PC to provide firmware package load 1348 receipts and errors [RFC4108]. Clients can be configured to 1349 automatically return receipts and errors after processing a firmware 1350 package or based on a PAL entry. 1352 The message flow is as depicted in Figure 4 modulo the receipt or 1353 error is for a firmware package. 1355 6.2.1. Provide Firmware Receipt or Error 1357 Clients return firmware receipts and errors to the server with an 1358 HTTP POST [RFC7231] using an operation path of "/firmware/return" and 1359 a Content-Transfer-Encoding of "base64". The optional 1360 encapsulatingContent and innerContent parameters SHOULD be included 1361 with Content-Type to indicate the protection afforded to the returned 1362 firmware receipt or error. The returned content varies: 1364 o If the firmware receipt is not digitally signed, the Content-Type 1365 is application/cms [RFC7193] and the content is the DER-encoded 1366 firmware receipt. 1368 o If the firmware receipt is digitally signed, the Content-Type is 1369 application/cms and the content is the DER-encoded signed data 1370 encapsulating the firmware receipt. 1372 o If the firmware error is not digitally signed, the Content-Type 1373 is application/cms and the content is the DER-encoded firmware 1374 error. 1376 o If the firmware error is digitally signed, the Content-Type is 1377 application/cms and the content is the DER-encoded signed data 1378 encapsulating the firmware error. 1380 [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use 1381 when protecting the firmware receipt or firmware error. 1383 6.2.2. Firmware Receipt or Error Response 1385 If the request is successful, the server response MUST have an HTTP 1386 200 response code with no content. 1388 When rejecting a request, the server MUST specify either an HTTP 4xx 1389 error, or an HTTP 5xx error. 1391 If a firmware receipt or firmware error is digitally signed, the 1392 server MUST reject it if the digital signature does not validate back 1393 to an authorized TA. 1395 7. Trust Anchor Management Protocol 1397 Servers distribute TAMP packages to manage TAs in a client's trust 1398 anchor databases; TAMP packages are defined in [RFC5934]. TAMP will 1399 allow the flexibility for a device to load authorities while 1400 maintaining an operational state. Unlike other systems that require 1401 new software loads when new PKI Roots are authorized for use, TAMP 1402 allows for automated management of roots for provisioning or 1403 replacement as needed. 1405 Clients MUST authenticate the server and clients MUST check server's 1406 authorization. 1408 Server MUST authenticate the client and the server MUST check the 1409 client's authorization. 1411 The /tamp PC uses an HTTP GET [RFC7231] and the tamp/return PC uses 1412 an HTTP POST [RFC7231]. GET is used when the server requests that 1413 the client retrieve a TAMP package (see Section 7.1); POST is used 1414 when the client provides a confirm (see Section 7.2), provides a 1415 response (see Section 7.2), or provides an error (see Section 7.2) 1416 for the TAMP package. 1418 7.1. TAMP Status Query, Trust Anchor Update, Apex Trust Anchor Update, 1419 Community Update, and Sequence Number Adjust 1421 Clients use the /tamp PC to retrieve the TAMP packages: TAMP Status 1422 Query, Trust Anchor Update, Apex Trust Anchor Update, Community 1423 Update, and Sequence Number Adjust. Clients can be configured to 1424 periodically poll the server for these packages or contact the server 1425 based on a PAL entry. 1427 The message flow is as depicted in Figure 3 modulo replacing 1428 "Symmetric Key" with the appropriate TAMP message. 1430 7.1.1. Request TAMP Packages 1432 Clients request the TAMP packages from the server with an HTTP GET 1433 [RFC7231] using an operation path of "/tamp". 1435 7.1.2. Return TAMP Packages 1437 If the request is successful, the server response MUST have an HTTP 1438 200 response code with Content-Transfer-Encoding of "base64" and a 1439 Content-Type of: 1440 o application/tamp-status-query for TAMP Status Query 1441 o application/tamp-update for Trust Anchor Update 1442 o application/tamp-apex-update for Apex Trust Anchor Update 1443 o application/tamp-community-update for Community Update 1444 o application/tamp-sequence-adjust for Sequence Number Adjust 1446 As specified in [RFC5934], these content types are digitally signed 1447 and clients must support validating the packages directly signed by 1448 TAs. For this specification, client MUST support validation with a 1449 certificate and clients MUST reject it if the digital signature does 1450 not validate back to an authorized TA. 1452 [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use 1453 when protecting the TAMP packages. 1455 7.2. TAMP Response, Confirm, and Errors 1457 Clients return the TAMP Status Query Response, Trust Anchor Update 1458 Confirm, Apex Trust Anchor Update Confirm, Community Update Confirm, 1459 Sequence Number Adjust Confirm, and TAMP Error to servers using the 1460 /tamp/return PC. Clients can be configured to automatically return 1461 responses, confirms, and errors after processing a TAMP package or 1462 based on a PAL entry. 1464 The message flow is as depicted in Figure 4 modulo replacing 1465 "Receipt/Error" with the appropriate TAMP response, confirm, or 1466 error. 1468 7.2.1. Provide TAMP Response, Confirm, or Error 1470 Clients provide the TAMP responses, confirms, and errors to the 1471 server with an HTTP POST using an operation path of "/tamp/return". 1472 The Content-Transfer-Encoding is "base64" and the Content-Type is: 1474 o application/tamp-status-query-response for TAMP Status Query 1475 Response 1476 o application/tamp-update-confirm for Trust Anchor Update Confirm 1477 o application/tamp-apex-update-confirm for Apex Trust Anchor Update 1478 Confirm 1479 o application/tamp-community-update-confirm for Community Update 1480 Confirm 1481 o application/tamp-sequence-adjust-confirm for Sequence Number 1482 Adjust Confirm 1483 o application/tamp-error for TAMP Error 1485 As specified in [RFC5934], these content types should be signed. If 1486 signed, a signed data encapsulates the TAMP content. 1488 [RFC3370], [RFC5753], and [RFC5754] provide algorithm details for use 1489 when protecting the TAMP packages. 1491 7.2.2. TAMP Response, Confirm, and Error Response 1493 If the request is successful, the server response MUST have an HTTP 1494 200 response code with no content. 1496 When rejecting a request, the server MUST specify either an HTTP 4xx 1497 error, or an HTTP 5xx error. 1499 If the package is digitally signed, the server MUST reject it if 1500 digital signature does not validate back to an authorized TA. 1502 8. Asymmetric Keys, Receipts, and Errors 1504 [RFC7030] defines the /serverkeygen PC to support server-side 1505 generation of asymmetric keys. Keys are returned either as an 1506 unprotected PKCS#8 when additional security beyond TLS is not 1507 employed or as a CMS asymmetric key package content type that is 1508 encapsulated in a signed data content type that is further 1509 encapsulated in an enveloped data content type when additional 1510 security beyond TLS is requested. Some implementations prefer the 1511 use of other CMS content types to encapsulate the asymmetric key 1512 package; this document extends the content types that can be returned 1513 in Section 8.1. 1515 [RFC7191] defines content types for key package receipts and errors. 1516 This document defines the /serverkeygen/return PC to add support for 1517 returning receipts and errors for asymmetric key packages in Section 1518 8.2. 1520 PKCS#12 [RFC7292], sometimes referred to as "PFX" (Personal 1521 inFormation eXchange), "P12", and "PKCS#12" files, are often used to 1522 distribute asymmetric private keys and the associated certificate. 1523 This document extends the /serverkeygen PC to allow servers to 1524 distribute using PKCS#12 server-generated asymmetric private keys and 1525 the associated certificate to clients in Section 8.3. 1527 8.1. Asymmetric Key Encapsulation 1529 CMS supports a number of content types to encapsulate other CMS 1530 content types; [RFC7030] includes one such possibility; note that 1531 when only relying on TLS the returned key is not a CMS content type. 1532 This document extends the CMS content types that can be returned. 1534 If the client supports CCC [RFC6010], then the client can indicate 1535 that it supports encapsulated asymmetric keys in the encrypted key 1536 package [RFC5958] by including the encrypted key package's OID in a 1537 content type attribute [RFC2985] in the CSR (Certificate Signing 1538 Request), aka the certification request, it provides to the server. 1539 If the server knows a prior that the client supports the encrypted 1540 key package content type, then the client need not include the 1541 content type attribute in the CSR. 1543 In all instances defined herein, the Content-Type is 1544 "application/cms" [RFC7193] the Content-Transfer-Encoding is 1545 "base64". The optional encapsulatingContent and innerContent 1546 parameters SHOULD be included with Content-Type to indicate the 1547 protection afforded to the returned asymmetric key package. 1549 If additional encryption and origin authentication is employed, the 1550 content associated with application/cms is a DER-encoded signed data 1551 that encapsulates an enveloped data that encapsulates a signed data 1552 that further encapsulates an asymmetric key package. 1554 If CCC (CMS Content Constraints) is supported and additional 1555 encryption is employed, the content associated with application/cms 1556 is a DER-encoded encrypted key package [RFC6032] content type that 1557 encapsulates a signed data that further encapsulates an asymmetric 1558 key package. 1560 If CCC is supported and additional encryption and additional origin 1561 authentication is employed, the content associated with 1562 application/cms is a DER-encoded signed data that encapsulates an 1563 encrypted key package content type that encapsulates a signed data 1564 that further encapsulates an asymmetric key package. 1566 Encrypted key package [RFC6032] provides three choices to encapsulate 1567 keys, encrypted data, enveloped data, and authenticated data, with 1568 enveloped data being the mandatory to implement choice. 1570 When rejecting a request, the server specifies either an HTTP 4xx 1571 error, or an HTTP 5xx error. 1573 If a asymmetric key package or an encrypted key package is digitally 1574 signed, the client MUST reject it if the digital signature does not 1575 validate back to an authorized TA. 1577 [RFC3370], [RFC5753], [RFC5754], [RFC6033], [RFC6161], and [RFC6162] 1578 provide algorithm details for use when protecting the asymmetric key 1579 package and encrypted key package. 1581 8.2. Asymmetric Key Package Receipts and Errors 1583 Clients can be configured to automatically return receipts after 1584 processing an asymmetric key package, return receipts based on 1585 processing of the key-package-identifier-and-receipt-request 1586 attribute [RFC7191], or return receipts when prompted by a PAL entry. 1588 Servers can indicate that clients return a receipt by including the 1589 key-package-identifier-and-receipt-request attribute [RFC7191] in a 1590 signed data as a signed attribute. 1592 The protocol flow is identical to that depicted in Figure 4 modulo 1593 the receipt or error is for asymmetric keys. 1595 The server and client processing is as described in Section 5.2.1 and 1596 5.2.2 modulo the PC, which for Asymmetric Key Packages is 1597 "/serverkeygen/return". 1599 8.3. PKCS#12 1601 PFX is widely deployed and supports protecting keys in the same 1602 fashion as CMS but it does so differently. 1604 8.3.1. Server-Side Key Generation Request 1606 Similar to the other server-generated asymmetric keys provided 1607 through the /serverkeygen PC: 1609 o The certificate request is HTTPS POSTed and is the same format as 1610 for the "/simpleenroll" and "/simplereenroll" path extensions 1611 with the same content-type and transfer encoding. 1613 o In all respects, the server SHOULD treat the CSR as it would any 1614 enroll or re-enroll CSR; the only distinction here is that the 1615 server MUST ignore the public key values and signature in the 1616 CSR. These are included in the request only to allow re-use of 1617 existing codebases for generating and parsing such requests. 1619 PBE (password based encryption) shrouding of PKCS#12 is supported and 1620 this specification makes no attempt to alter this defacto standard. 1621 As such, there is no support of the DecryptKeyIdentifier specified in 1622 [RFC7030] for use with PKCS#12 (i.e., "enveloping" is not supported). 1624 8.3.2. Server-Side Key Generation Response 1626 If the request is successful, the server response MUST have an HTTP 1627 200 response code with a content-type of "application/pkcs12" that 1628 consists of a base64-encoded DER-encoded [X.690] PFX [RFC7292] with a 1629 Content-Transfer-Encoding of "base64". 1631 Note that this response is different than the response returned in 1632 Section 4.4.2 of [RFC7030] because here the private key and the 1633 certificate are included in the same PFX. 1635 When rejecting a request, the server MUST specify either an HTTP 4xx 1636 error or an HTTP 5xx error. If the content-type is not set, the 1637 response data MUST be a plaintext human-readable error message. 1639 9. PAL & Certificate Enrollment 1640 The /fullcmc PC is defined in [RFC7030]; the CMC (Certificate 1641 Management over Cryptographic Message Syntax) requirements and 1642 packages are defined in [RFC5272], [RFC5273], [RFC5274], and 1643 [RFC6402]. This section describes PAL interactions. 1645 Under normal circumstances the client-server interactions for PKI 1646 enrollment are as follows: 1648 Client Server 1649 ---------------------> 1650 POST req: PKIRequest 1651 Content-Type: application/pkcs10 1652 or 1653 POST req: PKIRequest 1654 Content-Type: application/pkcs7-mime 1655 smime-type=CMC-request 1657 <-------------------- 1658 POST res: PKIResponse 1659 Content-Type: application/pkcs7-mime 1660 smime-type=certs-only 1661 or 1662 POST res: PKIResponse 1663 Content-Type: application/pkcs7-mime 1664 smime-type=CMC-response 1666 if the response is rejected during the same session: 1668 Client Server 1669 ---------------------> 1670 POST req: PKIRequest 1671 Content-Type: application/pkcs10 1672 or 1673 POST req: PKIRequest 1674 Content-Type: application/pkcs7-mime 1675 smime-type=CMC-request 1677 <-------------------- 1678 POST res: empty 1679 HTTPS Status Code 1680 or 1681 POST res: PKIResponse 1682 Content-Type: application/pkcs7-mime 1683 smime-type=CMC-response 1685 if the request is to be filled later: 1687 Client Server 1688 ---------------------> 1689 POST req: PKIRequest 1690 Content-Type: application/pkcs10 1691 or 1692 POST req: PKIRequest 1693 Content-Type: application/pkcs7-mime 1694 smime-type=CMC-request 1696 <-------------------- 1697 POST res: empty 1698 HTTPS Status Code 1699 + Retry-After 1700 or 1701 POST res: PKIResponse (pending) 1702 Content-Type: application/pkcs7-mime 1703 smime-type=CMC-response 1705 ---------------------> 1706 POST req: PKIRequest (same request) 1707 Content-Type: application/pkcs10 1708 or 1709 POST req: PKIRequest (CMC Status Info only) 1710 Content-Type: application/pkcs7-mime 1711 smime-type=CMC-request 1713 <-------------------- 1714 POST res: PKIResponse 1715 Content-Type: application/pkcs7-mime 1716 smime-type=certs-only 1717 or 1718 POST res: PKIResponse 1719 Content-Type: application/pkcs7-mime 1720 smime-type=CMC-response 1722 With the PAL, the client begins after pulling the PAL and a Start 1723 Issuance PAL package type essentially adding the following before the 1724 request: 1726 Client Server 1727 ---------------------> 1728 GET req: PAL 1730 <-------------------- 1731 GET res: PAL 1732 Content-Type: application/xml 1734 The client then proceeds as above with a simple PKI Enroll, Full CMC 1735 Enrollment, or begin enrollment assisted with a CSR: 1737 Client Server 1738 ---------------------> 1739 GET req: DS certificate with CSR 1741 <-------------------- 1742 GET res: PAL 1743 Content-Type: application/csr-attrs 1745 For immediately rejected request, CMC works well. If the server 1746 prematurely closes the connection, then the procedures in Section 1747 8.2.4 of [RFC7231] apply. But, this might leave the client and 1748 server in a different state. The client could merely resubmit the 1749 request but another option, documented herein, is for the client to 1750 instead download the PAL to see if the server has processed the 1751 request. Clients might also use this process when they are unable to 1752 remain connected to the server for the entire enrollment process; if 1753 the server does not or is not able to return a PKIData indicating a 1754 status of pending, then the client will not know whether the request 1755 was received. If a client uses the PAL and reconnects to determine 1756 if the certification or rekey/renew request was processed: 1758 o Clients MUST authenticate the server and clients MUST check 1759 server's authorization. 1761 o Server MUST authenticate the client and the server MUST check the 1762 client's authorization. 1764 o Clients retrieve the PAL using the /pal URI. 1766 o Clients and servers use the operation path of "/simpleenroll", 1767 "simplereenroll", or "/fullcmc", based on the PAL entry, with an 1768 HTTP GET [RFC7231] to get the success or failure response. 1770 Responses are as specified in [RFC7030]. 1772 10. Security Considerations 1774 This document relies on many other specifications. For HTTP, HTTPS, 1775 and TLS security considerations see [RFC7231], [RFC2818], and 1776 [RFC5246]; for URI security considerations see [RFC3986]; for content 1777 type security considerations see [RFC4073], [RFC4108], [RFC5272], 1778 [RFC5652], [RFC5751], [RFC5934], [RFC5958] [RFC6031], [RFC6032], 1779 [RFC6268], [RFC6402], [RFC7191], and [RFC7292]; for algorithms used 1780 to protect packages see [RFC3370], [RFC5649], [RFC5753], [RFC5754], 1781 [RFC5959], [RFC6033], [RFC6160], [RFC6161], [RFC6162] and [RFC7192]; 1782 for random numbers see [RFC4086]; for server-generated asymmetric key 1783 pairs see [RFC7030]. 1785 11. IANA Considerations 1787 IANA is requested to perform three registrations: PAL Name Space, PAL 1788 XML Schema, and PAL Package Types. 1790 11.1. PAL Name Space 1792 This section registers a new XML namespace [XMLNS], 1793 "urn:ietf:params:xml:ns:TBD" per the guidelines in [RFC3688]: 1795 URI: urn:ietf:params:xml:ns:TBD 1796 Registrant Contact: Sean Turner (turners@ieca.com) 1797 XML: 1798 BEGIN 1799 1800 1802 1803 1804 Package Availability List 1805 1806 1807

Namespace for Package Availability List

1808

urn:ietf:params:xml:ns:TBD

1809

See RFC TBD

1810 1811 1812 END 1814 11.2. PAL Schema 1816 This section registers an XML schema as per the guidelines in 1817 [RFC3688]. 1819 URI: urn:ietf:params:xml:schema:pal 1821 Registrant Contact: Sean Turner sean@sn3rd.com 1823 XML: See Section 2.1.2. 1825 11.3. PAL Package Types 1827 This section registers the PAL Package Types. Future PAL Package 1828 Types registrations are to be subject to Expert Review, as defined in 1829 RFC 5226 [RFC5226]. Package types MUST be paired with a media type. 1831 The initial registry values are found in Section 2.1.1. 1833 12. Acknowledgements 1835 Thanks in no particular order go to Alexey Melnikov, Paul Hoffman, 1836 Brad McInnis, Max Pritikin, Francois Rousseau, Chris Bonatti, and 1837 Russ Housley for taking time to provide comments. 1839 13. References 1841 13.1. Normative References 1843 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1844 Extensions (MIME) Part One: Format of Internet Message 1845 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1846 . 1848 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1849 Requirement Levels", BCP 14, RFC 2119, DOI 1850 10.17487/RFC2119, March 1997, . 1853 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 1854 Infrastructure Operational Protocols: FTP and HTTP", 1855 RFC 2585, DOI 10.17487/RFC2585, May 1999, . 1858 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, 1859 L., Leach, P., and T. Berners-Lee, "Hypertext Transfer 1860 Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, June 1861 1999, . Obsoleted 1862 by RFC7230, RFC7231, RFC7232, RFC7233, RFC7234, RFC7235. 1864 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 1865 10.17487/RFC2818, May 2000, . 1868 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1869 Classes and Attribute Types Version 2.0", RFC 2985, DOI 1870 10.17487/RFC2985, November 2000, . 1873 [RFC3370] Housley, R., "Cryptographic Message Syntax (CMS) 1874 Algorithms", RFC 3370, DOI 10.17487/RFC3370, August 2002, 1875 . 1877 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1878 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 1879 September 2002, . 1881 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1882 DOI 10.17487/RFC3688, January 2004, . 1885 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1886 Resource Identifier (URI): Generic Syntax", STD 66, 1887 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1888 . 1890 [RFC4073] Housley, R., "Protecting Multiple Contents with the 1891 Cryptographic Message Syntax (CMS)", RFC 4073, DOI 1892 10.17487/RFC4073, May 2005, . 1895 [RFC4108] Housley, R., "Using Cryptographic Message Syntax (CMS) to 1896 Protect Firmware Packages", RFC 4108, DOI 10.17487/RFC4108, 1897 August 2005, . 1899 [RFC4627] Crockford, D., "The application/json Media Type for 1900 JavaScript Object Notation (JSON)", RFC 4627, DOI 1901 10.17487/RFC4627, July 2006, . Obsoleted by RFC7159. 1904 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1905 IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 1906 10.17487/RFC5226, May 2008, . 1909 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1910 (TLS) Protocol Version 1.2", RFC 5246, DOI 1911 10.17487/RFC5246, August 2008, . 1914 [RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS 1915 (CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008, 1916 . 1918 [RFC5273] Schaad, J. and M. Myers, "Certificate Management over CMS 1919 (CMC): Transport Protocols", RFC 5273, DOI 1920 10.17487/RFC5273, June 2008, . 1923 [RFC5274] Schaad, J. and M. Myers, "Certificate Management Messages 1924 over CMS (CMC): Compliance Requirements", RFC 5274, DOI 1925 10.17487/RFC5274, June 2008, . 1928 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1929 Housley, R., and W. Polk, "Internet X.509 Public Key 1930 Infrastructure Certificate and Certificate Revocation List 1931 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1932 . 1934 [RFC5649] Housley, R. and M. Dworkin, "Advanced Encryption Standard 1935 (AES) Key Wrap with Padding Algorithm", RFC 5649, DOI 1936 10.17487/RFC5649, September 2009, . 1939 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1940 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1941 . 1943 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 1944 Mail Extensions (S/MIME) Version 3.2 Message 1945 Specification", RFC 5751, DOI 10.17487/RFC5751, January 1946 2010, . 1948 [RFC5753] Turner, S. and D. Brown, "Use of Elliptic Curve 1949 Cryptography (ECC) Algorithms in Cryptographic Message 1950 Syntax (CMS)", RFC 5753, DOI 10.17487/RFC5753, January 1951 2010, . 1953 [RFC5754] Turner, S., "Using SHA2 Algorithms with Cryptographic 1954 Message Syntax", RFC 5754, DOI 10.17487/RFC5754, January 1955 2010, . 1957 [RFC5934] Housley, R., Ashmore, S., and C. Wallace, "Trust Anchor 1958 Management Protocol (TAMP)", RFC 5934, DOI 1959 10.17487/RFC5934, August 2010, . 1962 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, DOI 1963 10.17487/RFC5958, August 2010, . 1966 [RFC5959] Turner, S., "Algorithms for Asymmetric Key Package Content 1967 Type", RFC 5959, DOI 10.17487/RFC5959, August 2010, 1968 . 1970 [RFC5967] Turner, S., "The application/pkcs10 Media Type", RFC 5967, 1971 DOI 10.17487/RFC5967, August 2010, . 1974 [RFC6010] Housley, R., Ashmore, S., and C. Wallace, "Cryptographic 1975 Message Syntax (CMS) Content Constraints Extension", 1976 RFC 6010, DOI 10.17487/RFC6010, September 2010, 1977 . 1979 [RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax 1980 (CMS) Symmetric Key Package Content Type", RFC 6031, DOI 1981 10.17487/RFC6031, December 2010, . 1984 [RFC6032] Turner, S. and R. Housley, "Cryptographic Message Syntax 1985 (CMS) Encrypted Key Package Content Type", RFC 6032, DOI 1986 10.17487/RFC6032, December 2010, . 1989 [RFC6033] Turner, S., "Algorithms for Cryptographic Message Syntax 1990 (CMS) Encrypted Key Package Content Type", RFC 6033, DOI 1991 10.17487/RFC6033, December 2010, . 1994 [RFC6160] Turner, S., "Algorithms for Cryptographic Message Syntax 1995 (CMS) Protection of Symmetric Key Package Content Types", 1996 RFC 6160, DOI 10.17487/RFC6160, April 2011, 1997 . 1999 [RFC6161] Turner, S., "Elliptic Curve Algorithms for Cryptographic 2000 Message Syntax (CMS) Encrypted Key Package Content Type", 2001 RFC 6161, DOI 10.17487/RFC6161, April 2011, 2002 . 2004 [RFC6162] Turner, S., "Elliptic Curve Algorithms for Cryptographic 2005 Message Syntax (CMS) Asymmetric Key Package Content Type", 2006 RFC 6162, DOI 10.17487/RFC6162, April 2011, 2007 . 2009 [RFC6268] Schaad, J. and S. Turner, "Additional New ASN.1 Modules for 2010 the Cryptographic Message Syntax (CMS) and the Public Key 2011 Infrastructure Using X.509 (PKIX)", RFC 6268, DOI 2012 10.17487/RFC6268, July 2011, . 2015 [RFC6402] Schaad, J., "Certificate Management over CMS (CMC) 2016 Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011, 2017 . 2019 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 2020 DOI 10.17487/RFC7303, July 2014, . 2023 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 2024 "Enrollment over Secure Transport", RFC 7030, DOI 2025 10.17487/RFC7030, October 2013, . 2028 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2029 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2030 2014, . 2032 [RFC7191] Housley, R., "Cryptographic Message Syntax (CMS) Key 2033 Package Receipt and Error Content Types", RFC 7191, DOI 2034 10.17487/RFC7191, April 2014, . 2037 [RFC7192] Turner, S., "Algorithms for Cryptographic Message Syntax 2038 (CMS) Key Package Receipt and Error Content Types", 2039 RFC 7192, DOI 10.17487/RFC7192, April 2014, 2040 . 2042 [RFC7193] Turner, S., Housley, R., and J. Schaad, "The 2043 application/cms Media Type", RFC 7193, DOI 2044 10.17487/RFC7193, April 2014, . 2047 [RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer 2048 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 2049 10.17487/RFC7231, June 2014, . 2052 [RFC7292] Moriarty, K., Ed., Nystrom, M., Parkinson, S., Rusch, A., 2053 and M. Scott, "PKCS #12: Personal Information Exchange 2054 Syntax v1.1", RFC 7292, DOI 10.17487/RFC7292, July 2014, 2055 . 2057 [XML] W3C, "Extensible Markup Language (XML) 1.0 (Fifth 2058 Edition)", W3C Recommendation, November 2008, 2059 . 2061 [XMLSCHEMA] 2062 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 2063 Second Edition", World Wide Web Consortium Recommendation 2064 REC-xmlschema-2-20041082, October 2004, 2065 . 2067 [X.690] ITU-T Recommendation X.690 (2002) | ISO/IEC 8825-1:2002. 2068 Information Technology - ASN.1 encoding rules: 2069 Specification of Basic Encoding Rules (BER), Canonical 2070 Encoding Rules (CER) and Distinguished Encoding Rules 2071 (DER). 2073 13.2. Informative References 2075 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 2076 Classes and Attribute Types Version 2.0", RFC 2985, DOI 2077 10.17487/RFC2985, November 2000, . 2080 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, "Randomness 2081 Requirements for Security", BCP 106, RFC 4086, DOI 2082 10.17487/RFC4086, June 2005, . 2085 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 2086 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2087 . 2089 [XMLNS] Hollander, D., Bray, T., and A. Layman, "Namespaces in 2090 XML", World Wide Web Consortium First Edition REC-xml- 2091 names-19990114, January 1999, 2092 . 2094 Appendix A. Example Use of PAL 2096 This is an informative appendix. It includes examples protocol 2097 flows. 2099 Steps for using a PAL include: 2100 1. Access PAL 2101 2. Process PAL entries 2102 2.1. Get CA Certificates 2103 2.2. Get CRLs 2104 2.3. Get CSR attributes 2105 2.4. Enroll: simple enrollment, re-enrollment, or full CMC 2106 2.5. Get Firmware, TAMP, Symmetric Keys, or EE Certificates 2108 Client Server 2109 ---------------------> -+ 2110 GET req: | /pal 2111 <--------------------- | 2112 GET res: PAL | 2113 Content-Type: application/xml | 2114 | 2115 ---------------------> -+ 2116 GET req: | /cacerts 2117 <--------------------- | 2118 GET res: CA Certificates | 2119 Content-Type: application/pkcs7-smime | 2120 smime-type=certs-only | 2121 | 2122 ---------------------> -+ 2123 GET req: | /crls 2124 <--------------------- | 2125 GET res: CRLs | 2126 Content-Type: application/pkcs7-smime | 2127 smime-type=crls-only | 2128 | 2129 ---------------------> -+ 2130 GET req: | /csrattrs 2131 <--------------------- | 2132 GET res: attributes | 2133 ---------------------> -+ 2134 POST req: PKIRequest | /simpleenroll & 2135 Content-Type: application/pkcs10 | /simplereenroll 2136 | 2137 Content-Type: application/pkcs7-mime | /fullcmc 2138 smime-type=CMC-request | 2139 | 2140 <-------------------- | 2141 (success or failure) | 2142 POST res: PKIResponse | /simpleenroll 2143 Content-Type: application/pkcs7-mime | /simplereenroll 2144 smime-type=certs-only | /fullcmc 2145 | 2146 Content-Type: application/pkcs7-mime | /fullcmc 2147 smime-type=CMC-response | 2148 | 2149 --------------------> -+ 2150 GET req: | /firmware 2151 <-------------------- | /tamp 2152 GET res: Firmware, TAMP Query | /symmetrickeys 2153 + Updates, Symmetric Keys | 2154 Content-Type: application/cms | 2155 | 2156 ---------------------> -+ 2157 POST res: Firmware Receipts or Errors, | /firmware/return 2158 TAMP Response or Confirms or Errors, | /tamp/return 2159 Symmetric Key Receipts or Errors, | /symmetrickeys/ 2160 | return 2161 | 2162 Content-Type: application/cms | 2163 <-------------------- | 2164 POST res: empty | 2165 (success or failure) | 2166 --------------------> -+ 2167 GET req: | /eecerts 2168 <-------------------- | 2169 GET res: Other EE certificates | 2170 Content-Type: application/pkcs7-mime | 2171 smime-type=certs-only | 2173 The figure above shows /eecerts after /*/return, but this is for 2174 illustrative purposes only. 2176 Appendix B. Additional CSR Attributes 2178 This is an informative appendix. 2180 In some cases, the client is severely limited in its ability to 2181 encode and decode ASN.1 objects. If the client knows a csr template 2182 is being provided during enrollment, then it can peel the returned 2183 csr attribute, generate its keys, place the public key in the 2184 certification request, and then sign the request. To accomplish 2185 this, the server returns a PKCS7PDU attribute [RFC2985] in as part of 2186 the /csrattrs (the following is pseudo ASN.1 and is only meant to 2187 show the fields needed to accomplish returning a template 2188 certification request): 2190 pKCS7PDU ATTRIBUTE ::= { 2191 WITH SYNTAX ContentInfo 2192 ID pkcs-9-at-pkcs7PDU 2193 } 2195 pkcs-9-at-pkcs7PDU OBJECT IDENTIFIER ::= { 2196 iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs9(9) 2197 at(25) 5 2198 } 2200 The ContentInfo is a PKIData: 2202 PKIData ::= SEQUENCE { 2203 reqSequence SEQUENCE SIZE(0..MAX) OF TaggedRequest, 2204 } 2206 Where TaggedRequest is a choice between the PKCS #10 or CRMF 2207 requests. 2209 TaggedRequest ::= CHOICE { 2210 tcr [0] TaggedCertificationRequest, 2211 crm [1] CertReqMsg, 2212 } 2214 Or, the Content Info can be a signed data content type that further 2215 encapsulates a PKIData. 2217 Authors' Addresses 2219 Sean Turner 2220 sn3rd 2222 EMail: sean@sn3rd.com