Copyright � 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 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 contains points which are still under discussion or are not well specified.
The Working Group will try to use a new namespace when 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 list [email protected] (pubicly archived).
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 at http://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. References to XML schema defined herein use the prefix
xbulk
and are in the namespace http://www.w3.org/2002/03/xkms-xbulk.
This specification makes use of the [XKMS] and [XMLDSIG] namespaces and schema definitions:
xmlns:xkms='http://www.w3.org/2002/03/xkms' xmlns:dsig='http://www.w3.org/2000/09/xmldsig#'
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 dsig: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 a header 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, revocation, 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 "outside" elements, then the request specifics, the status messages and finally the response elements. Finally the complete schema for X-BULK and the [WSDL] definition are presented.
Schema Definition: <?xml version="1.0" encoding="UTF-8"?> <schema targetNamespace="http://www.w3.org/2002/03/xkms-xbulk" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms" xmlns:xbulk="http://www.w3.org/2002/03/xkms-xbulk" xmlns="http://www.w3.org/2000/10/XMLSchema"> <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-20010330.xsd"/> <annotation> <documentation xml:lang="en"> XML Schema for X-BULK version 1.1 draft 5 </documentation> </annotation>
BatchHeader
element
The header is common to all the elements in this document; it will contain 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="BatchHeaderType"> <choice minOccurs="0" maxOccurs="unbounded"> <sequence> <element name="BatchID" type="string"/> <element name="BatchTime" type="dateTime"/> <element name="NumberOfRequests" type="positiveInteger"/> <element ref="xbulk:ProcessInfo" minOccurs="0"/> </sequence> </choice> </complexType> <element name="BatchHeader" type="xbulk:BatchHeaderType"/>
ProcessInfo
element
Things like customer name, that are not actually required for the batch to be
processed, MAY be included as ProcessInfo
.
Schema Definition: <complexType name="ProcessInfoType"> <sequence minOccurs="1" maxOccurs="unbounded"> <any namespace="##other"/> </sequence> </complexType> <element name="ProcessInfo" type="xbulk:ProcessInfoType"/>
BulkRegister
message
The BulkRegister
message is an XML element that consists of a
BatchHeader
, a response profile, a sequence of requests and a
Signature over the header and requests.
Schema Definition: <complexType name="BulkRegisterType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xkms:Respond" minOccurs="0"/> <element ref="xbulk:Requests"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="ds:Signature"/> </sequence> </complexType> <element name="BulkRegister" type="xbulk:BulkRegisterType"/>
xkms:Respond
element
A global xkms:Respond
element may be used to profile all requests
that do not contain a more specific setting. It can, for example, indicate that,
unless otherwise specified, the requests are for:
The full set of allowed Respond
values is defined in [XKMS].
Implementations MUST support: KeyName, KeyValue, X509Cert, X509Chain,
RetrievalMethod and Private.
Requests
element
The Requests
consists of an unbounded number of Request
elements. The number of Request
elements MUST be specified in the
number
attribute of Requests
.
Schema Definition: <complexType name="RequestsType"> <sequence> <element ref="xbulk:Request" maxOccurs="unbounded"/> </sequence> <attribute name="number" use="required"/> </complexType> <element name="Requests" type="xbulk:RequestsType"/>
Request
element
A Request
MUST contain a KeyID
, which must be unique
within the batch (this can anything; examples include a smart card serial number
, a MAC Address (cable modem), ICCID (used by S/WIM cards) or even simply 1,2,3),
and a dsig:KeyInfo
with keying information about the request.
A Request
may also contain xkms:Respond
,
ClientInfo
, and ProcessInfo
elements.
Schema Definition: <complexType name="RequestType"> <sequence> <element ref="xkms:KeyID"/> <element ref="dsig:KeyInfo"/> <element ref="xkms:Respond" minOccurs="0"/> <element ref="xbulk:ProcessInfo" minOccurs="0"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="Request" type="xbulk:RequestType"/>
dsig:KeyInfo
element
The following types of dsig:KeyInfo
within a Request
MUST be supported:
PKCS10
request
dsig:X509SubjectName
and key data (in which case the key data
can either be a dsig:KeyValue
or a PKCS1
public key)
dsig:X509SubjectName
without key data (server generated keys)
In addition, the following KeyInfo types from [XMLDSIG] SHOULD be supported:
dsig:KeyName
, dsig:KeyValue
,
dsig:RetrievalMethod
, and dsig:X509Data
.
ClientInfo
element
ClientInfo
, if present, MUST be ignored and treated as opaque data
by the responder. This element must be returned in the corresponding
RegisterResult
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"/>
An example BulkRegister
message follows:
<BulkRegister xmlns="http://www.w3.org/2002/03/xkms-xbulk"> <SignedPart Id="id-0"> <BatchHeader> <BatchID>batch-0</BatchID> <BatchTime>1999-05-31T13:20:00-05:00</BatchTime> <NumberOfRequests>2</NumberOfRequests> </BatchHeader> <xkms:Respond xmlns:xkms="http://www.w3.org/2002/03/xkms"> <string xmlns="">X509Cert</string> </xkms:Respond> <Requests number="2"> <Request> <xkms:KeyID xmlns:xkms="http://www.w3.org/2002/03/xkms"> mailto:[email protected] </xkms:KeyID> <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> <dsig:X509Data> <dsig:X509SubjectName>CN=Bar Foo</dsig:X509SubjectName> </dsig:X509Data> <dsig:KeyValue> <dsig:RSAKeyValue> <dsig:Modulus>...</dsig:Modulus> <dsig:Exponent>AQAB</dsig:Exponent> </dsig:RSAKeyValue> </dsig:KeyValue> </dsig:KeyInfo> <ClientInfo> <EmployeeID xmlns="urn:foo">6</EmployeeID> </ClientInfo> </Request> <Request> <xkms:KeyID xmlns:xkms="http://www.w3.org/2002/03/xkms"> mailto:[email protected] </xkms:KeyID> <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> <dsig:X509Data> <dsig:X509SubjectName>CN=Baz Foo</dsig:X509SubjectName> </dsig:X509Data> <dsig:KeyValue> <dsig:RSAKeyValue> <dsig:Modulus>...</dsig:Modulus> <dsig:Exponent>AQAB</dsig:Exponent> </dsig:RSAKeyValue> </dsig:KeyValue> </dsig:KeyInfo> <ClientInfo> <EmployeeID xmlns="urn:foo">007</EmployeeID> </ClientInfo> </Request> </Requests> </SignedPart> <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> ... URI="#id-0" ... </dsig:Signature> </BulkRegister>
BulkRegisterResult
element
The BulkRegisterResult
contains the header and a certificate
response for each request that was in the batch. The element contains a
BatchHeader
, RegisterResults
, and
dsig:Signature
.
Schema Definition: <complexType name="BulkRegisterResultType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xbulk:RegisterResults"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkRegisterResult" type="xbulk:BulkRegisterResultType"/>
RegisterResults
element
The RegisterResults
element contains one (and only one)
RegisterResult
for each and every Request
element in
the corresponding BulkRegister
. The number of
RegisterResult
elements MUST be an attribute to
RegisterResults
.
RegisterResult
is defined in [XKMS]; its
contents are dictated by the Respond
elements in the
BulkRegister
.
Schema Definition: <complexType name="RegisterResultsType"> <sequence> <element ref="xkms:RegisterResult" maxOccurs="unbounded"/> </sequence> <attribute name="number" use="required"/> </complexType> <element name="RegisterResults" type="xbulk:RegisterResultsType"/>
A sample response to the first example request:
<BulkRegisterResult xmlns="http://www.w3.org/2002/03/xkms-xbulk"> <SignedPart Id="id-0"> <BatchHeader> <BatchID>batch-0</BatchID> <BatchTime>1999-05-31T13:20:00-05:00</BatchTime> <NumberOfRequests>2</NumberOfRequests> </BatchHeader> <RegisterResults number="2"> <!-- xkms:RegisterResult is not the appropriate type --> <xkms:RegisterResult xmlns:xkms="http://www.w3.org/2002/03/xkms"> <xkms:Result>Success</xkms:Result> <xkms:Answer> <xkms:Status>Valid</xkms:Status> <xkms:KeyID> mailto:[email protected] </xkms:KeyID> <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> <dsig:X509Data> <dsig:X509Certificate>...</dsig:X509Certificate> </dsig:X509Data> </dsig:KeyInfo> </xkms:Answer> </xkms:RegisterResult> <xkms:RegisterResult xmlns:xkms="http://www.w3.org/2002/03/xkms"> <xkms:Result>Success</xkms:Result> <xkms:Answer> <xkms:Status>Valid</xkms:Status> <xkms:KeyID> mailto:[email protected] </xkms:KeyID> <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> <dsig:X509Data> <dsig:X509Certificate>...</dsig:X509Certificate> </dsig:X509Data> </dsig:KeyInfo> </xkms:Answer> </xkms:RegisterResult> </RegisterResults> </SignedPart> <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> ... URI="#id-0" ... </dsig:Signature> </BulkRegisterResult>
The BulkStatusRequest
is a request for the current status of a
batch. The batch is identified by its header. The element consists of a
BatchHeader
and dsig:Signature
.
The BatchID
MUST be exactly the same as in the header of the
corresponding BulkRegister
element.
Schema Definition: <complexType name="BulkStatusType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkStatus" type="xbulk:BulkStatusType"/>
An example status request:
<BulkStatus xmlns="http://www.w3.org/2002/03/xkms-xbulk"> <SignedPart Id="id-0"> <BatchHeader> <BatchID>batch-0</BatchID> <BatchTime>1999-05-31T13:20:00-05:00</BatchTime> <NumberOfRequests>2</NumberOfRequests> </BatchHeader> </SignedPart> <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> ... URI="#id-0" ... </dsig:Signature> </BulkStatus>
The BulkStatus
is a very simple element that contains the
BatchHeader
and StatusResult
of a batch. The
BatchHeader
MUST be exactly the same as the header in the
BulkRegister
element.
Schema Definition: <complexType name="BulkStatusResultType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xbulk:StatusResult"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkStatusResult" type="xbulk:BulkStatusResultType"/>
StatusResult
element
The StatusResult
element contains the following:
One application might be to use a XML style sheet to present this information to the customer over a web page.
Schema Definition: <complexType name="StatusResultType"> <sequence> <element name="Pending" type="positiveInteger"/> <element name="Successful" type="positiveInteger"/> <element name="Failed" type="positiveInteger"/> </sequence> </complexType> <element name="StatusResult" type="xbulk:StatusResultType"/>
A sample response to the example status request:
<BulkStatusResult xmlns="http://www.w3.org/2002/03/xkms-xbulk"> <SignedPart Id="id-0"> <BatchHeader> <BatchID>batch-0</BatchID> <BatchTime>1999-05-31T13:20:00-05:00</BatchTime> <NumberOfRequests>2</NumberOfRequests> </BatchHeader> <StatusResult> <Pending>0</BatchID> <Successful>2</BatchTime> <Failed>0</NumberOfRequests> </StatusResult> </SignedPart> <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> ... URI="#id-0" ... </dsig:Signature> </BulkStatusResult>
dsig:KeyInfo
The following new children of dsig:KeyInfo
are defined, for
integration with legacy systems:
PKCS1
element
The PKCS1
element contains a DER-encoded [PKCS1] public key.
Schema Definition: <element name="PKCS1" type="binary"/>
PKCS10
element
The 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" encoding="UTF-8"?> <schema targetNamespace="http://www.w3.org/2002/03/xkms-xbulk" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.w3.org/2002/03/xkms" xmlns:xbulk="http://www.w3.org/2002/03/xkms-xbulk" xmlns="http://www.w3.org/2000/10/XMLSchema"> <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-20010330.xsd"/> <annotation> <documentation xml:lang="en"> XML Schema for X-BULK version 1.1 draft 5 </documentation> </annotation> <!-- General Stuff --> <complexType name="BatchHeaderType"> <choice minOccurs="0" maxOccurs="unbounded"> <sequence> <element name="BatchID" type="string"/> <element name="BatchTime" type="dateTime"/> <element name="NumberOfRequests" type="positiveInteger"/> <element ref="xbulk:ProcessInfo" minOccurs="0"/> </sequence> </choice> </complexType> <element name="BatchHeader" type="xbulk:BatchHeaderType"/> <complexType name="ProcessInfoType"> <sequence minOccurs="1" maxOccurs="unbounded"> <any namespace="##other"/> </sequence> </complexType> <element name="ProcessInfo" type="xbulk:ProcessInfoType"/> <!-- copied from XKMS, since not typed there --> <element name="KeyID" type="uriReference"/> <element name="Respond"> <complexType> <sequence> <element name="string" type="string" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element> <!-- Register Stuff --> <complexType name="BulkRegisterType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xkms:Respond" minOccurs="0"/> <element ref="xbulk:Requests"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkRegister" type="xbulk:BulkRegisterType"/> <complexType name="RequestsType"> <sequence> <element ref="xbulk:Request" maxOccurs="unbounded"/> </sequence> <attribute name="number" use="required"/> </complexType> <element name="Requests" type="xbulk:RequestsType"/> <complexType name="RequestType"> <sequence> <element ref="xkms:KeyID"/> <element ref="dsig:KeyInfo"/> <element ref="xkms:Respond" minOccurs="0"/> <element ref="xbulk:ProcessInfo" minOccurs="0"/> <element ref="xbulk:ClientInfo" minOccurs="0"/> </sequence> </complexType> <element name="Request" type="xbulk:RequestType"/> <complexType name="ClientInfoType"> <sequence maxOccurs="unbounded"> <any namespace="##other"/> </sequence> </complexType> <element name="ClientInfo" type="xbulk:ClientInfoType"/> <!-- Result Specific Stuff --> <complexType name="BulkRegisterResultType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xbulk:RegisterResults"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkRegisterResult" type="xbulk:BulkRegisterResultType"/> <complexType name="RegisterResultsType"> <sequence> <element ref="xkms:RegisterResult" maxOccurs="unbounded"/> </sequence> <attribute name="number" use="required"/> </complexType> <element name="RegisterResults" type="xbulk:RegisterResultsType"/> <!-- Status Specific Stuff --> <complexType name="BulkStatusType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkStatus" type="xbulk:BulkStatusType"/> <complexType name="BulkStatusResultType"> <sequence> <element name="SignedPart"> <complexType> <sequence> <element ref="xbulk:BatchHeader"/> <element ref="xbulk:StatusResult"/> </sequence> <attribute name="Id" type="ID" use="required"/> </complexType> </element> <element ref="dsig:Signature"/> </sequence> </complexType> <element name="BulkStatusResult" type="xbulk:BulkStatusResultType"/> <complexType name="StatusResultType"> <sequence> <element name="Pending" type="positiveInteger"/> <element name="Successful" type="positiveInteger"/> <element name="Failed" type="positiveInteger"/> </sequence> </complexType> <element name="StatusResult" type="xbulk:StatusResultType"/> <!-- new types of dsig:KeyInfo --> <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: