1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Web Services Security:
SOAP Message Security 1.1
(WS-Security 2004)
OASIS Standard Specification, 1 February 2006
OASIS identifier:
wss-v1.1-spec-os-SOAPMessageSecurity
Location:
http://docs.oasis-open.org/wss/v1.1/
Technical Committee:
Web Service Security (WSS)
Chairs:
Editors:
Kelvin Lawrence, IBM
Chris Kaler, Microsoft
Anthony Nadalin, IBM
Chris Kaler, Microsoft
Ronald Monzillo, Sun
Phillip Hallam-Baker, Verisign
Abstract:
This specification describes enhancements to SOAP messaging to provide message
integrity and confidentiality. The specified mechanisms can be used to accommodate a
wide variety of security models and encryption technologies.
This specification also provides a general-purpose mechanism for associating security
tokens with message content. No specific type of security token is required, the
specification is designed to be extensible (i.e.. support multiple security token formats).
For example, a client might provide one format for proof of identity and provide another
format for proof that they have a particular business certification.
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 1 of 76
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
Additionally, this specification describes how to encode binary security tokens, a
framework for XML-based tokens, and how to include opaque encrypted keys. It also
includes extensibility mechanisms that can be used to further describe the characteristics
of the tokens that are included with a message.
Status:
This is an OASIS Standard document produced by the Web Services Security Technical
Committee. It was approved by the OASIS membership on 1 February 2006. Check the
current location noted above for possible errata to this document.
Technical Committee members should send comments on this specification to the
technical Committee’s email list. Others should send comments to the Technical
Committee by using the “Send A Comment” button on the Technical Committee’s web
page at www.oasisopen.org/committees/wss.
For patent disclosure information that may be essential to the implementation of this
specification, and any offers of licensing terms, refer to the Intellectual Property Rights
section of the OASIS Web Services Security Technical Committee (WSS TC) web page
at http://www.oasis-open.org/committees/wss/ipr.php. General OASIS IPR information
can be found at http://www.oasis-open.org/who/intellectualproperty.shtml.
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 2 of 76
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
Notices
OASIS takes no position regarding the validity or scope of any intellectual property or other rights
that might be claimed to pertain to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or might not be vailable;
neither does it represent that it has made any effort to identify any such rights. Information on
OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS
website. Copies of claims of rights made available for publication and any assurances of licenses
to be made available, or the result of an attempt made to obtain a general license or permission
for the use of such proprietary rights by implementors or users of this specification, can be
obtained from the OASIS Executive Director. OASIS invites any interested party to bring to its
attention any copyrights, patents or patent applications, or other proprietary rights which may
cover technology that may be required to implement this specification. Please address the
information to the OASIS Executive Director.
Copyright (C) OASIS Open 2002-2006. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works
that comment on or otherwise explain it or assist in its implementation may be prepared, copied,
published and distributed, in whole or in part, without restriction of any kind, provided that the
above copyright notice and this paragraph are included on all such copies and derivative works.
However, this document itself may not be modified in any way, such as by removing the copyright
notice or references to OASIS, except as needed for the purpose of developing OASIS
specifications, in which case the procedures for copyrights defined in the OASIS Intellectual
Property Rights document must be followed, or as required to translate it into languages other
than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its
successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE
ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.
OASIS has been notified of intellectual property rights claimed in regard to some or all of the
contents of this specification. For more information consult the online list of claimed rights.
This section is non-normative.
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 3 of 76
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
Table of Contents
1
2
4
Introduction ............................................................................................................................. 7
1.1 Goals and Requirements ...................................................................................................... 7
1.1.1 Requirements................................................................................................................. 8
1.1.2 Non-Goals...................................................................................................................... 8
Notations and Terminology..................................................................................................... 9
2.1 Notational Conventions ......................................................................................................... 9
2.2 Namespaces ......................................................................................................................... 9
2.3 Acronyms and Abbreviations .............................................................................................. 10
2.4 Terminology......................................................................................................................... 11
2.5 Note on Examples............................................................................................................... 12
3 Message Protection Mechanisms......................................................................................... 13
3.1 Message Security Model..................................................................................................... 13
3.2 Message Protection............................................................................................................. 13
3.3 Invalid or Missing Claims .................................................................................................... 14
3.4 Example .............................................................................................................................. 14
ID References ....................................................................................................................... 17
4.1 Id Attribute........................................................................................................................... 17
4.2 Id Schema ........................................................................................................................... 18
Security Header .................................................................................................................... 20
Security Tokens .................................................................................................................... 23
6.1 Attaching Security Tokens .................................................................................................. 23
6.1.1 Processing Rules......................................................................................................... 23
6.1.2 Subject Confirmation.................................................................................................... 23
6.2 User Name Token ............................................................................................................... 23
6.2.1 Usernames................................................................................................................... 23
6.3 Binary Security Tokens ....................................................................................................... 24
6.3.1 Attaching Security Tokens ........................................................................................... 24
6.3.2 Encoding Binary Security Tokens................................................................................ 24
6.4 XML Tokens ........................................................................................................................ 26
6.5 EncryptedData Token ......................................................................................................... 26
6.6 Identifying and Referencing Security Tokens ..................................................................... 26
Token References................................................................................................................. 27
7.1 SecurityTokenReference Element ...................................................................................... 27
7.2 Direct References................................................................................................................ 29
5
6
7
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 4 of 76
9
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
8
7.3 Key Identifiers...................................................................................................................... 30
7.4 Embedded References ....................................................................................................... 32
7.5 ds:KeyInfo ........................................................................................................................... 33
7.6 Key Names.......................................................................................................................... 33
7.7 Encrypted Key reference..................................................................................................... 34
Signatures............................................................................................................................. 35
8.1 Algorithms ........................................................................................................................... 35
8.2 Signing Messages............................................................................................................... 38
8.3 Signing Tokens.................................................................................................................... 38
8.4 Signature Validation ............................................................................................................ 41
8.5 Signature Confirmation ....................................................................................................... 42
8.5.1 Response Generation Rules........................................................................................ 43
8.5.2 Response Processing Rules........................................................................................ 43
8.6 Example .............................................................................................................................. 44
Encryption ............................................................................................................................. 45
9.1 xenc:ReferenceList ............................................................................................................. 45
9.2 xenc:EncryptedKey ............................................................................................................. 46
9.3 Encrypted Header ............................................................................................................... 47
9.4 Processing Rules ................................................................................................................ 47
9.4.1 Encryption .................................................................................................................... 48
9.4.2 Decryption.................................................................................................................... 48
9.4.3 Encryption with EncryptedHeader ............................................................................... 49
9.4.4 Processing an EncryptedHeader................................................................................. 49
9.4.5 Processing the mustUnderstand attribute on EncryptedHeader ................................. 50
10 Security Timestamps ............................................................................................................ 51
11 Extended Example................................................................................................................ 54
12 Error Handling....................................................................................................................... 57
13 Security Considerations........................................................................................................ 59
13.1 General Considerations .................................................................................................... 59
13.2 Additional Considerations ................................................................................................. 59
13.2.1 Replay........................................................................................................................ 59
13.2.2 Combining Security Mechanisms .............................................................................. 60
13.2.3 Challenges ................................................................................................................. 60
13.2.4 Protecting Security Tokens and Keys........................................................................ 60
13.2.5 Protecting Timestamps and Ids ................................................................................. 61
13.2.6 Protecting against removal and modification of XML Elements ................................ 61
13.2.7 Detecting Duplicate Identifiers ................................................................................... 62
Interoperability Notes............................................................................................................ 63
1 February 2006
Page 5 of 76
14
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
163
164
165
166
167
168
169
170
171
172
15 Privacy Considerations ......................................................................................................... 64
16 References............................................................................................................................ 65
Appendix A: Acknowledgements................................................................................................... 67
Appendix B: Revision History ........................................................................................................ 70
Appendix C: Utility Elements and Attributes.................................................................................. 71
16.1 Identification Attribute........................................................................................................ 71
16.2 Timestamp Elements ........................................................................................................ 71
16.3 General Schema Types .................................................................................................... 72
Appendix D: SecurityTokenReference Model ............................................................................... 73
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 6 of 76
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
1 Introduction
This OASIS specification is the result of significant new work by the WSS Technical Committee
and supersedes the input submissions, Web Service Security (WS-Security) Version 1.0 April 5,
2002 and Web Services Security Addendum Version 1.0 August 18, 2002.
This specification proposes a standard set of SOAP [SOAP11, SOAP12] extensions that can be
used when building secure Web services to implement message content integrity and
confidentiality. This specification refers to this set of extensions and modules as the “Web
Services Security: SOAP Message Security” or “WSS: SOAP Message Security”.
This specification is flexible and is designed to be used as the basis for securing Web services
within a wide variety of security models including PKI, Kerberos, and SSL. Specifically, this
specification provides support for multiple security token formats, multiple trust domains, multiple
signature formats, and multiple encryption technologies. The token formats and semantics for
using these are defined in the associated profile documents.
This specification provides three main mechanisms: ability to send security tokens as part of a
message, message integrity, and message confidentiality. These mechanisms by themselves do
not provide a complete security solution for Web services. Instead, this specification is a building
block that can be used in conjunction with other Web service extensions and higher-level
application-specific protocols to accommodate a wide variety of security models and security
technologies.
These mechanisms can be used independently (e.g., to pass a security token) or in a tightly
coupled manner (e.g., signing and encrypting a message or part of a message and providing a
security token or token path associated with the keys used for signing and encryption).
1.1 Goals and Requirements
The goal of this specification is to enable applications to conduct secure SOAP message
exchanges.
This specification is intended to provide a flexible set of mechanisms that can be used to
construct a range of security protocols; in other words this specification intentionally does not
describe explicit fixed security protocols.
As with every security protocol, significant efforts must be applied to ensure that security
protocols constructed using this specification are not vulnerable to any one of a wide range of
attacks. The examples in this specification are meant to illustrate the syntax of these mechanisms
and are not intended as examples of combining these mechanisms in secure ways.
The focus of this specification is to describe a single-message security language that provides for
message security that may assume an established session, security context and/or policy
agreement.
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 7 of 76
215
The requirements to support secure message exchange are listed below.
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
1.1.1 Requirements
The Web services security language must support a wide variety of security models. The
following list identifies the key driving requirements for this specification:
• Multiple security token formats
• Multiple trust domains
• Multiple signature formats
• Multiple encryption technologies
• End-to-end message content security and not just transport-level security
1.1.2 Non-Goals
The following topics are outside the scope of this document:
• Establishing a security context or authentication mechanisms.
• Key derivation.
• Advertisement and exchange of security policy.
• How trust is established or determined.
• Non-repudiation.
WSS: SOAP Message Security (WS-Security 2004)
Copyright © OASIS Open 2002-2006. All Rights Reserved.
1 February 2006
Page 8 of 76