This document indicates the policy assertions for use with [WS-Policy] which apply to WSS: SOAP Message Security [WSS10, WSS11], [WS-Trust] and [WS-SecureConversation]

Status:

This document was last revised or approved by the WS-SX TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

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 http://www.oasis-open.org/committees/ws-sx.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-open.org/committees/ws-sx/ipr.php).

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/ws-sx.

Notices

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

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 available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on 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 implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

Table of Contents

1.4.1 Notational Conventions 9

1.5 Normative References 10

1.6 Non-Normative References 13

2 Security Policy Model 14

2.1 Security Assertion Model 14

2.2 Nested Policy Assertions 15

2.3 Security Binding Abstraction 15

3 Policy Considerations 17

3.1 Nested Policy 17

3.2 Policy Subjects 17

4 Protection Assertions 19

4.1 Integrity Assertions 19

4.1.1 SignedParts Assertion 19

4.1.2 SignedElements Assertion 20

4.2 Confidentiality Assertions 21

4.2.1 EncryptedParts Assertion 21

4.2.2 EncryptedElements Assertion 22

4.2.3 ContentEncryptedElements Assertion 22

4.3 Required Elements Assertion 23

4.3.1 RequiredElements Assertion 23

4.3.2 RequiredParts Assertion 24

5 Token Assertions 25

5.1 Token Inclusion 25

5.1.1 Token Inclusion Values 25

5.1.2 Token Inclusion and Token References 26

5.2 Token Issuer and Required Claims 26

5.2.1 Token Issuer 26

5.2.2 Token Issuer Name. 26

5.2.3 Required Claims 26

5.2.4 Processing Rules and Token Matching. 27

5.3 Token Properties 27

5.3.1 [Derived Keys] Property 27

5.3.2 [Explicit Derived Keys] Property 27

5.3.3 [Implied Derived Keys] Property 27

5.4 Token Assertion Types 27

5.4.1 UsernameToken Assertion 27

5.4.2 IssuedToken Assertion 29

5.4.3 X509Token Assertion 31

5.4.4 KerberosToken Assertion 33

5.4.5 SpnegoContextToken Assertion 34

5.4.6 SecurityContextToken Assertion 36

5.4.7 SecureConversationToken Assertion 37

5.4.8 SamlToken Assertion 40

5.4.9 RelToken Assertion 42

5.4.10 HttpsToken Assertion 43

5.4.11 KeyValueToken Assertion. 44

6 Security Binding Properties 47

6.1 [Algorithm Suite] Property 47

6.2 [Timestamp] Property 49

6.3 [Protection Order] Property 49

6.4 [Signature Protection] Property 49

6.5 [Token Protection] Property 50

6.6 [Entire Header and Body Signatures] Property 50

6.7 [Security Header Layout] Property 50

6.7.1 Strict Layout Rules for WSS 1.0 50

7 Security Binding Assertions 53

7.1 AlgorithmSuite Assertion 53

7.2 Layout Assertion 55

7.3 TransportBinding Assertion 56

7.4 SymmetricBinding Assertion 57

7.5 AsymmetricBinding Assertion 59

8 Supporting Tokens 62

8.1 SupportingTokens Assertion 63

8.2 SignedSupportingTokens Assertion 64

8.3 EndorsingSupportingTokens Assertion 66

8.4 SignedEndorsingSupportingTokens Assertion 68

8.5 SignedEncryptedSupportingTokens Assertion 70

8.6 EncryptedSupportingTokens Assertion 70

8.7 EndorsingEncryptedSupportingTokens Assertion 70

8.8 SignedEndorsingEncryptedSupportingTokens Assertion 70

8.9 Interaction between [Token Protection] property and supporting token assertions 70

8.10 Example 71

9 WSS: SOAP Message Security Options 72

9.1 Wss10 Assertion 73

9.2 Wss11 Assertion 74

10 WS-Trust Options 76

10.1 Trust13 Assertion 77

11 Guidance on creating new assertions and assertion extensibility 79

11.1 General Design Points 79

11.2 Detailed Design Guidance 79

12 Security Considerations 81

A. Assertions and WS-PolicyAttachment 82

A.1 Endpoint Policy Subject Assertions 82

A.1.1 Security Binding Assertions 82

A.1.2 Token Assertions 82

A.1.3 WSS: SOAP Message Security 1.0 Assertions 82

A.1.4 WSS: SOAP Message Security 1.1 Assertions 82

A.1.5 Trust 1.0 Assertions 82

A.2 Operation Policy Subject Assertions 82

A.2.1 Security Binding Assertions 82

A.2.2 Supporting Token Assertions 82

A.3 Message Policy Subject Assertions 83

A.3.1 Supporting Token Assertions 83

A.3.2 Protection Assertions 83

A.4 Assertions With Undefined Policy Subject 83

A.4.1 General Assertions 83

A.4.2 Token Usage Assertions 83

A.4.3 Token Assertions 83

B. Issued Token Policy 85

C. Strict Security Header Layout Examples 87

C.1 Transport Binding. 87

C.1.1 Policy 87

C.1.2 Initiator to Recipient Messages 88

C.1.3 Recipient to Initiator Messages 89

C.2 Symmetric Binding. 90

C.2.1 Policy 91

C.2.2 Initiator to Recipient Messages 92

C.2.3 Recipient to Initiator Messages 96

C.3 Asymmetric Binding. 99

C.3.1 Policy 99

C.3.2 Initiator to Recipient Messages 101

C.3.3 Recipient to Initiator Messages 105

D. Signed and Encrypted Elements in the Security Header 109

D.1 Elements signed by the message signature 109

D.2 Elements signed by all endorsing signatures 109

D.3 Elements signed by a specific endorsing signature 109

D.4 Elements that are encrypted. 109

E. Acknowledgements 110

1 Introduction

WS-Policy defines a framework for allowing web services to express their constraints and requirements. Such constraints and requirements are expressed as policy assertions. This document defines a set of security policy assertions for use with the [WS-Policy] framework with respect to security features provided in WSS: SOAP Message Security [WSS10, WSS11], [WS-Trust] and [WS-SecureConversation]. The assertions defined within this specification have been designed to work independently of a specific version of WS-Policy. At the time of the publication of this specification the versions of WS-Policy known to correctly compose with this specification are WS-Policy 1.2 and 1.5. Within this specification the use of the namespace prefix wsp refers generically to the WS-Policy namespace, not a specific version. This document takes the approach of defining a base set of assertions that describe how messages are to be secured. Flexibility with respect to token types, cryptographic algorithms and mechanisms used, including using transport level security is part of the design and allows for evolution over time. The intent is to provide enough information for compatibility and interoperability to be determined by web service participants along with all information necessary to actually enable a participant to engage in a secure exchange of messages.

Sections 11, 12 and all examples and all Appendices are non-normative.

1.1 Example

Table 1 shows an "Effective Policy" example, including binding assertions and associated property assertions, token assertions and integrity and confidentiality assertions. This example has a scope of [Endpoint Policy Subject], but for brevity the attachment mechanism is not shown.

Table 1: Example security policy.

(01) <wsp:Policy xmlns:wsp="..." xmlns:sp="...">

(02) <sp:SymmetricBinding>

(03) <wsp:Policy>

(04) <sp:ProtectionToken>

(05) <wsp:Policy>

(06) <sp:Kerberos sp:IncludeToken=".../IncludeToken/Once" />

(07) <wsp:Policy>

(08) <sp:WSSKerberosV5ApReqToken11/>

(09) <wsp:Policy>

(10) </sp:Kerberos>

(11) </wsp:Policy>

(12) </sp:ProtectionToken>

(13) <sp:SignBeforeEncrypting />

(14) <sp:EncryptSignature />

(15) </wsp:Policy>

(16) </sp:SymmetricBinding>

(17) <sp:SignedParts>

(18) <sp:Body/>

(19)     <sp:Header
       Namespace="http://schemas.xmlsoap.org/ws/2004/08/addressing"
    />

(20) </sp:SignedParts>

(21) <sp:EncryptedParts>

(22) <sp:Body/>

(23) </sp:EncryptedParts>

(24) </wsp:Policy>

Line 1 in Table 1 indicates that this is a policy statement and that all assertions contained by the wsp:Policy element are required to be satisfied. Line 2 indicates the kind of security binding in force. Line 3 indicates a nested wsp:Policy element which contains assertions that qualify the behavior of the SymmetricBinding assertion. Line 4 indicates a ProtectionToken assertion. Line 5 indicates a nested wsp:Policy element which contains assertions indicating the type of token to be used for the ProtectionToken. Lines 6 to 10 indicate that a Kerberos V5 APREQ token is to be used by both parties in a message exchange for protection. Line 13 indicates that signatures are generated over plaintext rather than ciphertext. Line 14 indicates that the signature over the signed messages parts is required to be encrypted. Lines 17-20 indicate which message parts are to be covered by the primary signature; in this case the soap:Body element, indicated by Line 18 and any SOAP headers in the WS-Addressing namespace, indicated by line 19. Lines 21-23 indicate which message parts are to be encrypted; in this case just the soap:Body element, indicated by Line 22.

1.2 Namespaces

The XML namespace URI that MUST be used by implementations of this specification is:

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702

Table 2 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 2: Prefixes and XML Namespaces used in this specification.

Prefix	Namespace	Specification(s)
S	http://schemas.xmlsoap.org/soap/envelope/	[SOAP]
S12	http://www.w3.org/2003/05/soap-envelope	[SOAP12]
ds	http://www.w3.org/2000/09/xmldsig#	[XML-Signature]
enc	http://www.w3.org/2001/04/xmlenc#	[XML-Encrypt]
wsu	http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd	[WSS10]