[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Rescert] Revision of the Up/Down Protocol Spec and XML Schema
Hi,
As a followup to the RPKI security review I've made some amendments to
the protocol specification. The changes are:
1 - specify HTTPS transport with 2-way SSL certs
2 - drop msg-ref processing
3 - insist on strict sequential processing of child requests
4 - drop XML content duplication of cert contents
5 - alter the schema to reflect these changes
What I have not done is place the error codes into the schema, but left
them in the specification. We've discussed this here at APNIC and we're
of the view that to the receiver an unknown error code still remains an
error, and its not a schema violation. If the error codes were to be
loaded into the schema then the receiver would be forced to use a
stripped schema (without the error codes) to check the message for
syntactic correctness in order to ensure that it has caught all possible
error codes as error notifications.
The revised protocol spec is at:
http://mirin.apnic.net/resourcecerts/wiki/index.php/IR-ISP_Definition
The ascii version is attached (as generated by Rob A's mirror at:
http://subvert-rpki.hactrn.net/wiki-mirror/text/mirin.apnic.net/resourcecerts/wiki/index.php/IR-ISP_Definition)
regards,
Geoff
IR-ISP Definition
>From ResourceCertification
Jump to: navigation, search
Version 1.1
28 June 2007
Contents
* 1 IR / ISP Resource Certificate Provisioning Protocol
* 2 Goals and Non-Goals of this Protocol Specification
* 3 Protocol
+ 3.1 Common Message format
+ 3.2 Control - Resource Class Query
o 3.2.1 Resource Class List Query
o 3.2.2 Resource Class List Response
+ 3.3 CA - Certificate Issuance
o 3.3.1 Certificate Issuance Request
o 3.3.2 Certificate Issuance Response
+ 3.4 Certificate Revocation
o 3.4.1 Certificate Revocation Request
o 3.4.2 Certificate Revocation Response
+ 3.5 Request-Not-Performed Response
* 4 XML Schema
[edit]
IR / ISP Resource Certificate Provisioning Protocol
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.
The protocol is implemented as an exchange of XML data objects. The schema
for these XML objects is described in the XML Schema section of this
document.
[edit]
Goals and Non-Goals of this Protocol Specification
The objective is to define 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 (or "IR Back End", or "IRBE") is the authoritative source of what
resource allocations may be certified for an ISP.
It is noted that 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 signing of objects with keys
that are certified by resource certificates, nor the issuance of end-entity
certificates.
This protocol specification does not encompass the specification of
interaction with the IRBE, nor the specification of a protocol to manage
the publication repository. These specifications are being maintained in
Rob Austein'sSubversion Docs area.
[edit]
Protocol
This protocol is expressed as a request/response interaction, where the ISP
passes a request to the IR, and the IR generates a response. The intended
functionality is that the requestor (the ISP always initiates a request in
this protocol) poses the request to the other entity (IR), and is provided
with a response to that operation, in a style of functionality similar to
that of a simple client / server interaction.
For the reminder of this document the requestor (ISP) is termed the "client
" and the responder (IR) is termed the "server". The "issuer" is the CA
entity on whose behalf the server is operating.
The underlying transport for this protocol is HTTPS using 2 way (mutual)
SSL. The client initiates an HTTP POST with content type of "application/
x-rpki", with the message 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 operation will be a "well-formed" DER encoded CMS
object.
The request / response mechanism is assumed to be reliable, in that all
requests will generate a matching response. The protocol requires
sequential operation, where the server will not accept a client's request
unless it has generated and sent a response to the 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.
[edit]
Common Message format
<?xml version="1.0" encoding="UTF-8"?>
<message xmlns="http://www.apnic.net/specs/rescerts/up-down/";
version="1"
sender="sender name"
recipient = "recipient name"
type="message type">
[payload]
</message>
[The message is passed over an HTTPS transport connection that safeguards
against interception and replay attacks. The HTTPS session uses two-way
SSL. The HTTPS keys and assocaited 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 HTTPS.]
version
value is the version of this protocol. This document describes
version 1.
sender
value is the agreed name of the message sender, as set at
initial entity-key exchange.
recipient
value is the agreed name of the message recipient, as set at
initial entity-key exchange.
type
possible values 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.
A message in this protocol is a digitally signed object that makes use
of Cryptographic Message Syntax (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
rest of this document 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 SSL
certificate using the appropriate Business PKI.
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 system respectively.
5. Verify the digital signature using the public key provided in the
certificate carried in the CMS
6. Validate the CMS-provided certificate using the Business PKI that
is associated with the sender
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.
Errors in tests 2 through 6 would generate an HTTP 400 Bad Data
response. An error in steps 7 would generate a "Request-Not-Performed"
response.
[edit]
Control - Resource Class Query
[edit]
Resource Class List Query
type="list"
Payload:
[No message payload is defined for this query]
[edit]
Resource Class List Response
type="list_response"
Payload:
<class class_name="class name"
cert_url="url"
resource_set_as="as resource set"
resource_set_ipv4="ipv4 resource set"
resource_set_ipv6="ipv6 resource set"
suggested_sia_head="[directory uri]" >
<certificate cert_url="url"
req_resource_set_as="as resource set"
req_resource_set_ipv4="ipv4 resource set"
req_resource_set_ipv6="ipv6 resource set" >
[certificate]
</certificate>
...
(repeated for each current certificate where the client is the
certificate's subject)
<issuer>[issuer's certificate]</issuer>
</class>
...
(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 issuer's
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 client has multiple certificates in a Resource Class with
different public keys (as may occur during a client key rollover),
there will be multiple certificate elements in the response, with
distinct cert_ski values for each of the client's certified public
keys.
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 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
value is the issuer-assigned name of the issuer's Resource
Class.
cert_url
in the context of a class, this is the URL of 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)
resource_set_as
in the context of a class, this 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, this 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 <dotted quad>/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="1.2.3.0/
24,1.2.4.5/32,2.3.4.5-7.8.9.10") 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, this 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 <hex nibble sequence>/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=
"2003:A::/32,2001:7ABC::-2001:7FFF::"). 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.
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 SIA collection. 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.
The publication protocol [1] contains further details on how
this works.
[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 a current certificate
exists then the cert_url, cert_ski, cert_aki, cert_serial,
resource_set_as, resource_set_ipv4, resource_set_ipv6, and
[certificate] will be present. The attributes req_resource_set_as,
req_resource_set_ipv4, and req_resource_set_ipv6 may be present,
depending on whether these attributes were defined in the
associated client's certificate request. If no current certificate
has been issued, then no certificate element will be included in
the response.
cert_url
the URL reference where the certificate issuer has
published this certificate.
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.
[certificate]
value is the Base64 encoding of the DER-encoded
certificate.
[edit]
CA - Certificate Issuance
[edit]
Certificate Issuance Request
type="issue"
Payload:
<request
class_name="class name"
req_resource_set_as="as resource set"
req_resource_set_ipv4="ipv4 resource set"
req_resource_set_ipv6="ipv6 resource set">
[Certificate request]
</request>
The client must use different key pairs for each distinct resource
class.
If any of 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.
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.
[edit]
Certificate Issuance Response
type="issue_response"
Payload:
<class class_name="class name"
cert_url="url"
resource_set_as="as resource set"
resource_set_ipv4="ipv4 resource set"
resource_set_ipv6="ipv6 resource set" >
<certificate cert_url="url"
req_resource_set_as="as resource set"
req_resource_set_ipv4="ipv4 resource set"
req_resource_set_ipv6="ipv6 resource set" >
[certificate]
</certificate>
<issuer>[issuer's certificate]</issuer>
</class>
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.
[edit]
Certificate Revocation
[edit]
Certificate Revocation Request
type="revoke"
Payload:
<key class_name="class name"
ski="[g(ski)]" />
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 g(SKI) of the client's public key that is to be
revoked. The g() function is defined above.
[edit]
Certificate Revocation Response
type="revoke_response"
Payload:
<key class_name="class name"
ski="[g(ski)]" />
class_name
value is the issuer-assigned name of the server's Resource
Class.
ski
value is the g(SKI) of the client's public key that has
been marked for revocation. The g() function is defined
above.
[edit]
Request-Not-Performed Response
type="error_response"
Payload:
<status>[Code]</status>
<description xml:lang="en-US">[Readable text]</description>
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.
last_msg_processed
value indicates the responder's last processed msg_ref value.
This element MUST be present when an "incorrect msg_ref" status
code is used. It MUST NOT be present in all other cases.
description
value is a text field. This element MAY be present. It's value
has no defined meaning within the scope of this protocol.
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 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
1000+ Client Error
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
2001 Internal Server Error - Request not performed
[edit]
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:anyURI { maxLength="1024" } },
attribute resource_set_as { xsd:string { maxLength="512000" } },
attribute resource_set_ipv4 { xsd:string { maxLength="512000" } },
attribute resource_set_ipv6 { xsd:string { maxLength="512000" } },
attribute suggested_sia_head { xsd:string { maxLength="1024" } }?,
element certificate {
attribute cert_url { xsd:anyURI { maxLength="1024" } },
attribute req_resource_set_as { xsd:string { maxLength="512000" } }?,
attribute req_resource_set_ipv4 { xsd:string { maxLength="512000" } }?,
attribute req_resource_set_ipv6 { xsd:string { maxLength="512000" } }?,
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" } }?,
attribute req_resource_set_ipv4 { xsd:string { maxLength="512000" } }?,
attribute req_resource_set_ipv6 { xsd:string { maxLength="512000" } }?,
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" } }?
}
Retrieved from "http://mirin.apnic.net/resourcecerts/wiki/index.php/
IR-ISP_Definition"
Category: Protocols
