diff options
| l---------[-rw-r--r--] | docs/up-down-protocol | 508 |
1 files changed, 1 insertions, 507 deletions
diff --git a/docs/up-down-protocol b/docs/up-down-protocol index 9387bd02..db428d38 100644..120000 --- a/docs/up-down-protocol +++ b/docs/up-down-protocol @@ -1,507 +1 @@ -$URL$ -$Id$ - -[This document is derived from a collaborative work originally - maintained by Geoff Huston (thanks, Geoff!). Most of the changes - from Geoff's version to date have been editorial, but the XML - described here differs from Geoff's on a few points where the design - group has not yet achived a consensus on the best way to proceed.] - -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. All - resources listed in single certificate share a common - validation path. (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. - - <message version="1"> - <header sender="sender name" - recipient = "recipient name" - msg_ref="reference" /> - - [payload] - - </message> - - 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_query /> - - -Resource Class List Response - - Payload: - - <class ca="ca_name" - issuer_cert_url="url" - issuer_cert_ski="g(ski)" - resource_set_as="as resource set" - resource_set_ipv4="ipv4 resource set" - resource_set_ipv6="ipv6 resource set" - suggested_sia_head="rsync://foo/bar/baz/"> - - <cert cert_url="url" - cert_ski="g(ski)" - cert_aki="g(aki)" - cert_serial="serial" - resource_set_as="as resource set" - resource_set_ipv4="ipv4 resource set" - resource_set_ipv6="ipv6 resource set" - status="keyword" /> - ... - </class> - ... - [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.) - - suggested_sia_head - If this field is present then it indicates a publication - namespace which the IR has made available to the ISP to - use for its own SIA collection. Presence of this field - does not mean that the ISP has permission from the - repository operator to lodge under this URI, only that the - ISP has permission from the IR to lodge under this URI. - See the publication protocol for details on how this works. - -Certificate Issuance Request - - Payload: - - - <issue_request_class ca="ca_name" - resource_set_as="as resource set" - resource_set_ipv4="ipv4 resource set" - resource_set_ipv6="ipv6 resource set" /> - - [Certificate request] - - </issue_request_class> - - - 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 ca="ca_name" - cert_url="url" /> - - [certificate] - - </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: - - <revoke_request_class ca="ca_name" - cert_ski="g(ski)" /> - - - 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: - - <revoke_response_class ca="ca_name" - cert_ski="g(ski)" /> - - - 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: - - <status code="reason code" wait="wait time" /> - - 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. +../wiki-mirror/text/mirin.apnic.net/resourcecerts/wiki/index.php/IR-ISP_Definition_v_0.9.0
\ No newline at end of file |