- From: Blair Dillaway <blaird@exchange.microsoft.com>
- Date: Wed, 13 Nov 2002 08:42:59 -0800
- To: <www-xkms@w3.org>
- Message-ID: <0A0B36F65A314D4AB8D2CF1D1FD835F1AB0B3D@df-muttley.dogfood>
Below is suggested text for the specifications to address the SOAP
binding requirement.
Part 1: Schema
1. Replace the 2nd paragaph of Section 2 with the following text:
"XKMS protocol messages share a common format that may be
carried within a variety of protocols. A binding to the SOAP message
protocol is provided in Part II: Protocol Bindings. Implementaters MAY
implement bindings to other protocols at their option."
2. Remove "Section 2.3 SOAP Transport".
Part II: Protocol Bindings
1. Insert the below text under "Section 3. SOAP Binding"
This section describes a mechanism for communicating the XKMS messages
defined in Part 1 of this specification using the SOAP message protocol.
XKMS implementers should support the SOAP message protocol for
interoperability. When doing do, they MUST use the binding described
herein. Bindings for both SOAP 1.2 [SOAP1.2-1][SOAP1.2-2] and SOAP
1.1[SOAP] protocols are specified. Use of SOAP 1.2 is recommended
though implementers may prefer SOAP 1.1 in the near term for
compatibility with existing tools and supporting infrastructure.
3.1 XKMS SOAP Message Binding
3.1.1 SOAP 1.2 Binding
XKMS implementers shall use SOAP document style request-response
messaging with the XKMS messages defined in Part 1 carried as unencoded
Body element content. The SOAP 1.2 RPC representation, and requisite
encoding style, are not used. The potential benefits of using the RPC
representation do not justify the additional effort required to define a
mapping from the Part 1 messages to an appropriate encoding style.
The XKMS binding shall use the SOAP Request-Response Message Exchange
Pattern defined in [SOAP1.2-2] and message processing shall conform to
that model. SOAP 1.2 messages carrying XKMS content shall use the UTF-8
character encoding to insure interoperability.
SOAP 1.2 messages carrying XKMS content shall conform to the following
structure:
XKMS Request Message
<?xml version='1.0' encoding="utf-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Header>
<env:Body>
XKMS Request Message element
</env:Body>
</env:Envelope>
XKMS Response Message
<?xml version='1.0' encoding="utf-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Header>
<env:Body>
XKMS Response Message element
</env:Body>
</env:Envelope>
The XKMS SOAP message binding does not require use of SOAP Headers.
Headers may be used with SOAP messages carrying XKMS content to provide
additional services such as communications security or routing. The use
of such Headers is beyond the scope of this specification. If used
however, they must not alter the message encoding style or SOAP
processing model specified herein.
Sample XKMS LocateRequest and LocateResponse message communicated using
SOAP 1.2 message transport are shown below:
LocateRequest Message
<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Body>
<LocateRequest xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
Id="I94d1048aa24259465d7271cb4433dbb4"
Service=http://test.xmltrustcenter.org/XKMS
<http://test.xmltrustcenter.org/XKMS>
xmlns="http://www.w3.org/2002/03/xkms#">
<RespondWith>KeyName</RespondWith>
<RespondWith>KeyValue</RespondWith>
<RespondWith>X509Cert</RespondWith>
<RespondWith>X509Chain</RespondWith>
<RespondWith>PGPWeb</RespondWith>
<RespondWith>PGP</RespondWith>
<RespondWith>Multiple</RespondWith>
<QueryKeyBinding>
<KeyUsage>Encryption</KeyUsage>
<UseKeyWith Application="urn:ietf:rfc:2440"
Identifier="bob@bobcorp.test" />
<UseKeyWith Application="urn:ietf:rfc:2633"
Identifier="bob@bobcorp.test" />
</QueryKeyBinding>
</LocateRequest>
</env:Body>
</env:Envelope>
LocateResponse Message
<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Body>
<LocateResult xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
Id="I075365c6e4d9feec5abf1d8a4504e4e8"
Service=http://test.xmltrustcenter.org/XKMS
<http://test.xmltrustcenter.org/XKMS>
ResultMajor="Success"
RequestId="#I94d1048aa24259465d7271cb4433dbb4"
xmlns="http://www.w3.org/2002/03/xkms#">
<KeyBinding Id="I9b2502783d8587288b55263b1332c83d">
<KeyInfo>
<ds:KeyValue>
<ds:RSAKeyValue>
<ds:Modulus>4i0BEhQ8Jc4tjwZYbvtMyYfBrIGOMx34K4Cdo2pAzoGnV679FLmGHWnQy2cS
j39hf5D1mIa
PyD3j/33TdfglTaaKqp7IPf6ei754fOuI/r1HpX7uqsw+j9LC4Z7GnG3yoY/eBJOZ8TRwMnx
+MkwmopXPVLvhMWRyiUOcO3SE
kTE=</ds:Modulus>
<ds:Exponent>AQAB</ds:Exponent>
</ds:RSAKeyValue>
</ds:KeyValue>
<ds:X509Data>
<ds:X509Certificate>MIIB+zCCAWigAwIBAgIQhzf6GHdFobRCYrjlFTCekjAJBgUrDgMC
HQUAMBIxEDAO
BgNVBAMTB1Rlc3QgQ0EwHhcNMDIwNjEzMjEzMzQyWhcNMzkxMjMxMjM1OTU5WjAlMSMwIQYD
VQQGExpVUyBPPUJvYiBDb3JwI
ENOPUJvYiBCYWtlcjCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAtw2qGqYbO0aKeZFb0
Z3verx3Cp+KS94LiHG09D1Ddg
Td48FZaB5eXa4U3mLax2/Fsg/cxGZkXJur0YylS8QvRuX+9STQgiFTO277sHFfRMvtFsuQ56
ovrQWH/KoGQZssMUIqO2aN2cb
MQJST3a2HZuxqPQ1rwXxHrEoAXHZv3ysCAwEAAaNHMEUwQwYDVR0BBDwwOoAQRWvWDxzHMSR
0xfgYCUPpNqEUMBIxEDAOBgNV
BAMTB1Rlc3QgQ0GCEHKxUcSI0WKITaXFa+Ylh5IwCQYFKw4DAh0FAAOBgQCieDKjvNCo7MPs
gUwHydkid4KnulcuBbZet87lc
IA7ReH1qEK4s0p49po2UM69eWG7hfv8LW2Ga8HiEexTwLDFBvH2g7f09xI/vYgPw4qhJfWoZ
uY/HWHUzZIRSoggipndVfdvUk
msFSx1rR4FMu0mYBjq79OkYsmwISQlaXejUg==</ds:X509Certificate>
<ds:X509Certificate>MIIB9zCCAWSgAwIBAgIQcrFRxIjRYohNpcVr5iWHkjAJBgUrDgMC
HQUAMBIxEDA
OBgNVBAMTB1Rlc3QgQ0EwHhcNMDIwNjEzMjEzMzQxWhcNMzkxMjMxMjM1OTU5WjASMRAwDgY
DVQQDEwdUZXN0IENBMIGfMA0
GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDPF33VmCmSSFufPnu0JdFaKsPHsx0ee+OYedhMxVh
3LXMkMNC++JWDva7H+E9o+uj
7dt5cwxHSePsyxPx3Vq+AbEZOsYxGxXgf4OuGb8ONBv3B5c8hraOg24c5hjFS6tfNzoiatLV
KHeOmPnifhkBI8h8LD7dLHsH
fKUrVNwIJNQIDAQABo1YwVDANBgNVHQoEBjAEAwIHgDBDBgNVHQEEPDA6gBBFa9YPHMcxJHT
F+BgJQ+k2oRQwEjEQMA4GA1U
EAxMHVGVzdCBDQYIQcrFRxIjRYohNpcVr5iWHkjAJBgUrDgMCHQUAA4GBAAynWUPRSbabAEu
X0Z8kKN/C2GoEuULW73QxX6Q
0PHAatRM6G9ZnzU+ce3lELgOj0Usw/xC9Y+2FMgj68rIas+DId5JMMj+SIZEUV1vPPTEiEQ1
6Gxz9piUQoFljhI22hEl8ki0
hIJlFGnki+K9dhv/7trMrfKSSHAPIDQZuz01P</ds:X509Certificate>
</ds:X509Data>
</KeyInfo>
<KeyUsage>Signature</KeyUsage>
<KeyUsage>Encryption</KeyUsage>
<KeyUsage>Exchange</KeyUsage>
<UseKeyWith Application="urn:ietf:rfc:2633"
Identifier="bob@bobcorp.test" />
<Status StatusValue="Valid">
<Reason>Signature</Reason>
<Reason>ValidityInterval</Reason>
</Status>
</KeyBinding>
</LocateResult>
</env:Body>
</env:Envelope>
The structure of conformant SOAP 1.2 messages carrying other XKMS
message types should be evident based on this example.
3.1.2 SOAP 1.1 Binding
XKMS implementers using SOAP 1.1 messaging shall use request-response
messaging and carry the XKMS messages as unencoded content within the
SOAP Body element. The SOAP 1.1 Section 5 encoding model shall not be
used. SOAP 1.1 messages carrying XKMS content shall use the UTF-8
character encoding to insure interoperability.
The structure of XKMS SOAP 1.1 messages shall conform to:
XKMS Request Message
<?xml version='1.0' encoding="utf-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope">
<env:Header>
<env:Body>
XKMS Request Message element
</env:Body>
</env:Envelope>
XKMS Response Message
<?xml version='1.0' encoding="utf-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope">
<env:Header>
<env:Body>
XKMS Response Message element
</env:Body>
</env:Envelope>
As with the SOAP 1.2 binding, the SOAP 1.1 binding does not require use
of SOAP Headers. Headers may be used with SOAP messages carrying XKMS
content to provide additional services such as communications security
or routing providing they don't impact the encoding style or SOAP
processing model specified herein.
SOAP 1.1 messages carrying XKMS content will are identical to those
using SOAP 1.2 except for the namespace of the Envelope and Body
elements. Hence, the examples shown in Section 3.1.1 are conformant
once the SOAP 1.2 namespace is replaced by the SOAP 1.1 namespace
(http://schemas.xmlsoap.org/soap/envelope)..
3.3 Namespace inclusions
In using the XKMS SOAP binding, XKMS messages are constructed as defined
in Part 1 of this specification including all required namespace
declarations. The top-level message element is then inserted as a child
of the SOAP Body element. Promotion of XKMS namespace declarations to
the parent SOAP Body (or grandparent Envelope) element is not required,
but may be done at the discretion of the implementer.
Insertion of an XKMS message into the SOAP message structure must not
alter namespace prefixes, or use of default namespaces, within the XKMS
message. Any change in these encodings will likely break XML Signature
internal to the XKMS messages. The implementer must insure that prefix
values used with the SOAP namespaces
"http://www.w3.org/2002/06/soap-envelope
<http://www.w3.org/2002/06/soap-envelope> " (SOAP 1.2) and "ht
<http://schemas.xmlsoap.org/soap/envelope>
tp://schemas.xmlsoap.org/soap/envelope" (SOAP 1.1) do not conflict with
prefixes used in the XKMS message.
3.4 Computation of XML Signature Elements in XKMS Messages
Use of the XKMS SOAP binding does not affect processing of the XML
Signature-based elements (KeyBindingAuthentication and
ProofOfPossession) defined in Part 1. These are computed as described
in Part 1, Section 6.0.2 and 6.0.3 respectively, and assume the XKMS
message has been removed from the SOAP message 'wrapper' at the time
processing occurs. That is, the SOAP defined nodes and namespaces do
not contribute to the Signature computation.
3.5 Use of SOAP Faults
SOAP Faults shall be used by an XKMS service to communicate errors that
prevent the processing of a received XKMS request message. XKMS clients
should never send a SOAP Fault message to an XKMS service.
3.5.1 SOAP 1.2 Faults
The following SOAP Fault messages are defined for use with the XKMS SOAP
1.2 binding. Consistent with the SOAP 1.2 specification, these Fault
messages shall contain the mandatory Code and Reason element information
items. Inclusion of other elements is at the discretion of the
implementer.
In response to an XKMS request message, the receiver shall respond with
one of the following SOAP Faults if it is unable to process the message.
If it is able to process the message, then the response should conform
to a valid XKMS response message as described in Part 1.
1. A fault with a Value of "env:VersionMismatch" for Code shall be
returned when the XKMS service finds an invalid element information item
instead of the expected Envelope element information item, or the
namespace, local name or both did not match the required Envelope
element information item. The Reason element shall be "Unsupported SOAP
version".
2. A fault with a Value of "env:MustUnderstand" for Code shall be
returned if there is an immediate child element information item of the
SOAP Header element information item that was either not understood or
not obeyed by the faulting node when the Header contained a SOAP
mustUnderstand attribute information item with a value of "true". The
value for Reason shall be "Unable to process [header element name]"
where the expression in brackets is replaced by the header element
information item which caused the initial fault.
3. A fault with a Value of "env:Receiver" for Code shall be
generated when the receiver cannot handle the message because of some
temporary condition, e.g. when it is out of memory. The Reason shall be
"Service temporarily unable".
4. A fault with a Value of "env:Sender" for Code and a Value of
"xkms:MessageNotSupported" for Subcode shall be generated when the
receiver does not support the type of request message. The Reason shall
be "[XKMS message type] not supported" where the expression in brackets
is replace by the element information item name corresponding to the
received XKMS request message.
5. A fault with a Value of "env:Sender" for Code and a Value of
"xkms:BadMessage" for Subcode shall be generated when the receiver
cannot parse the received XKMS message. The Reason shall be "[XKMS
message type] invalid" where the expression in brackets is replaced by
the element information item name corresponding to the received XKMS
request message.
A sample SOAP 1.2 fault message that would be returned when the received
XKMS request message isn't supported by the service is shown below:
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
<env:Subcode>
<env:Value>xkms:MessageNotSupported</env:Value>
</env:Subcode>
</env:Code>
<env:Reason>LocateRequest message not supported</env:Reason>
</env:Fault>
</env:Body>
</env:Envelope>
3.5.2 SOAP 1.1 Faults
The following SOAP Fault messages are defined for use with the XKMS SOAP
1.1 binding. Consistent with the SOAP 1.1 specification, these Fault
messages shall contain the faultcode and faultstring elements. Inclusion
of other elements is at the discretion of the implementer.
In response to an XKMS request message, the receiver shall respond with
one of the following SOAP Faults if it is unable to process the message.
If it is able to process the message, then the response should conform
to a valid XKMS response message as described in [XKMS1].
1. A fault with a faultcode of "env:VersionMismatch" shall be
returned when the XKMS service doesn't find the expected Envelope
element or the namespace, local name or both did not match the required
Envelope element. The faultstring element shall contain "Unsupported
SOAP version".
2. A fault with a faultcode of "env:MustUnderstand" shall be
returned if there is an immediate child element of the SOAP Header
element that was either not understood or not obeyed by the faulting
node when the header contained a SOAP mustUnderstand attribute item with
a value of "true". The faultstring shall be "Unable to process [header
element name]" where the expression in brackets is replaced by the first
header element information item which caused the fault.
3. A fault with a faultcode of "env:Server" shall be returned when
the service cannot handle the message because of some temporary
condition, e.g. when it is out of memory. The faultstring shall be
"Service temporarily unable".
4. A fault with a faultcode of "env:Client" shall be returned when
the receiver does not support the type of request message. The value
for faultstring shall be "[XKMS message type] not supported" where the
expression in brackets is replace by the element information item name
corresponding to the received XKMS request message.
5. A fault with a faultcode of "env:Client" shall be returned when
the receiver cannot parse the received XKMS message. The faultstring
shall be "[XKMS message type] invalid" where the expression in brackets
is replace by the element information item name corresponding to the
received XKMS request message.
A sample SOAP 1.1 fault message that would be returned when the received
XKMS request message isn't supported by the service is shown below:
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
<env:Body>
<env:Fault>
<env:faultcode>env:Client</env:faultcode>
<env:faultstring>LocateRequest message not
supported</env:faultstring>
</env:Fault>
</env:Body>
</env:Envelope>
3.6 SOAP over HTTP binding
It is recommended XKMS implementers support SOAP over HTTP for
interoperability purposes.
When the XKMS binding to SOAP 1.2 is implemented, the SOAP messages
should be sent using HTTP POST consistent with the recommendations of
Section 6.4.2 in [SOAP1.2-2]. Processing shall be consistent with
Section 7, SOAP HTTP Binding in that specification.
When the XKMS binding to SOAP 1.1 is implemented, the SOAP messages
should be sent using HTTP POST consistent with the of Section 6.1 in
[SOAP].
2. Add the following items to Appendix A References
[SOAP1.2-1] W3C Working Draft "SOAP Version 1.2 Part 1: Messaging
Framework", Marting Gudgin, et al, 26 June 2002 (Last call Working
Draft)
[SOAP1.2-2] W3C Working Draft "SOAP Version 1.2 Part 2: Adjuncts",
Martin Gudgin, et al, 26 June 2002 (Last call Working Draft)
Received on Wednesday, 13 November 2002 11:43:02 UTC