idnits 2.17.1 draft-ietf-pkix-cmp-transport-protocols-09.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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The draft header indicates that this document updates RFC4210, but the abstract doesn't seem to directly say this. It does mention RFC4210 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4210, updated by this document, for RFC5378 checks: 2000-03-07) -- 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 (July 09, 2010) is 5033 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 641 -- Looks like a reference, but probably isn't: '2' on line 642 -- Looks like a reference, but probably isn't: '4' on line 643 -- Looks like a reference, but probably isn't: '6' on line 644 -- Looks like a reference, but probably isn't: '7' on line 645 -- Looks like a reference, but probably isn't: '9' on line 646 -- Looks like a reference, but probably isn't: '11' on line 647 -- Looks like a reference, but probably isn't: '13' on line 648 -- Looks like a reference, but probably isn't: '15' on line 697 -- Looks like a reference, but probably isn't: '16' on line 698 -- Looks like a reference, but probably isn't: '17' on line 699 -- Looks like a reference, but probably isn't: '18' on line 700 -- Looks like a reference, but probably isn't: '20' on line 653 -- Looks like a reference, but probably isn't: '21' on line 655 -- Looks like a reference, but probably isn't: '23' on line 656 -- Looks like a reference, but probably isn't: '24' on line 657 -- Looks like a reference, but probably isn't: '25' on line 658 -- Looks like a reference, but probably isn't: '1' on line 358 -- Looks like a reference, but probably isn't: '3' on line 359 -- Looks like a reference, but probably isn't: '5' on line 360 -- Looks like a reference, but probably isn't: '8' on line 361 -- Looks like a reference, but probably isn't: '10' on line 362 -- Looks like a reference, but probably isn't: '12' on line 363 -- Looks like a reference, but probably isn't: '14' on line 364 -- Looks like a reference, but probably isn't: '19' on line 365 -- Looks like a reference, but probably isn't: '22' on line 366 -- Looks like a reference, but probably isn't: '26' on line 368 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2482 (Obsoleted by RFC 6082) -- Obsolete informational reference (is this intentional?): RFC 2510 (Obsoleted by RFC 4210) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 33 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Kause 3 Internet-Draft SSH 4 Updates: 4210 (if approved) M. Peylo 5 Intended status: Standards Track NSN 6 Expires: January 10, 2011 July 09, 2010 8 Internet X.509 Public Key Infrastructure -- Transport Protocols for CMP 9 draft-ietf-pkix-cmp-transport-protocols-09.txt 11 Abstract 13 This document describes how to layer the Certificate Management 14 Protocol over various transport protocols. It is the "CMPtrans" 15 document referenced in RFC 4210 and therefore updates the reference 16 given therein. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 10, 2011. 35 Copyright Notice 37 Copyright (c) 2010 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 This document may contain material from IETF Documents or IETF 51 Contributions published or made publicly available before November 52 10, 2008. The person(s) controlling the copyright in some of this 53 material may not have granted the IETF Trust the right to allow 54 modifications of such material outside the IETF Standards Process. 55 Without obtaining an adequate license from the person(s) controlling 56 the copyright in such materials, this document may not be modified 57 outside the IETF Standards Process, and derivative works of it may 58 not be created outside the IETF Standards Process, except to format 59 it for publication as an RFC or to translate it into languages other 60 than English. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3. TCP-Based Management Protocol . . . . . . . . . . . . . . . . 6 67 3.1. General Form . . . . . . . . . . . . . . . . . . . . . . . 6 68 3.2. Version . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 3.2.1. Version Negotiation . . . . . . . . . . . . . . . . . 7 70 3.2.2. Detection and Interoperation with RFC2510 71 Conformant Implementations . . . . . . . . . . . . . . 8 72 3.3. Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.3.1. Connection Close Flag . . . . . . . . . . . . . . . . 8 74 3.4. Message-Types . . . . . . . . . . . . . . . . . . . . . . 9 75 3.4.1. pkiReq . . . . . . . . . . . . . . . . . . . . . . . . 9 76 3.4.2. pkiRep . . . . . . . . . . . . . . . . . . . . . . . . 10 77 3.4.3. pollReq . . . . . . . . . . . . . . . . . . . . . . . 10 78 3.4.4. pollRep . . . . . . . . . . . . . . . . . . . . . . . 11 79 3.4.5. finRep . . . . . . . . . . . . . . . . . . . . . . . . 11 80 3.4.6. errorMsgRep . . . . . . . . . . . . . . . . . . . . . 11 81 3.4.6.1. VersionNotSupported . . . . . . . . . . . . . . . 12 82 3.4.6.2. GeneralClientError . . . . . . . . . . . . . . . . 13 83 3.4.6.3. InvalidMessageType . . . . . . . . . . . . . . . . 13 84 3.4.6.4. InvalidPollID . . . . . . . . . . . . . . . . . . 14 85 3.4.6.5. GeneralServerError . . . . . . . . . . . . . . . . 14 86 4. HTTP-Based Protocol . . . . . . . . . . . . . . . . . . . . . 15 87 4.1. HTTP Versions . . . . . . . . . . . . . . . . . . . . . . 15 88 4.2. Persistent Connections . . . . . . . . . . . . . . . . . . 15 89 4.3. General Form . . . . . . . . . . . . . . . . . . . . . . . 15 90 4.4. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 16 91 4.5. Communication Workflow . . . . . . . . . . . . . . . . . . 16 92 4.6. HTTP Request-URI . . . . . . . . . . . . . . . . . . . . . 16 93 4.7. Announcements . . . . . . . . . . . . . . . . . . . . . . 17 94 4.7.1. Pushing of Announcements . . . . . . . . . . . . . . . 17 95 4.7.2. Polling of Announcements . . . . . . . . . . . . . . . 18 96 4.7.2.1. CA Key Update Announcement . . . . . . . . . . . . 18 97 4.7.2.2. Revocation Announcement . . . . . . . . . . . . . 19 98 4.7.2.3. CRL Announcement . . . . . . . . . . . . . . . . . 19 99 4.8. HTTP Considerations . . . . . . . . . . . . . . . . . . . 20 100 4.9. Compatibility Issues with Legacy Implementations . . . . . 20 101 5. File-Based Protocol . . . . . . . . . . . . . . . . . . . . . 21 102 6. Mail-Based Protocol . . . . . . . . . . . . . . . . . . . . . 22 103 7. Security Considerations . . . . . . . . . . . . . . . . . . . 23 104 8. Information Security Considerations . . . . . . . . . . . . . 24 105 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 106 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 107 10.1. Normative References . . . . . . . . . . . . . . . . . . . 26 108 10.2. Informative References . . . . . . . . . . . . . . . . . . 26 109 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 27 110 Appendix B. Registration of the application/pkixcmp Media Type . 28 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 113 1. Introduction 115 The Certificate Management Protocol (CMP) [RFC4210] requires well 116 defined transport mechanisms to enable End Entities, RAs and CAs to 117 pass PKIMessage sequences between them. This document defines the 118 transport mechanisms which were removed from the main CMP 119 specification with the second release and referred to be in a 120 separate document. 122 The first version of the CMP specification [RFC2510] included a brief 123 description of a simple TCP-based transport protocol. Its features 124 are simple transport level error-handling and a mechanism to poll for 125 outstanding PKI messages. Additionally, it was mentioned that PKI 126 messages could also be conveyed using file-, E-mail- and HTTP-based 127 transport. 129 The current version of the CMP specification incorporated an own 130 polling mechanism and thus the need for a transport protocol 131 providing this functionality vanished. The remaining features CMP 132 requires from its transport protocols are connection- and error- 133 handling. 135 During the long time it existed as draft, this RFC was undergoing 136 drastic changes. The TCP-based transport specification was enhanced 137 and a TCP-Messages-over-HTTP transport specification appeared. Both 138 proved to be needless and cumbersome, implementers preferred to use 139 plain HTTP transport. This specification now aims to reflect that. 141 HTTP transport is generally easy to implement, traverses network 142 borders utilizing ubiquitous proxies and is already commonly found in 143 existing implementations. TCP-based transport is only documented for 144 information and optional downward compatibility. E-Mail or file 145 transfer are also mentioned and may be used to convey PKIMessage 146 sequences - provided that scenarios are identified where they are 147 better suited than HTTP. 149 2. Requirements 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. 155 3. TCP-Based Management Protocol 157 The so-called "TCP-based transport" is OPTIONAL and its use is 158 deprecated. Its description appears here only for information and 159 downward compatibility. HTTP-based transport, as described in 160 Section 4, should be preferred when transporting CMP messages as 161 defined in [RFC4210]. The reasoning for that is given in Section 1. 163 While this section is called TCP-based and the messages are called 164 TCP-Messages, the same protocol can be used over any reliable, 165 connection oriented transport protocol (e.g. SNA, DECnet, etc.). 166 This protocol is suitable for cases where an end entity (or an RA) 167 initiates a transaction and can poll to pick up the results. 169 The client sends a TCP-Message to the server, and the server responds 170 with another TCP-Message. A response MUST be sent for every request, 171 even if the encapsulated CMP message in the request does not have a 172 corresponding response. 174 The protocol requires a listener process on an RA or CA which can 175 accept TCP-Messages on a well-defined port (default TCP port number 176 is 829). Typically a client initiates the connection to the server 177 and instantly submits a TCP-Message. The server replies with a TCP- 178 Message containing either a CMP message or a reference number to be 179 used later when polling for the actual CMP response message. 181 If a polling-reference was supplied, the client SHOULD send a polling 182 request using this polling-reference after waiting for at least the 183 time specified along with the reference number. The server may again 184 reply with a new polling-reference or with the actual CMP message 185 response. 187 When the final CMP response message has been picked up by the client, 188 no new polling reference is supplied. 190 3.1. General Form 192 The format of a TCP-Message is shown below: 194 0 1 2 3 195 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 196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 197 | Length | 198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 199 | Version = 10 | Flags | Message-Type | \ 200 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / 201 \ \ 202 / Value (variable length) / 203 \ \ 204 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 206 Length: 32 bits (unsigned integer) 207 This field contains the number of remaining octets of the TCP- 208 Message (i.e. number of octets of the Value field plus 3). All 209 bit values in this protocol are specified to be in network byte 210 order. 212 Version: 8-bits (unsigned integer) 213 The version of the TCP-Message is 10 in for this document. It 214 MUST be incremented in each future specification modification 215 e.g. changing the Flags field in a way that is not fully 216 backwards compatible. 218 Flags: 8 bits 219 TCP-Message specific flags as described in Section 3.3. 221 Message-Type: 8 bits 222 A value indicating the type of the TCP-Message. 224 Value: variable length 225 Message-type dependent data is stored here. The usage of this 226 field is described along with the respective message-type 228 3.2. Version 230 The TCP-Message version is 10 for this document. The number has 231 deliberately been chosen to prevent [RFC2510] compliant applications 232 from treating it as a valid message type. Applications receiving a 233 version less than 10 SHOULD interpret the message as being an 234 [RFC2510] style message. 236 3.2.1. Version Negotiation 238 If a client knows the protocol version(s) supported by the server 239 (e.g. from a previous TCP-Message exchange or via some out-of-band 240 means) then it SHOULD send a TCP-Message with the highest version 241 supported both by it and the server. If a client does not know what 242 version(s) the server supports then it SHOULD send a TCP-Message 243 using the highest version it supports. 245 If a server receives a TCP-Message version that it supports, then it 246 MUST reply with a TCP-Message of the same version. If the version 247 received is higher than what the server supports, it MUST send back a 248 VersionNotSupported errorMsgRep containing the highest version it 249 supports, see Section 3.4.6. 251 3.2.2. Detection and Interoperation with RFC2510 Conformant 252 Implementations 254 Servers wishing to interoperate with clients conforming to [RFC2510] 255 can do so by treating any received message with a version less than 256 10 as an [RFC2510] message and responding in that format. Servers 257 not wishing to support [RFC2510] messages MUST respond with a 258 [RFC2510] errorMsgRep. 260 If a client receives a [RFC2510] errorMsgRep (message-type 06) 261 message, it MAY automatically resend the same request on the same 262 connection, falling back to the [RFC2510] format; if the received 263 message is not an errorMsgRep, it MUST terminate the connection. It 264 MAY then retry the communication falling back completely to the 265 [RFC2510] format. 267 Naturally, a client MUST abort the connection attempt if the server 268 does not support any of the client's supported versions. It SHOULD 269 retry the version negotiation after a delay to check if the server 270 was updated. 272 3.3. Flags 274 The LSB of the Flags field is used to indicate a connection close; 275 all other bits in the Flags octet MUST be ignored by receivers, and 276 MUST be set to zero by senders. 278 3.3.1. Connection Close Flag 280 By default connections are kept open after the receipt of a response. 281 Either party (client or server) MAY set the connection close bit at 282 any time. If the connection close bit is set on a request, then the 283 server MUST set the bit in the response and close the connection 284 after sending the response. If the bit is set on a response from the 285 server, the client MUST NOT send any further requests on that 286 connection. Applications MAY decide to close an idle connection (one 287 on which no response is outstanding) after some time-out. Because of 288 the problem where a client sends a request and the server closes the 289 connection while the request is still in flight, clients SHOULD 290 automatically retry a request for which no part of the response could 291 be read due to a connection close or reset. 293 If the connection is kept open, it MUST only be used for subsequent 294 request/response transactions started by the client - the server MUST 295 NOT use it to send requests to the client. Different transactions 296 may be freely interwoven on the same connection. E.g. a CR/CP need 297 not immediately be followed by the Confirm, but may be followed by 298 any other request from a different transaction. 300 3.4. Message-Types 302 Message-Types 0-127 are reserved and are to be issued under IANA 303 auspices. Message-types 128-255 are reserved for application use. 305 The Message-Types currently defined are: 307 ID Value Message Name 308 -------- ------------ 309 '00'H pkiReq 310 '01'H pollRep 311 '02'H pollReq 312 '03'H finRep 313 '05'H pkiRep 314 '06'H errorMsgRep 316 If a server receives an unknown message-type, it MUST reply with an 317 InvalidMessageType errorMsgRep. If a client receives an unknown 318 message-type, it MUST abort the current CMP transaction and terminate 319 the connection. 321 The different TCP-Message-types are discussed in the following 322 sections: 324 3.4.1. pkiReq 326 A pkiReq message conveys a PKIMessage from a client to a server. The 327 Value field of this TCP-Message contains a DER-encoded PKIMessage. 329 The type of PKIMessages that can be carried by pkiReq TCP-Messages 330 are (in the order they are defined in [RFC4210]): 331 [0] Initialization Request 332 [2] Certification Request 333 [4] PKCS-10 Request 334 [6] pop Response 335 [7] Key Update Request 337 [9] Key Recovery Request 338 [11] Revocation Request 339 [13] Cross-Certification Request 340 [15] CA Key Update Announcement 341 [16] Certificate Announcement 342 [17] Revocation Announcement 343 [18] CRL Announcement 344 [20] Nested Message 345 [21] General Message 346 [23] Error Message 347 [24] Certificate Confirmation 348 [25] Polling Request 350 3.4.2. pkiRep 352 TCP-Messages of this type are used to send a response to the 353 requestor. The Value field of the pkiRep contains a DER encoded 354 PKIMessage. 356 The type of PKIMessages that can be carried by such pkiRep messages 357 are (in the order they are defined in [RFC4210]): 358 [1] Initialization Response 359 [3] Certification Response 360 [5] pop Challenge 361 [8] Key Update Response 362 [10] Key Recovery Response 363 [12] Revocation Response 364 [14] Cross-Certificate Response 365 [19] Confirmation 366 [22] General Response 367 [23] Error Message 368 [26] Polling Response 370 3.4.3. pollReq 372 A pollReq is used by a client to check the status of a pending TCP- 373 Message. The Value portion of a pollReq contains: 375 0 1 2 3 376 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 377 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 378 | Polling-Reference | 379 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 381 Polling-Reference: 32 bits (unsigned integer) 382 This polling-reference MUST be the one returned via the 383 respective pollRep TCP-Message. 385 3.4.4. pollRep 387 A pollRep is sent by the server to the client as response in case 388 there is no PKIMessage ready yet. The Value portion of the pollRep 389 looks as follows: 391 0 1 2 3 392 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 393 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 394 | Polling-Reference | 395 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 396 | Time-to-Check-Back | 397 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 399 Polling-Reference: 32 bits (unsigned integer) 400 A unique 32-bit number identifying the transaction. 402 Time-to-Check-Back: 32 bits (unsigned integer) 403 The time in seconds indicating the minimum interval after which 404 the client SHOULD check the status again. The duration for which 405 the server keeps the polling-reference unique is left to the 406 implementation. 408 3.4.5. finRep 410 A finRep is sent by the server whenever no other response applies, 411 such as after receiving a CMP pkiConf. The Value portion of the 412 finRep SHALL contain: 414 0 1 2 3 4 5 6 7 415 +-+-+-+-+-+-+-+-+ 416 | '00'H | 417 +-+-+-+-+-+-+-+-+ 419 '00'H: 8 bits 420 All bits set to zero. 422 3.4.6. errorMsgRep 424 This TCP-Message is sent when a TCP-Message level protocol error is 425 detected. It is imperative that PKIError messages MUST NOT be sent 426 using this message type. Examples of TCP-Message level errors are: 428 o Invalid protocol version 429 o Invalid TCP message-type 430 o Invalid polling reference number 432 The Value field of the errorMsgRep TCP-Message MUST contain: 434 0 1 2 3 435 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 436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 437 | Error-Type | Data-Length | 438 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 439 \ \ 440 / Data (variable length) / 441 \ \ 442 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 Error-Type: 16 bits A value (format described below) indicating the 445 type of the error. 447 Data-Length: 16 bits (unsigned integer) Contains the length of the 448 Data field in number of octets. Error messages not conveying 449 additional information MUST set Data-Length to 0. 451 Data: octets 452 An UTF8 text string for user readable error messages, containing 453 additional information about the error. Note that it does not 454 contain a terminating NULL character at the end. It SHOULD 455 include an [RFC5646] language tag, as described in [RFC2482] 457 The Error-Type is in the format MMNN where M and N are hex digits 458 (0-F) and MM represents the major category and NN the minor. The 459 major categories defined by this specification are: 461 ID Value Major Categories 462 -------- ---------------- 463 '01'H TCP-Message version negotiation 464 '02'H client errors 465 '03'H server errors 467 The major categories '80'H-'FF'H are reserved for application use. 469 The different error-types are discussed in the following sections: 471 3.4.6.1. VersionNotSupported 473 The VersionNotSupported errorMsgRep is defined as follows: 475 +------------------+------------------------+ 476 | Field | Value | 477 +------------------+------------------------+ 478 | Error-Type | '0101'H | 479 | | | 480 | Data-Length | 1 | 481 | | | 482 | Data | | 483 | | | 484 | UTF8-text String | implementation defined | 485 +------------------+------------------------+ 487 where is the highest TCP-Message protocol version the 488 server supports. 490 3.4.6.2. GeneralClientError 492 The GeneralClientError errorMsgRep is defined as follows: 494 +------------------+------------------------+ 495 | Field | Value | 496 +------------------+------------------------+ 497 | Error-Type | '0200'H | 498 | | | 499 | Data-Length | 0 | 500 | | | 501 | Data | | 502 | | | 503 | UTF8-text String | implementation defined | 504 +------------------+------------------------+ 506 3.4.6.3. InvalidMessageType 508 The InvalidMessageType errorMsgRep is defined as follows: 510 +------------------+------------------------+ 511 | Field | Value | 512 +------------------+------------------------+ 513 | Error-Type | '0201'H | 514 | | | 515 | Data-Length | 1 | 516 | | | 517 | Data | | 518 | | | 519 | UTF8-text String | implementation defined | 520 +------------------+------------------------+ 522 where is the invalid Message-Type ID received by the 523 server. 525 3.4.6.4. InvalidPollID 527 The InvalidPollID errorMsgRep is defined as follows: 529 +------------------+------------------------+ 530 | Field | Value | 531 +------------------+------------------------+ 532 | Error-Type | '0202'H | 533 | | | 534 | Data-Length | 4 | 535 | | | 536 | Data | | 537 | | | 538 | UTF8-text String | implementation defined | 539 +------------------+------------------------+ 541 where is the polling-reference received by the 542 server, identifying the transaction. 544 3.4.6.5. GeneralServerError 546 The GeneralServerError errorMsgRep is defined as follows: 548 +------------------+------------------------+ 549 | Field | Value | 550 +------------------+------------------------+ 551 | Error-Type | '0300'H | 552 | | | 553 | Data-Length | 0 | 554 | | | 555 | Data | | 556 | | | 557 | UTF8-text String | implementation defined | 558 +------------------+------------------------+ 560 4. HTTP-Based Protocol 562 For direct interaction between two entities, where a reliable 563 transport protocol like TCP is available, HTTP SHOULD be utilized for 564 conveying CMP messages. 566 With its status codes, HTTP provides needed error reporting 567 capabilities. General problems on the server side as well as those 568 directly caused by the respective request can be reported to the 569 client. 571 As CMP implements a transaction ID, identifying transactions 572 consisting of more than just a single request/response pair, the 573 statelessness of HTTP is not blocking its usage as transport protocol 574 for CMP messages. 576 4.1. HTTP Versions 578 Either HTTP/1.0 as described in [RFC1945] or HTTP/1.1 as in [RFC2616] 579 MAY be used. Naturally, the newer version should be preferred. To 580 support legacy implementations, both server and client MUST be able 581 to interact with counterparts utilizing the other HTTP protocol 582 version. 584 4.2. Persistent Connections 586 HTTP permits to reuse a connection for subsequent requests. 587 Implementations may use this functionality for messages within the 588 same transaction but MUST NOT rely on that, as e.g. intermediate HTTP 589 proxies might terminate the connection after each request/response 590 pair. 592 In contrast to HTTP/1.1, persistent connections are explicitly 593 negotiated in HTTP/1.0. To avoid the problems described in chapter 594 19.6.2 in [RFC2616], HTTP/1.0 implementations must not send Keep- 595 Alive when talking to proxies. 597 4.3. General Form 599 An ASN.1 DER-encoded PKIMessage is sent as the entity-body of an HTTP 600 POST request. If this HTTP request is successful, the server returns 601 the CMP reply in the body of the HTTP response. The response status 602 code in this case MUST be 200; other 2xx codes MUST NOT be used for 603 this purpose. The HTTP responses with empty message body to CMP 604 Announcement messages also utilize the status codes 201 and 202 to 605 identify if the information was properly processed. 607 Note that a server may return any 1xx, 3xx, 4xx, or 5xx status code 608 if the HTTP request needs further handling or is otherwise not 609 acceptable. 611 4.4. Media Type 613 The Internet Media Type "application/pkixcmp" MUST be set in the HTTP 614 header when conveying a PKIMessage. 616 4.5. Communication Workflow 618 In CMP most communication is initiated by the end entities where 619 every CMP request triggers a CMP response message from the CA or RA. 621 The CMP Announcement messages described in Section 4.7 are an 622 exception. Their creation may be triggered by events or generated on 623 a regular basis by a CA. The recipient of the Announcement only 624 replies with an HTTP status code acknowledging the receipt or 625 indicating an error but not with a CMP response. 627 The receipt of every HTTP message is confirmed by the counterpart 628 using HTTP means or it MUST be assumed by the sender that it was not 629 successfully delivered to its destination. 631 4.6. HTTP Request-URI 633 The Request-URI is formed as specified in [RFC3986]. 635 Client requests containing a PKI message MUST be directed to an 636 Request-URI depicting a directory. A server implementation MUST 637 handle Request-URIs with or without a trailing slash as identical. 638 The following list contains all such CMP message types. The prefixed 639 numbers reflect ASN.1 numbering of the respective element. 641 [0] Initialization Request 642 [2] Certification Request 643 [4] PKCS-10 Request 644 [6] pop Response 645 [7] Key Update Request 646 [9] Key Recovery Request 647 [11] Revocation Request 648 [13] Cross-Certification Request 649 [15] CA Key Update Announcement 650 [16] Certificate Announcement 651 [17] Revocation Announcement 652 [18] CRL Announcement 653 [20] Nested Message 655 [21] General Message 656 [23] Error Message 657 [24] Certificate Confirmation 658 [25] Polling Request 660 An example of a Request-Line and a Host header field in an HTTP/1.1 661 header, sending a CMP request to a server, located in the "/cmp" 662 directory of the host example.com, would be 664 POST /cmp HTTP/1.1 665 Host: example.com 667 or in the absoluteURI form 669 POST http://example.com/cmp/ HTTP/1.1 670 Host: example.com 672 A CMP server may be logically located either inside the root- or 673 within subdirectories of an HTTP server. As default, the path should 674 end in a "cmp" directory. 676 4.7. Announcements 678 A CMP server may create event-triggered announcements or generate 679 them on a regular basis. It MAY also utilize HTTP transport to 680 convey them to a suitable recipient. They can either be pushed to 681 the recipient or polled from the HTTP CMP server. 683 4.7.1. Pushing of Announcements 685 The ASN.1 encoded structures are sent as the entity-body of an HTTP 686 POST request. 688 Suitable recipients for CMP announcements might e.g. be repositories 689 storing the announced information such as directory services. Those 690 listen for incoming messages, utilizing the same HTTP Request-URI 691 scheme as defined in Section 4.6. 693 The following PKIMessages are announcements that may be pushed by a 694 CA. The prefixed numbers reflect ASN.1 numbering of the respective 695 element. 697 [15] CA Key Update Announcement 698 [16] Certificate Announcement 699 [17] Revocation Announcement 700 [18] CRL Announcement 702 CMP announcement messages do not require any CMP response. However, 703 the recipient MUST acknowledge receipt with a HTTP message having an 704 appropriate status code and an empty body. The sending side should 705 assume the delivery unsuccessful without such reply and retry if 706 applicable after waiting for an appropriate time span. 708 If the announced issue was successfully stored in a database or was 709 already present, the answer MUST be an HTTP message with a "201 710 Created" status code and empty message body. 712 In case the announced issue was only stored for further processing, 713 the status code of the returned HTTP message must be "202 Accepted". 714 After an appropriate delay, the server may then try to send the 715 Announcement again and may repeat this until it receives a 716 confirmation that it had been successfully stored. The appropriate 717 duration of the delay and the option to increase it between 718 consecutive attempts should be carefully considered. 720 A receiver MUST answer with a suitable 4xx or 5xx HTTP error code 721 when a problem occurs. 723 4.7.2. Polling of Announcements 725 As an OPTIONAL feature a CA may provide CA Key Update Announcement, 726 Revocation Announcement and CRL Announcement messages for polling 727 using HTTP GET requests. 729 The server replies with the requested Announcement as the body of a 730 HTTP response having a 200 status code. If no suitable announcement 731 message is available, an HTTP "404 Not Found" error code MUST be 732 returned. 734 Query components are formed according to [RFC3986]. Their start is 735 indicated by the first question mark in the Request-URI and they are 736 containing "key=value" pairs. Hexadecimal representations of ASN.1 737 strings used as value MAY contain lower or upper case letters and are 738 neither grouped nor prefixed. 740 The given examples are for a self-signed certificate with the common 741 name (OID 2.5.4.3) "Example CA", the keyIdentifier in hexadecimal 742 representation BE911E711EDB685BF94D9B176A1BC715CE51D794 and the 743 serial number 008F8B7E383D88327C. 745 4.7.2.1. CA Key Update Announcement 747 When updating its key pair, a CA can produce a CA Key Update 748 Announcement Message that can be made available to the relevant end 749 entities. This is described as "Root CA Key Update" in E.4 of 750 [RFC4210]. 752 A CMP server may provide this message via an HTTP GET request for the 753 CAKeyUpdAnn.PKI file in the respective server's path. The 754 identification of the old key in question is created according to the 755 Authority Key Identifier as defined in chapter 4.2.1.1 of [RFC5280]. 756 The query component then cosists of one single "key=value" pair, 757 having the string "AuthorityKeyIdentifier" as key, and the 758 hexadecimal representation of the ASN.1 AuthorityKeyIdentifier 759 sequence as value. 761 An example of the query component, when requesting a CA Key Update 762 Announcement Message for an old key identified with the 763 AuthorityKeyIdentifier 303C8014BE911E711EDB685BF94D9B176A1BC715CE51D7 764 94A119A4173015311330110603550403130A4578616D706C652043418209008F8B7E3 765 83D88327C 767 ?AuthorityKeyIdentifier=303C8014BE911E711EDB685BF94D9B176A1BC715CE 768 51D794A119A4173015311330110603550403130A4578616D706C65204341820900 769 8F8B7E383D88327C 771 4.7.2.2. Revocation Announcement 773 A CMP server MAY permit subjects to poll for a Revocation 774 Announcement using HTTP means. This enables a subject to determine 775 if its certificate is about to be (or has been) revoked. 777 The Request-URI of the HTTP GET targets the RevAnn.PKI file in the 778 respective server's path. The query component contains two 779 "key=value" pairs identifying the certificate in question: 780 o an "issuer" key with the hexadecimal representation of the 781 certificate's issuer's GeneralNames ASN.1 sequence as value 782 o a "serialNumber" key with the hexadecimal representation of the 783 certificate's serial number 785 An example of the query component, when requesting a Revocation 786 Announcement of a certificate issued by "Example CA" having the 787 decimal serialNumber 6699 would be: 789 ?issuer=3015311330110603550403130A4578616D706C65204341& 790 serialNumber=1A2B 792 4.7.2.3. CRL Announcement 794 A CMP server MAY offer the possibility to poll for the latest CRL 795 Announcement of a specific CA. 797 The Request-URI targets the CRLAnn.PKI file. The query component 798 consists of one one "key=value" pair containing an "issuer" key with 799 the hexadecimal representation of the CA's GeneralNames' ASN.1 800 sequence as value. 802 An example of a Request-URI for the latest CRL Announcement of 803 "Example CA" from a CMP server located in the "/cmp" directory of the 804 host example.com would be 806 http://example.com/cmp/ 807 CRLAnn.PKI?issuer=3015311330110603550403130A4578616D706C65204341 809 4.8. HTTP Considerations 811 In general, CMP messages are not cachable; requests and responses 812 MUST include a "Cache-Control: no-cache" (and, if either side uses 813 HTTP/1.0, a "Pragma: no-cache") to prevent the client from getting 814 cached responses. 816 Connection management is based on the HTTP provided mechanisms 817 (Connection and Proxy-Connection header fields). 819 While an implementation MAY make use of all defined features of the 820 HTTP protocol, it SHOULD keep the protocol utilization as simple as 821 possible. 823 There is no need for the clients to send an Expect request-header 824 field with the "100-continue" expectation and wait for a 100 825 (Continue) status as described in chapter 8.2.3 of [RFC2616]. The 826 CMP payload sent by a client is relatively small, so having extra 827 messages exchanged is more inefficient as the server will anyway only 828 seldomly reject the message without looking at the body. 830 Content codings MAY be applied. 832 4.9. Compatibility Issues with Legacy Implementations 834 As this document was subject of multiple changes during the long 835 period of time it was created in, implementations using a different 836 approach for HTTP transport may exist. While only those 837 implementations according to this specification are compliant, 838 implementers should to be aware that there might be existing ones 839 which behave differently. 841 Legacy implementations might also use an unregistered "application/ 842 pkixcmp-poll" MIME type as it was specified in earlier drafts of this 843 document. Here, the entity-body of an HTTP POST request contains a 844 TCP-Message instead of a plain DER-encoded PKIMessage. Effectively, 845 this is conveying PKIMessage over TCP-Message over HTTP. 847 5. File-Based Protocol 849 A file containing a PKIMessage MUST contain only the DER encoding of 850 one PKIMessage, there MUST NOT be extraneous header or trailer 851 information in the file. 853 Such files can be used to transport PKIMessage sequences using e.g. 854 FTP. 856 6. Mail-Based Protocol 858 This subsection specifies a means for conveying ASN.1-encoded 859 messages for the protocol exchanges via Internet mail [RFC5321]. A 860 simple MIME object is specified as follows. 862 Content-Type: application/pkixcmp 863 Content-Transfer-Encoding: base64 865 <> 867 This MIME object can be sent and received using common MIME 868 processing engines and provides a simple Internet mail transport for 869 PKIX-CMP messages. Implementations MAY wish to also recognize and 870 use the "application/x-pkixcmp" MIME type (specified in earlier 871 versions of this document) in order to support backward compatibility 872 wherever applicable. 874 7. Security Considerations 876 Four aspects need to be considered by server side implementers: 878 1. There is the risk for denial of service attacks through resource 879 consumption by opening many connections, therefore idle 880 connections should be terminated after an appropriate timeout, 881 maybe also depending on the available free resources. After 882 sending a CMP Error Message, the server should close the 883 connection even if the CMP transaction is not yet fully 884 completed. 886 2. There is no security at the TCP and HTTP protocol level (unless 887 tunneled via SSL/TLS) and thus information from TCP-Messages or 888 the HTTP protocol SHOULD NOT be used to change state of the 889 transaction. Change of state SHOULD be triggered by the signed 890 PKIMessages which are carried within the TCP-Message. 892 3. If the server is going to be sending messages with sensitive 893 information (not meant for public consumption) in the clear, it 894 is RECOMMENDED that the server sends back the message directly 895 and not use the TCP-Message pollRep. 897 4. The TCP-Message polling request/response mechanism can be used 898 for all kinds of denial of service attacks. It is RECOMMENDED 899 that a server does not change the polling-reference between 900 polling requests. 902 8. Information Security Considerations 904 CMP provides inbuilt integrity protection and authentication. Due to 905 the nature of a PKI, from a security perspective the information 906 communicated unencrypted does not contain sensitive information. 908 However, it might be possible for an interceptor to utilize the 909 available information to gather confidential technical or business 910 critical information. Therefore, users of the HTTP CMP transport 911 might want to use HTTP over TLS according to [RFC2818] or should 912 consider to use virtual private networks created e.g. utilizing 913 Internet Protocol Security according to [RFC4301]. 915 9. IANA Considerations 917 The IANA has already registered TCP and UDP port 829 for "PKIX-3 918 CA/RA" and the MIME media type "application/pkixcmp" for identifying 919 CMP sequences. 921 No further action by the IANA is necessary for this document or any 922 anticipated updates. 924 10. References 926 10.1. Normative References 928 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 929 Requirement Levels", BCP 14, RFC 2119, March 1997. 931 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 932 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 933 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 935 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 936 Resource Identifier (URI): Generic Syntax", STD 66, 937 RFC 3986, January 2005. 939 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 940 "Internet X.509 Public Key Infrastructure Certificate 941 Management Protocol (CMP)", RFC 4210, September 2005. 943 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 944 Housley, R., and W. Polk, "Internet X.509 Public Key 945 Infrastructure Certificate and Certificate Revocation List 946 (CRL) Profile", RFC 5280, May 2008. 948 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 949 October 2008. 951 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 952 Languages", BCP 47, RFC 5646, September 2009. 954 10.2. Informative References 956 [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, "Hypertext 957 Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996. 959 [RFC2482] Whistler, K. and G. Adams, "Language Tagging in Unicode 960 Plain Text", RFC 2482, January 1999. 962 [RFC2510] Adams, C. and S. Farrell, "Internet X.509 Public Key 963 Infrastructure Certificate Management Protocols", 964 RFC 2510, March 1999. 966 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 968 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 969 Internet Protocol", RFC 4301, December 2005. 971 Appendix A. Acknowledgments 973 Until the fifth draft version of this document, released in November 974 24th 2000, the sole authors were Amit Kapoor and Ronald Tschlaer from 975 Certicom. Up to this point, besides editorial changes, the now 976 deprecated TCP-Based transport was described as it is still included 977 herein. They are not available for this working on this document 978 anymore at the time it is entering the "Authors Final Review state 979 AUTH48". As they therefore cannot approve this document as it would 980 be necessary, their names were moved to this section. Their contact 981 data, as originally stated by them, is as follows: 983 Amit Kapoor 984 Certicom 985 25801 Industrial Blvd 986 Hayward, CA 987 US 988 Email: amit@trustpoint.com 990 Ronald Tschalaer 991 Certicom 992 25801 Industrial Blvd 993 Hayward, CA 994 US 995 Email: ronald@trustpoint.com 997 The authors gratefully acknowledge the contributions of various 998 members of the IETF PKIX Working Group and the ICSA CA-talk mailing 999 list (a list solely devoted to discussing CMP interoperability 1000 efforts). 1002 By providing ideas, giving hints and doing invaluable review work, 1003 the following individuals, listed alphabetically, have significantly 1004 contributed to this document: 1006 Tomas Gustavsson, Primekey 1007 Peter Gutmann, University of Auckland 1008 Wolf-Dietrich Moeller, Nokia Siemens Networks 1010 Appendix B. Registration of the application/pkixcmp Media Type 1011 To: ietf-types@iana.org 1012 Subject: Registration of MIME media type application/pkixcmp 1014 MIME media type name: application 1016 MIME subtype name: pkixcmp 1018 Required parameters: - 1020 Optional parameters: - 1022 Encoding considerations: 1024 Content may contain arbitrary octet values (the ASN.1 DER encoding 1025 of a PKIMessage sequence, as defined in the IETF PKIX Working Group 1026 specifications). base64 encoding is required for MIME e-mail; no 1027 encoding is necessary for HTTP. 1029 Security considerations: 1031 This MIME type may be used to transport Public-Key Infrastructure 1032 (PKI) messages between PKI entities. These messages are defined by 1033 the IETF PKIX Working Group and are used to establish and maintain 1034 an Internet X.509 PKI. There is no requirement for specific 1035 security mechanisms to be applied at this level if the PKI messages 1036 themselves are protected as defined in the PKIX specifications. 1038 Interoperability considerations: - 1040 Published specification: this document 1042 Applications which use this media type: Applications using 1043 certificate management, operational, or ancillary protocols (as 1044 defined by the IETF PKIX Working Group) to send PKI messages via 1045 E-Mail or HTTP. 1047 Additional information: 1049 Magic number (s): - 1050 File extension (s): ".PKI" 1051 Macintosh File Type Code (s): - 1053 Person and email address to contact for further information: 1054 Martin Peylo, martin.peylo@nsn.com 1056 Intended usage: COMMON 1058 Author/Change controller: Martin Peylo 1060 Authors' Addresses 1062 Tomi Kause 1063 SSH Communications Security Corp. 1064 Fredrikinkatu 42 1065 Helsinki 00100 1066 Finland 1068 Email: toka@ssh.com 1070 Martin Peylo 1071 Nokia Siemens Networks 1072 Linnoitustie 6 1073 Espoo 02600 1074 Finland 1076 Email: martin.peylo@nsn.com