NRO Technical Report G. Huston B. Ellacot R. Loomans APNIC October 16, 2007 A Profile for X.509 PKIX Resource Certificates Abstract This document defines a framework for certificate management interactions between a resource issuer ("Internet Registry" or "IR") and a resource recipient ("Internet Service Provider" or "ISP") through the specification of a protocol for interaction between the two parties. The protocol supports the transmission of requests from the ISP, and corresponding responses from the IR encompassing the actions of certificate issuance, certificate revocation and certificate status information reports. This protocol is intended to be limited to the application of resource certificate management and is not intended to be used as part of a more general certificate management framework. Huston, et al. [Page 1] Resource Certificate Profile October 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Protocol Specification . . . . . . . . . . . . . . . . . . . . 4 3.1. Common Message format . . . . . . . . . . . . . . . . . . 5 3.2. Control - Resource Class Query . . . . . . . . . . . . . . 6 3.2.1. Resource Class List Query . . . . . . . . . . . . . . 6 3.2.2. Resource Class List Response . . . . . . . . . . . . . 6 3.3. CA - Certificate Issuance . . . . . . . . . . . . . . . . 10 3.3.1. Certificate Issuance Request . . . . . . . . . . . . . 10 3.3.2. Certificate Issuance Response . . . . . . . . . . . . 11 3.4. Certificate Revocation . . . . . . . . . . . . . . . . . . 11 3.4.1. Certificate Revocation Request . . . . . . . . . . . . 12 3.4.2. Certificate Revocation Response . . . . . . . . . . . 12 3.5. Request-Not-Performed Response . . . . . . . . . . . . . . 13 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16 8. Normative References . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Huston, et al. [Page 2] Resource Certificate Profile October 2007 1. Introduction This document defines a framework for certificate management interactions between a resource issuer ("Internet Registry" or "IR") and a resource recipient ("Internet Service Provider" or "ISP") through the specification of a protocol for interaction between the two parties. The protocol supports the transmission of requests from the ISP, and corresponding responses from the IR encompassing the actions of certificate issuance, certificate revocation and certificate status information reports. This protocol is intended to be limited to the application of resource certificate management and is not intended to be used as part of a more general certificate management framework. 1.1. Terminology It is assumed that the reader is familiar with the terms and concepts described in "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile" [RFC3280], "X.509 Extensions for IP Addresses and AS Identifiers" [RFC3779], "Internet Protocol" [RFC0791], "Internet Protocol Version 6 (IPv6) Addressing Architecture" [RFC4291], "Internet Registry IP Allocation Guidelines" [RFC2050], and related regional Internet registry address management policy documents. Additional terms used in this document are: "IR" an abbreviation of "Internet Registry", using in the context of this document as an entity undertaking the role of resource issuer. An IR is a Certificate Authority, and can issue Resource Certificates. "ISP" an abbreviation of "Internet Service Provider", using in the context of this document as an entity undertaking the role of resource recipient who is the subject of a Resource Certificate. An ISP may be issued with a CA-enabled certificate, allowing the entity to also assume the role of an IR. "resource class" a resource class refers to a collection of resources that can be certified in a single resource certificate by an issuer. "server" in the contxt of this client/server protocol specification, the IR assumes the role of the "server." "client" in the contxt of this client/server protocol specification, the ISP assumes the role of the "client." The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Huston, et al. [Page 3] Resource Certificate Profile October 2007 2. Scope This protocol defines a basic set of interactions that allow an ISP to request certificate issuance, revocation and status information from the IR, and for a IR to maintain an issued certificate set that is aligned to the allocation records relating to each ISP. The IR's resource allocation database, is the authoritative source of what resource allocations the IR may certify for an ISP. A resource recipient (ISP) may also undertake the role of a resource issuer (IR), such as in the case of a Local Internet Registry (LIR). This protocol specification does not encompass: o signing of objects with keys that are certified by resource certificates, nor the issuance of end-entity certificates. o the specification of interaction with the IR's resource allocation database, nor the specification of a protocol to manage the publication repository. o the interactions between client and server that establish identities, exchange the keys used in the protection of the communications channel betwen client and server, and the exchange of the certificates and validation PKI contexts used in the Cryptographic Message Syntax message exchange. 3. Protocol Specification This protocol is expressed as a simple request/response interaction, where the client passes a request to the server, and the server generates a corresponding response. The protocol is implemented as an exchange of XML-formatted data objects. The underlying transport for this protocol is HTTPS [RFC2818] using 2 way (mutual) identification. The client initiates an HTTP POST with content type of "application/x-rpki", with the message object as the body. The server's response will similarly be the body of the response with a content type of "application/x-rpki". The content of the POST, and the server's response, will be a "well-formed" Cryptographic Message Syntax (CMS) [RFC3852] object, encoded using the Distinguished Encoding Rules for ASN.1 (DER) [X.509-88]. The request / response interaction is assumed to be reliable, in that all requests will generate a matching response. The protocol requires sequential operation, where the server MUST NOT accept a client's request unless it has generated and sent a response to the Huston, et al. [Page 4] Resource Certificate Profile October 2007 client's previous request. Attempts by the client to initiate multiple requests in parallel MUST be detected by the server and rejected with an error response. 3.1. Common Message format [payload] The message is passed over an HTTPS transport connection that safeguards against interception and replay attacks. The HTTPS session uses mutually authenticated TLS. The TLS keys and associated certificates have been previously established between the two entities. The message is signed by the sender using a communications key and associated certificate that has been previously established between the two entities. The message signing format is CMS with a timestamp. The CMS keys and certificates MAY be the same as those used for TLS. version the value of this attribute is the version of this protocol. This document describes version 1. sender the value of this attribute is the agreed name of the message sender, as determined between the client and the server by prior arrangement. recipient the value of this attribute is the agreed name of the message recipient, as determined between the client and the server by prior arrangement. type the possible values of this attribute are "list", "list_response", "issue", "issue_response", "revoke", "revoke_response", and "error_response". Conforming parsers MUST reject any document with a version number they do not understand, or with any elements or attributes they do not understand. Servers must generate an error response when receiving such a request. Clients should generate an operator alert error when receiving such a response. Huston, et al. [Page 5] Resource Certificate Profile October 2007 A message in this protocol is a digitally signed object that makes use of CMS [RFC3852], and is encoded as DER. It uses the signed-data object contentType OID, 1.2.840.113549.1.7.2. The attribute "id- signingTime" (contentType OID 1.2.840.113549.1.9.5) MUST be present in the CMS object. The encapsulated content of the CMS wrapping is an XML document. The remainder of this protocol specification omits this CMS wrapper and only discusses the XML document. Messages are checked using the following tests: 1. Check the integrity of the HTTPS message and validate the TLA certificate using the PKI that has been determined by prior arrangement between client and server. 2. Check that the CMS is well-formed. 3. Check that the XML is well-formed. 4. Check that the XML sender and recipient attributes reference a known client and this server's system respectively. 5. Verify the digital signature using the public key provided in the certificate carried in the CMS wrapper. 6. Validate the CMS-provided certificate using the PKI that has been determined by prior arrangement between client and server. 7. Check that the value of the version number of the message is 1. The checks should generally be applied in the order specified here. Any errors encountered while checking items 1 through 6 would cause the server to generate an "HTTP 400 Bad Data" response to the HTTPS POST operation. An error in step 7 would cause the server to generate a "Request-Not-Performed" error response. 3.2. Control - Resource Class Query 3.2.1. Resource Class List Query The value of the message "type" message attribute for this query is: type="list" Payload: [No message payload is defined for this query] 3.2.2. Resource Class List Response The value of the message "type" element for this response is: type="list_response" Huston, et al. [Page 6] Resource Certificate Profile October 2007 Payload: [certificate] ... (repeated for each current certificate where the client is the certificate's subject) [issuer's certificate] ... (repeated for each of the issuer's resource class where the client has been allocated resources) Where the client has been allocated resources from multiple resource classes, then the response will contain multiple class elements, corresponding to the complete set of the issuer's resource classes where the client holds allocated resources. Those issuer's resource classes where the client holds no allocated resources will not be included in the response. Where the issuer has issued multiple certificates in a resource class signed with different keys (as may occur during a staged issuer-key rollover), only the most recent certificate issued with the currently "active" issuer's key will be listed in the response. Each "class" element describes a set of resources that are certified within the scope of a single certificate, referring to a single resource class with a common validation path. class_name the value of this attribute is the issuer-assigned name of the issuer's Resource Class. cert_url in the context of a class element, the value of this attribute is a pointer to the issuer's CA certificate (i.e. a reference to the immediate superior certificate, being the CA- enabled certificate where the issuer is the certificate's subject). Its value is a comma-separated list of URIs, of which Huston, et al. [Page 7] Resource Certificate Profile October 2007 at least one MUST be an RSYNC URI. Any comma values within a URI MUST be escaped ("%2C"). The ordering of the list may be interpreted by the client as a relative preference for access methods as expressed by the publisher of this certificate. resource_set_as in the context of a class element, the value of this attribute is the set of AS numbers and AS number ranges that the issuer has allocated to the client within the scope of this resource class, presented in ASCII as a comma-separated list. The list elements are decimal integer values and ranges of decimal integers specified by the low and high value of the range with a hyphen delimiter, using the canonical order as described in [RFC3779], without leading zeros, and with no white space or punctuation other than the comma and the hyphen range designator (e.g.: resource_set_as="123,456-789,123456"). If there are no AS numbers in this Resource Class the empty set will be represented by a null string value ("") for this attribute. resource_set_ipv4 in the context of a class element, the value of this attribute is the set of IPv4 addresses that the issuer has allocated to the client within the scope of this resource class. The value is presented in ASCII as a comma-separated list of elements. Each element is either an address prefix using the notation of /mask length, or a range specified as low and high range values in dotted quad notation with a hyphen delimiter. The list is presented in canonical order, as described in [RFC3779]. The dotted quad notation is without leading zeros, and the list contains no white space or punctuation other than the period, forward slash, hyphen and comma. (e.g. resource_set_ipv4="192.0.2.0/26,192.0.2.66-192.0.2.76") If there are no IPv4 addresses in this resource class the empty set will be represented by a null string value ("") for this attribute. resource_set_ipv6: in the context of a class element, the value of this attribute is the set of IPv6 addresses that the issuer has allocated to the client within the scope of this resource class. The value is presented in ASCII as a comma-separated list of elements. Each element is either an address prefix using the notation of /mask length, or a range specified as low and high range values in hex nibble notation with a hyphen delimiter. Trailing zero nibbles are truncated and represented by '::'. The list is presented in canonical order, as described in [RFC3779]. The hex nibble sequence notation is without leading zeros, and the list contains no white space or punctuation other than the colon, forward slash, hyphen and comma (e.g. resource_set_ipv6="2001:0DB8::/ 48,2001:0DB8:002::-2001:0DB8:005::"). The XML Schema data type is http://www.w3.org/TR/xmlschema-2/#hexBinary and value is case insensitive, with the canonical form being upper case. If there are no IPv6 addresses in this resource class the empty set will be represented by a null string value ("") for this attribute. Huston, et al. [Page 8] Resource Certificate Profile October 2007 suggested_sia_head: (OPTIONAL) If this field is present then it indicates a publication namespace which the server has made available to the client to use for its own collection of published products. Presence of this field does not mean that the client has permission from the repository operator to lodge under this URI, only that the client has permission from the server to lodge under this URI. [issuer's certificate] value is the Base64 encoding of the DER- encoded issuer's CA certificate (the CA-enabled certificate where the issuer is the certificate's subject). Each certificate element describes the most recently issued current certificate where the certificate's subject refers to the client for each active client key pair. A "current" certificate is a non- expired, non-revoked certificate. If no current certificate has been issued, then no certificate element will be included in the response. cert_url in the context of a certificate element, this is a pointer to the location where the certificate issuer has published this certificate. This field is the issuer's suggestion for the AIA field for the subject to use in subordinate certificates that are issued by the subject. According to the the Resource Certificate Profile [insert ref here] the AIA field is a non-empty (contains a minimum of 1 element) list of URI's, one of which MUST be an RSYNC URI. The order of URI's in the AIA field may be interpreted as the publisher's relative preference for access methods for this certificate. The cert_url conforms to this AIA specification. Its value is a comma-separated list of URIs, one of which MUST be an RSYNC URI. Any comma values within a URI MUST be escaped ("%2C"). req_resource_set_as the set of AS numbers that were specified in the corresponding original certificate request that defined the maximal requested span of the certified AS number set, following the syntax described above. If this attribute was present in the certificate request, then the attribute MUST be present in this response, otherwise it MUST NOT be present. req_resource_set_ipv4 the set of IPv4 addresses that were specified in the corresponding original certificate request that defined the maximal requested span of the certified IPv4 address set, following the syntax described above. If this attribute was present in the certificate request, then the attribute MUST be present in this response, otherwise it MUST NOT be present. req_resource_set_ipv6 the set of IPv6 addresses that were specified in the corresponding original certificate request that defined the maximal requested span of the certified IPv6 address set, following the syntax described above. If this attribute was present in the certificate request, then the attribute MUST be present in this response, otherwise it MUST NOT be present. Huston, et al. [Page 9] Resource Certificate Profile October 2007 [certificate] value is the Base64 encoding of the DER-encoded certificate. 3.3. CA - Certificate Issuance 3.3.1. Certificate Issuance Request The value of the message "type" element for this request is: type="issue" Payload: [Certificate request] The client must use different key pairs for each distinct resource class. If any of the req_resource_set attributes are specified in the request, then any missing req_resource_set attributes are to be interpreted as specifying the complete set of the corresponding resource type that match the client's current resource allocation. If the value of any req_resource_set attributes is the null value (""), then this indicates that no resources of that resource type are to be certified with this request. The requested resource set values are held as a local record by the issuer against the resource class and the client's public key. Any subsequent Certificate Issuance Requests that specify the same Resource Class and the same client's public key will (re)set the issuer's local record of the requested resource sets to the most recently specified values. class_name: value is the server's identifier of a Resource Class. req_resource_set_as (OPTIONAL) the set of AS numbers that define the maximal requested span of the certified AS number set, formatted as per the resource_set_as attribute of the Resource Class List Response. req_resource_set_ipv4 (OPTIONAL) the set of IPv4 addresses that define the maximal requested span of the certified IPv4 address set, formatted as per the resource_set_ipv4 attribute of the Resource Class List Response. Huston, et al. [Page 10] Resource Certificate Profile October 2007 req_resource_set_ipv6 (OPTIONAL) the set of IPv6 addresses that define the maximal requested span of the certified IPv6 address set, formatted as per the resource_set_ipv6 attribute of the Resource Class List Response. [Certificate request] value is the certificate request. This is a Base-64 encoded DER version of a request formatted using PKCS#10. 3.3.2. Certificate Issuance Response The value of the message "type" element for this response is: type="issue_response" Payload: [certificate] [issuer's certificate] If the certificate issuer determines that the issued certificate would be identical in all respects to the most recently issued certificate for this client, other than the certificate's serial number, were the certificate to be issued, the issuer may choose to respond with the most recently issued certificate and not issue a new certificate for this request. The definition of the attributes and syntax of the values is the same as the resource class list response, but the response only references the (single) named resource class, and the (single) certificate issued against the client's public key as provided in the corresponding certificate request. 3.4. Certificate Revocation Huston, et al. [Page 11] Resource Certificate Profile October 2007 3.4.1. Certificate Revocation Request The value of the message "type" element for this request is: type="revoke" Payload: This command 'retires' a client's key pair by requesting the issuer to revoke all certificates for this client that contain the matching public key, within the scope of a named Resource Class. Individual issued certificates cannot be revoked within the scope of this protocol. This command directs the issuer to immediately mark all issued valid certificates issued by this issuer within the named Resource Class with this client's SKI value to be marked as revoked, causing the issued certificates to be withdrawn from the publication repository and to be listed in the server's subsequent CRLs within this Resource Class. class_name value is the issuer-assigned name of the issuer's Resource Class. ski value is the encoded hash of the client's public key that is to be revoked. The algorithm for the encoding is to generate the 160-bit SHA-1 hash of the client's public key, as defined in method (1) of section 4.2.1.2 of [RFC3280], and encode this value using the Base 64 encoding with URL and Filename Safe Alphabet, as defined in section 5 of [RFC4648]. 3.4.2. Certificate Revocation Response The value of the message "type" element for this response is: type="revoke_response" Payload: Huston, et al. [Page 12] Resource Certificate Profile October 2007 class_name value is the issuer-assigned name of the server's Resource Class. ski value is the encoded hash of the client's public key that is to be revoked. The algorithm for the encoding is to generate the 160-bit SHA-1 hash of the client's public key, as defined in method (1) of section 4.2.1.2 of [RFC3280], and encode this value using the Base 64 encoding with URL and Filename Safe Alphabet, as defined in section 5 of [RFC4648]. 3.5. Request-Not-Performed Response The value of the message "type" element for this response is: type="error_response" Payload: [Code] [Readable text] All states where an error response if to be generated, either due to detected errors or inconsistencies in the content of the request or server-side states that prevent the request being performed, generate a Request-Not-Performed response. description value is a text field. This element MAY be present. It's value has no defined meaning within the scope of this protocol, and implementations may assume that some form of human- readable text may be used here. If the HTTP request that triggered this error response includes an Accept-Language header as defined in section 14.4 of the HTTP/1.1 specification [insert reference to RFC2616] then the server will make a best effort to include a second description element using the highest ranked preferred language of the client. The en-US description will always be included if the element is present. The error code set is: Code Value Description 1101 already processing request 1102 version number error 1103 unrecognised request type 1201 request - no such resource class 1202 request - no resources allocated in resource class 1203 request - badly formed certificate request 1301 revoke - no such resource class 1302 revoke - no such key 2000+ Server Error Huston, et al. [Page 13] Resource Certificate Profile October 2007 2001 Internal Server Error - Request not performed 4. XML Schema The following is a RelaxNG compact form schema describing the IR-ISP Protocol, version 1. default namespace = "http://www.apnic.net/specs/rescerts/up-down/" grammar { start = element message { attribute version { xsd:positiveInteger { maxInclusive="1" } }, attribute sender { xsd:token { maxLength="1024" } }, attribute recipient { xsd:token { maxLength="1024" } }, payload } payload |= attribute type { "list" }, list_request payload |= attribute type { "list_response"}, list_response payload |= attribute type { "issue" }, issue_request payload |= attribute type { "issue_response"}, issue_response payload |= attribute type { "revoke" }, revoke_request payload |= attribute type { "revoke_response"}, revoke_response payload |= attribute type { "error_response"}, error_response list_request = empty list_response = class* class = element class { attribute class_name { xsd:token { maxLength="1024" } }, attribute cert_url { xsd:string { maxLength="4096" } }, attribute resource_set_as { xsd:string { maxLength="512000" pattern="[\-,0-9]*" } }, attribute resource_set_ipv4 { xsd:string { maxLength="512000" pattern="[\-,/.0-9]*" } }, attribute resource_set_ipv6 { xsd:string { maxLength="512000" pattern="[\-,/:0-9a-fA-F]*" } }, attribute suggested_sia_head { xsd:anyURI { maxLength="1024" pattern="rsync://.+"} }?, element certificate { attribute cert_url { xsd:string { maxLength="4096" } }, attribute req_resource_set_as { xsd:string { maxLength="512000" pattern="[\-,0-9]*" } }?, attribute req_resource_set_ipv4 { xsd:string { maxLength="512000" pattern="[\-,/.0-9]*" } }?, Huston, et al. [Page 14] Resource Certificate Profile October 2007 attribute req_resource_set_ipv6 { xsd:string { maxLength="512000" pattern="[\-,/:0-9a-fA-F]*" } }?, xsd:base64Binary { maxLength="512000" } }*, element issuer { xsd:base64Binary { maxLength="512000" } } } issue_request = element request { attribute class_name { xsd:token { maxLength="1024" } }, attribute req_resource_set_as { xsd:string { maxLength="512000" pattern="[\-,0-9]*" } }?, attribute req_resource_set_ipv4 { xsd:string { maxLength="512000" pattern="[\-,/.0-9]*" } }?, attribute req_resource_set_ipv6 { xsd:string { maxLength="512000" pattern="[\-,/:0-9a-fA-F]*" } }?, xsd:base64Binary { maxLength="512000" } } issue_response = class revoke_request = revocation revoke_response = revocation revocation = element key { attribute class_name { xsd:token { maxLength="1024" } }, attribute ski { xsd:token { maxLength="1024" } } } error_response = element status { xsd:positiveInteger { maxInclusive="999999999999999" } }, element description { attribute xml:lang { xsd:language }, xsd:string { maxLength="1024" } }? } 5. Security Considerations [To be defined] Huston, et al. [Page 15] Resource Certificate Profile October 2007 6. IANA Considerations [Note to IANA, to be removed prior to publication: there are no IANA considerations stated in this version of the document.] 7. Acknowledgements The authors would like to acknowledge the valued contributions from Rob Austein, Robert Kisteleki, and Randy Bush in the preparation of the protocol described in this document. 8. Normative References [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. [RFC2050] Hubbard, K., Kosters, M., Conrad, D., Karrenberg, D., and J. Postel, "INTERNET REGISTRY IP ALLOCATION GUIDELINES", BCP 12, RFC 2050, November 1996. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3280, April 2002. [RFC3779] Lynn, C., Kent, S., and K. Seo, "X.509 Extensions for IP Addresses and AS Identifiers", RFC 3779, June 2004. [RFC3852] Housley, R., "Cryptographic Message Syntax (CMS)", RFC 3852, July 2004. [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, February 2006. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. [X.509-88] CCITT, "Recommendation X.509: The Directory - Authentication Framework", 1988. Huston, et al. [Page 16] Resource Certificate Profile October 2007 Authors' Addresses Geoff Huston Asia Pacific Network Information Centre Email: gih@apnic.net URI: http://www.apnic.net Byron Ellicot Asia Pacific Network Information Centre Email: bye@apnic.net URI: http://www.apnic.net Robert Loomans Asia Pacific Network Information Centre Email: robertl@apnic.net URI: http://www.apnic.net Huston, et al. [Page 17]