Copyright © 2001,2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This document extends the XML Key Management Specification [XKMS] protocol to encompass the bulk registration operations necessary for interfacing with such systems as smart card management systems.
X-BULK is defined in terms of structures expressed in the XML Schema Language [XML-Schema] and web services description language [WSDL].
This is an editor's copy and has no status at all.
This is the first draft of the "XML Key Management Specification Bulk Operation (X-BULK)" specification from theW3C XML Key Management Working Group(Activity Statement). This version attempts to capture the consensus resulting from the 1 March 2001 face-to-face meeting and subsequent discussion on thelist. However, it does contain points which are still under discussion or not well specified.
The Working Group will try touse a new namespacewhen changes in its syntax or processing are substantive. However, this namespace might be reused (prior to reaching Candidate Recommendation) by subsequent drafts in such a way as to cause instances using the namespace to become invalid or to change in meaning or affect the operation of existing software. Requests for a more stringent level of namespace stability should be made to the Working Group.
Publication of this document does not imply endorsement by the W3C membership. This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite a W3C Working Draft as anything other than a "work in progress." Please send comments to the editor and cc: the listwww-xkms@w3.org(archives).
Patent disclosures relevant to this specification may be found on the Working Group'spatent disclosure pagein conformance with W3C.
A list of current W3C working drafts can be found athttp://www.w3.org/TR/.
XKMS currently addresses one-by-one registration (X-KRSS) and key information and validation services (X-KISS). However, we feel that a standard must also address bulk issuance cases and are proposing that an X-BULK specification, built on the basis of X-KRSS be included in scope of the work.
The use cases where X-BULK is required include:
Key differences between X-KRSS and X-BULK include:
X-BULK does however reuse element definitions from the current X-KRSS specification.
Separating bulk from one-by-one registration has the benefit that the separately defined messages required are simpler than if a single message format handling both one-by-one and bulk cases were to be defined. It is also better not to burden a client for one-by-one operation with the additional complexity required in batch operation.
Demand for this functionality is shown by the emergence of a number of proprietary solutions in this space.
Design criteria include:
For clarity, some examples of XML are not complete documents and namespace [XML-Names] declarations may be omitted from XML fragments. In this document, certain namespace prefixes represent certain namespaces as follows
Prefix | Specification | Schema |
XML Schema | http://www.w3.org/2001/XMLSchema | |
ds | XML Signature | http://www.w3.org/2000/09/xmldsig# |
xkms | XKMS | http://www.w3.org/2002/03/xkms# |
xbulk | X-BULK | http://www.w3.org/2002/04/xbulk# |
These namespaces are declared in the XKMS schema as follows:
Schema Definition: <?xml version="1.0"?> <schema targetNamespace="http://www.w3.org/2002/04/xbulk#" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" elementFormDefault="qualified" attributeFormDefault="unqualified"> <import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/> <import namespace="http://www.w3.org/2002/03/xkms#" schemaLocation="xkms-schema.xsd"/> <annotation> <documentation xml:lang="en"> XML Schema for X-BULK draft 2 16th April 2002 </documentation> </annotation>
X-BULK defines a batch element that can contain registration requests, responses and status requests. The basic idea is that a single batch can contain a number of independently referencable requests or responses. Batches are produced both from the requestor and responder. A responder will process an entire batch and produce a single batch of responses after processing.
All batches MUST be authenticated; that is, the originator of a batch must be able to protect the batch. Implementations MUST support the RSA algorithm for digitally signing batches. Implementations MUST be capable of using the XKMS Register operation for the registration of the keys used to authenticate batches.
Implementations MUST include a ds:X509Data
element in the
Signature, which is used together with the BatchID
to ensure
batch uniqueness.
The basic mode of operation is that a batch of requests is submitted. The responder processes the batch and produces a response batch that contains one response for each request in the batch. Other, more flexible modes of operation may be defined later (e.g. allowing responses to be spread over multiple batches). This mode of "full batch processing" is sufficient for most use cases and is considerably simpler than supporting "selective batch processing."
Each batch has an information element that identifies the batch (and can contain additional unprocessed information).
In order to allow the requestor to track the progress of batch processing implementations MAY support status requests. A status request is a request to determine the status of processing of the referenced batch. The response gives a simple indication of the numbers of requests from the batch that are in the various possible states (processed, failed, etc.).
A batch response contains one response for each request, not necessarily in the same order as in the request batch. That is, requestors MUST be able to handle responses that are not sorted in any particular way.
In many use cases, the requestor requires "additional information" to be "carried around" with a batch or request, but which is not intended for processing by the responder.
Responders MAY also add more additional information to the specific responses. Requestors MUST be able to handle such additional information.
The basic request and response structures are as in [XKMS] and can support the same level of functionality (registration of new keys, local/central key generation, etc.).
This specification uses XML Schemas [XML-Schema] to describe the content model.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC2119 [Keywords]:
"they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmissions)"
Consequently, we use these capitalized keywords to unambiguously specify requirements over protocol and application features and behavior that affect the interoperability and security of implementations. These key words are not used (capitalized) to describe XML grammar; schema definitions unambiguously describe such requirements and we wish to reserve the prominence of these terms for the natural language descriptions of protocols and features. For instance, an XML attribute might be described as being "optional." Compliance with the XML-namespace specification [XML-Names] is described as "REQUIRED."
The remainder of this document describes the X-BULK messages; first the generic message types; then the messages and elements associated with bulk registration, along with examples; and then the messages associated with bulk status checking, along with examples. Finally the complete schema for X-BULK and the [WSDL] definition are presented.
X-BULK messages reuse the standard XKMS abstract request/response framework.
BulkRequestAbstractType
typeThe BulkRequestAbstractType
type extends the XKMS abstract
request type to include generic batch information:
Schema Definition: <complexType name="BulkRequestAbstractType" abstract="true"> <complexContent> <extension base="xkms:RequestAbstractType"> <sequence> <element ref="xbulk:BatchInfo"/> </sequence> </extension> </complexContent> </complexType>
Processing of the inherited attributes and elements is the same as specified in XKMS.
BulkResultAbstractType
typeThe BulkResultAbstractType
type extends the XKMS abstract
result type to include generic batch information:
Schema Definition: <complexType name="BulkResultAbstractType" abstract="true"> <complexContent> <extension base="xkms:ResultAbstractType"> <sequence> <element ref="xbulk:BatchInfo"/> </sequence> </extension> </complexContent> </complexType>
Processing of the inherited attributes and elements is the same as specified in XKMS.
BatchInfo
elementThe BatchInfo
element is common to all the mesages in this document;
it contains the following information:
BatchID combined with the originating party X509Data (from the Signature) MUST be unique at a given moment in time.
Schema Definition: <complexType name="BatchInfoType"> <choice minOccurs="0" maxOccurs="unbounded"> <sequence> <element name="BatchID" type="string"/> <element name="BatchTime" type="dateTime"/> <element name="NumberOfRequests" type="positiveInteger"/> <element ref="xkms:ProcessInfo" minOccurs="0"/> </sequence> </choice> </complexType> <element name="BatchInfo" type="xbulk:BatchInfoType"/>
The following messages comprise the bulk registration process:
BulkRegisterRequest
messageThe BulkRegisterRequest
message is an XML element that consists of a
BatchInfo
, a response profile, a sequence of requests and a
Signature over the entire message.
Schema Definition: <complexType name="BulkRegisterRequestType"> <complexContent> <extension base="xbulk:BulkRequestAbstractType"> <sequence> <element ref="xbulk:BulkPrototype" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkRegisterRequest" type="xbulk:BulkRegisterRequestType"/>
MessageAbstractType
.RespondWith
element inherited from RequestAbstractType
. The full set of
allowed RespondWith
values is defined in [XKMS].
Implementations MUST support Pending.PendingRequest
element inherited from RequestAbstractType
.BulkPrototype
element.BulkPrototype
elementThe BulkPrototype
element associates a ClientInfo
element, which may contain per-registration client-side book keeping
information, with an XKMS Prototype
element.
Schema Definition: <complexType name="BulkPrototypeType"> <sequence> <element ref="xkms:Prototype"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="BulkPrototype" type="xbulk:BulkPrototypeType"/>
The following types of ds:KeyInfo
within a
xkms:Prototype
MUST be supported:
PKCS10
requestds:X509SubjectName
and key data (in which case the
key data can either be a ds:KeyValue
or a
PKCS1
public key)ds:X509SubjectName
without key data (server generated
keys)In addition, the following KeyInfo types from [XMLDSIG] SHOULD be
supported: ds:KeyName
, ds:KeyValue
,
ds:RetrievalMethod
, and ds:X509Data
.
ClientInfo
elementClientInfo
, if present, MUST be ignored and treated as opaque
data by the responder. This element must be returned in the corresponding
BulkKeyBinding
element. This can be used by the client for
bookkeeping.
Schema Definition: <complexType name="ClientInfoType"> <sequence maxOccurs="unbounded"> <any namespace="##other"/> </sequence> </complexType> <element name="ClientInfo" type="xbulk:ClientInfoType"/>
BulkRegisterResult
messageThe BulkRegisterResult
contains the batch information, and one
(and only one) BulkKeyBinding
for each and every BulkPrototype
element
in the corresponding BulkRegisterRequest
.
Schema Definition: <complexType name="BulkRegisterResultType"> <complexContent> <extension base="xbulk:BulkResultAbstractType"> <sequence> <element ref="xbulk:BulkKeyBinding" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkRegisterResult" type="xbulk:BulkRegisterResultType"/>
BulkKeyBinding
elementThe BulkKeyBinding
element associates a ClientInfo
element and optional private key with the sequence of XKMS key bindings
that may result from an individual registration request.
Schema Definition: <complexType name="BulkKeyBindingType"> <sequence> <element ref="xkms:Prototype" maxOccurs="unbounded"/> <element ref="xkms:Private" minOccurs="0"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="BulkKeyBinding" type="xbulk:BulkKeyBindingType"/>
BulkRegisterRequest
exampleAn example BulkRegisterRequest
message follows:
<xbulk:BulkRegisterRequest xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" MajorVersion="2" MinorVersion="0" Service="http://example.org/xbulk" RequestID="bulk-register-0"> <ds:Signature> ... URI="#bulk-register-0" ... </ds:Signature> <xkms:RespondWith>X509Cert</xkms:RespondWith> <xkms:RespondWith>Pending</xkms:RespondWith> <xkms:PendingNotification Mechanism="rfc822" Identifier="mailto:1234@example.org" /> <xbulk:BatchInfo> <xbulk:BatchID>batch-0</xbulk:BatchID> <xbulk:BatchTime>1999-05-31T13:20:00-05:00</xbulk:BatchTime> <xbulk:NumberOfRequests>2</xbulk:NumberOfRequests> </xbulk:BatchInfo> <xbulk:Prototype> <xkms:Prototype> <xkms:Status>Valid</xkms:Status> <ds:KeyInfo> <ds:X509Data> <ds:X509SubjectName>CN=Bar Foo</ds:X509SubjectName> </ds:X509Data> <ds:KeyValue> <ds:RSAKeyValue> <ds:Modulus>...</ds:Modulus> <ds:Exponent>AQAB</ds:Exponent> </ds:RSAKeyValue> </ds:KeyValue> </ds:KeyInfo> </xkms:Prototype> <ClientInfo> <EmployeeID xmlns="http://example.org/emp">6</EmployeeID> </ClientInfo> </xbulk:Prototype> <xbulk:Prototype> <xkms:Prototype> <xkms:Status>Valid</xkms:Status> <ds:KeyInfo> <ds:X509Data> <ds:X509SubjectName>CN=Baz Foo</ds:X509SubjectName> </ds:X509Data> <ds:KeyValue> <ds:RSAKeyValue> <ds:Modulus>...</ds:Modulus> <ds:Exponent>AQAB</ds:Exponent> </ds:RSAKeyValue> </ds:KeyValue> </ds:KeyInfo> </xkms:Prototype> <ClientInfo> <EmployeeID xmlns="http://example.org/emp">007</EmployeeID> </ClientInfo> </xbulk:Prototype> </xbulk:BulkRegisterRequest>
BulkRegisterResult
exampleA sample response to the first example request:
<xbulk:BulkRegisterResult xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" MajorVersion="2" MinorVersion="0" ResultMajor="Success" RequestID="bulk-register-0" ResponseID="bulk-register-result-0"> <ds:Signature> ... URI="#bulk-register-result-0" ... </ds:Signature> <xbulk:BatchInfo> <xbulk:BatchID>batch-0</xbulk:BatchID> <xbulk:BatchTime>1999-05-31T13:20:00-05:00</xbulk:BatchTime> <xbulk:NumberOfRequests>2</xbulk:NumberOfRequests> </xbulk:BatchInfo> <xbulk:KeyBinding> <xkms:KeyBinding> <xkms:Status>Valid</xkms:Status> <ds:KeyInfo> <ds:X509Data> <ds:X509Certificate>...</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </xkms:KeyBinding> <ClientInfo> <EmployeeID xmlns="http://example.org/emp">6</EmployeeID> </ClientInfo> </xbulk:KeyBinding> <xbulk:KeyBinding> <xkms:KeyBinding> <xkms:Status>Valid</xkms:Status> <ds:KeyInfo> <ds:X509Data> <ds:X509Certificate>...</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </xkms:KeyBinding> <ClientInfo> <EmployeeID xmlns="http://example.org/emp">007</EmployeeID> </ClientInfo> </xbulk:KeyBinding> </xbulk:BulkRegisterResult>
The following messages comprise the batch status checking process:
BulkStatusRequest
messageThe BulkStatusRequest
message is an XML element that consists of
just a BatchInfo
and optional Signature.
Schema Definition: <complexType name="BulkStatusRequestType"> <complexContent> <extension base="xbulk:BulkRequestAbstractType"> </extension> </complexContent> </complexType> <element name="BulkStatusRequest" type="xbulk:BulkStatusRequestType"/>
The BulkStatusRequest
is a request for the current status of
a batch. The batch is identified by its BatchInfo
.
Response profiling has no meaning for this message; the inherited
RespondWith
MUST NOT contain any of the codes corresponding
to returned key info types.
BulkStatusResult
messageThe BulkStatusResult
returns the processing status of a
previously-submitted batch.
Schema Definition: <complexType name="BulkStatusResultType"> <complexContent> <extension base="xbulk:BulkResultAbstractType"> <sequence> <element name="Pending" type="positiveInteger"/> <element name="Successful" type="positiveInteger"/> <element name="Failed" type="positiveInteger"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkStatusResult" type="xbulk:BulkStatusResultType"/>
The status is presented simply in the form of the following data:
One application might be to use a XML style sheet to present this information to the customer over a web page.
BulkStatusRequest
exampleAn example BulkStatusRequest
message follows:
<xbulk:BulkStatusRequest xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" MajorVersion="2" MinorVersion="0" Service="http://example.org/xbulk" RequestID="bulk-status-0"> <ds:Signature> ... URI="#bulk-status-0" ... </ds:Signature> <xbulk:BatchInfo> <xbulk:BatchID>batch-0</xbulk:BatchID> <xbulk:BatchTime>1999-05-31T13:20:00-05:00</xbulk:BatchTime> <xbulk:NumberOfRequests>2</xbulk:NumberOfRequests> </xbulk:BatchInfo> </xbulk:BulkStatusRequest>
BulkStatusResult
exampleA corresponding BulkStatusResult
message follows:
<xbulk:BulkStatusResult xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" MajorVersion="2" MinorVersion="0" Service="http://example.org/xbulk" RequestID="bulk-status-0" ResponseID="bulk-status-result-0"> <ds:Signature> ... URI="#bulk-status-result-0" ... </ds:Signature> <xbulk:BatchInfo> <xbulk:BatchID>batch-0</xbulk:BatchID> <xbulk:BatchTime>1999-05-31T13:20:00-05:00</xbulk:BatchTime> <xbulk:NumberOfResults>2</xbulk:NumberOfResults> </xbulk:BatchInfo> <xbulk:Pending>1</xbulk:Pending> <xbulk:Successful>1</xbulk:Successful> <xbulk:Failed>0</xbulk:Failed> </xbulk:BulkStatusResult>
ds:KeyInfo
The following new children of ds:KeyInfo
are defined, for
integration with legacy systems:
PKCS1
elementThe PKCS1
element contains a DER-encoded [PKCS1] public
key.
Schema Definition: <element name="PKCS1" type="binary"/>
PKCS10
elementThe PKCS10
element contains a DER-encoded [PKCS10] public
key.
Schema Definition: <element name="PKCS10" type="binary"/>
The complete schema definition is as follows:
Schema Definition: <?xml version="1.0"?> <schema targetNamespace="http://www.w3.org/2002/04/xbulk#" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms#" xmlns:xbulk="http://www.w3.org/2002/04/xbulk#" elementFormDefault="qualified" attributeFormDefault="unqualified"> <import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/> <import namespace="http://www.w3.org/2002/03/xkms#" schemaLocation="xkms-schema.xsd"/> <annotation> <documentation xml:lang="en"> XML Schema for X-BULK draft 2 16th April 2002 </documentation> </annotation> <!-- abstract types --> <complexType name="BulkRequestAbstractType" abstract="true"> <complexContent> <extension base="xkms:RequestAbstractType"> <sequence> <element ref="xbulk:BatchInfo"/> </sequence> </extension> </complexContent> </complexType> <complexType name="BulkResultAbstractType" abstract="true"> <complexContent> <extension base="xkms:ResultAbstractType"> <sequence> <element ref="xbulk:BatchInfo"/> </sequence> </extension> </complexContent> </complexType> <!-- batch information --> <complexType name="BatchInfoType"> <choice minOccurs="0" maxOccurs="unbounded"> <sequence> <element name="BatchID" type="string"/> <element name="BatchTime" type="dateTime"/> <element name="NumberOfRequests" type="positiveInteger"/> <element ref="xkms:ProcessInfo" minOccurs="0"/> </sequence> </choice> </complexType> <element name="BatchInfo" type="xbulk:BatchInfoType"/> <!-- bulk registration --> <complexType name="BulkRegisterRequestType"> <complexContent> <extension base="xbulk:BulkRequestAbstractType"> <sequence> <element ref="xbulk:BulkPrototype" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkRegisterRequest" type="xbulk:BulkRegisterRequestType"/> <complexType name="BulkRegisterResultType"> <complexContent> <extension base="xbulk:BulkResultAbstractType"> <sequence> <element ref="xbulk:BulkKeyBinding" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkRegisterResult" type="xbulk:BulkRegisterResultType"/> <complexType name="BulkPrototypeType"> <sequence> <element ref="xkms:Prototype"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="BulkPrototype" type="xbulk:BulkPrototypeType"/> <complexType name="BulkKeyBindingType"> <sequence> <element ref="xkms:Prototype" maxOccurs="unbounded"/> <element ref="xkms:Private" minOccurs="0"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="BulkKeyBinding" type="xbulk:BulkKeyBindingType"/> <complexType name="ClientInfoType"> <sequence maxOccurs="unbounded"> <any namespace="##other"/> </sequence> </complexType> <element name="ClientInfo" type="xbulk:ClientInfoType"/> <!-- batch status check --> <complexType name="BulkStatusRequestType"> <complexContent> <extension base="xbulk:BulkRequestAbstractType"> </extension> </complexContent> </complexType> <element name="BulkStatusRequest" type="xbulk:BulkStatusRequestType"/> <complexType name="BulkStatusResultType"> <complexContent> <extension base="xbulk:BulkResultAbstractType"> <sequence> <element name="Pending" type="positiveInteger"/> <element name="Successful" type="positiveInteger"/> <element name="Failed" type="positiveInteger"/> </sequence> </extension> </complexContent> </complexType> <element name="BulkStatusResult" type="xbulk:BulkStatusResultType"/> <element name="PKCS1" type="binary"/> <element name="PKCS10" type="binary"/> </schema>
The WSDL is as follows:
WSDL Definition: <!-- to follow from a more stable schema -->
The following people provided valuable feedback that improved the quality of this specification: