path: root/docs/up-down-protocol

$URL$
$Id$

[This document is derived from a collaborative work originally
 maintained by Geoff Huston (thanks, Geoff!).  Changes from Geoff's
 version to date have largely been editorial.]

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.

    <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.