WS-SecurityPolicy 1.2

Committee Draft 01, 4 December 2006

Artifact Identifier:

ws-securitypolicy-1.2-spec-cd-01

Location:

Current: docs.oasis-open.org/ws-sx/ws-securitypolicy/200512

This Version: docs.oasis-open.org/ws-sx/ws-securitypolicy/200512

Previous Version: n/a

Artifact Type:

specification

Technical Committee:

OASIS Web Services Secure Exchange TC

Chair(s):

Kelvin Lawrence, IBM

Chris Kaler, Microsoft

Editor(s):

Anthony Nadalin, IBM

Marc Goodner, Microsoft

Martin Gudgin, Microsoft

Abbie Barbir, Nortel

Hans Granqvist, VeriSign

OASIS Conceptual Model topic area:

Related work:

N/A

Abstract:

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.

Table of Contents

1.4.1 Notational Conventions 8

1.5 Normative References 9

1.6 Non-Normative References 12

2 Security Policy Model 13

2.1 Security Assertion Model 13

2.2 Nested Policy Assertions 14

2.3 Security Binding Abstraction 14

3 Policy Considerations 15

3.1 Nested Policy 15

3.2 Policy Subjects 15

4 Protection Assertions 17

4.1 Integrity Assertions 17

4.1.1 SignedParts Assertion 17

4.1.2 SignedElements Assertion 18

4.2 Confidentiality Assertions 18

4.2.1 EncryptedParts Assertion 19

4.2.2 EncryptedElements Assertion 20

4.2.3 ContentEncryptedElements Assertion 20

4.3 Required Elements Assertion 21

4.3.1 RequiredElements Assertion 21

4.3.2 RequiredParts Assertion 21

5 Token Assertions 23

5.1 Token Inclusion 23

5.1.1 Token Inclusion Values 23

5.1.2 Token Inclusion and Token References 24

5.2 Token Properties 24

5.2.1 [Derived Keys] Property 24

5.2.2 [Explicit Derived Keys] Property 24

5.2.3 [Implicit Derived Keys] Property 24

5.3 Token Assertion Types 24

5.3.1 UsernameToken Assertion 24

5.3.2 IssuedToken Assertion 26

5.3.3 X509Token Assertion 27

5.3.4 KerberosToken Assertion 29

5.3.5 SpnegoContextToken Assertion 30

5.3.6 SecurityContextToken Assertion 31

5.3.7 SecureConversationToken Assertion 32

5.3.8 SamlToken Assertion 34

5.3.9 RelToken Assertion 36

5.3.10 HttpsToken Assertion 37

6 Security Binding Properties 38

6.1 [Algorithm Suite] Property 38

6.2 [Timestamp] Property 40

6.3 [Protection Order] Property 40

6.4 [Signature Protection] Property 40

6.5 [Token Protection] Property 41

6.6 [Entire Header and Body Signatures] Property 41

6.7 [Security Header Layout] Property 41

6.7.1 Strict Layout Rules for WSS 1.0 41

7 Security Binding Assertions 44

7.1 AlgorithmSuite Assertion 44

7.2 Layout Assertion 46

7.3 TransportBinding Assertion 47

7.4 SymmetricBinding Assertion 48

7.5 AsymmetricBinding Assertion 50

8 Supporting Tokens 53

8.1 SupportingTokens Assertion 54

8.2 SignedSupportingTokens Assertion 55

8.3 EndorsingSupportingTokens Assertion 57

8.4 SignedEndorsingSupportingTokens Assertion 59

8.5 SignedEncryptedSupportingTokens Assertion 61

8.6 EndorsingEncryptedSupportingTokens Assertion 61

8.7 SignedEndorsingEncryptedSupportingTokens Assertion 61

8.8 Interaction between [Token Protection] property and supporting token assertions 61

8.9 Example 61

9 WSS: SOAP Message Security Options 63

9.1 Wss10 Assertion 64

9.2 Wss11 Assertion 65

10 WS-Trust Options 67

10.1 Trust10 Assertion 68

11 Guidance on creating new assertions and assertion extensibility 69

11.1 General Design Points 69

11.2 Detailed Design Guidance 69

12 Security Considerations 71

A. Assertions and WS-PolicyAttachment 72

A.1 Endpoint Policy Subject Assertions 72

A.1.1 Security Binding Assertions 72

A.1.2 Token Assertions 72

A.1.3 WSS: SOAP Message Security 1.0 Assertions 72

A.1.4 WSS: SOAP Message Security 1.1 Assertions 72

A.1.5 Trust 1.0 Assertions 72

A.2 Operation Policy Subject Assertions 72

A.2.1 Security Binding Assertions 72

A.2.2 Supporting Token Assertions 72

A.3 Message Policy Subject Assertions 73

A.3.1 Supporting Token Assertions 73

A.3.2 Protection Assertions 73

A.4 Assertions With Undefined Policy Subject 73

A.4.1 General Assertions 73

A.4.2 Token Usage Assertions 73

A.4.3 Token Assertions 73

B. Issued Token Policy 75

C. Strict Security Header Layout Examples 77

C.1 Transport Binding. 77

C.1.1 Policy 77

C.1.2 Initiator to Recipient Messages 78

C.1.3 Recipient to Initiator Messages 79

C.2 Symmetric Binding. 80

C.2.1 Policy 81

C.2.2 Initiator to Recipient Messages 82

C.2.3 Recipient to Initiator Messages 86

C.3 Asymmetric Binding. 89

C.3.1 Policy 89

C.3.2 Initiator to Recipient Messages 91

C.3.3 Recipient to Initiator Messages 95

D. Signed and Encrypted Elements in the Security Header 99

D.1 Elements signed by the message signature 99

D.2 Elements signed by all endorsing signatures 99

D.3 Elements signed by a specific endorsing signature 99

D.4 Elements that are encrypted. 99

E. Acknowledgements 100

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]. 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/200512

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]
wsse	http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd	[WSS10]
wsse11	http://docs.oasis-open.org/wss/oasis-wss-wsecurity-secext-1.1.xsd	[WSS11]
wsp	http://schemas.xmlsoap.org/ws/2004/09/policy	[WS-Policy], [WS-PolicyAttachment]