idnits 2.17.1 draft-ietf-pkix-cmp-transport-protocols-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC2510, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC4210, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC2510, updated by this document, for RFC5378 checks: 1996-06-14) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 26, 2009) is 5289 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 650 -- Looks like a reference, but probably isn't: '2' on line 651 -- Looks like a reference, but probably isn't: '4' on line 652 -- Looks like a reference, but probably isn't: '6' on line 653 -- Looks like a reference, but probably isn't: '7' on line 654 -- Looks like a reference, but probably isn't: '9' on line 655 -- Looks like a reference, but probably isn't: '11' on line 656 -- Looks like a reference, but probably isn't: '13' on line 657 -- Looks like a reference, but probably isn't: '15' on line 701 -- Looks like a reference, but probably isn't: '16' on line 702 -- Looks like a reference, but probably isn't: '17' on line 703 -- Looks like a reference, but probably isn't: '18' on line 704 -- Looks like a reference, but probably isn't: '20' on line 662 -- Looks like a reference, but probably isn't: '21' on line 663 -- Looks like a reference, but probably isn't: '23' on line 664 -- Looks like a reference, but probably isn't: '24' on line 665 -- Looks like a reference, but probably isn't: '25' on line 666 -- Looks like a reference, but probably isn't: '1' on line 355 -- Looks like a reference, but probably isn't: '3' on line 356 -- Looks like a reference, but probably isn't: '5' on line 357 -- Looks like a reference, but probably isn't: '8' on line 358 -- Looks like a reference, but probably isn't: '10' on line 359 -- Looks like a reference, but probably isn't: '12' on line 360 -- Looks like a reference, but probably isn't: '14' on line 361 -- Looks like a reference, but probably isn't: '19' on line 362 -- Looks like a reference, but probably isn't: '22' on line 363 -- Looks like a reference, but probably isn't: '26' on line 365 ** Obsolete normative reference: RFC 2510 (Obsoleted by RFC 4210) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4646 (Obsoleted by RFC 5646) -- Obsolete informational reference (is this intentional?): RFC 2482 (Obsoleted by RFC 6082) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 33 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Kapoor 3 Internet-Draft R. Tschalaer 4 Updates: 2510,4210 Certicom 5 (if approved) T. Kause 6 Intended status: Standards Track SSH 7 Expires: April 29, 2010 M. Peylo 8 NSN 9 October 26, 2009 11 Internet X.509 Public Key Infrastructure -- Transport Protocols for CMP 12 draft-ietf-pkix-cmp-transport-protocols-07.txt 14 Status of this Memo 16 This Internet-Draft is submitted to IETF in full conformance with the 17 provisions of BCP 78 and BCP 79. This document may contain material 18 from IETF Documents or IETF Contributions published or made publicly 19 available before November 10, 2008. The person(s) controlling the 20 copyright in some of this material may not have granted the IETF 21 Trust the right to allow modifications of such material outside the 22 IETF Standards Process. Without obtaining an adequate license from 23 the person(s) controlling the copyright in such materials, this 24 document may not be modified outside the IETF Standards Process, and 25 derivative works of it may not be created outside the IETF Standards 26 Process, except to format it for publication as an RFC or to 27 translate it into languages other than English. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on April 29, 2010. 47 Copyright Notice 48 Copyright (c) 2009 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents in effect on the date of 53 publication of this document (http://trustee.ietf.org/license-info). 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. 57 Abstract 59 This document describes how to layer Certificate Management Protocols 60 over various transport protocols. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3. TCP-Based Management Protocol . . . . . . . . . . . . . . . . 7 67 3.1. General Form . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.2. Version . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 3.2.1. Version Negotiation . . . . . . . . . . . . . . . . . 8 70 3.2.2. Detection and Interoperation with RFC2510 71 Conformant Implementations . . . . . . . . . . . . . . 9 72 3.3. Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 3.3.1. Connection Close Flag . . . . . . . . . . . . . . . . 9 74 3.4. Message-Types . . . . . . . . . . . . . . . . . . . . . . 10 75 3.4.1. pkiReq . . . . . . . . . . . . . . . . . . . . . . . . 10 76 3.4.2. pkiRep . . . . . . . . . . . . . . . . . . . . . . . . 11 77 3.4.3. pollReq . . . . . . . . . . . . . . . . . . . . . . . 11 78 3.4.4. pollRep . . . . . . . . . . . . . . . . . . . . . . . 12 79 3.4.5. finRep . . . . . . . . . . . . . . . . . . . . . . . . 12 80 3.4.6. errorMsgRep . . . . . . . . . . . . . . . . . . . . . 12 81 3.4.6.1. VersionNotSupported . . . . . . . . . . . . . . . 13 82 3.4.6.2. GeneralClientError . . . . . . . . . . . . . . . . 14 83 3.4.6.3. InvalidMessageType . . . . . . . . . . . . . . . . 14 84 3.4.6.4. InvalidPollID . . . . . . . . . . . . . . . . . . 15 85 3.4.6.5. GeneralServerError . . . . . . . . . . . . . . . . 15 86 4. HTTP-Based Protocol . . . . . . . . . . . . . . . . . . . . . 16 87 4.1. HTTP Versions . . . . . . . . . . . . . . . . . . . . . . 16 88 4.2. Persistent Connections . . . . . . . . . . . . . . . . . . 16 89 4.3. General Form . . . . . . . . . . . . . . . . . . . . . . . 17 90 4.4. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.5. Communication Workflow . . . . . . . . . . . . . . . . . . 17 92 4.6. HTTP Request-URI . . . . . . . . . . . . . . . . . . . . . 17 93 4.6.1. Common Client Requests . . . . . . . . . . . . . . . . 17 94 4.6.2. Announcements . . . . . . . . . . . . . . . . . . . . 18 95 4.6.2.1. CA Key Update Announcement . . . . . . . . . . . . 19 96 4.7. HTTP Considerations . . . . . . . . . . . . . . . . . . . 20 97 4.8. HTTP Information Security Considerations . . . . . . . . . 20 98 4.9. Compatibility Issues with Legacy Implementations . . . . . 20 99 5. File-Based Protocol . . . . . . . . . . . . . . . . . . . . . 22 100 6. Mail-Based Protocol . . . . . . . . . . . . . . . . . . . . . 23 101 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 102 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 104 9.1. Normative References . . . . . . . . . . . . . . . . . . . 26 105 9.2. Informative References . . . . . . . . . . . . . . . . . . 26 106 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 27 107 Appendix B. Registration of the application/pkixcmp Media Type . 28 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 110 1. Introduction 112 The Certificate Management Protocol (CMP) [RFC4210] requires well 113 defined transport mechanisms to enable End Entities, RAs and CAs to 114 pass PKIMessage sequences between them. This document defines the 115 transport mechanisms which were removed from the main CMP 116 specification with the second release and referred to be in a 117 separate document. 119 The first version of the CMP specification [RFC2510] included a brief 120 description of a simple TCP-based transport protocol. Its features 121 are simple transport level error-handling and a mechanism to poll for 122 outstanding PKI messages. Additionally, it was mentioned that PKI 123 messages could also be conveyed using file-, E-mail- and HTTP-based 124 transport. 126 The current version of the CMP specification incorporated an own 127 polling mechanism and thus the need for a transport protocol 128 providing this functionality vanished. The remaining features CMP 129 requires from its transport protocols are connection- and error- 130 handling. 132 During the long time it existed as draft, this RFC was undergoing 133 drastic changes. The TCP-based transport specification was enhanced 134 and a TCP-Messages-over-HTTP transport specification appeared. Both 135 proved to be needless and cumbersome, implementers preferred to use 136 plain HTTP transport. This specification now aims to reflect that. 138 HTTP transport is generally easy to implement, traverses network 139 borders utilizing ubiquitous proxies and is already commonly found in 140 existing implementations. TCP-based transport is only documented for 141 information and optional downward compatibility. E-Mail or file 142 transfer are also mentioned and may be used to convey PKIMessage 143 sequences - provided that scenarios are identified where they are 144 better suited than HTTP. 146 2. Requirements 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 3. TCP-Based Management Protocol 154 The so-called "TCP-based transport" is OPTIONAL and its use is 155 deprecated. Its description appears here only for information and 156 downward compatibility. HTTP-based transport, as described in 157 Section 4, SHOULD be preferred when transporting CMP messages as 158 defined in [RFC4210]. The reasoning for that is given in Section 1. 160 While this section is called TCP-based and the messages are called 161 TCP-Messages, the same protocol can be used over any reliable, 162 connection oriented transport protocol (e.g. SNA, DECnet, etc.). 163 This protocol is suitable for cases where an end entity (or an RA) 164 initiates a transaction and can poll to pick up the results. 166 The client sends a TCP-Message to the server, and the server responds 167 with another TCP-Message. A response MUST be sent for every request, 168 even if the encapsulated CMP message in the request does not have a 169 corresponding response. 171 The protocol requires a listener process on an RA or CA which can 172 accept TCP-Messages on a well-defined port (default TCP port number 173 is 829). Typically a client initiates the connection to the server 174 and instantly submits a TCP-Message. The server replies with a TCP- 175 Message containing either a CMP message or a reference number to be 176 used later when polling for the actual CMP response message. 178 If a polling-reference was supplied, the client SHOULD send a polling 179 request using this polling-reference after waiting for at least the 180 time specified along with the reference number. The server may again 181 reply with a new polling-reference or with the actual CMP message 182 response. 184 When the final CMP response message has been picked up by the client, 185 no new polling reference is supplied. 187 3.1. General Form 189 The format of a TCP-Message is shown below: 191 0 1 2 3 192 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 194 | Length | 195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 196 | Version = 10 | Flags | Message-Type | \ 197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / 198 \ \ 199 / Value (variable length) / 200 \ \ 201 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 203 Length: 32 bits (unsigned integer) 204 This field contains the number of remaining octets of the TCP- 205 Message (i.e. number of octets of the Value field plus 3). All 206 bit values in this protocol are specified to be in network byte 207 order. 209 Version: 8-bits (unsigned integer) 210 The version of the TCP-Message is 10 in for this document. It 211 MUST be incremented in each future specification modification 212 e.g. changing the Flags field in a way that is not fully 213 backwards compatible. 215 Flags: 8 bits 216 TCP-Message specific flags as described in Section 3.3. 218 Message-Type: 8 bits 219 A value indicating the type of the TCP-Message. 221 Value: variable length 222 Message-type dependent data is stored here. The usage of this 223 field is described along with the respective message-type 225 3.2. Version 227 The TCP-Message version is 10 for this document. The number has 228 deliberately been chosen to prevent [RFC2510] compliant applications 229 from treating it as a valid message type. Applications receiving a 230 version less than 10 SHOULD interpret the message as being an 231 [RFC2510] style message. 233 3.2.1. Version Negotiation 235 If a client knows the protocol version(s) supported by the server 236 (e.g. from a previous TCP-Message exchange or via some out-of-band 237 means) then it SHOULD send a TCP-Message with the highest version 238 supported both by it and the server. If a client does not know what 239 version(s) the server supports then it SHOULD send a TCP-Message 240 using the highest version it supports. 242 If a server receives a TCP-Message version that it supports, then it 243 MUST reply with a TCP-Message of the same version. If the version 244 received is higher than what the server supports, it MUST send back a 245 VersionNotSupported errorMsgRep containing the highest version it 246 supports, see Section 3.4.6. 248 3.2.2. Detection and Interoperation with RFC2510 Conformant 249 Implementations 251 Servers wishing to interoperate with clients conforming to [RFC2510] 252 can do so by treating any received message with a version less than 253 10 as an [RFC2510] message and responding in that format. Servers 254 not wishing to support [RFC2510] messages MUST respond with a 255 [RFC2510] errorMsgRep. 257 If a client receives a [RFC2510] errorMsgRep (message-type 06) 258 message, it MAY automatically resend the same request on the same 259 connection, falling back to the [RFC2510] format; if the received 260 message is not an errorMsgRep, it MUST terminate the connection. It 261 MAY then retry the communication falling back completely to the 262 [RFC2510] format. 264 Naturally, a client MUST abort the connection attempt if the server 265 does not support any of the client's supported versions. It SHOULD 266 retry the version negotiation after a delay to check if the server 267 was updated. 269 3.3. Flags 271 The LSB of the Flags field is used to indicate a connection close; 272 all other bits in the Flags octet MUST be ignored by receivers, and 273 MUST be set to zero by senders. 275 3.3.1. Connection Close Flag 277 By default connections are kept open after the receipt of a response. 278 Either party (client or server) MAY set the connection close bit at 279 any time. If the connection close bit is set on a request, then the 280 server MUST set the bit in the response and close the connection 281 after sending the response. If the bit is set on a response from the 282 server, the client MUST NOT send any further requests on that 283 connection. Applications MAY decide to close an idle connection (one 284 on which no response is outstanding) after some time-out. Because of 285 the problem where a client sends a request and the server closes the 286 connection while the request is still in flight, clients SHOULD 287 automatically retry a request for which no part of the response could 288 be read due to a connection close or reset. 290 If the connection is kept open, it MUST only be used for subsequent 291 request/response transactions started by the client - the server MUST 292 NOT use it to send requests to the client. Different transactions 293 may be freely interwoven on the same connection. E.g. a CR/CP need 294 not immediately be followed by the Confirm, but may be followed by 295 any other request from a different transaction. 297 3.4. Message-Types 299 Message-Types 0-127 are reserved and are to be issued under IANA 300 auspices. Message-types 128-255 are reserved for application use. 302 The Message-Types currently defined are: 304 ID Value Message Name 305 -------- ------------ 306 '00'H pkiReq 307 '01'H pollRep 308 '02'H pollReq 309 '03'H finRep 310 '05'H pkiRep 311 '06'H errorMsgRep 313 If a server receives an unknown message-type, it MUST reply with an 314 InvalidMessageType errorMsgRep. If a client receives an unknown 315 message-type, it MUST abort the current CMP transaction and terminate 316 the connection. 318 The different TCP-Message-types are discussed in the following 319 sections: 321 3.4.1. pkiReq 323 A pkiReq message conveys a PKIMessage from a client to a server. The 324 Value field of this TCP-Message contains a DER-encoded PKIMessage. 326 The type of PKIMessages that can be carried by pkiReq TCP-Messages 327 are (in the order they are defined in [RFC4210]): 328 [0] Initialization Request 329 [2] Certification Request 330 [4] PKCS-10 Request 331 [6] pop Response 332 [7] Key Update Request 334 [9] Key Recovery Request 335 [11] Revocation Request 336 [13] Cross-Certification Request 337 [15] CA Key Update Announcement 338 [16] Certificate Announcement 339 [17] Revocation Announcement 340 [18] CRL Announcement 341 [20] Nested Message 342 [21] General Message 343 [23] Error Message 344 [24] Certificate Confirmation 345 [25] Polling Request 347 3.4.2. pkiRep 349 TCP-Messages of this type are used to send a response to the 350 requestor. The Value field of the pkiRep contains a DER encoded 351 PKIMessage. 353 The type of PKIMessages that can be carried by such pkiRep messages 354 are (in the order they are defined in [RFC4210]): 355 [1] Initialization Response 356 [3] Certification Response 357 [5] pop Challenge 358 [8] Key Update Response 359 [10] Key Recovery Response 360 [12] Revocation Response 361 [14] Cross-Certificate Response 362 [19] Confirmation 363 [22] General Response 364 [23] Error Message 365 [26] Polling Response 367 3.4.3. pollReq 369 A pollReq is used by a client to check the status of a pending TCP- 370 Message. The Value portion of a pollReq contains: 372 0 1 2 3 373 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 374 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 375 | Polling-Reference | 376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 378 Polling-Reference: 32 bits (unsigned integer) 379 This polling-reference MUST be the one returned via the 380 respective pollRep TCP-Message. 382 3.4.4. pollRep 384 A pollRep is sent by the server to the client as response in case 385 there is no PKIMessage ready yet. The Value portion of the pollRep 386 looks as follows: 388 0 1 2 3 389 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 390 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 391 | Polling-Reference | 392 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 393 | Time-to-Check-Back | 394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 396 Polling-Reference: 32 bits (unsigned integer) 397 A unique 32-bit number identifying the transaction. 399 Time-to-Check-Back: 32 bits (unsigned integer) 400 The time in seconds indicating the minimum interval after which 401 the client SHOULD check the status again. The duration for which 402 the server keeps the polling-reference unique is left to the 403 implementation. 405 3.4.5. finRep 407 A finRep is sent by the server whenever no other response applies, 408 such as after receiving a CMP pkiConf. The Value portion of the 409 finRep SHALL contain: 411 0 1 2 3 4 5 6 7 412 +-+-+-+-+-+-+-+-+ 413 | '00'H | 414 +-+-+-+-+-+-+-+-+ 416 '00'H: 8 bits 417 All bits set to zero. 419 3.4.6. errorMsgRep 421 This TCP-Message is sent when a TCP-Message level protocol error is 422 detected. It is imperative that PKIError messages MUST NOT be sent 423 using this message type. Examples of TCP-Message level errors are: 425 o Invalid protocol version 426 o Invalid TCP message-type 427 o Invalid polling reference number 429 The Value field of the errorMsgRep TCP-Message MUST contain: 431 0 1 2 3 432 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 433 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 434 | Error-Type | Data-Length | 435 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 436 \ \ 437 / Data (variable length) / 438 \ \ 439 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 441 Error-Type: 16 bits A value (format described below) indicating the 442 type of the error. 444 Data-Length: 16 bits (unsigned integer) Contains the length of the 445 Data field in number of octets. Error messages not conveying 446 additional information MUST set Data-Length to 0. 448 Data: octets 449 An UTF8 text string for user readable error messages, containing 450 additional information about the error. Note that it does not 451 contain a terminating NULL character at the end. It SHOULD 452 include an [RFC4646] language tag, as described in [RFC2482] 454 The Error-Type is in the format MMNN where M and N are hex digits 455 (0-F) and MM represents the major category and NN the minor. The 456 major categories defined by this specification are: 458 ID Value Major Categories 459 -------- ---------------- 460 '01'H TCP-Message version negotiation 461 '02'H client errors 462 '03'H server errors 464 The major categories '80'H-'FF'H are reserved for application use. 466 The different error-types are discussed in the following sections: 468 3.4.6.1. VersionNotSupported 470 The VersionNotSupported errorMsgRep is defined as follows: 472 +------------------+------------------------+ 473 | Field | Value | 474 +------------------+------------------------+ 475 | Error-Type | '0101'H | 476 | | | 477 | Data-Length | 1 | 478 | | | 479 | Data | | 480 | | | 481 | UTF8-text String | implementation defined | 482 +------------------+------------------------+ 484 where is the highest TCP-Message protocol version the 485 server supports. 487 3.4.6.2. GeneralClientError 489 The GeneralClientError errorMsgRep is defined as follows: 491 +------------------+------------------------+ 492 | Field | Value | 493 +------------------+------------------------+ 494 | Error-Type | '0200'H | 495 | | | 496 | Data-Length | 0 | 497 | | | 498 | Data | | 499 | | | 500 | UTF8-text String | implementation defined | 501 +------------------+------------------------+ 503 3.4.6.3. InvalidMessageType 505 The InvalidMessageType errorMsgRep is defined as follows: 507 +------------------+------------------------+ 508 | Field | Value | 509 +------------------+------------------------+ 510 | Error-Type | '0201'H | 511 | | | 512 | Data-Length | 1 | 513 | | | 514 | Data | | 515 | | | 516 | UTF8-text String | implementation defined | 517 +------------------+------------------------+ 519 where is the invalid Message-Type ID received by the 520 server. 522 3.4.6.4. InvalidPollID 524 The InvalidPollID errorMsgRep is defined as follows: 526 +------------------+------------------------+ 527 | Field | Value | 528 +------------------+------------------------+ 529 | Error-Type | '0202'H | 530 | | | 531 | Data-Length | 4 | 532 | | | 533 | Data | | 534 | | | 535 | UTF8-text String | implementation defined | 536 +------------------+------------------------+ 538 where is the polling-reference received by the 539 server, identifying the transaction. 541 3.4.6.5. GeneralServerError 543 The GeneralServerError errorMsgRep is defined as follows: 545 +------------------+------------------------+ 546 | Field | Value | 547 +------------------+------------------------+ 548 | Error-Type | '0300'H | 549 | | | 550 | Data-Length | 0 | 551 | | | 552 | Data | | 553 | | | 554 | UTF8-text String | implementation defined | 555 +------------------+------------------------+ 557 4. HTTP-Based Protocol 559 For direct interaction between two entities, where a reliable 560 transport protocol like TCP is available, HTTP SHOULD be utilized for 561 conveying CMP messages. 563 With its status codes, HTTP provides needed error reporting 564 capabilities. General problems on the server side as well as those 565 directly caused by the respective request can be reported to the 566 client. 568 As CMP implements a transaction ID, identifying transactions 569 consisting of more than just a single request/response pair, the 570 statelessness of HTTP is not blocking its usage as transport protocol 571 for CMP messages. 573 4.1. HTTP Versions 575 Either HTTP/1.0 as described in [RFC1945] or HTTP/1.1 as in [RFC2616] 576 SHALL be used. Naturally, the newer version should be preferred. To 577 support legacy implementations, both server and client MUST be able 578 to interact with counterparts utilizing the other HTTP protocol 579 version. 581 4.2. Persistent Connections 583 HTTP permits to reuse a connection for subsequent requests. 584 Implementations may use this functionality for messages within the 585 same transaction but MUST NOT rely on that, as e.g. intermediate HTTP 586 proxies might terminate the connection after each request/response 587 pair. 589 In contrast to HTTP/1.1, persistent connections are explicitly 590 negotiated in HTTP/1.0. To avoid the problems described in chapter 591 19.6.2 in [RFC2616], HTTP/1.0 implementations must not send Keep- 592 Alive when talking to proxies. 594 Each time a full CMP transaction is completed, both sides MUST close 595 the connection. There is the risk for denial of service attacks 596 through resource consumption by opening many connections, therefore 597 idle connections must be terminated after an appropriate timeout, 598 maybe depending on the available free resources. Also after sending 599 a CMP Error Message, the server should close the connection even if 600 the CMP transaction is not yet fully completed. 602 4.3. General Form 604 An ASN.1 DER-encoded PKIMessage is sent as the entity-body of an HTTP 605 POST request. If this HTTP request is successful, the server returns 606 the CMP reply in the body of the HTTP response. The response status 607 code in this case MUST be 200; other 2xx codes MUST NOT be used for 608 this purpose. The HTTP responses with empty message body to CMP 609 Announcement messages also utilize the status codes 201 and 202 to 610 identify if the information was properly processed. 612 Note that a server may return any 1xx, 3xx, 4xx, or 5xx status code 613 if the HTTP request needs further handling or is otherwise not 614 acceptable. 616 4.4. Media Type 618 The Internet Media Type "application/pkixcmp" MUST be set in the HTTP 619 header when conveying a PKIMessage. 621 4.5. Communication Workflow 623 In CMP most communication is initiated by the end entities where 624 every CMP request triggers a CMP response message from the CA or RA. 626 The CMP Announcement messages described in Section 4.6.2 are an 627 exception. Their creation may be triggered by events or generated on 628 a regular basis by a CA. The recipient of the Announcement only 629 replies with an HTTP status code acknowledging the receipt or 630 indicating an error but not with a CMP response. 632 The receipt of every HTTP message is confirmed by the counterpart 633 using HTTP means or it MUST be assumed by the sender that it was not 634 successfully delivered to its destination. 636 4.6. HTTP Request-URI 638 The Request-URI is formed as specified in [RFC3986]. 640 4.6.1. Common Client Requests 642 TODO: The following is not more than a proposal as the exact unified 643 style is currently under discussion. 645 Client requests containing a PKI message MUST be directed to an 646 Request-URI depicting a directory having a trailing slash. The 647 following list contains all such CMP message types. The prefixed 648 numbers reflect ASN.1 numbering of the respective element. 650 [0] Initialization Request 651 [2] Certification Request 652 [4] PKCS-10 Request 653 [6] pop Response 654 [7] Key Update Request 655 [9] Key Recovery Request 656 [11] Revocation Request 657 [13] Cross-Certification Request 658 [15] CA Key Update Announcement 659 [16] Certificate Announcement 660 [17] Revocation Announcement 661 [18] CRL Announcement 662 [20] Nested Message 663 [21] General Message 664 [23] Error Message 665 [24] Certificate Confirmation 666 [25] Polling Request 668 An example of a Request-Line and a Host header field in an HTTP/1.1 669 header, sending a CMP request to a server, located in the "exampleCA" 670 directory of the host example.com, would be 672 POST /exampleCA/ HTTP/1.1 673 Host: example.com 675 or in the absoluteURI form 677 POST http://example.com/exampleCA/ HTTP/1.1 679 Host: example.com 681 As CAs may be logically located either inside the root- or within 682 subdirectories, it is possible to set up multiple, logically 683 separated CAs on one host. 685 4.6.2. Announcements 687 A CMP server may create event-triggered announcements or generate 688 them on a regular basis. It MAY also utilize HTTP transport to 689 convey them to a suitable recipient. The ASN.1 encoded structures 690 are sent as the entity-body of an HTTP POST request. 692 Suitable recipients for CMP announcements might e.g. be repositories 693 storing the announced information such as directory services. Those 694 listen for incoming messages, utilizing the same HTTP Request-URI 695 scheme as defined in Section 4.6. 697 The following PKIMessages are announcements that may be pushed by a 698 CA. The prefixed numbers reflect ASN.1 numbering of the respective 699 element. 701 [15] CA Key Update Announcement 702 [16] Certificate Announcement 703 [17] Revocation Announcement 704 [18] CRL Announcement 706 CMP announcement messages do not require any CMP response. However, 707 the recipient MUST acknowledge receipt with a HTTP message having an 708 appropriate status code and an empty body. The sending side should 709 assume the delivery unsuccessful without such reply and retry if 710 applicable after waiting for an appropriate time span. 712 If the announced issue was successfully stored in a database or was 713 already present, the answer MUST be an HTTP message with a "201 714 Created" status code and empty message body. 716 In case the announced issue was only stored for further processing, 717 the status code of the returned HTTP message must be "202 Accepted". 718 After an appropriate delay, the server may then try to send the 719 Announcement again and may repeat this until it receives a 720 confirmation that it was successfully stored. The appropriate 721 duration of the delay and the option to increase it between 722 consecutive attempts should be carefully considered. 724 A receiver MUST answer with suitable 4xx or 5xx HTTP error codes when 725 a problem occurs. 727 4.6.2.1. CA Key Update Announcement 729 When updating its key pair, a CA can produce a CA Key Update 730 Announcement Message that can be made available to the relevant end 731 entities. 733 As an OPTIONAL feature, a CA may also provide this message to be 734 available via an HTTP GET request for the CAKeyUpdAnnContent.PKI file 735 in the respective CA's path. The query component of the Request-URI 736 contains a string with the ASCII representation of the serialNumber 737 of the certificate holding the old key. 739 According to [RFC3986], the query component is indicated by the first 740 question mark ("?") character and terminated by a number sign ("#") 741 character or by the end of the URI. 743 An example of a Request-Line and a Host header field in an HTTP/1.1 744 header, requesting a CA Key Update Announcement Message for an old 745 certificate with the serialNumber 4711 from a CMP server, located in 746 the root directory of the host example.com, would be 747 GET /CAKeyUpdAnnContent.PKI?4711 HTTP/1.1 748 Host: example.com 749 or in the absoluteURI form 750 GET http://example.com/CAKeyUpdAnnContent.PKI?4711 HTTP/1.1 751 Host: example.com 753 If there is no "CA Key Update Announcement" available for the 754 certificate in question, an HTTP "404 Not Found" message MUST be 755 returned. 757 4.7. HTTP Considerations 759 In general, CMP messages are not cachable; requests and responses 760 MUST include a "Cache-Control: no-cache" (and, if either side uses 761 HTTP/1.0, a "Pragma: no-cache") to prevent the client from getting 762 cached responses. 764 Connection management is based on the HTTP provided mechanisms 765 (Connection and Proxy-Connection header fields). 767 While an implementation MAY make use of all defined features of the 768 HTTP protocol, it SHOULD keep the protocol utilization as simple as 769 possible. 771 Content codings MAY be applied. 773 4.8. HTTP Information Security Considerations 775 CMP provides inbuilt integrity protection and authentication. Due to 776 the nature of a PKI, from a security perspective the information 777 communicated unencrypted does not contain sensitive information. 779 However, it might be possible for an interceptor to utilize the 780 available information to gather confidential technical or business 781 critical information. Therefore, users of the HTTP CMP transport 782 might want to use HTTP over TLS according to [RFC2818] or should 783 consider to use virtual private networks created e.g. utilizing 784 Internet Protocol Security according to [RFC4301]. 786 4.9. Compatibility Issues with Legacy Implementations 788 As this document was subject of multiple changes during the long 789 period of time it was created in, implementations using a different 790 approach for HTTP transport may exist. While only those 791 implementations according to this specification are compliant, 792 implementers should to be aware that there might be existing ones 793 which behave differently. 795 Legacy implementations might also use an unregistered "application/ 796 pkixcmp-poll" MIME type as it was specified in earlier drafts of this 797 document. Here, the entity-body of an HTTP POST request contains a 798 TCP-Message instead of a plain DER-encoded PKIMessage. Effectively, 799 this is conveying PKIMessage over TCP-Message over HTTP. 801 5. File-Based Protocol 803 A file containing a PKIMessage MUST contain only the DER encoding of 804 one PKIMessage, there MUST NOT be extraneous header or trailer 805 information in the file. 807 Such files can be used to transport PKIMessage sequences using e.g. 808 FTP. 810 6. Mail-Based Protocol 812 This subsection specifies a means for conveying ASN.1-encoded 813 messages for the protocol exchanges via Internet mail [RFC5321]. A 814 simple MIME object is specified as follows. 816 Content-Type: application/pkixcmp 817 Content-Transfer-Encoding: base64 819 <> 821 This MIME object can be sent and received using common MIME 822 processing engines and provides a simple Internet mail transport for 823 PKIX-CMP messages. Implementations MAY wish to also recognize and 824 use the "application/x-pkixcmp" MIME type (specified in earlier 825 versions of this document) in order to support backward compatibility 826 wherever applicable. 828 7. Security Considerations 830 Three aspects need to be considered by server side implementers: 832 1. There is no security at the TCP and HTTP protocol level (unless 833 tunneled via SSL/TLS) and thus information from TCP-Messages or 834 the HTTP protocol SHOULD NOT be used to change state of the 835 transaction. Change of state SHOULD be triggered by the signed 836 PKIMessages which are carried within the TCP-Message. 838 2. If the server is going to be sending messages with sensitive 839 information (not meant for public consumption) in the clear, it 840 is RECOMMENDED that the server sends back the message directly 841 and not use the TCP-Message pollRep. 843 3. The TCP-Message polling request/response mechanism can be used 844 for all kinds of denial of service attacks. It is RECOMMENDED 845 that a server does not change the polling-reference between 846 polling requests. 848 8. IANA Considerations 850 The IANA has already registered TCP and UDP port 829 for "PKIX-3 851 CA/RA" and the MIME media type "application/pkixcmp" for identifying 852 CMP sequences. 854 No further action by the IANA is necessary for this document or any 855 anticipated updates. 857 9. References 859 9.1. Normative References 861 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 862 Requirement Levels", BCP 14, RFC 2119, March 1997. 864 [RFC2510] Adams, C. and S. Farrell, "Internet X.509 Public Key 865 Infrastructure Certificate Management Protocols", 866 RFC 2510, March 1999. 868 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 869 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 870 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 872 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 873 Resource Identifier (URI): Generic Syntax", STD 66, 874 RFC 3986, January 2005. 876 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 877 "Internet X.509 Public Key Infrastructure Certificate 878 Management Protocol (CMP)", RFC 4210, September 2005. 880 [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying 881 Languages", BCP 47, RFC 4646, September 2006. 883 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 884 October 2008. 886 9.2. Informative References 888 [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, "Hypertext 889 Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996. 891 [RFC2482] Whistler, K. and G. Adams, "Language Tagging in Unicode 892 Plain Text", RFC 2482, January 1999. 894 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 896 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 897 Internet Protocol", RFC 4301, December 2005. 899 Appendix A. Acknowledgments 901 TODO: Add contributors and reviewers. 903 The authors gratefully acknowledge the contributions of various 904 members of the IETF PKIX Working Group and the ICSA CA-talk mailing 905 list (a list solely devoted to discussing CMP interoperability 906 efforts). 908 Appendix B. Registration of the application/pkixcmp Media Type 909 To: ietf-types@iana.org 910 Subject: Registration of MIME media type application/pkixcmp 912 MIME media type name: application 914 MIME subtype name: pkixcmp 916 Required parameters: - 918 Optional parameters: - 920 Encoding considerations: 922 Content may contain arbitrary octet values (the ASN.1 DER encoding 923 of a PKIMessage sequence, as defined in the IETF PKIX Working Group 924 specifications). base64 encoding is required for MIME e-mail; no 925 encoding is necessary for HTTP. 927 Security considerations: 929 This MIME type may be used to transport Public-Key Infrastructure 930 (PKI) messages between PKI entities. These messages are defined by 931 the IETF PKIX Working Group and are used to establish and maintain 932 an Internet X.509 PKI. There is no requirement for specific 933 security mechanisms to be applied at this level if the PKI messages 934 themselves are protected as defined in the PKIX specifications. 936 Interoperability considerations: - 938 Published specification: this document 940 Applications which use this media type: Applications using 941 certificate management, operational, or ancillary protocols (as 942 defined by the IETF PKIX Working Group) to send PKI messages via 943 E-Mail or HTTP. 945 Additional information: 947 Magic number (s): - 948 File extension (s): ".PKI" 949 Macintosh File Type Code (s): - 951 Person and email address to contact for further information: 952 Martin Peylo, martin.peylo@nsn.com 954 Intended usage: COMMON 956 Author/Change controller: Martin Peylo 958 Authors' Addresses 960 Amit Kapoor 961 Certicom 962 25801 Industrial Blvd 963 Hayward, CA 964 US 966 Email: amit@trustpoint.com 968 Ronald Tschalaer 969 Certicom 970 25801 Industrial Blvd 971 Hayward, CA 972 US 974 Email: ronald@trustpoint.com 976 Tomi Kause 977 SSH Communications Security Corp. 978 Fredrikinkatu 42 979 Helsinki 00100 980 Finland 982 Email: toka@ssh.com 984 Martin Peylo 985 Nokia Siemens Networks 986 Linnoitustie 6 987 Espoo 02600 988 Finland 990 Email: martin.peylo@nsn.com