Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)

abdomendebonairSecurity

Nov 2, 2013 (3 years and 11 months ago)

124 views

WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 1 of 56

1
Web Services Security:
2
SOAP Message Security 1.0
3
(WS-Security 2004)
4
OASIS Standard 200401, March 2004
5
Document identifier: 6
{WSS: SOAP Message Security }-{1.0} (Word) (PDF) 7
Document Location: 8
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0 9
Errata Location: 10
http://www.oasis-open.org/committees/wss 11
Editors: 12
Anthony Nadalin IBM
Chris Kaler Microsoft
Phillip Hallam-Baker VeriSign
Ronald Monzillo Sun
Contributors: 13
Gene

Thurston

AmberPoint

Frank

Siebenlist

Argonne National Lab

Merlin

Hughes

Baltimore Technologies

Irving

Reid

Baltimore Technologies

Peter

Dapkus

BEA

Hal

Lockhart

BEA

Symon

Chang

CommerceOne

Srinivas
Davanum
Computer Associates
Thomas

DeMartini

ContentGuard

Guillermo

Lao

ContentGuard

TJ

Pannu

ContentGuard

Shawn

Sharp

Cyclone Commerce

Ganesh

Vaideeswaran

Documentum

Sam

Wei

Documentum

John

Hughes

Entegrity

Tim

Moses

Entrust

Toshihiro

Nishimura

Fujitsu

Tom

Rutt

Fujitsu

Yutaka

Kudo

Hitachi

Jason

Rouault

HP

Paula Austel IBM
Bob

Blakley

IBM


WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 2 of 56

Joel Farrell IBM
Satoshi Hada IBM
Maryann

Hondo

IBM

Michael McIntosh IBM
Hiroshi Maruyama IBM
David Melgar IBM
Anthony

Nadalin

IBM

Nataraj

Nagaratnam

IBM

Wayne Vicknair IBM
Kelvin

Lawrence

IBM (co-Chair)

Don

Flinn

Individual

Bob

Morgan

Individual

Bob Atkinson Microsoft


Keith Ballinger Microsoft
Allen Brown Microsoft


Paul

Cotton

Microsoft

Giovanni Della-Libera Microsoft
Vijay

Gajjala

Microsoft

Johannes Klein Microsoft
Scott Konersmann Microsoft
Chris

Kurt

Microsoft

Brian LaMacchia Microsoft


Paul Leach Microsoft


John Manferdelli Microsoft
John

Shewchuk

Microsoft

Dan Simon Microsoft


Hervey Wilson Microsoft
Chris

Kaler

Microsoft (co-Chair)

Prateek

Mishra

Netegrity

Frederick

Hirsch

Nokia

Senthil

Sengodan

Nokia

Lloyd

Burch

Novell

Ed

Reed

Novell

Charles

Knouse

Oblix

Steve

Anderson

OpenNetwork (Sec)

Vipin

Samar

Oracle

Jerry

Schwarz

Oracle

Eric

Gravengaard

Reactivity

Stuart

King

Reed Elsevier

Andrew

Nash

RSA Security

Rob

Philpott

RSA Security

Peter

Rostin

RSA Security

Martijn

de Boer

SAP

Blake Dournaee Sarvega
Pete

Wenzel

SeeBeyond

Jonathan

Tourzan

Sony

Yassir

Elley

Sun Microsystems

Jeff

Hodges

Sun Microsystems

Ronald

Monzillo

Sun Microsystems

Jan

Alexander

Systinet

Michael

Nguyen

The IDA of Singapore

Don

Adams

TIBCO

WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 3 of 56

John

Weiland

US Navy

Phillip

Hallam-Baker

VeriSign

Mark Hays Verisign
Hemma Prafullchandra VeriSign
14

Abstract: 15
This specification describes enhancements to SOAP messaging to provide message 16
integrity and confidentiality. The specified mechanisms can be used to accommodate a 17
wide variety of security models and encryption technologies. 18
This specification also provides a general-purpose mechanism for associating security 19
tokens with message content. No specific type of security token is required, the 20
specification is designed to be extensible (i.e.. support multiple security token formats). 21
For example, a client might provide one format for proof of identity and provide another 22
format for proof that they have a particular business certification. 23
Additionally, this specification describes how to encode binary security tokens, a 24
framework for XML-based tokens, and how to include opaque encrypted keys. It also 25
includes extensibility mechanisms that can be used to further describe the characteristics 26
of the tokens that are included with a message. 27
Status: 28
This is a technical committee document submitted for consideration by the OASIS Web 29
Services Security (WSS) technical committee. Please send comments to the editors. If 30
you are on the wss@lists.oasis-open.org list for committee members, send comments 31
there. If you are not on that list, subscribe to the wss-comment@lists.oasis-open.org list 32
and send comments there. To subscribe, send an email message to wss-comment-33
request@lists.oasis-open.org with the word "subscribe" as the body of the message. For 34
patent disclosure information that may be essential to the implementation of this 35
specification, and any offers of licensing terms, refer to the Intellectual Property Rights 36
section of the OASIS Web Services Security Technical Committee (WSS TC) web page 37
at http://www.oasis-open.org/committees/wss/ipr.php. General OASIS IPR information 38
can be found at http://www.oasis-open.org/who/intellectualproperty.shtml. 39
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 4 of 56

Table of Contents
40
1

Introduction.............................................................................................................................6

41
1.1 Goals and Requirements......................................................................................................6

42
1.1.1 Requirements.................................................................................................................6

43
1.1.2 Non-Goals......................................................................................................................6

44
2

Notations and Terminology.....................................................................................................8

45
2.1 Notational Conventions.........................................................................................................8

46
2.2 Namespaces.........................................................................................................................8

47
2.3 Acronyms and Abbreviations................................................................................................9

48
2.4 Terminology...........................................................................................................................9

49
3

Message Protection Mechanisms.........................................................................................11

50
3.1 Message Security Model.....................................................................................................11

51
3.2 Message Protection.............................................................................................................11

52
3.3 Invalid or Missing Claims....................................................................................................11

53
3.4 Example..............................................................................................................................12

54
4

ID References.......................................................................................................................14

55
4.1 Id Attribute...........................................................................................................................14

56
4.2 Id Schema...........................................................................................................................14

57
5

Security Header....................................................................................................................16

58
6

Security Tokens....................................................................................................................18

59
6.1 Attaching Security Tokens..................................................................................................18

60
6.1.1 Processing Rules.........................................................................................................18

61
6.1.2 Subject Confirmation....................................................................................................18

62
6.2 User Name Token...............................................................................................................18

63
6.2.1 Usernames...................................................................................................................18

64
6.3 Binary Security Tokens.......................................................................................................19

65
6.3.1 Attaching Security Tokens...........................................................................................19

66
6.3.2 Encoding Binary Security Tokens................................................................................19

67
6.4 XML Tokens........................................................................................................................20

68
6.4.1 Identifying and Referencing Security Tokens..............................................................20

69
7

Token References.................................................................................................................21

70
7.1 SecurityTokenReference Element......................................................................................21

71
7.2 Direct References................................................................................................................22

72
7.3 Key Identifiers......................................................................................................................23

73
7.4 Embedded References.......................................................................................................23

74
7.5 ds:KeyInfo...........................................................................................................................24

75
7.6 Key Names..........................................................................................................................24

76
8

Signatures.............................................................................................................................26

77
8.1 Algorithms...........................................................................................................................26

78
8.2 Signing Messages...............................................................................................................28

79
8.3 Signing Tokens....................................................................................................................29

80
8.4 Signature Validation............................................................................................................30

81
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 5 of 56

8.5 Example..............................................................................................................................31

82
9

Encryption.............................................................................................................................32

83
9.1 xenc:ReferenceList.............................................................................................................32

84
9.2 xenc:EncryptedKey.............................................................................................................33

85
9.3 Processing Rules................................................................................................................33

86
9.3.1 Encryption....................................................................................................................34

87
9.3.2 Decryption....................................................................................................................34

88
9.4 Decryption Transformation..................................................................................................35

89
10

Security Timestamps............................................................................................................36

90
11

Extended Example................................................................................................................38

91
12

Error Handling.......................................................................................................................41

92
13

Security Considerations........................................................................................................42

93
13.1 General Considerations....................................................................................................42

94
13.2 Additional Considerations.................................................................................................42

95
13.2.1 Replay........................................................................................................................42

96
13.2.2 Combining Security Mechanisms..............................................................................43

97
13.2.3 Challenges.................................................................................................................43

98
13.2.4 Protecting Security Tokens and Keys........................................................................43

99
13.2.5 Protecting Timestamps and Ids.................................................................................44

100
14

Interoperability Notes............................................................................................................45

101
15

Privacy Considerations.........................................................................................................46

102
16

References............................................................................................................................47

103
Appendix A: Utility Elements and Attributes..................................................................................49

104
A.1. Identification Attribute........................................................................................................49

105
A.2. Timestamp Elements.........................................................................................................49

106
A.3. General Schema Types.....................................................................................................50

107
Appendix B: SecurityTokenReference Model................................................................................51

108
Appendix C: Revision History........................................................................................................55

109
Appendix D: Notices......................................................................................................................56

110
111
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 6 of 56

1 Introduction
112
This OASIS specification is the result of significant new work by the WSS Technical Committee 113
and supersedes the input submissions, Web Service Security (WS-Security) Version 1.0 April 5, 114
2002 and Web Services Security Addendum Version 1.0 August 18, 2002. 115
This specification proposes a standard set of SOAP [SOAP11, SOAP12] extensions that can be 116
used when building secure Web services to implement message content integrity and 117
confidentiality. This specification refers to this set of extensions and modules as the “Web 118
Services Security: SOAP Message Security” or “WSS: SOAP Message Security”. 119
This specification is flexible and is designed to be used as the basis for securing Web services 120
within a wide variety of security models including PKI, Kerberos, and SSL. Specifically, this 121
specification provides support for multiple security token formats, multiple trust domains, multiple 122
signature formats, and multiple encryption technologies. The token formats and semantics for 123
using these are defined in the associated profile documents. 124
This specification provides three main mechanisms: ability to send security tokens as part of a 125
message, message integrity, and message confidentiality. These mechanisms by themselves do 126
not provide a complete security solution for Web services. Instead, this specification is a building 127
block that can be used in conjunction with other Web service extensions and higher-level 128
application-specific protocols to accommodate a wide variety of security models and security 129
technologies. 130
These mechanisms can be used independently (e.g., to pass a security token) or in a tightly 131
coupled manner (e.g., signing and encrypting a message or part of a message and providing a 132
security token or token path associated with the keys used for signing and encryption). 133
1.1 Goals and Requirements
134
The goal of this specification is to enable applications to conduct secure SOAP message 135
exchanges. 136
This specification is intended to provide a flexible set of mechanisms that can be used to 137
construct a range of security protocols; in other words this specification intentionally does not 138
describe explicit fixed security protocols. 139
As with every security protocol, significant efforts must be applied to ensure that security 140
protocols constructed using this specification are not vulnerable to any one of a wide range of 141
attacks. The examples in this specification are meant to illustrate the syntax of these mechanisms 142
and are not intended as examples of combining these mechanisms in secure ways. 143
The focus of this specification is to describe a single-message security language that provides for 144
message security that may assume an established session, security context and/or policy 145
agreement. 146
The requirements to support secure message exchange are listed below. 147
1.1.1 Requirements
148
The Web services security language must support a wide variety of security models. The 149
following list identifies the key driving requirements for this specification: 150
• Multiple security token formats 151
• Multiple trust domains 152
• Multiple signature formats 153
• Multiple encryption technologies 154
• End-to-end message content security and not just transport-level security 155
1.1.2 Non-Goals
156
The following topics are outside the scope of this document: 157
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 7 of 56

• Establishing a security context or authentication mechanisms. 158
• Key derivation. 159
• Advertisement and exchange of security policy. 160
• How trust is established or determined. 161
• Non-repudiation. 162
163
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 8 of 56

2 Notations and Terminology
164
This section specifies the notations, namespaces, and terminology used in this specification. 165
2.1 Notational Conventions
166
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 167
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 168
interpreted as described in RFC 2119. 169
When describing abstract data models, this specification uses the notational convention used by 170
the XML Infoset. Specifically, abstract property names always appear in square brackets (e.g., 171
[some property]). 172
When describing concrete XML schemas, this specification uses a convention where each 173
member of an element’s [children] or [attributes] property is described using an XPath-like 174
notation (e.g., /x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates the presence 175
of an element wildcard (<xs:any/>). The use of @{any} indicates the presence of an attribute 176
wildcard (<xs:anyAttribute/>). 177
Readers are presumed to be familiar with the terms in the Internet Security Glossary [GLOS]. 178
2.2 Namespaces
179
Namespace URIs (of the general form "some-URI") represents some application-dependent or 180
context-dependent URI as defined in RFC 2396 [URI]. The XML namespace URIs that MUST be 181
used by implementations of this specification are as follows (note that elements used in this 182
specification are from various namespaces): 183
184
http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
185
wssecurity-secext-1.0.xsd
186
http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
187
wssecurity-utility-1.0.xsd
188
189
This specification is designed to work with the general SOAP [SOAP11, SOAP12] message 190
structure and message processing model, and should be applicable to any version of SOAP. The 191
current SOAP 1.1 namespace URI is used herein to provide detailed examples, but there is no 192
intention to limit the applicability of this specification to a single version of SOAP. 193
The namespaces used in this document are shown in the following table (note that for brevity, the 194
examples use the prefixes listed below but do not include the URIs – those listed below are 195
assumed). 196
197
Prefix Namespace
ds http://www.w3.org/2000/09/xmldsig#
S11 http://schemas.xmlsoap.org/soap/envelope/
S12 http://www.w3.org/2003/05/soap-envelope
wsse http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd
wsu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 9 of 56

xenc http://www.w3.org/2001/04/xmlenc#
The URLs provided for the wsse and wsu namespaces can be used to obtain the schema files. 198
2.3 Acronyms and Abbreviations
199
The following (non-normative) table defines acronyms and abbreviations for this document. 200
Term Definition
HMAC Keyed-Hashing for Message Authentication
SHA-1 Secure Hash Algorithm 1
SOAP Simple Object Access Protocol
URI Uniform Resource Identifier
XML Extensible Markup Language
2.4 Terminology
201
Defined below are the basic definitions for the security terminology used in this specification. 202
Claim – A claim is a declaration made by an entity (e.g. name, identity, key, group, privilege, 203
capability, etc). 204
Claim Confirmation – A claim confirmation is the process of verifying that a claim applies to 205
an entity 206
Confidentiality – Confidentiality is the property that data is not made available to 207
unauthorized individuals, entities, or processes. 208
Digest – A digest is a cryptographic checksum of an octet stream. 209
Digital Signature – In this document, digital signature and signature are used 210
interchangeably and have the same meaning. 211
End-To-End Message Level Security - End-to-end message level security is 212
established when a message that traverses multiple applications (one or more SOAP 213
intermediaries) within and between business entities, e.g. companies, divisions and business 214
units, is secure over its full route through and between those business entities. This includes not 215
only messages that are initiated within the entity but also those messages that originate outside 216
the entity, whether they are Web Services or the more traditional messages. 217
Integrity – Integrity is the property that data has not been modified. 218
Message Confidentiality - Message Confidentiality is a property of the message and 219
encryption is the mechanism by which this property of the message is provided. 220
Message Integrity - Message Integrity is a property of the message and digital signature is a 221
mechanism by which this property of the message is provided. 222
Signature - A signature is a value computed with a cryptographic algorithm and bound 223
to data in such a way that intended recipients of the data can use the signature to verify that the 224
data has not been altered and/or has originated from the signer of the message, providing 225
message integrity and authentication. The signature can be computed and verified with 226
symmetric key algorithms, where the same key is used for signing and verifying, or with 227
asymmetric key algorithms, where different keys are used for signing and verifying (a private and 228
public key pair are used). 229
Security Token – A security token represents a collection (one or more) of claims. 230
231
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 10 of 56

232
233
Signed Security Token – A signed security token is a security token that is asserted and 234
cryptographically signed by a specific authority (e.g. an X.509 certificate or a Kerberos ticket). 235
Trust - Trust is the characteristic that one entity is willing to rely upon a second entity to execute 236
a set of actions and/or to make set of assertions about a set of subjects and/or scopes. 237
238
239
240
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 11 of 56

3 Message Protection Mechanisms
241
When securing SOAP messages, various types of threats should be considered. This includes, 242
but is not limited to: 243
• the message could be modified or read by antagonists or 244
• an antagonist could send messages to a service that, while well-formed, lack appropriate 245
security claims to warrant processing. 246
To understand these threats this specification defines a message security model. 247
3.1 Message Security Model
248
This document specifies an abstract message security model in terms of security tokens 249
combined with digital signatures to protect and authenticate SOAP messages. 250
Security tokens assert claims and can be used to assert the binding between authentication 251
secrets or keys and security identities. An authority can vouch for or endorse the claims in a 252
security token by using its key to sign or encrypt (it is recommended to use a keyed encryption) 253
the security token thereby enabling the authentication of the claims in the token. An X.509 [X509] 254
certificate, claiming the binding between one’s identity and public key, is an example of a signed 255
security token endorsed by the certificate authority. In the absence of endorsement by a third 256
party, the recipient of a security token may choose to accept the claims made in the token based 257
on its trust of the producer of the containing message. 258
Signatures are used to verify message origin and integrity. Signatures are also used by message 259
producers to demonstrate knowledge of the key, typically from a third party, used to confirm the 260
claims in a security token and thus to bind their identity (and any other claims occurring in the 261
security token) to the messages they create. 262
It should be noted that this security model, by itself, is subject to multiple security attacks. Refer 263
to the Security Considerations section for additional details. 264
Where the specification requires that an element be "processed" it means that the element type 265
MUST be recognized to the extent that an appropriate error is returned if the element is not 266
supported. 267
3.2 Message Protection
268
Protecting the message content from being disclosed (confidentiality) or modified without 269
detection (integrity) are primary security concerns. This specification provides a means to protect 270
a message by encrypting and/or digitally signing a body, a header, or any combination of them (or 271
parts of them). 272
Message integrity is provided by XML Signature [XMLSIG] in conjunction with security tokens to 273
ensure that modifications to messages are detected. The integrity mechanisms are designed to 274
support multiple signatures, potentially by multiple SOAP actors/roles, and to be extensible to 275
support additional signature formats. 276
Message confidentiality leverages XML Encryption [XMLENC] in conjunction with security tokens 277
to keep portions of a SOAP message confidential. The encryption mechanisms are designed to 278
support additional encryption processes and operations by multiple SOAP actors/roles. 279
This document defines syntax and semantics of signatures within a <wsse:Security> element. 280
This document does not specify any signature appearing outside of a <wsse:Security> 281
element. 282
3.3 Invalid or Missing Claims
283
A message recipient SHOULD reject messages containing invalid signatures, messages missing 284
necessary claims or messages whose claims have unacceptable values. Such messages are 285
unauthorized (or malformed). This specification provides a flexible way for the message producer 286
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 12 of 56

to make a claim about the security properties by associating zero or more security tokens with the 287
message. An example of a security claim is the identity of the producer; the producer can claim 288
that he is Bob, known as an employee of some company, and therefore he has the right to send 289
the message. 290
3.4 Example
291
The following example illustrates the use of a custom security token and associated signature. 292
The token contains base64 encoded binary data conveying a symmetric key which, we assume, 293
can be properly authenticated by the recipient. The message producer uses the symmetric key 294
with an HMAC signing algorithm to sign the message. The message receiver uses its knowledge 295
of the shared secret to repeat the HMAC key calculation which it uses to validate the signature 296
and in the process confirm that the message was authored by the claimed user identity. 297
298
(001) <?xml version="1.0" encoding="utf-8"?>
299
(002) <S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
300
xmlns:ds="...">
301
(003) <S11:Header>
302
(004) <wsse:Security
303
xmlns:wsse="...">
304
(005) <xxx:CustomToken wsu:Id="MyID"
305
xmlns:xxx="http://fabrikam123/token">
306
(006) FHUIORv...
307
(007) </xxx:CustomToken>
308
(008) <ds:Signature>
309
(009) <ds:SignedInfo>
310
(010) <ds:CanonicalizationMethod
311
Algorithm=
312
"http://www.w3.org/2001/10/xml-exc-c14n#"/>
313
(011) <ds:SignatureMethod
314
Algorithm=
315
"http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
316
(012) <ds:Reference URI="#MsgBody">
317
(013) <ds:DigestMethod
318
Algorithm=
319
"http://www.w3.org/2000/09/xmldsig#sha1"/>
320
(014) <ds:DigestValue>LyLsF0Pi4wPU...</ds:DigestValue>
321
(015) </ds:Reference>
322
(016) </ds:SignedInfo>
323
(017) <ds:SignatureValue>DJbchm5gK...</ds:SignatureValue>
324
(018) <ds:KeyInfo>
325
(019) <wsse:SecurityTokenReference>
326
(020) <wsse:Reference URI="#MyID"/>
327
(021) </wsse:SecurityTokenReference>
328
(022) </ds:KeyInfo>
329
(023) </ds:Signature>
330
(024) </wsse:Security>
331
(025) </S11:Header>
332
(026) <S11:Body wsu:Id="MsgBody">
333
(027) <tru:StockSymbol xmlns:tru="http://fabrikam123.com/payloads">
334
QQQ
335
</tru:StockSymbol>
336
(028) </S11:Body>
337
(029) </S11:Envelope>
338
339
The first two lines start the SOAP envelope. Line (003) begins the headers that are associated 340
with this SOAP message. 341
Line (004) starts the <wsse:Security> header defined in this specification. This header 342
contains security information for an intended recipient. This element continues until line (024). 343
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 13 of 56

Lines (005) to (007) specify a custom token that is associated with the message. In this case, it 344
uses an externally defined custom token format. 345
Lines (008) to (023) specify a digital signature. This signature ensures the integrity of the signed 346
elements. The signature uses the XML Signature specification identified by the ds namespace 347
declaration in Line (002). 348
Lines (009) to (016) describe what is being signed and the type of canonicalization being used. 349
Line (010) specifies how to canonicalize (normalize) the data that is being signed. Lines (012) to 350
(015) select the elements that are signed and how to digest them. Specifically, line (012) 351
indicates that the <S11:Body> element is signed. In this example only the message body is 352
signed; typically all critical elements of the message are included in the signature (see the 353
Extended Example below). 354
Line (017) specifies the signature value of the canonicalized form of the data that is being signed 355
as defined in the XML Signature specification. 356
Lines (018) to (022) provides information, partial or complete, as to where to find the security 357
token associated with this signature. Specifically, lines (019) to (021) indicate that the security 358
token can be found at (pulled from) the specified URL. 359
Lines (026) to (028) contain the body (payload) of the SOAP message. 360
361
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 14 of 56

4 ID References
362
There are many motivations for referencing other message elements such as signature 363
references or correlating signatures to security tokens. For this reason, this specification defines 364
the wsu:Id attribute so that recipients need not understand the full schema of the message for 365
processing of the security elements. That is, they need only "know" that the wsu:Id attribute 366
represents a schema type of ID which is used to reference elements. However, because some 367
key schemas used by this specification don't allow attribute extensibility (namely XML Signature 368
and XML Encryption), this specification also allows use of their local ID attributes in addition to 369
the wsu:Id attribute. As a consequence, when trying to locate an element referenced in a 370
signature, the following attributes are considered: 371
• Local ID attributes on XML Signature elements 372
• Local ID attributes on XML Encryption elements 373
• Global wsu:Id attributes (described below) on elements 374
In addition, when signing a part of an envelope such as the body, it is RECOMMENDED that an 375
ID reference is used instead of a more general transformation, especially XPath [XPATH]. This is 376
to simplify processing. 377
4.1 Id Attribute
378
There are many situations where elements within SOAP messages need to be referenced. For 379
example, when signing a SOAP message, selected elements are included in the scope of the 380
signature. XML Schema Part 2 [XMLSCHEMA] provides several built-in data types that may be 381
used for identifying and referencing elements, but their use requires that consumers of the SOAP 382
message either have or must be able to obtain the schemas where the identity or reference 383
mechanisms are defined. In some circumstances, for example, intermediaries, this can be 384
problematic and not desirable. 385
Consequently a mechanism is required for identifying and referencing elements, based on the 386
SOAP foundation, which does not rely upon complete schema knowledge of the context in which 387
an element is used. This functionality can be integrated into SOAP processors so that elements 388
can be identified and referred to without dynamic schema discovery and processing. 389
This section specifies a namespace-qualified global attribute for identifying an element which can 390
be applied to any element that either allows arbitrary attributes or specifically allows a particular 391
attribute. 392
4.2 Id Schema
393
To simplify the processing for intermediaries and recipients, a common attribute is defined for 394
identifying an element. This attribute utilizes the XML Schema ID type and specifies a common 395
attribute for indicating this information for elements. 396
The syntax for this attribute is as follows: 397
398
<anyElement wsu:Id="...">...</anyElement>
399
400
The following describes the attribute illustrated above: 401
.../@wsu:Id 402
This attribute, defined as type xsd:ID, provides a well-known attribute for specifying the 403
local ID of an element. 404
Two wsu:Id attributes within an XML document MUST NOT have the same value. 405
Implementations MAY rely on XML Schema validation to provide rudimentary enforcement for 406
intra-document uniqueness. However, applications SHOULD NOT rely on schema validation 407
alone to enforce uniqueness. 408
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 15 of 56

This specification does not specify how this attribute will be used and it is expected that other 409
specifications MAY add additional semantics (or restrictions) for their usage of this attribute. 410
The following example illustrates use of this attribute to identify an element: 411
412
<x:myElement wsu:Id="ID1" xmlns:x="..."
413
xmlns:wsu="..."/>
414
415
Conformant processors that do support XML Schema MUST treat this attribute as if it was 416
defined using a global attribute declaration. 417
Conformant processors that do not support dynamic XML Schema or DTDs discovery and 418
processing are strongly encouraged to integrate this attribute definition into their parsers. That is, 419
to treat this attribute information item as if its PSVI has a [type definition] which {target 420
namespace} is "http://www.w3.org/2001/XMLSchema" and which {name} is "Id." Doing so 421
allows the processor to inherently know how to process the attribute without having to locate and 422
process the associated schema. Specifically, implementations MAY support the value of the 423
wsu:Id as the valid identifier for use as an XPointer [XPointer] shorthand pointer for 424
interoperability with XML Signature references. 425
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 16 of 56

5 Security Header
426
The <wsse:Security> header block provides a mechanism for attaching security-related 427
information targeted at a specific recipient in the form of a SOAPactor/role. This may be either 428
the ultimate recipient of the message or an intermediary. Consequently, elements of this type 429
may be present multiple times in a SOAP message. An active intermediary on the message path 430
MAY add one or more new sub-elements to an existing <wsse:Security> header block if they 431
are targeted for its SOAP node or it MAY add one or more new headers for additional targets. 432
As stated, a message MAY have multiple <wsse:Security> header blocks if they are targeted 433
for separate recipients. However, only one <wsse:Security> header block MAY omit the S11: 434
actor or S12:role attributes. Two <wsse:Security> header blocks MUST NOT have the 435
same value for S11:actor or S12:role. Message security information targeted for different 436
recipients MUST appear in different <wsse:Security> header blocks. This is due to potential 437
processing order issues (e.g. due to possible header re-ordering). The <wsse:Security> 438
header block without a specified S11:actor or S12:role MAY be processed by anyone, but 439
MUST NOT be removed prior to the final destination or endpoint. 440
As elements are added to a <wsse:Security> header block, they SHOULD be prepended to 441
the existing elements. As such, the <wsse:Security> header block represents the signing and 442
encryption steps the message producer took to create the message. This prepending rule 443
ensures that the receiving application can process sub-elements in the order they appear in the 444
<wsse:Security> header block, because there will be no forward dependency among the sub-445
elements. Note that this specification does not impose any specific order of processing the sub-446
elements. The receiving application can use whatever order is required. 447
When a sub-element refers to a key carried in another sub-element (for example, a signature 448
sub-element that refers to a binary security token sub-element that contains the X.509 certificate 449
used for the signature), the key-bearing element SHOULD be ordered to precede the key-using 450
Element: 451
452
<S11:Envelope>
453
<S11:Header>
454
...
455
<
wsse:
Security S11:actor="..." S11:mustUnderstand="...">
456
...
457
</
wsse:
Security>
458
...
459
</S11:Header>
460
...
461
</S11:Envelope>
462
463
The following describes the attributes and elements listed in the example above: 464
/wsse:Security 465
This is the header block for passing security-related message information to a recipient. 466
/wsse:Security/@S11:actor 467
This attribute allows a specific SOAP 1.1 [SPOAP11] actor to be identified. This attribute 468
is optional; however, no two instances of the header block may omit a actor or specify the 469
same actor. 470
/wsse:Security/@S12:role 471
This attribute allows a specific SOAP 1.2 [SOAP12] role to be identified. This attribute is 472
optional; however, no two instances of the header block may omit a role or specify the 473
same role. 474
475
/wsse:Security/{any} 476
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 17 of 56

This is an extensibility mechanism to allow different (extensible) types of security 477
information, based on a schema, to be passed. Unrecognized elements SHOULD cause 478
a fault. 479
/wsse:Security/@{any} 480
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 481
added to the header. Unrecognized attributes SHOULD cause a fault. 482
All compliant implementations MUST be able to process a <wsse:Security> element. 483
All compliant implementations MUST declare which profiles they support and MUST be able to 484
process a <wsse:Security> element including any sub-elements which may be defined by that 485
profile. It is RECOMMENDED that undefined elements within the <wsse:Security> header 486
not be processed. 487
The next few sections outline elements that are expected to be used within a <wsse:Security> 488
header. 489
When a <wsse:Security> header includes a mustUnderstand="true" attribute: 490
• The receiver MUST generate a SOAP fault if does not implement the WSS: SOAP 491
Message Security specification corresponding to the namespace. Implementation means 492
ability to interpret the schema as well as follow the required processing rules specified in 493
WSS: SOAP Message Security. 494
• The receiver must generate a fault if unable to interpret or process security tokens 495
contained in the <wsse:Security> header block according to the corresponding WSS: 496
SOAP Message Security token profiles. 497
• Receivers MAY ignore elements or extensions within the <wsse:Security> element, 498
based on local security policy. 499
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 18 of 56

6 Security Tokens
500
This chapter specifies some different types of security tokens and how they are attached to 501
messages. 502
6.1 Attaching Security Tokens
503
This specification defines the <wsse:Security> header as a mechanism for conveying 504
security information with and about a SOAP message. This header is, by design, extensible to 505
support many types of security information. 506
For security tokens based on XML, the extensibility of the <wsse:Security> header allows for 507
these security tokens to be directly inserted into the header. 508
6.1.1 Processing Rules
509
This specification describes the processing rules for using and processing XML Signature and 510
XML Encryption. These rules MUST be followed when using any type of security token. Note 511
that if signature or encryption is used in conjunction with security tokens, they MUST be used in a 512
way that conforms to the processing rules defined by this specification. 513
6.1.2 Subject Confirmation
514
This specification does not dictate if and how claim confirmation must be done; however, it does 515
define how signatures may be used and associated with security tokens (by referencing the 516
security tokens from the signature) as a form of claim confirmation. 517
6.2 User Name Token
518
6.2.1 Usernames
519
The <wsse:UsernameToken> element is introduced as a way of providing a username. This 520
element is optionally included in the <wsse:Security> header. 521
The following illustrates the syntax of this element: 522
523
<wsse:UsernameToken wsu:Id="...">
524
<wsse:Username>...</wsse:Username>
525
</wsse:UsernameToken>
526
527
The following describes the attributes and elements listed in the example above: 528
/wsse:UsernameToken 529
This element is used to represent a claimed identity. 530
/wsse:UsernameToken/@wsu:Id 531
A string label for this security token. 532
/wsse:UsernameToken/wsse:Username 533
This required element specifies the claimed identity. 534
/wsse:UsernameToken/wsse:Username/@{any} 535
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 536
added to the <wsse:Username> element. 537
/wsse:UsernameToken/{any} 538
This is an extensibility mechanism to allow different (extensible) types of security 539
information, based on a schema, to be passed. Unrecognized elements SHOULD cause 540
a fault. 541
/wsse:UsernameToken/@{any} 542
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 19 of 56

This is an extensibility mechanism to allow additional attributes, based on schemas, to be 543
added to the <wsse:UsernameToken> element. Unrecognized attributes SHOULD 544
cause a fault. 545
All compliant implementations MUST be able to process a <wsse:UsernameToken> element. 546
The following illustrates the use of this: 547
548
<S11:Envelope xmlns:S11="..." xmlns:wsse="...">
549
<S11:Header>
550
...
551
<wsse:Security>
552
<wsse:UsernameToken>
553
<wsse:Username>Zoe</wsse:Username>
554
</wsse:UsernameToken>
555
</wsse:Security>
556
...
557
</S11:Header>
558
...
559
</S11:Envelope>
560

561
6.3 Binary Security Tokens
562
6.3.1 Attaching Security Tokens
563
For binary-formatted security tokens, this specification provides a 564
<wsse:BinarySecurityToken> element that can be included in the <wsse:Security> 565
header block. 566
6.3.2 Encoding Binary Security Tokens
567
Binary security tokens (e.g., X.509 certificates and Kerberos [KERBEROS] tickets) or other non-568
XML formats require a special encoding format for inclusion. This section describes a basic 569
framework for using binary security tokens. Subsequent specifications MUST describe the rules 570
for creating and processing specific binary security token formats. 571
The <wsse:BinarySecurityToken> element defines two attributes that are used to interpret 572
it. The ValueType attribute indicates what the security token is, for example, a Kerberos ticket. 573
The EncodingType tells how the security token is encoded, for example Base64Binary. 574
The following is an overview of the syntax: 575
576
<wsse:BinarySecurityToken wsu:Id=...
577
EncodingType=...
578
ValueType=.../>
579
580
The following describes the attributes and elements listed in the example above: 581
/wsse:BinarySecurityToken 582
This element is used to include a binary-encoded security token. 583
/wsse:BinarySecurityToken/@wsu:Id 584
An optional string label for this security token. 585
/wsse:BinarySecurityToken/@ValueType 586
The ValueType attribute is used to indicate the "value space" of the encoded binary 587
data (e.g. an X.509 certificate). The ValueType attribute allows a URI that defines the 588
value type and space of the encoded binary data. Subsequent specifications MUST 589
define the ValueType value for the tokens that they define. The usage of ValueType is 590
RECOMMENDED. 591
/wsse:BinarySecurityToken/@EncodingType 592
The EncodingType attribute is used to indicate, using a URI, the encoding format of the 593
binary data (e.g., base64 encoded). A new attribute is introduced, as there are issues 594
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 20 of 56

with the current schema validation tools that make derivations of mixed simple and 595
complex types difficult within XML Schema. The EncodingType attribute is interpreted 596
to indicate the encoding format of the element. The following encoding formats are pre-597
defined (note that the URI fragments are relative to the URI for this specification): 598
599
URI Description
#Base64Binary
(default)
XML Schema base 64 encoding
600
/wsse:BinarySecurityToken/@{any} 601
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 602
added. 603
All compliant implementations MUST be able to process a <wsse:BinarySecurityToken> 604
element. 605
When a <wsse:BinarySecurityToken> is included in a signature—that is, it is referenced 606
from a <ds:Signature> element--care should be taken so that the canonicalization algorithm 607
(e.g., Exclusive XML Canonicalization [EXC-C14N]) does not allow unauthorized replacement of 608
namespace prefixes of the QNames used in the attribute or element values. In particular, it is 609
RECOMMENDED that these namespace prefixes be declared within the 610
<wsse:BinarySecurityToken> element if this token does not carry the validating key (and 611
consequently it is not cryptographically bound to the signature). 612
6.4 XML Tokens
613
This section presents framework for using XML-based security tokens. Profile specifications 614
describe rules and processes for specific XML-based security token formats. 615
6.4.1 Identifying and Referencing Security Tokens
616
This specification also defines multiple mechanisms for identifying and referencing security 617
tokens using the wsu:Id attribute and the <wsse:SecurityTokenReference> element (as 618
well as some additional mechanisms). Please refer to the specific profile documents for the 619
appropriate reference mechanism. However, specific extensions MAY be made to the 620
<wsse:SecurityTokenReference> element. 621
622
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 21 of 56

7 Token References
623
This chapter discusses and defines mechanisms for referencing security tokens. 624
7.1 SecurityTokenReference Element
625
A security token conveys a set of claims. Sometimes these claims reside somewhere else and 626
need to be "pulled" by the receiving application. The <wsse:SecurityTokenReference> 627
element provides an extensible mechanism for referencing security tokens. 628
The <wsse:SecurityTokenReference> element provides an open content model for 629
referencing security tokens because not all tokens support a common reference pattern. 630
Similarly, some token formats have closed schemas and define their own reference mechanisms. 631
The open content model allows appropriate reference mechanisms to be used when referencing 632
corresponding token types. 633
If a <wsse:SecurityTokenReference> is used outside of the <wsse:Security> header 634
block the meaning of the response and/or processing rules of the resulting references MUST be 635
specified by the containing element and are out of scope of this specification. 636
The following illustrates the syntax of this element: 637
638
<wsse:SecurityTokenReference wsu:Id="...">
639
...
640
</wsse:SecurityTokenReference>
641
642
The following describes the elements defined above: 643
/wsse:SecurityTokenReference 644
This element provides a reference to a security token. 645
/wsse:SecurityTokenReference/@wsu:Id 646
A string label for this security token reference which names the reference. This attribute 647
does not indicate the ID of what is being referenced, that SHOULD be done using a 648
fragment URI in a <wsse:Reference> element within the 649
<wsse:SecurityTokenReference> element. 650
/wsse:SecurityTokenReference/@wsse:Usage 651
This optional attribute is used to type the usage of the <wsse:SecurityToken>. 652
Usages are specified using URIs and multiple usages MAY be specified using XML list 653
semantics. No usages are defined by this specification. 654
/wsse:SecurityTokenReference/{any} 655
This is an extensibility mechanism to allow different (extensible) types of security 656
references, based on a schema, to be passed. Unrecognized elements SHOULD cause a 657
fault. 658
/wsse:SecurityTokenReference/@{any} 659
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 660
added to the header. Unrecognized attributes SHOULD cause a fault. 661
All compliant implementations MUST be able to process a 662
<wsse:SecurityTokenReference> element. 663
This element can also be used as a direct child element of <ds:KeyInfo> to indicate a hint to 664
retrieve the key information from a security token placed somewhere else. In particular, it is 665
RECOMMENDED, when using XML Signature and XML Encryption, that a 666
<wsse:SecurityTokenReference> element be placed inside a <ds:KeyInfo> to reference 667
the security token used for the signature or encryption. 668
There are several challenges that implementations face when trying to interoperate. Processing 669
the IDs and references requires the recipient to understand the schema. This may be an 670
expensive task and in the general case impossible as there is no way to know the "schema 671
location" for a specific namespace URI. As well, the primary goal of a reference is to uniquely 672
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 22 of 56

identify the desired token. ID references are, by definition, unique by XML. However, other 673
mechanisms such as "principal name" are not required to be unique and therefore such 674
references may be not unique. 675
The following list provides a list of the specific reference mechanisms defined in WSS: SOAP 676
Message Security in preferred order (i.e., most specific to least specific): 677
• Direct References – This allows references to included tokens using URI fragments and 678
external tokens using full URIs. 679
• Key Identifiers – This allows tokens to be referenced using an opaque value that 680
represents the token (defined by token type/profile). 681
• Key Names – This allows tokens to be referenced using a string that matches an identity 682
assertion within the security token. This is a subset match and may result in multiple 683
security tokens that match the specified name. 684
• Embedded References - This allows tokens to be embedded (as opposed to a pointer 685
to a token that resides elsewhere). 686
7.2 Direct References
687
The <wsse:Reference> element provides an extensible mechanism for directly referencing 688
security tokens using URIs. 689
The following illustrates the syntax of this element: 690
691
<wsse:SecurityTokenReference wsu:Id="...">
692
<wsse:Reference URI="..." ValueType="..."/>
693
</wsse:SecurityTokenReference>
694
695
The following describes the elements defined above: 696
/wsse:SecurityTokenReference/wsse:Reference 697
This element is used to identify an abstract URI location for locating a security token. 698
/wsse:SecurityTokenReference/wsse:Reference/@URI 699
This optional attribute specifies an abstract URI for where to find a security token. If a 700
fragment is specified, then it indicates the local ID of the token being referenced. 701
/wsse:SecurityTokenReference/wsse:Reference/@ValueType 702
This optional attribute specifies a URI that is used to identify the type of token being 703
referenced. This specification does not define any processing rules around the usage of 704
this attribute, however, specifications for individual token types MAY define specific 705
processing rules and semantics around the value of the URI and how it SHALL be 706
interpreted. If this attribute is not present, the URI MUST be processed as a normal URI. 707
The usage of ValueType is RECOMMENDED for references with local URIs. 708
/wsse:SecurityTokenReference/wsse:Reference/{any} 709
This is an extensibility mechanism to allow different (extensible) types of security 710
references, based on a schema, to be passed. Unrecognized elements SHOULD cause a 711
fault. 712
/wsse:SecurityTokenReference/wsse:Reference/@{any} 713
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 714
added to the header. Unrecognized attributes SHOULD cause a fault. 715
The following illustrates the use of this element: 716
717
<wsse:SecurityTokenReference
718
xmlns:wsse="...">
719
<wsse:Reference
720
URI="http://www.fabrikam123.com/tokens/Zoe"/>
721
</wsse:SecurityTokenReference>
722
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 23 of 56

7.3 Key Identifiers
723
Alternatively, if a direct reference is not used, then it is RECOMMENDED to use a key identifier to 724
specify/reference a security token instead of a <ds:KeyName>. A KeyIdentifier is a value 725
that can be used to uniquely identify a security token (e.g. a hash of the important elements of the 726
security token). The exact value type and generation algorithm varies by security token type (and 727
sometimes by the data within the token), Consequently, the values and algorithms are described 728
in the token-specific profiles rather than this specification. 729
The <wsse:KeyIdentifier> element SHALL be placed in the 730
<wsse:SecurityTokenReference> element to reference a token using an identifier. This 731
element SHOULD be used for all key identifiers. 732
The processing model assumes that the key identifier for a security token is constant. 733
Consequently, processing a key identifier is simply looking for a security token whose key 734
identifier matches a given specified constant. 735
The following is an overview of the syntax: 736
737
<wsse:SecurityTokenReference>
738
<wsse:KeyIdentifier wsu:Id="..."
739
ValueType="..."
740
EncodingType="...">
741
...
742
</wsse:KeyIdentifier>
743
</wsse:SecurityTokenReference>
744
745
The following describes the attributes and elements listed in the example above: 746
/wsse:SecurityTokenReference/wsse:KeyIdentifier 747
This element is used to include a binary-encoded key identifier. 748
/wsse:SecurityTokenReference/wsse:KeyIdentifier/@wsu:Id 749
An optional string label for this identifier. 750
/wsse:SecurityTokenReference/wsse:KeyIdentifier/@ValueType 751
The optional ValueType attribute is used to indicate the type of KeyIdentifier being 752
used. Each specific token profile specifies the KeyIdentifier types that may be used 753
to refer to tokens of that type. It also specifies the critical semantics of the identifier, such 754
as whether the KeyIdentifier is unique to the key or the token. If no value is specified 755
then the key identifier will be interpreted in an application-specific manner. 756
/wsse:SecurityTokenReference/wsse:KeyIdentifier/@EncodingType 757
The optional EncodingType attribute is used to indicate, using a URI, the encoding 758
format of the KeyIdentifier (#Base64Binary). The base values defined in this 759
specification are used (Note that URI fragments are relative to this document's URI): 760
761
URI Description
#Base64Binary XML Schema base 64 encoding (default)
762
/wsse:SecurityTokenReference/wsse:KeyIdentifier/@{any} 763
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 764
added. 765
7.4 Embedded References
766
In some cases a reference may be to an embedded token (as opposed to a pointer to a token 767
that resides elsewhere). To do this, the <wsse:Embedded> element is specified within a 768
<wsse:SecurityTokenReference> element. 769
The following is an overview of the syntax: 770
771
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 24 of 56

<wsse:SecurityTokenReference>
772
<wsse:Embedded wsu:Id="...">
773
...
774
</wsse:Embedded>
775
</wsse:SecurityTokenReference>
776
777
The following describes the attributes and elements listed in the example above: 778
/wsse:SecurityTokenReference/wsse:Embedded 779
This element is used to embed a token directly within a reference (that is, to create a 780
local or literal reference). 781
/wsse:SecurityTokenReference/wsse:Embedded/@wsu:Id 782
An optional string label for this element. This allows this embedded token to be 783
referenced by a signature or encryption. 784
/wsse:SecurityTokenReference/wsse:Embedded/{any} 785
This is an extensibility mechanism to allow any security token, based on schemas, to be 786
embedded. Unrecognized elements SHOULD cause a fault. 787
/wsse:SecurityTokenReference/wsse:Embedded/@{any} 788
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 789
added. Unrecognized attributes SHOULD cause a fault. 790
The following example illustrates embedding a SAML assertion: 791
792
<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="...">
793
<S11:Header>
794
<wsse:Security>
795
...
796
<wsse:SecurityTokenReference>
797
<wsse:Embedded wsu:Id="tok1">
798
<saml:Assertion xmlns:saml="...">
799
...
800
</saml:Assertion>
801
</wsse:Embedded>
802
</wsse:SecurityTokenReference>
803
...
804
<wsse:Security>
805
</S11:Header>
806
...
807
</S11:Envelope>
808
7.5 ds:KeyInfo
809
The <ds:KeyInfo> element (from XML Signature) can be used for carrying the key information 810
and is allowed for different key types and for future extensibility. However, in this specification, 811
the use of <wsse:BinarySecurityToken> is the RECOMMENDED mechanism to carry key 812
material if the key type contains binary data. Please refer to the specific profile documents for the 813
appropriate way to carry key material. 814
The following example illustrates use of this element to fetch a named key: 815
816
<ds:KeyInfo Id="..." xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
817
<ds:KeyName>CN=Hiroshi Maruyama, C=JP</ds:KeyName>
818
</ds:KeyInfo>
819
7.6 Key Names
820
It is strongly RECOMMENDED to use <wsse:KeyIdentifier> elements. However, if key 821
names are used, then it is strongly RECOMMENDED that <ds:KeyName> elements conform to 822
the attribute names in section 2.3 of RFC 2253 (this is recommended by XML Signature for 823
<ds:X509SubjectName>) for interoperability. 824
Additionally, e-mail addresses, SHOULD conform to RFC 822: 825
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 25 of 56

EmailAddress=ckaler@microsoft.com
826
827
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 26 of 56

8 Signatures
828
Message producers may want to enable message recipients to determine whether a message 829
was altered in transit and to verify that the claims in a particular security token apply to the 830
producer of the message. 831
Demonstrating knowledge of a confirmation key associated with a token key-claim confirms the 832
accompanying token claims. Knowledge of a confirmation key may be demonstrated using that 833
key to create an XML Signature, for example. The relying party acceptance of the claims may 834
depend on its confidence in the token. Multiple tokens may contain a key-claim for a signature 835
and may be referenced from the signature using a <wsse:SecurityTokenReference>. A 836
key-claim may be an X.509 Certificate token, or a Kerberos service ticket token to give two 837
examples. 838
Because of the mutability of some SOAP headers, producers SHOULD NOT use the Enveloped 839
Signature Transform defined in XML Signature. Instead, messages SHOULD explicitly include 840
the elements to be signed. Similarly, producers SHOULD NOT use the Enveloping Signature 841
defined in XML Signature [XMLSIG]. 842
This specification allows for multiple signatures and signature formats to be attached to a 843
message, each referencing different, even overlapping, parts of the message. This is important 844
for many distributed applications where messages flow through multiple processing stages. For 845
example, a producer may submit an order that contains an orderID header. The producer signs 846
the orderID header and the body of the request (the contents of the order). When this is received 847
by the order processing sub-system, it may insert a shippingID into the header. The order sub-848
system would then sign, at a minimum, the orderID and the shippingID, and possibly the body as 849
well. Then when this order is processed and shipped by the shipping department, a shippedInfo 850
header might be appended. The shipping department would sign, at a minimum, the shippedInfo 851
and the shippingID and possibly the body and forward the message to the billing department for 852
processing. The billing department can verify the signatures and determine a valid chain of trust 853
for the order, as well as who authorized each step in the process. 854
All compliant implementations MUST be able to support the XML Signature standard. 855
8.1 Algorithms
856
This specification builds on XML Signature and therefore has the same algorithm requirements as 857
those specified in the XML Signature specification. 858
The following table outlines additional algorithms that are strongly RECOMMENDED by this 859
specification: 860
861
Algorithm Type Algorithm Algorithm URI
Canonicalization Exclusive XML
Canonicalization
http://www.w3.org/2001/10/xml-exc-c14n#
862
As well, the following table outlines additional algorithms that MAY be used: 863
Algorithm Type Algorithm Algorithm URI
Transform SOAP Message
Normalization
http://www.w3.org/TR/2003/NOTE-soap12-
n11n-20030328/
864
The Exclusive XML Canonicalization algorithm addresses the pitfalls of general canonicalization 865
that can occur from leaky namespaces with pre-existing signatures. 866
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 27 of 56

Finally, if a producer wishes to sign a message before encryption, then following the ordering 867
rules laid out in section 5, "Security Header", they SHOULD first prepend the signature element to 868
the <wsse:Security> header, and then prepend the encryption element, resulting in a 869
<wsse:Security> header that has the encryption element first, followed by the signature 870
element: 871
872
<wsse:Security> header
[encryption element]
[signature element]
.
.
873
Likewise, if a producer wishes to sign a message after encryption, they SHOULD first prepend 874
the encryption element to the <wsse:Security> header, and then prepend the signature 875
element. This will result in a <wsse:Security> header that has the signature element first, 876
followed by the encryption element: 877
878
<wsse:Security> header
[signature element]
[encryption element]
.
.
879
The XML Digital Signature WG has defined two canonicalization algorithms: XML 880
Canonicalization and Exclusive XML Canonicalization. To prevent confusion, the first is also 881
called Inclusive Canonicalization. Neither one solves all possible problems that can arise. The 882
following informal discussion is intended to provide guidance on the choice of which one to use 883
in particular circumstances. For a more detailed and technically precise discussion of these 884
issues see: [XML-C14N] and [EXC-C14N]. 885
There are two problems to be avoided. On the one hand, XML allows documents to be changed 886
in various ways and still be considered equivalent. For example, duplicate namespace 887
declarations can be removed or created. As a result, XML tools make these kinds of changes 888
freely when processing XML. Therefore, it is vital that these equivalent forms match the same 889
signature. 890
On the other hand, if the signature simply covers something like xx:foo, its meaning may change 891
if xx is redefined. In this case the signature does not prevent tampering. It might be thought that 892
the problem could be solved by expanding all the values in line. Unfortunately, there are 893
mechanisms like XPATH which consider xx="http://example.com/"; to be different from 894
yy="http://example.com/"; even though both xx and yy are bound to the same namespace. 895
The fundamental difference between the Inclusive and Exclusive Canonicalization is the 896
namespace declarations which are placed in the output. Inclusive Canonicalization copies all the 897
declarations that are currently in force, even if they are defined outside of the scope of the 898
signature. It also copies any xml: attributes that are in force, such as xml:lang or xml:base. 899
This guarantees that all the declarations you might make use of will be unambiguously specified. 900
The problem with this is that if the signed XML is moved into another XML document which has 901
other declarations, the Inclusive Canonicalization will copy then and the signature will be invalid. 902
This can even happen if you simply add an attribute in a different namespace to the surrounding 903
context. 904
Exclusive Canonicalization tries to figure out what namespaces you are actually using and just 905
copies those. Specifically, it copies the ones that are "visibly used", which means the ones that 906
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 28 of 56

are a part of the XML syntax. However, it does not look into attribute values or element content, 907
so the namespace declarations required to process these are not copied. For example 908
if you had an attribute like xx:foo="yy:bar" it would copy the declaration for xx, but not yy. (This 909
can even happen without your knowledge because XML processing tools will add xsi:type if 910
you use a schema subtype.) It also does not copy the xml: attributes that are declared outside the 911
scope of the signature. 912
Exclusive Canonicalization allows you to create a list of the namespaces that must be declared, 913
so that it will pick up the declarations for the ones that are not visibly used. The only problem is 914
that the software doing the signing must know what they are. In a typical SOAP software 915
environment, the security code will typically be unaware of all the namespaces being used by 916
the application in the message body that it is signing. 917
Exclusive Canonicalization is useful when you have a signed XML document that you wish to 918
insert into other XML documents. A good example is a signed SAML assertion which might be 919
inserted as a XML Token in the security header of various SOAP messages. The Issuer who 920
signs the assertion will be aware of the namespaces being used and able to construct the list. 921
The use of Exclusive Canonicalization will insure the signature verifies correctly every time. 922
Inclusive Canonicalization is useful in the typical case of signing part or all of the SOAP body in 923
accordance with this specification. This will insure all the declarations fall under the signature, 924
even though the code is unaware of what namespaces are being used. At the same time, it is 925
less likely that the signed data (and signature element) will be inserted in some other XML 926
document. Even if this is desired, it still may not be feasible for other reasons, for example there 927
may be Id's with the same value defined in both XML documents. 928
In other situations it will be necessary to study the requirements of the application and the 929
detailed operation of the canonicalization methods to determine which is appropriate. 930
This section is non-normative. 931
932
8.2 Signing Messages
933
The <wsse:Security> header block MAY be used to carry a signature compliant with the XML 934
Signature specification within a SOAP Envelope for the purpose of signing one or more elements 935
in the SOAP Envelope. Multiple signature entries MAY be added into a single SOAP Envelope 936
within one <wsse:Security> header block. Producers SHOULD sign all important elements of 937
the message, and careful thought must be given to creating a signing policy that requires signing 938
of parts of the message that might legitimately be altered in transit. 939
SOAP applications MUST satisfy the following conditions: 940
A compliant implementation MUST be capable of processing the required elements defined in the 941
XML Signature specification. 942
To add a signature to a <wsse:Security> header block, a <ds:Signature> element 943
conforming to the XML Signature specification MUST be prepended to the existing content of the 944
<wsse:Security> header block, in order to indicate to the receiver the correct order of 945
operations. All the <ds:Reference> elements contained in the signature SHOULD refer to a 946
resource within the enclosing SOAP envelope as described in the XML Signature specification. 947
However, since the SOAP message exchange model allows intermediate applications to modify 948
the Envelope (add or delete a header block; for example), XPath filtering does not always result 949
in the same objects after message delivery. Care should be taken in using XPath filtering so that 950
there is no subsequent validation failure due to such modifications. 951
The problem of modification by intermediaries (especially active ones) is applicable to more than 952
just XPath processing. Digital signatures, because of canonicalization and digests, present 953
particularly fragile examples of such relationships. If overall message processing is to remain 954
robust, intermediaries must exercise care that the transformation algorithms used do not affect 955
the validity of a digitally signed component. 956
Due to security concerns with namespaces, this specification strongly RECOMMENDS the use of 957
the "Exclusive XML Canonicalization" algorithm or another canonicalization algorithm that 958
provides equivalent or greater protection. 959
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 29 of 56

For processing efficiency it is RECOMMENDED to have the signature added and then the 960
security token pre-pended so that a processor can read and cache the token before it is used. 961
8.3 Signing Tokens
962
It is often desirable to sign security tokens that are included in a message or even external to the 963
message. The XML Signature specification provides several common ways for referencing 964
information to be signed such as URIs, IDs, and XPath, but some token formats may not allow 965
tokens to be referenced using URIs or IDs and XPaths may be undesirable in some situations. 966
This specification allows different tokens to have their own unique reference mechanisms which 967
are specified in their profile as extensions to the <wsse:SecurityTokenReference> element. 968
This element provides a uniform referencing mechanism that is guaranteed to work with all token 969
formats. Consequently, this specification defines a new reference option for XML Signature: the 970
STR Dereference Transform. 971
This transform is specified by the URI #STR-Transform (Note that URI fragments are relative to 972
this document's URI) and when applied to a <wsse:SecurityTokenReference> element it 973
means that the output is the token referenced by the <wsse:SecurityTokenReference> 974
element not the element itself. 975
As an overview the processing model is to echo the input to the transform except when a 976
<wsse:SecurityTokenReference> element is encountered. When one is found, the element 977
is not echoed, but instead, it is used to locate the token(s) matching the criteria and rules defined 978
by the <wsse:SecurityTokenReference> element and echo it (them) to the output. 979
Consequently, the output of the transformation is the resultant sequence representing the input 980
with any <wsse:SecurityTokenReference> elements replaced by the referenced security 981
token(s) matched. 982
The following illustrates an example of this transformation which references a token contained 983
within the message envelope: 984
985
...
986
<wsse:SecurityTokenReference wsu:Id="Str1">
987
...
988
</wsse:SecurityTokenReference>
989
...
990
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
991
<ds:SignedInfo>
992
...
993
<ds:Reference URI="#Str1">
994
<ds:Transforms>
995
<ds:Transform
996
Algorithm="...#STR-Transform">
997
<wsse:TransformationParameters>
998
<ds:CanonicalizationMethod
999
Algorithm="http://www.w3.org/TR/2001/REC-xml-
1000
c14n-20010315" />
1001
</wsse:TransformationParameters>
1002
</ds:Transform>
1003
<ds:DigestMethod Algorithm=
1004
"http://www.w3.org/2000/09/xmldsig#sha1"/>
1005
<ds:DigestValue>...</ds:DigestValue>
1006
</ds:Reference>
1007
</ds:SignedInfo>
1008
<ds:SignatureValue></ds:SignatureValue>
1009
</ds:Signature>
1010
...
1011
1012
The following describes the attributes and elements listed in the example above: 1013
/wsse:TransformationParameters 1014
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 30 of 56

This element is used to wrap parameters for a transformation allows elements even from 1015
the XML Signature namespace. 1016
/wsse:TransformationParameters/ds:Canonicalization 1017
This specifies the canolicalization algorithm to apply to the selected data. 1018
/wsse:TransformationParameters/{any} 1019
This is an extensibility mechanism to allow different (extensible) parameters to be 1020
specified in the future. Unrecognized parameters SHOULD cause a fault. 1021
/wsse:TransformationParameters/@{any} 1022
This is an extensibility mechanism to allow additional attributes, based on schemas, to be 1023
added to the element in the future. Unrecognized attributes SHOULD cause a fault. 1024
1025
The following is a detailed specification of the transformation. 1026
The algorithm is identified by the URI: #STR-Transform 1027
Transform Input: 1028
• The input is a node set. If the input is an octet stream, then it is automatically parsed; cf. 1029
XML Digital Signature [XMLSIG]. 1030
Transform Output: 1031
• The output is an octet steam. 1032
Syntax: 1033
• The transform takes a single mandatory parameter, a 1034
<ds:CanonicalizationMethod> element, which is used to serialize the input node 1035
set. Note, however, that the output may not be strictly in canonical form, per the 1036
canonicalization algorithm; however, the output is canonical, in the sense that it is 1037
unambiguous. However, because of syntax requirements in the XML Signature 1038
definition, this parameter MUST be wrapped in a 1039
<wsse:TransformationParameters> element. 1040
Processing Rules: 1041
• Let N be the input node set. 1042
• Let R be the set of all <wsse:SecurityTokenReference> elements in N. 1043
• For each Ri in R, let Di be the result of dereferencing Ri. 1044
• If Di cannot be determined, then the transform MUST signal a failure. 1045
• If Di is an XML security token (e.g., a SAML assertion or a 1046
<wsse:BinarySecurityToken> element), then let Ri' be Di.Otherwise, Di is a raw 1047
binary security token; i.e., an octet stream. In this case, let Ri' be a node set consisting of 1048
a <wsse:BinarySecurityToken> element, utilizing the same namespace prefix as 1049
the <wsse:SecurityTokenReference> element Ri, with no EncodingType attribute, 1050
a ValueType attribute identifying the content of the security token, and text content 1051
consisting of the binary-encoded security token, with no white space. 1052
• Finally, employ the canonicalization method specified as a parameter to the transform to 1053
serialize N to produce the octet stream output of this transform; but, in place of any 1054
dereferenced <wsse:SecurityTokenReference> element Ri and its descendants, 1055
process the dereferenced node set Ri' instead. During this step, canonicalization of the 1056
replacement node set MUST be augmented as follows: 1057
o Note: A namespace declaration xmlns="" MUST be emitted with every apex 1058
element that has no namespace node declaring a value for the default 1059
namespace; cf. XML Decryption Transform. 1060
8.4 Signature Validation
1061
The validation of a <ds:Signature> element inside an <wsse:Security> header block 1062
SHALL fail if: 1063
• the syntax of the content of the element does not conform to this specification, or 1064
• the validation of the signature contained in the element fails according to the core 1065
validation of the XML Signature specification [XMLSIG], or 1066
WSS: SOAP Message Security (WS-Security 2004) 15 March 2004
Copyright © OASIS Open 2002-2004. All Rights Reserved. Page 31 of 56

• the application applying its own validation policy rejects the message for some reason 1067
(e.g., the signature is created by an untrusted key – verifying the previous two steps only 1068
performs cryptographic validation of the signature). 1069