Copyright © 2001 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 the W3C 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 the list. However, it does contain points which are still under discussion or 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 www-xkms@w3.org (archives).
Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page in 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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd.
This specification uses the elements already defined in the XKMS and XML
Signature namespaces. The XKMS namespace is represented by the prefix
xkms
and is declared as http://www.xmltrustcenter.org/xml/schema/2000-11-12-XKMS.sdl.
The XML Signature namespace is represented by the prefix dsig
and is declared as http://www.w3.org/2000/09/xmldsig#.
The XML Signature schema is defined in [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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.xkms.org/schema/xkms-2001-01-20" xmlns:xbulk="http://www.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd" 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.xkms.org/schema/xkms-2001-01-20" schemaLocation="xkms-20010330.xsd"/> <annotation> <documentation xml:lang="en"> XML Schema for X-BULK version 1.1 draft 5 </documentation> </annotation>
BatchHeader
elementThe 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
elementThings 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
messageThe 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
elementA 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
elementThe 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
elementA 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
elementThe following types of dsig:KeyInfo
within a
Request
MUST be supported:
PKCS10
requestdsig: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
elementClientInfo
, 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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd"> <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.xkms.org/schema/xkms-2001-01-20"> <string xmlns="">X509Cert</string> </xkms:Respond> <Requests number="2"> <Request> <xkms:KeyID xmlns:xkms="http://www.xkms.org/schema/xkms-2001-01-20"> mailto:bar@foo.com </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.xkms.org/schema/xkms-2001-01-20"> mailto:baz@foo.com </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
elementThe 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
elementThe 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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd"> <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.xkms.org/schema/xkms-2001-01-20"> <xkms:Result>Success</xkms:Result> <xkms:Answer> <xkms:Status>Valid</xkms:Status> <xkms:KeyID> mailto:bar@foo.com </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.xkms.org/schema/xkms-2001-01-20"> <xkms:Result>Success</xkms:Result> <xkms:Answer> <xkms:Status>Valid</xkms:Status> <xkms:KeyID> mailto:baz@foo.com </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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd"> <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
elementThe 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.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd"> <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
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" encoding="UTF-8"?> <schema targetNamespace="http://www.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:xkms="http://www.xkms.org/schema/xkms-2001-01-20" xmlns:xbulk="http://www.xmltrustcenter.org/xkms/docs/x-bulk-2001-07-04.xsd" 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.xkms.org/schema/xkms-2001-01-20" 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: