$URL$ $Id$ Terminology IR An Internet Registry that performs resource allocations and certificate issuance and revocation. ISP A recipient of a resource allocation and the subject of resource certificate(s). CA A Certificate Authority. In this context a CA is a module with a key pair, a copy of its own certificate (issued by the superior CA), a next serial number, and a CRL. It has a pointer to a publication area (used in the SIA fields of subordinate issued certificates), and a pointer to the issued CA certificate (used in the AIA fields of all subordinate issued certificates). It has access to a record of all of its issued certificates. There may be a transient situation within a CA where there are two key pairs that share a common publication area, and a common Subject Name, as may be encountered in CA key rollover. In terms of subordinate certificate issuance only one CA key pair (the most recently certified generation of this CA) is "active" at any point in time. Resource Class A Resource Class is a set of IR-managed resources that are allocated to an ISP that have a common validation path and a common validity expiration time. In the IR context multiple classes for an ISP may refer to a single IR CA (differing validity times), while in the ISP context each resource class is represented a distinct ISP CA. All resources listed in single certificate share a common validation path and share common validity dates. (Other documents may refer to a "Resource Class" as a "Resource Genre".) Resource Certificate A Resource Certificate is an X.509 v3 certificate with a critical extension ip IP resources, as defined in RFC 3779. A Resource Class may have a number of CA generations (one for each current issuer's key pair) and each CA generation may have a number of certificates that have been issued to the same subject. It is up to the issuer to determine which of the CA generations is the currently "active" CA in terms of certificate issuance, so the subject need only specify the particular resource class in a certificate issuance request. Protocol This protocol is expressed as a request/response interaction, where the ISP passes a request to the Internet Registry (IR), and the IR generates a response. The request / response mechanism is assumed to be reliable, in that queued requests will generate a matching response, and sequential, in that multiple requests will be ordered and processed by the IR Class in the order of receipt by the IR Class. Common Message format The protocol uses signed messages (object security) in order to provide an auditable authentication trail. Confidentiality is not required. The overall message format is DER-encoded CMS wrapping XML, with the entire XML message contained within the eContent OCTET STRING of the CMS message. The "bag of certs" portion of the CMS wrapper should contain the entire certificate chain up to (but not including) the business trust anchor that the sender expects the receiver to use to authenticate the message. The rest of this document omits the CMS wrapper and only discusses the XML protocol.
[payload] version value is defined as "1" for this version of the protocol sender value is the agreed name of the sender, as set at entity key-exchange time. recipient value is the agreed name of the message recipient, as set at entity key-exchange time. msg_ref value is set by the sender when generating a query. The corresponding response message contains the same msg_ref value. A sender must ensure that different msg_refs are used for each query. The recipient need not answer the same msg_ref more than once. [payload] is one of the protocol requests or responses below. Resource Class List Query Payload: Resource Class List Response Payload: ... ... [repeated for each active class where the ISP has resources] TODO: prune unnecessary fat Where the ISP has multiple certificates in a Resource Class with different public keys (as in an ISP key rollover), there will be multiple cert entries in the respose, with distinct cert_ski values for each of the ISP's public keys. Where the IR has issued multiple certificates in a Resource Class signed with different IR keys (as in an IR key rollover), only the most recent certificate issued by the current "active" IR CA will be listed in the response. The cert_aki field reflects the public key of the "active" IR ca. The ca value describes a set of resources that are certified within the scope of a single certificate, referring to a resource set with a common validation path. ca value is the issuer-assigned name of the issuer's CA. When combined with the subcaca value this doublet represents the ISP's Resource Class identifier. issuer_cert_url The issuer_cert_url is an object reference that refers to the publication point of the IR's CA certificate for this resource class. Note: this is under debate. The three Robs believe that we need at least the issuer's SIA in order to build some of the URLs to go into cert requests. Rob L believes that it is useful to be able to get the parent's whole cert. issuer_cert_ski The value is the g(SKI) of the IR CA's public key. cert_url optional, only present when the issuer has issued a current certificate to this subject. The cert_url is an object reference that refers to the issuer's publication point of this certificate. cert_ski The value is the g(SKI) of the ISP CA's public key. cert_serial The cert_serial value is the serial number of the most recently issued valid certificate to this subject, in decimal representation. When combined with the cert_aki value, this doublet represents a unique identifier of the most recently issued certificate. cert_aki The cert_aki is the g(aki) value of the most recently issued valid certificate to this subject. When combined with the cert_serial value, this doublet represents a unique identifier of the most recently issued certificate. status The value undersize indicates that the certificate does not encompass all resources allocated to the ISP within this class (filtered by the resource_set value, if specified). The value match indicates that the certificate spans all currently ISP-allocated resources in this class. The value issuance_pending reflects the situation where the subject has requested that a certificate be issued, but that this operation has not been undertaken as yet by the issuer (due to an asynchronous key signing engine in operation). Note: some of these status values go away because they can be derived from the class resource set and the cert resource sets. May need a status to use during parent key rollover saying: you better request new certs because your parent has been re-issued resource_set_as If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of AS numbers that is no larger than that described in the value of this attribute. The value is the ascii representation of an AS Number resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of AS Numbers and ranges of AS numbers, represented as decimal integers, with no other punctuation or whitespace.) resource_set_ipv4 If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of IPv4 address resources that is no larger than that described in the value of this attribute. The value is the ascii representation of an IPv4 address resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of IPv4 address prefixes and ranges of IPv4 address, represented as dotted quad decimal integers, with no other punctuation or whitespace.) resource_set_ipv6 If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of IPv4 address resources that is no larger than that described in the value of this attribute. The value is the ascii representation of an IPv6 address resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of IPv4 address prefixes and ranges of IPv4 address, represented as colon delimited 16 bit nibbles using hexadecimal integers and "::" compression, with no other punctuation or whitespace.) Certificate Issuance Request Payload: [Certificate request] The ISP must use different key pairs for each distinct resource class (i.e. for each distinct value of the ca and subca pair). ca value is the IR's identifier of a CA instance. TODO: pull address format from Rob A's post to mailing list and drop references to RFC3779 resource_set_as Optional. If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of AS numbers that is no larger than that described in the value of this attribute. The value is the ascii representation of an AS Number resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of AS Numbers and ranges of AS numbers, represented as decimal integers, with no other punctuation or whitespace.) If the attribute value is empty (i.e. resource_set_as="") then this is the null set, and no AS number resources will be certified. If this attribute is not present, then the issuer will issue a certificate that encompasses all AS Number resources that are certificated by this CA instance. resource_set_ipv4 Optional. If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of IPv4 address resources that is no larger than that described in the value of this attribute. The value is the ascii representation of an IPv4 address resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of IPv4 address prefixes and ranges of IPv4 address, represented as dotted quad decimal integers, with no other punctuation or whitespace.) If the attribute value is empty (i.e. resource_set_ipv4="") then this is the null set, and no IPv4 address resources will be certified. If this attribute is not present, then the issuer will issue a certificate that encompasses all IPv4 address resources that are certificated by this CA instance. resource_set_ipv6 Optional. If this field is present then it indicates that the ISP has requested that the certificate's resource extension encompass the set of IPv4 address resources that is no larger than that described in the value of this attribute. The value is the ascii representation of an IPv6 address resource collection, presented in the canonical format as described in RFC3779. (i.e. a comma separated list of IPv4 address prefixes and ranges of IPv4 address, represented as colon delimited 16 bit nibbles using hexadecimal integers and "::" compression, with no other punctuation or whitespace.) If the attribute value is empty (i.e. resource_set_ipv6="") then this is the null set, and no IPv4 address resources will be certified. If this attribute is not present, then the issuer will issue a certificate that encompasses all IPv4 address resources that are certificated by this CA instance. [Certificate request] value is the certificate request. This is a Base-64 encoded DER version of a request formatted using PKCS#10. Certificate Issuance Response Payload: [certificate] The issued certificate has a resource extension that fully covers the ISP's resources in this resource class. If the issuer determines that the issued certificate would be identifical in all respects to the most recently issued certificate for this subject (other than the issuer'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. If asynchronous key signing is being used then this request will generate a "Request Not Performed" response with a status code of "Request Queued" may be used as a response to the certificate issuance request. This response is to be interpreted by the ISP as a well formed request that will be completed by the IR at a later time. Within the IR certificate system asynchronous key signing implies that the request has been enqueued in the key signing queue. If the certificate issuance request has the same CA and SKI as an already-queued issue request, then the already-queued entry request must be removed from the queue when this (more recent) queue request is enqueued. ca value is the issuer-assigned name of the issuer's CA. When combined with the subcaca value this doublet represents the ISP's Resource Class identifier. cert_url value is an object reference that refers to the issuer's publication point of this certificate. [certificate] value is the Base64 encoding of the DER-formatted issued certificate. Key Revocation Request Payload: This request directs the IR Resource Class to revoke all certificates for this subject that contain the matching public key, across all IR CA generations within this Resource Class. This command directs the system to immediately mark all issued valid certificates issued by this CA with this SKI value as revoked, causing the most recently issued certificate to be withdrawn from the publication respistory and all marked certificates to be listed in the Isser's subsequent CRLs. If asynchronous key signing is in place then all queued requests to the key pair corresponding to this CA are removed from the queue. If an asynchronous key signing event is taking place (i.e. some certificate issuance requests have been taken off-line for signing) then an input filter entry for signed objects is added to filter out signed objects referring to this CA and this SKI value when they are passed back from the off-line signing process. ca value is the issuer-assigned name of the issuer's CA. cert_ski value is the g(SKI) of the ISP CA's public key. Key Revocation Response Payload: ca value is the issuer-assigned name of the resource class. cert_ski value is the g(SKI) of the ISP CA's public key Request-Not-Performed Response Payload: code value is ascii text response code which is a protocol element. TODO: Allowed values must be specified in this document. wait Optional. value is a positive number in seconds, suggesting when to try this request again Messages that fail (envelope / outer wrapper) signature validation do not generate any response. All other messages that are not processed, either due to inconsistencies in the request or server-side states that prevent the request being performed, generate a response use this Request-Not-Performed response (such as non existent class, for example). Where the CA operates asynchronously, requiring that certificate issuance requests be queued for signing, this "Request Not Performed" message, with a status code of "request_queued" may be used as a response to the certificate issuance request. Asynchronous (Off-line) Key Signing Operation TODO: update this section in light of changes to the protocol (2007-03-22) This protocol is intended to operate consistently irrespective of whether the IR uses a synchronous (on-line) or asynchronous (off-line) key signing. In the case of a synchronous (on-line) singing engine the cetificate issuance and certificate revocation requests are passed directly to the signing engine, and the results passed back to the Certificate system. In this case the signing engine's response is used to generate the XML response to the ISP. The ISP can correctly assume that the certificate operation has been completed by the time the response is received. In the case of an asynchronous (off-line) signing engine, the certificate issuance, CRL signing and signing of certificate request tasks must all be queued in the key signing queue. Certificate issue requests generate a "pending" response, indicating that the request appears to be well formed, but the signing engine actions are forthcoming. For an asynchronous (off-line) key signing model there is a queue of items that are awaiting signing. There are some associated queue management tasks that are necessary in order to minimize the number of extraneous issued certificates. A certificate issuance request generates a new queue entry for the CA. Unless otherwise directed, the key signing queue entry has the side effect of removing all other certificate issuance requests from the same subject with the same public key for the same IR's CA instance that have been already enqueued for signing. When the queue is drained to load up onto the device to pass to the key signing equipment a side effect of the drain operation is to perform a resource check with the resource allocation database to ensure that the 3779 attributes of the certificate request reflect the resource allocation database state at the time of passing the request to the key signing module. When a key signing operation is in place a "key signing active" state is raised, allowing other modules to place entries into a signed object filter. When the key signing event completes the "key signing active" state is cleared. The signed objects (signed while the "key signing active" state was active) are passed through the filter before being placed in the relevant local stores. The filter set is then cleared.