aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
l---------[-rw-r--r--]docs/up-down-protocol508
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