WS-Trust V1 - OASIS€¦ · ws-trust-1.3-spec-ed-07 09 May 2006 ... [WS-Security] to provide a ......

ws-trust-1.3-spec-ed-07 09 May 2006 Copyright © OASIS Open 2006. All Rights Reserved. of 76

WS-Trust V1.3 Editors Draft 01, 09 May 2006 Artifact Identifier:

ws-trust-1.3-spec-ed-07 Location:

Current: docs.oasis-open.org/ws-sx/200512/ws-trust This Version: docs.oasis-open.org/ws-sx/200512/ws-trust Previous Version: N/A

Artifact Type: specification

Technical Committee: OASIS Web Service Secure Exchange TC

Chair(s): Kelvin Lawrence, IBM Chris Kaler, Microsoft

Editor(s): Anthony Nadalin, IBM Martin Gudgin, Microsoft Abbie Barbir, Nortel Hans Granqvist, VeriSign

OASIS Conceptual Model topic area: [Topic Area]

Related work: N/A

Abstract: This specification defines extensions that build on [WS-Security] to provide a framework for requesting and issuing security tokens, and to broker trust relationships.

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 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 (www.oasis-open.org/committees/ws-sx/ipr.php. The non-normative errata page for this specification is located at www.oasis-open.org/committees/ws-sx.

Deleted: 26

Deleted: April

Deleted: 06

Deleted: 5

Deleted: 26

Deleted: April


Notices Copyright © OASIS Open 2006. All Rights Reserved. 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.

Deleted: 5

Deleted: 26

Deleted: April


Table of Contents 1 Introduction ........................................................................................................................................5

1.1 Goals and Non-Goals.......................................................................................................................5 1.2 Requirements...................................................................................................................................6 1.3 Namespace......................................................................................................................................6 1.4 Schema and WSDL Files .................................................................................................................7 1.5 Terminology .....................................................................................................................................7

1.5.1 Notational Conventions.............................................................................................................8 1.6 Normative References......................................................................................................................8 1.7 Non-Normative References..............................................................................................................9

2 Web Services Trust Model ...............................................................................................................10 2.1 Models for Trust Brokering and Assessment..................................................................................12 2.2 Token Acquisition...........................................................................................................................12 2.3 Out-of-Band Token Acquisition.......................................................................................................12 2.4 Trust Bootstrap...............................................................................................................................12

3 Security Token Service Framework .................................................................................................14 3.1 Requesting a Security Token .........................................................................................................14 3.2 Returning a Security Token............................................................................................................15 3.3 Binary Secrets................................................................................................................................17 3.4 Composition ...................................................................................................................................18

4 Issuance Binding .............................................................................................................................19 4.1 Requesting a Security Token .........................................................................................................19 4.2 Returning a Security Token............................................................................................................22

4.2.1 wsp:AppliesTo in RST and RSTR ...........................................................................................25 4.2.2 Requested References ...........................................................................................................26 4.2.3 Keys and Entropy....................................................................................................................26 4.2.4 Returning Computed Keys ......................................................................................................27 4.2.5 Sample Response with Encrypted Secret ...............................................................................28 4.2.6 Sample Response with Unencrypted Secret ...........................................................................28 4.2.7 Sample Response with Token Reference ...............................................................................29 4.2.8 Sample Response without Proof-of-Possession Token...........................................................29

4.3 Returning Multiple Security Tokens...................................................Error! Bookmark not defined. 4.3.1 Zero or One Proof-of-Possession Token Case .......................................................................29 4.3.2 More Than One Proof-of-Possession Tokens Case ................................................................30

4.4 Returning Security Tokens in Headers...........................................................................................31 5 Renewal Binding..............................................................................................................................33 6 Cancel Binding.................................................................................................................................36 7 Validation Binding ............................................................................................................................39 8 Negotiation and Challenge Extensions ............................................................................................42

8.1 Negotiation and Challenge Framework ..........................................................................................43 8.2 Signature Challenges.....................................................................................................................43 8.3 Binary Exchanges and Negotiations...............................................................................................44 8.4 Key Exchange Tokens ...................................................................................................................45 8.5 Custom Exchanges ........................................................................................................................46

Deleted: 28

Deleted: 29

Deleted: 44

Deleted: 44

Deleted: 5

Deleted: 26

Deleted: April


8.6 Signature Challenge Example........................................................................................................46 8.7 Custom Exchange Example ...........................................................................................................48 8.8 Protecting Exchanges ....................................................................................................................49 8.9 Authenticating Exchanges..............................................................................................................50

9 Key and Token Parameter Extensions.............................................................................................52 9.1 On-Behalf-Of Parameters...............................................................................................................52 9.2 Key and Encryption Requirements .................................................................................................52 9.3 Delegation and Forwarding Requirements .....................................................................................56 9.4 Policies...........................................................................................................................................57 9.5 Authorized Token Participants........................................................................................................57

10 Key Exchange Token Binding..........................................................................................................59 11 Error Handling..................................................................................................................................61 12 Security Considerations ...................................................................................................................62 A. Key Exchange..................................................................................................................................64

A.1 Ephemeral Encryption Keys...........................................................................................................64 A.2 Requestor-Provided Keys ..............................................................................................................65 A.3 Issuer-Provided Keys.....................................................................................................................65 A.4 Composite Keys.............................................................................................................................66 A.5 Key Transfer and Distribution ........................................................................................................66

A.5.1 Direct Key Transfer.................................................................................................................66 A.5.2 Brokered Key Distribution .......................................................................................................67 A.5.3 Delegated Key Transfer..........................................................................................................67 A.5.4 Authenticated Request/Reply Key Transfer ............................................................................68

A.6 Perfect Forward Secrecy ...............................................................................................................69 B. WSDL ..............................................................................................................................................71 C. Acknowledgements..........................................................................................................................73 D. Non-Normative Text.........................................................................................................................75 E. Revision History...............................................................................................................................76

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 44

Deleted: 5

Deleted: 26

Deleted: April


1 Introduction 1

[WS-Security] defines the basic mechanisms for providing secure messaging. This 2 specification uses these base mechanisms and defines additional primitives and extensions 3 for security token exchange to enable the issuance and dissemination of credentials within 4 different trust domains. 5 6 In order to secure a communication between two parties, the two parties must exchange 7 security credentials (either directly or indirectly). However, each party needs to determine 8 if they can "trust" the asserted credentials of the other party. 9 10 In this specification we define extensions to [WS-Security] that provide: 11 • Methods for issuing, renewing, and validating security tokens. 12 • Ways to establish, assess the presence of, and broker trust relationships. 13 14 Using these extensions, applications can engage in secure communication designed to work 15 with the general Web services framework, including WSDL service descriptions, UDDI 16 businessServices and bindingTemplates, and [SOAP] messages. 17 18 To achieve this, this specification introduces a number of elements that are used to request 19 security tokens and broker trust relationships. 20 21 This specification defines a number of extensions; compliant services are NOT REQUIRED to 22 implement everything defined in this specification. However, if a service implements an 23 aspect of the specification, it MUST comply with the requirements specified (e.g. related 24 "MUST" statements). 25 26 Section 12 is non-normative. 27

1.1 Goals and Non-Goals 28

The goal of WS-Trust is to enable applications to construct trusted [SOAP] message 29 exchanges. This trust is represented through the exchange and brokering of security tokens. 30 This specification provides a protocol agnostic way to issue, renew, and validate these 31 security tokens. 32 33 This specification is intended to provide a flexible set of mechanisms that can be used to 34 support a range of security protocols; this specification intentionally does not describe 35 explicit fixed security protocols. 36 37 As with every security protocol, significant efforts must be applied to ensure that specific 38 profiles and message exchanges constructed using WS-Trust are not vulnerable to attacks 39 (or at least that the attacks are understood). 40 41

Deleted: 5

Deleted: 26

Deleted: April


The following are explicit non-goals for this document: 42 • Password authentication 43 • Token revocation 44 • Management of trust policies 45 46 Additionally, the following topics are outside the scope of this document: 47 • Establishing a security context token 48 • Key derivation 49

1.2 Requirements 50

The Web services trust specification must support a wide variety of security models. The 51 following list identifies the key driving requirements for this specification: 52 • Requesting and obtaining security tokens 53 • Establishing, managing and assessing trust relationships 54

1.3 Namespace 55

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

http://docs.oasis-open.org/ws-sx/ws-trust/200512 57

The following namespaces are used in this document: 58

Prefix Namespace

S11 http://schemas.xmlsoap.org/soap/envelope/

S12 http://www.w3.org/2003/05/soap-envelope

wsu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

wsse http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd

wst http://docs.oasis-open.org/ws-sx/ws-trust/200512

ds http://www.w3.org/2000/09/xmldsig#

xenc http://www.w3.org/2001/04/xmlenc#

wsp http://schemas.xmlsoap.org/ws/2004/09/policy

wsa http://schemas.xmlsoap.org/ws/2004/08/addressing

xs http://www.w3.org/2001/XMLSchema

Deleted: 5

Deleted: 26

Deleted: April


1.4 Schema and WSDL Files 59

The schema for this specification can be located at: 60

http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust.xsd 61

62 The WSDL for this specification can be located in Appendix II of this document as well as at: 63

http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust.wsdl 64

In this document, reference is made to the wsu:Id attribute, wsu:Created and wsu:Expires 65 elements in the utility schema. These were added to the utility schema with the intent that other 66 specifications requiring such an ID or timestamp could reference it (as is done here). 67

1.5 Terminology 68

Claim – A claim is a statement made about a client, service or other resource (e.g. name, 69 identity, key, group, privilege, capability, etc.). 70 Security Token – A security token represents a collection of claims. 71 Signed Security Token – A signed security token is a security token that is 72 cryptographically endorsed by a specific authority (e.g. an X.509 certificate or a Kerberos 73 ticket). 74 Proof-of-Possession Token – A proof-of-possession (POP) token is a security token that 75 contains secret data that can be used to demonstrate authorized use of an associated 76 security token. Typically, although not exclusively, the proof-of-possession information is 77 encrypted with a key known only to the recipient of the POP token. 78 Digest – A digest is a cryptographic checksum of an octet stream. 79 Signature – A signature is a value computed with a cryptographic algorithm and bound to 80 data in such a way that intended recipients of the data can use the signature to verify that 81 the data has not been altered and/or has originated from the signer of the message, 82 providing message integrity and authentication. The signature can be computed and verified 83 with symmetric key algorithms, where the same key is used for signing and verifying, or 84 with asymmetric key algorithms, where different keys are used for signing and verifying (a 85 private and public key pair are used). 86 Trust Engine – The trust engine of a Web service is a conceptual component that evaluates 87 the security-related aspects of a message as described in section 2 below. 88 Security Token Service – A security token service (STS) is a Web service that issues 89 security tokens (see [WS-Security]). That is, it makes assertions based on evidence that it 90 trusts, to whoever trusts it (or to specific recipients). To communicate trust, a service 91 requires proof, such as a signature to prove knowledge of a security token or set of security 92 tokens. A service itself can generate tokens or it can rely on a separate STS to issue a 93 security token with its own trust statement (note that for some security token formats this 94 can just be a re-issuance or co-signature). This forms the basis of trust brokering. 95 Trust – Trust is the characteristic that one entity is willing to rely upon a second entity to 96 execute a set of actions and/or to make set of assertions about a set of subjects and/or 97 scopes. 98 Direct Trust – Direct trust is when a relying party accepts as true all (or some subset of) 99 the claims in the token sent by the requestor. 100 Direct Brokered Trust – Direct Brokered Trust is when one party trusts a second party 101 who, in turn, trusts or vouches for, a third party. 102

Deleted: 5

Deleted: 26

Deleted: April


Indirect Brokered Trust – Indirect Brokered Trust is a variation on direct brokered trust 103 where the second party negotiates with the third party, or additional parties, to assess the 104 trust of the third party. 105 Message Freshness – Message freshness is the process of verifying that the message has not been 106 replayed and is currently valid. 107 We provide basic definitions for the security terminology used in this specification. Note 108 that readers should be familiar with the [WS-Security] specification. 109

1.5.1 Notational Conventions 110

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 111 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 112 interpreted as described in [RFC2119]. 113 114 Namespace URIs of the general form "some-URI" represents some application-dependent or 115 context-dependent URI as defined in [RFC2396]. 116

1.6 Normative References 117

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, 118 http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997. 119

[RFC2246] IETF Standard, "The TLS Protocol," January 1999. 120 [SOAP] W3C Note, "SOAP: Simple Object Access Protocol 1.1," 08 May 2000. 121 [SOAP12] W3C Recommendation, "SOAP 1.2 Part 1: Messaging Framework," 24 122

June 2003. 123 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers 124

(URI): Generic Syntax," RFC 2396, MIT/LCS, U.C. Irvine, Xerox 125 Corporation, August 1998. 126

[WS-Addressing] "Web Services Addressing (WS-Addressing)," BEA, IBM, Microsoft, SAP, 127 Sun Microsystems, Inc., August 2004. 128

[WS-Federation] "Web Services Federation Language," BEA, IBM, Microsoft, RSA Security, 129 VeriSign, July 2003. 130

[WS-Policy] "Web Services Policy Framework," BEA, IBM, Microsoft, SAP, Sonic 131 Software, Verisign, September 2004. 132

[WS-PolicyAttachment] "Web Services Policy Attachment," BEA, IBM, Microsoft, SAP, Sonic 133 Software, Verisign, September 2004. 134

[WS-Security] OASIS,"Web Services Security: SOAP Message Security," 15 March 2004. 135 [WS-SecurityPolicy] "Web Services Security Policy Language," IBM, Microsoft, RSA Security, 136

VeriSign, December 2002. 137 [XML-C14N] W3C Candidate Recommendation, "Canonical XML Version 1.0," 26 138

October 2000. 139 [XML-Encrypt] W3C Recommendation, "XML Encryption Syntax and Processing," 10 140

December, 2002. 141 [XML-ns] W3C Recommendation, "Namespaces in XML," 14 January 1999. 142 [XML-Schema1] W3C Recommendation, "XML Schema Part 1: Structures,"2 May 2001. 143 [XML-Schema2] W3C Recommendation, "XML Schema Part 2: Datatypes," 2 May 2001. 144 [XML-Signature] W3C Candidate Recommendation, "XML-Signature Syntax and 145

Processing," 31 October 2000. 146 [X509] S. Santesson, et al,"Internet X.509 Public Key Infrastructure Qualified 147

Certificates Profile." 148 Deleted: 5

Deleted: 26

Deleted: April


[Kerberos] J. Kohl and C. Neuman, "The Kerberos Network Authentication Service 149 (V5)," RFC 1510, September 1993. 150

1.7 Non-Normative References 151

[Reference] [Full reference citation] 152

Deleted: 5

Deleted: 26

Deleted: April


2 Web Services Trust Model 153

The Web service security model defined in WS-Trust is based on a process in which a Web 154 service can require that an incoming message prove a set of claims (e.g., name, key, 155 permission, capability, etc.). If a message arrives without having the required proof of 156 claims, the service SHOULD ignore or reject the message. A service can indicate its 157 required claims and related information in its policy as described by [WS-Policy] and [WS-158 PolicyAttachment] specifications. 159 160 Authentication of requests is based on a combination of optional network and transport-161 provided security and information (claims) proven in the message. Requestors can 162 authenticate recipients using network and transport-provided security, claims proven in 163 messages, and encryption of the request using a key known to the recipient. 164 165 One way to demonstrate authorized use of a security token is to include a digital signature 166 using the associated secret key (from a proof-of-possession token). This allows a requestor 167 to prove a required set of claims by associating security tokens (e.g., PKIX, X.509 168 certificates) with the messages. 169 • If the requestor does not have the necessary token(s) to prove required claims to a 170

service, it can contact appropriate authorities (as indicated in the service's policy) and 171 request the needed tokens with the proper claims. These "authorities", which we refer 172 to as security token services, may in turn require their own set of claims for 173 authenticating and authorizing the request for security tokens. Security token services 174 form the basis of trust by issuing a range of security tokens that can be used to broker 175 trust relationships between different trust domains. 176

• This specification also defines a general mechanism for multi-message exchanges during 177 token acquisition. One example use of this is a challenge-response protocol that is also 178 defined in this specification. This is used by a Web service for additional challenges to a 179 requestor to ensure message freshness and verification of authorized use of a security 180 token. 181

182 This model is illustrated in the figure below, showing that any requestor may also be a 183 service, and that the Security Token Service is a Web service (that is, it may express policy 184 and require security tokens). 185 186

Deleted: 5

Deleted: 26

Deleted: April


187

This general security model – claims, policies, and security tokens – subsumes and supports 188 several more specific models such as identity-based authorization, access control lists, and 189 capabilities-based authorization. It allows use of existing technologies such as X.509 public-190 key certificates, XML-based tokens, Kerberos shared-secret tickets, and even password 191 digests. The general model in combination with the [WS-Security] and [WS-Policy] 192 primitives is sufficient to construct higher-level key exchange, authentication, policy-based 193 access control, auditing, and complex trust relationships. 194 195 In the figure above the arrows represent possible communication paths; the requestor may 196 obtain a token from the security token service, or it may have been obtained indirectly. The 197 requestor then demonstrates authorized use of the token to the Web service. The Web 198 service either trusts the issuing security token service or may request a token service to 199 validate the token (or the Web service may validate the token itself). 200 201 In summary, the Web service has a policy applied to it, receives a message from a 202 requestor that possibly includes security tokens, and may have some protection applied to it 203 using [WS-Security] mechanisms. The following key steps are performed by the trust 204 engine of a Web service (note that the order of processing is non-normative): 205

1. Verify that the claims in the token are sufficient to comply with the policy and that 206 the message conforms to the policy. 207

2. Verify that the attributes of the claimant are proven by the signatures. In brokered 208 trust models, the signature may not verify the identity of the claimant – it may verify 209 the identity of the intermediary, who may simply assert the identity of the claimant. 210 The claims are either proven or not based on policy. 211

3. Verify that the issuers of the security tokens (including all related and issuing 212 security token) are trusted to issue the claims they have made. The trust engine 213 may need to externally verify or broker tokens (that is, send tokens to a security 214 token service in order to exchange them for other security tokens that it can use 215 directly in its evaluation). 216

217 If these conditions are met, and the requestor is authorized to perform the operation, then 218 the service can process the service request. 219 In this specification we define how security tokens are requested and obtained from security 220 token services and how these services may broker trust and trust policies so that services 221 can perform step 3. 222

Deleted: 5

Deleted: 26

Deleted: April


Network and transport protection mechanisms such as IPsec or TLS/SSL can be used in 223 conjunction with this specification to support different security requirements and scenarios. 224 If available, requestors should consider using a network or transport security mechanism to 225 authenticate the service when requesting, validating, or renewing security tokens, as an 226 added level of security. 227 228 The [WS-Federation] specification builds on this specification to define mechanisms for 229 brokering and federating trust, identity, and claims. Examples are provided in [WS-230 Federation] illustrating different trust scenarios and usage patterns. 231

2.1 Models for Trust Brokering and Assessment 232

This section outlines different models for obtaining tokens and brokering trust. These 233 methods depend on whether the token issuance is based on explicit requests (token 234 acquisition) or if it is external to a message flow (out-of-band and trust management). 235

2.2 Token Acquisition 236

As part of a message flow, a request may be made of a security token service to exchange 237 a security token (or some proof) of one form for another. The exchange request can be 238 made either by a requestor or by another party on the requestor's behalf. If the security 239 token service trusts the provided security token (for example, because it trusts the issuing 240 authority of the provided security token), and the request can prove possession of that 241 security token, then the exchange is processed by the security token service. 242 243 The previous paragraph illustrates an example of token acquisition in a direct trust 244 relationship. In the case of a delegated request (one in which another party provides the 245 request on behalf of the requestor rather than the requestor presenting it themselves), the 246 security token service generating the new token may not need to trust the authority that 247 issued the original token provided by the original requestor since it does trust the security 248 token service that is engaging in the exchange for a new security token. The basis of the 249 trust is the relationship between the two security token services. 250

2.3 Out-of-Band Token Acquisition 251

The previous section illustrated acquisition of tokens. That is, a specific request is made 252 and the token is obtained. Another model involves out-of-band acquisition of tokens. For 253 example, the token may be sent from an authority to a party without the token having been 254 explicitly requested or the token may have been obtained as part of a third-party or legacy 255 protocol. In any of these cases the token is not received in response to a direct SOAP 256 request. 257

2.4 Trust Bootstrap 258

An administrator or other trusted authority may designate that all tokens of a certain type 259 are trusted (e.g. all Kerberos tokens from a specific realm or all X.509 tokens from a 260 specific CA). The security token service maintains this as a trust axiom and can 261 communicate this to trust engines to make their own trust decisions (or revoke it later), or 262 the security token service may provide this function as a service to trusting services. 263 There are several different mechanisms that can be used to bootstrap trust for a service. 264 These mechanisms are non-normative and are not required in any way. That is, services 265

Deleted: 5

Deleted: 26

Deleted: April


are free to bootstrap trust and establish trust among a domain of services or extend this 266 trust to other domains using any mechanism. 267 268 Fixed trust roots – The simplest mechanism is where the recipient has a fixed set of trust 269 relationships. It will then evaluate all requests to determine if they contain security tokens 270 from one of the trusted roots. 271 272 Trust hierarchies – Building on the trust roots mechanism, a service may choose to allow 273 hierarchies of trust so long as the trust chain eventually leads to one of the known trust 274 roots. In some cases the recipient may require the sender to provide the full hierarchy. In 275 other cases, the recipient may be able to dynamically fetch the tokens for the hierarchy 276 from a token store. 277 278 Authentication service – Another approach is to use an authentication service. This can 279 essentially be thought of as a fixed trust root where the recipient only trusts the 280 authentication service. Consequently, the recipient forwards tokens to the authentication 281 service, which replies with an authoritative statement (perhaps a separate token or a signed 282 document) attesting to the authentication. 283

Deleted: 5

Deleted: 26

Deleted: April


3 Security Token Service Framework 284

This section defines the general framework used by security token services for token 285 issuance. 286 287 A requestor sends a request, and if the policy permits and the recipient's requirements are 288 met, then the requestor receives a security token response. This process uses the 289 <wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse> elements 290 respectively. These elements are passed as the payload to specific WSDL ports (described 291 in section 1.4) that are implemented by security token services. 292 293 This framework does not define specific actions; each binding defines its own actions. 294 When requesting and returning security tokens additional parameters can be included in 295 requests, or provided in responses to indicate server-determined (or used) values. If a 296 requestor specifies a specific value that isn't supported by the recipient, then the recipient 297 MAY fault with a wst:InvalidRequest (or a more specific fault code), or they MAY return a 298 token with their chosen parameters that the requestor may then choose to discard because 299 it doesn't meet their needs. 300 301 The requesting and returning of security tokens can be used for a variety of purposes. 302 Bindings define how this framework is used for specific usage patterns. Other specifications 303 may define specific bindings and profiles of this mechanism for additional purposes. 304 In general, it is RECOMMENDED that sources of requests be authenticated; however, in 305 some cases an anonymous request may be appropriate. Requestors MAY make anonymous 306 requests and it is up to the recipient's policy to determine if such requests are acceptable. 307 If not a fault SHOULD be generated (but is not required to be returned for denial-of-service 308 reasons). 309 310 The [WS-Security] specification defines and illustrates time references in terms of the 311 dateTime type defined in XML Schema. It is RECOMMENDED that all time references use 312 this type. It is further RECOMMENDED that all references be in UTC time. Requestors and 313 receivers SHOULD NOT rely on other applications supporting time resolution finer than 314 milliseconds. Implementations MUST NOT generate time instants that specify leap seconds. 315 Also, any required clock synchronization is outside the scope of this document. 316 317 The following sections describe the basic structure of token request and response elements 318 identifying the general mechanisms and most common sub-elements. Specific bindings 319 extend these elements with binding-specific sub-elements. That is, sections 3.1 and 3.2 320 should be viewed as patterns or templates on which specific bindings build. 321 It should be noted that all time references use the XML Schema dateTime type and use 322 universal time. 323

3.1 Requesting a Security Token 324

The <wst:RequestSecurityToken> element (RST) is used to request a security token (for 325 any purpose). This element SHOULD be signed by the requestor, using tokens 326

Deleted: 5

Deleted: 26

Deleted: April


contained/referenced in the request that are relevant to the request. If using a signed 327 request, the requestor MUST prove any required claims to the satisfaction of the security 328 token service. 329 If a parameter is specified in a request that the recipient doesn't understand, the recipient 330 SHOULD fault. 331 The syntax for this element is as follows: 332

<wst:RequestSecurityToken Context="..."> 333 <wst:TokenType>...</wst:TokenType> 334 <wst:RequestType>...</wst:RequestType> 335 ... 336 </wst:RequestSecurityToken> 337

The following describes the attributes and elements listed in the schema overview above: 338 /wst:RequestSecurityToken 339

This is a request to have a security token issued. 340

/wst:RequestSecurityToken/@Context 341 This optional URI specifies an identifier/context for this request. All subsequent RSTR elements 342 relating to this request MUST carry this attribute. This, for example, allows the request and 343 subsequent responses to be correlated. Note that no ordering semantics are provided; that is left 344 to the application/transport. 345

/wst:RequestSecurityToken/wst:TokenType 346 This optional element describes the type of security token requested, specified as a URI. That is, 347 the type of token that will be returned in the <wst:RequestSecurityTokenResponse> 348 message. Token type URIs are typically defined in token profiles such as those in the OASIS 349 WSS TC. 350

/wst:RequestSecurityToken/wst:RequestType 351 The mandatory RequestType element is used to indicate, using a URI, the class of function that 352 is being requested. The allowed values are defined by specific bindings and profiles of WS-Trust. 353 Frequently this URI corresponds to the [WS-Addressing] Action URI provided in the message 354 header as described in the binding/profile; however, specific bindings can use the Action URI to 355 provide more details on the semantic processing while this parameter specifies the general class 356 of operation (e.g., token issuance). This parameter is required. 357

/wst:RequestSecurityToken/{any} 358 This is an extensibility mechanism to allow additional elements to be added. This allows 359 requestors to include any elements that the service can use to process the token request. As 360 well, this allows bindings to define binding-specific extensions. If an element is found that is not 361 understood, the recipient SHOULD fault. 362

/wst:RequestSecurityToken/@{any} 363 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added. 364 If an attribute is found that is not understood, the recipient SHOULD fault. 365

3.2 Returning a Security Token 366

The <wst:RequestSecurityTokenResponse> element (RSTR) is used to return a security 367 token or response to a security token request. The 368 <wst:RequestSecurityTokenResponseCollection> element (RSTRC) MUST be used to 369 return a security token or response to a security token request on the final response. 370 371

Deleted: 5

Deleted: 26

Deleted: April


It should be noted that any type of parameter specified as input to a token request MAY be 372 present on response in order to specify the exact parameters used by the issuer. Specific 373 bindings describe appropriate restrictions on the contents of the RST and RSTR elements. 374 In general, the returned token should be considered opaque to the requestor. That is, the 375 requestor shouldn't be required to parse the returned token. As a result, information that 376 the requestor may desire, such as token lifetimes, SHOULD be returned in the response. 377 Specifically, any field that the requestor includes SHOULD be returned. If an issuer doesn't 378 want to repeat all input parameters, then, at a minimum, if the issuer chooses a value 379 different from what was requested, the issuer SHOULD include the parameters that were 380 changed. 381 If a parameter is specified in a response that the recipient doesn't understand, the recipient 382 SHOULD fault. 383 In this specification the RSTR message is illustrated as being passed in the body of a 384 message. However, there are scenarios where the RSTR must be passed in conjunction 385 with an existing application message. In such cases the RSTR (or the RSTR collection) MAY 386 be specified inside a header block. The exact location is determined by layered 387 specifications and profiles; however, the RSTR MAY be located in the <wsse:Security> 388 header if the token is being used to secure the message (note that the RSTR SHOULD occur 389 before any uses of the token). The combination of which header block contains the RSTR 390 and the value of the optional @Context attribute indicate how the RSTR is processed. It 391 should be noted that multiple RST elements can be specified in the header blocks of a 392 message. 393 It should be noted that there are cases where an RSTR is issued to a recipient who did not 394 explicitly issue an RST (e.g. to propagate tokens). In such cases, the RSTR may be passed 395 in the body or in a header block. 396 The syntax for this element is as follows: 397

<wst:RequestSecurityTokenResponse Context="..."> 398 <wst:TokenType>...</wst:TokenType> 399 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 400 ... 401 </wst:RequestSecurityTokenResponse> 402

The following describes the attributes and elements listed in the schema overview above: 403 /wst:RequestSecurityTokenResponse 404

This is the response to a security token request. 405

/wst:RequestSecurityTokenResponse/@Context 406 This optional URI specifies the identifier from the original request. That is, if a context URI is 407 specified on a RST, then it MUST be echoed on the corresponding RSTRs. For unsolicited 408 RSTRs (RSTRs that aren't the result of an explicit RST), this represents a hint as to how the 409 recipient is expected to use this token. No values are pre-defined for this usage; this is for use by 410 specifications that leverage the WS-Trust mechanisms. 411

/wst:RequestSecurityTokenResponse/wst:TokenType 412 This optional element specifies the type of security token returned. 413

/wst:RequestSecurityTokenResponse/wst:RequestedSecurityToken 414 This optional element is used to return the requested security token. Normally the requested 415 security token is the contents of this element but a security token reference MAY be used instead. 416 For example, if the requested security token is used in securing the message, then the security 417 token is placed into the <wsse:Security> header (as described in [WS-Security]) and a 418 <wsse:SecurityTokenReference> element is placed inside of the 419

Deleted: 5

Deleted: 26

Deleted: April


<wst:RequestedSecurityToken> element to reference the token in the <wsse:Security> 420 header. The response MAY contain a token reference where the token is located at a URI 421 outside of the message. In such cases the recipient is assumed to know how to fetch the token 422 from the URI address or specified endpoint reference. It should be noted that when the token is 423 not returned as part of the message it cannot be secured, so a secure communication 424 mechanism SHOULD be used to obtain the token. 425

/wst:RequestSecurityTokenResponse/{any} 426 This is an extensibility mechanism to allow additional elements to be added. If an element is 427 found that is not understood, the recipient SHOULD fault. 428

/wst:RequestSecurityTokenResponse/@{any} 429 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added. 430 If an attribute is found that is not understood, the recipient SHOULD fault. 431

3.3 Binary Secrets 432

It should be noted that in some cases elements include a key that is not encrypted. 433 Consequently, the <xenc:EncryptedData> cannot be used. Instead, the 434 <wst:BinarySecret> element can be used. This SHOULD only be used when the message 435 is otherwise protected (e.g. transport security is used or the containing element is 436 encrypted). This element contains a base64 encoded value that represents an arbitrary 437 octet sequence of a secret (or key). The general syntax of this element is as follows (note 438 that the ellipses below represent the different containers in which this element may appear, 439 for example, a <wst:Entropy> or <wst:RequestedProofToken> element): 440 .../wst:BinarySecret 441

This element contains a base64 encoded binary secret (or key). This can be either a symmetric 442 key, the private portion of an asymmetric key, or any data represented as binary octets. 443

.../wst:BinarySecret/@Type 444 This optional attribute indicates the type of secret being encoded. The pre-defined values are 445 listed in the table below: 446

URI Meaning

http://docs.oasis-open.org/ws-sx/ws-trust/200512/AsymmetricKey

The private portion of a public key token is returned – this URI assumes both parties agree on the format of the octets; other bindings and profiles MAY define additional URIs with specific formats

http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey

A symmetric key token is returned (default)

http://docs.oasis-open.org/ws-sx/ws-trust/200512/Nonce

A raw nonce value (typically passed as entropy or key material)

.../wst:BinarySecret/@{any} 447 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added. 448 If an attribute is found that is not understood, the recipient SHOULD fault. 449

Deleted: 5

Deleted: 26

Deleted: April


3.4 Composition 450

The sections below, as well as other documents, describe a set of bindings using the model 451 framework described in the above sections. Each binding describes the amount of 452 extensibility and composition with other parts of WS-Trust that is permitted. Additional 453 profile documents MAY further restrict what can be specified in a usage of a binding. 454

Deleted: 5

Deleted: 26

Deleted: April


4 Issuance Binding 455

Using the token request framework, this section defines bindings for requesting security 456 tokens to be issued: 457

Issue – Based on the credential provided/proven in the request, a new token is issued, possibly 458 with new proof information. 459

For this binding, the following [WS-Addressing] actions are defined to enable specific 460 processing context to be conveyed to the recipient: 461

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue 462 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Issue 463 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal 464

For this binding, the <wst:RequestType> element uses the following URI: 465

http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 466

The mechanisms defined in this specification apply to both symmetric and asymmetric keys. 467 As an example, a Kerberos KDC could provide the services defined in this specification to 468 make tokens available; similarly, so can a public key infrastructure. In such cases, the 469 issuing authority is the security token service. It should be noted that in practice, 470 asymmetric key usage often differs as it is common to reuse existing asymmetric keys 471 rather than regenerate due to the time cost and desire to map to a common public key. In 472 such cases a request might be made for an asymmetric token providing the public key and 473 proving ownership of the private key. The public key is then used in the issued token. 474 475 A public key directory is not really a security token service per se; however, such a service 476 MAY implement token retrieval as a form of issuance. It is also possible to bridge 477 environments (security technologies) using PKI for authentication or bootstrapping to a 478 symmetric key. 479 480 This binding provides a general token issuance action that can be used for any type of token 481 being requested. Other bindings MAY use separate actions if they have specialized 482 semantics. 483 484 This binding supports the optional use of exchanges during the token acquisition process as 485 well as the optional use of the key extensions described in a later section. Additional 486 profiles are needed to describe specific behaviors (and exclusions) when different 487 combinations are used. 488

4.1 Requesting a Security Token 489

When requesting a security token to be issued, the following optional elements MAY be 490 included in the request and MAY be provided in the response. The syntax for these 491 elements is as follows (note that the base elements described above are included here 492 italicized for completeness): 493

<wst:RequestSecurityToken> 494 <wst:TokenType>...</wst:TokenType> 495 <wst:RequestType>...</wst:RequestType> 496 ... 497

Deleted: 5

Deleted: 26

Deleted: April


<wsp:AppliesTo>...</wsp:AppliesTo> 498 <wst:Claims Dialect="...">...</wst:Claims> 499 <wst:Entropy> 500 <wst:BinarySecret>...</wst:BinarySecret> 501 </wst:Entropy> 502 <wst:Lifetime> 503 <wsu:Created>...</wsu:Created> 504 <wsu:Expires>...</wsu:Expires> 505 </wst:Lifetime> 506 </wst:RequestSecurityToken> 507

The following describes the attributes and elements listed in the schema overview above: 508 /wst:RequestSecurityToken/wst:TokenType 509

If this optional element is not specified in an issue request, it is RECOMMENDED that the 510 optional element <wsp:AppliesTo> be used to indicate the target where this token will be used 511 (similar to the Kerberos target service model). This assumes that a token type can be inferred 512 from the target scope specified. That is, either the <wst:TokenType> or the 513 <wsp:AppliesTo> element SHOULD be defined within a request. If both the 514 <wst:TokenType> and <wsp:AppliesTo> elements are defined, the <wsp:AppliesTo> 515 element takes precedence (for the current request only) in case the target scope requires a 516 specific type of token. 517

/wst:RequestSecurityToken/wsp:AppliesTo 518 This optional element specifies the scope for which this security token is desired – for example, 519 the service(s) to which this token applies. Refer to [WS-PolicyAttachment] for more information. 520 Note that either this element or the <wst:TokenType> element SHOULD be defined in a 521 <wst:RequestSecurityToken> message. In the situation where BOTH fields have values, 522 the <wsp:AppliesTo> field takes precedence. This is because the issuing service is more 523 likely to know the type of token to be used for the specified scope than the requestor (and 524 because returned tokens should be considered opaque to the requestor). 525

/wst:RequestSecurityToken/wst:Claims 526 This optional element requests a specific set of claims. Typically, this element contains required 527 and/or optional claim information identified in a service's policy. 528

/wst:RequestSecurityToken/wst:Claims/@Dialect 529 This required attribute contains a URI that indicates the syntax used to specify the set of 530 requested claims along with how that syntax should be interpreted. No URIs are defined by this 531 specification; it is expected that profiles and other specifications will define these URIs and the 532 associated syntax. 533

/wst:RequestSecurityToken/wst:Entropy 534 This optional element allows a requestor to specify entropy that is to be used in creating the key. 535 The value of this element SHOULD be either a <xenc:EncryptedKey> or 536 <wst:BinarySecret> depending on whether or not the key is encrypted. Secrets SHOULD be 537 encrypted unless the transport/channel is already providing encryption. 538

/wst:RequestSecurityToken/wst:Entropy/wst:BinarySecret 539 This optional element specifies a base64 encoded sequence of octets representing the 540 requestor's entropy. The value can contain either a symmetric or the private key of an 541 asymmetric key pair, or any suitable key material. The format is assumed to be understood by 542 the requestor because the value space may be (a) fixed, (b) indicated via policy, (c) inferred from 543 the indicated token aspects and/or algorithms, or (d) determined from the returned token. (See 544 Section 3.3) 545

/wst:RequestSecurityToken/wst:Lifetime 546 Deleted: 5

Deleted: 26

Deleted: April


This optional element is used to specify the desired valid time range (time window during which 547 the token is valid for use) for the returned security token. That is, to request a specific time 548 interval for using the token. The issuer is not obligated to honor this range – they may return a 549 more (or less) restrictive interval. It is RECOMMENDED that the issuer return this element with 550 issued tokens (in the RSTR) so the requestor knows the actual validity period without having to 551 parse the returned token. 552

/wst:RequestSecurityToken/wst:Lifetime/wsu:Created 553 This optional element represents the creation time of the security token. Within the SOAP 554 processing model, creation is the instant that the infoset is serialized for transmission. The 555 creation time of the token SHOULD NOT differ substantially from its transmission time. The 556 difference in time should be minimized. If this time occurs in the future then this is a request for a 557 postdated token. If this attribute isn't specified, then the current time is used as an initial period. 558

/wst:RequestSecurityToken/wst:Lifetime/wsu:Expires 559 This optional element specifies an absolute time representing the upper bound on the validity 560 time period of the requested token. If this attribute isn't specified, then the service chooses the 561 lifetime of the security token. A Fault code (wsu:MessageExpired) is provided if the recipient 562 wants to inform the requestor that its security semantics were expired. A service MAY issue a 563 Fault indicating the security semantics have expired. 564

565 The following is a sample request. In this example, a username token is used as the basis 566 for the request as indicated by the use of that token to generate the signature. The 567 username (and password) is encrypted for the recipient and a reference list element is 568 added. The <ds:KeyInfo> element refers to a <wsse:UsernameToken> element that has 569 been encrypted to protect the password (note that the token has the wsu:Id of "myToken" 570 prior to encryption). The request is for a custom token type to be returned. 571

<S11:Envelope xmlns:S11="..." xmlns:wsu="..." xmlns:wsse="..." 572 xmlns:xenc="..." xmlns:wst="..."> 573 <S11:Header> 574 ... 575 <wsse:Security> 576 <xenc:ReferenceList>...</xenc:ReferenceList> 577 <xenc:EncryptedData Id="encUsername">...</xenc:EncryptedData> 578 <ds:Signature xmlns:ds="..."> 579 ... 580 <ds:KeyInfo> 581 <wsse:SecurityTokenReference> 582 <wsse:Reference URI="#myToken"/> 583 </wsse:SecurityTokenReference> 584 </ds:KeyInfo> 585 </ds:Signature> 586 </wsse:Security> 587 ... 588 </S11:Header> 589 <S11:Body wsu:Id="req"> 590 <wst:RequestSecurityToken> 591 <wst:TokenType> 592 http://example.org/mySpecialToken 593 </wst:TokenType> 594 <wst:RequestType> 595 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 596 </wst:RequestType> 597 </wst:RequestSecurityToken> 598 </S11:Body> 599 </S11:Envelope> 600 Deleted: 5

Deleted: 26

Deleted: April

4.2 Request Security Token Collection 601

There are occasions where efficiency is important. Reducing the number of messages in a 602 message exchange pattern can greatly improve efficiency. One way to do this in the context 603 of WS-Trust is to avoid repeated round-trips for multiple token requests. An example is 604 requesting an identity token as well as tokens that offer other claims in a single batch 605 request operation. 606 607

To give an example, imagine an automobile parts supplier that wishes to offer parts to an 608 automobile manufacturer. To interact with the manufacturer web service the parts supplier 609 may have to present a number of tokens, such as an identity token as well as tokens with 610 claims, such as tokens indicating various certifications to meet supplier requirements. 611 612 It is possible for the supplier to authenticate to a trust server and obtain an identity token 613 and then subsequently present that token to obtain a certification claim token. However, it 614 may be much more efficient to request both in a single interaction (especially when more 615 than two tokens are required). 616 617 Here is an example of a collection of authentication requests corresponding to this scenario: 618 619

<wst:RequestSecurityTokenCollection> 620 621  622 <wst:RequestSecurityToken Context="http://www.example.com/1"> 623 <wst:TokenType> 624 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-625 1.1#SAMLV2.0 626 </wst:TokenType> 627 <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-628 trust/200512/BatchIssue</wst:RequestType> 629 <wsp:AppliesTo 630 xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"> 631 <wsa:EndpointReference> 632 <wsa:Address>http://manufacturer.example.com/</wsa:Address> 633 </wsa:EndpointReference> 634 </wsp:AppliesTo> 635 <wsp:PolicyReference 636 URI='http://manufacturer.example.com/IdentityPolicy' /> 637 </wst:RequestSecurityToken> 638 639 <!—certification claim token request --> 640 <wst:RequestSecurityToken Context="http://www.example.com/2"> 641 <wst:TokenType> 642 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-643 1.1#SAMLV2.0 644 </wst:TokenType> 645 <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512 646 /BatchIssue</wst:RequestType> 647 <wsp:Claims> 648 http://manufacturer.example.com/certification 649 </wsp:Claims> 650 <wsp:PolicyReference 651 URI='http://certificationbody.example.org/certificationPolicy’ /> 652 </wst:RequestSecurityToken> 653 </wst:RequestSecurityTokenCollection> 654

655

Deleted: 5

Deleted: 26

Deleted: April


The following describes the attributes and elements listed in the overview above: 656 657 /wst:RequestSecurityTokenCollection 658

The RequestSecurityTokenCollection (RSTC) element is used to provide multiple RST 659 requests. One or more RSTR elements in an RSTRC element are returned in the response to the 660 RequestSecurityTokenCollection. 661

4.2.1 Processing Rules 662

The RequestSecurityTokenCollection (RSTC) element contains 2 or more 663 RequestSecurityToken elements. 664 665

1. The single RequestSecurityTokenResponseCollection response MUST contain at 666 least one RSTR element corresponding to each RST element in the request. A RSTR 667 element corresponds to an RST element if it has the same Context attribute value as 668 the RST element. Note: Each request may generate more than one RSTR sharing the 669 same Context attribute value 670

a. Specifically there is no notion of a deferred response 671 b. If any RST request results in an error, then no RSTRs will be returned and a 672

SOAP Fault will be generated as the entire response. 673 2. Every RST in the request MUST use an action URI value in the RequestType element 674

that is a batch version corresponding to the non-batch version, in particular one of 675 the following: 676

• http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchIssue 677 • http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchValidate 678 • http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchRenew 679 • http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchCancel 680

681 These URIs MUST also be used for the [WS-Addressing] actions defined to enable 682 specific processing context to be conveyed to the recipient. 683 684 Note: that these operations require that the service can either succeed on all the 685 RST requests or must not perform any partial operation. 686 687

3. All Signatures MUST reference the entire RSTC. One or more Signatures referencing 688 the entire collection MAY be used. 689

4. No negotiation or other multi-leg authentication mechanisms are allowed in batch 690 requests or responses to batch requests; the communication with STS is limited to 691 one RSTC request and one RSTRC response. 692

5. This mechanism requires that every RST in a RSTC is to be handled by the single 693 endpoint processing the RSTC. 694

695 If any error occurs in the processing of the RSTC or one of its contained RSTs, a SOAP fault 696 must be generated for the entire batch request so no RSTC element will be returned. 697

698

Deleted: 5

Deleted: 26

Deleted: April


4.3 Returning a Security Token 699

When returning a security token, the following optional elements MAY be included in the 700 response. Security tokens can only be returned in the RSTRC on the final leg. The syntax 701 for these elements is as follows (note that the base elements described above are included 702 here italicized for completeness): 703

<wst:RequestSecurityTokenResponse> 704 <wst:TokenType>...</wst:TokenType> 705 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 706 ... 707 <wsp:AppliesTo>...</wsp:AppliesTo> 708 <wst:RequestedAttachedReference> 709 ... 710 </wst:RequestedAttachedReference> 711 <wst:RequestedUnattachedReference> 712 ... 713 </wst:RequestedUnattachedReference> 714 <wst:RequestedProofToken>...</wst:RequestedProofToken> 715 <wst:Entropy> 716 <wst:BinarySecret>...</wst:BinarySecret> 717 </wst:Entropy> 718 <wst:Lifetime>...</wst:Lifetime> 719 </wst:RequestSecurityTokenResponse> 720

The following describes the attributes and elements listed in the schema overview above: 721 /wst:RequestSecurityTokenResponse/wsp:AppliesTo 722

This optional element specifies the scope to which this security token applies. Refer to [WS-723 PolicyAttachment] for more information. Note that if an <wsp:AppliesTo> was specified in the 724 request, the same scope SHOULD be returned in the response (if a <wsp:AppliesTo> is 725 returned). 726

/wst:RequestSecurityTokenResponse/wst:RequestedSecurityToken 727 This optional element is used to return the requested security token. This element is optional, but 728 it is REQUIRED that at least one of <wst:RequestedSecurityToken> or 729 <wst:RequestedProofToken> be returned unless there is an error or part of an on-going 730 message exchange (e.g. negotiation). If returning more than one security token see section 4.3, 731 Returning Multiple Security Tokens. 732

/wst:RequestSecurityTokenResponse/wst:RequestedAttachedReference 733 Since returned tokens are considered opaque to the requestor, this optional element is specified 734 to indicate how to reference the returned token when that token doesn't support references using 735 URI fragments (XML ID). This element contains a <wsse:SecurityTokenReference> 736 element that can be used verbatim to reference the token (when the token is placed inside a 737 message). Typically tokens allow the use of wsu:Id so this element isn't required. Note that a 738 token MAY support multiple reference mechanisms; this indicates the issuer’s preferred 739 mechanism. When encrypted tokens are returned, this element is not needed since the 740 <xenc:EncryptedData> element supports an ID reference. If this element is not present in the 741 RSTR then the recipient can assume that the returned token (when present in a message) 742 supports references using URI fragments. 743

/wst:RequestSecurityTokenResponse/wst:RequestedUnattachedReference 744 In some cases tokens need not be present in the message. This optional element is specified to 745 indicate how to reference the token when it is not placed inside the message. This element 746 contains a <wsse:SecurityTokenReference> element that can be used verbatim to 747 reference the token (when the token is not placed inside a message) for replies. Note that a token 748 MAY support multiple external reference mechanisms; this indicates the issuer’s preferred 749 mechanism. 750

Deleted: 5

Deleted: 26

Deleted: April


/wst:RequestSecurityTokenResponse/wst:RequestedProofToken 751 This optional element is used to return the proof-of-possession token associated with the 752 requested security token. Normally the proof-of-possession token is the contents of this element 753 but a security token reference MAY be used instead. The token (or reference) is specified as the 754 contents of this element. For example, if the proof-of-possession token is used as part of the 755 securing of the message, then it is placed in the <wsse:Security> header and a 756 <wsse:SecurityTokenReference> element is used inside of the 757 <wst:RequestedProofToken> element to reference the token in the <wsse:Security> 758 header. This element is optional, but it is REQUIRED that at least one of 759 <wst:RequestedSecurityToken> or <wst:RequestedProofToken> be returned unless 760 there is an error. 761

/wst:RequestSecurityTokenResponse/wst:Entropy 762 This optional element allows an issuer to specify entropy that is to be used in creating the key. 763 The value of this element SHOULD be either a <xenc:EncryptedKey> or 764 <wst:BinarySecret> depending on whether or not the key is encrypted (it SHOULD be unless 765 the transport/channel is already encrypted). 766

/wst:RequestSecurityTokenResponse/wst:Entropy/wst:BinarySecret 767 This optional element specifies a base64 encoded sequence of octets represent the responder's 768 entropy. (See Section 3.3) 769

/wst:RequestSecurityTokenResponse/wst:Lifetime 770 This optional element specifies the lifetime of the issued security token. If omitted the lifetime is 771 unspecified (not necessarily unlimited). It is RECOMMENDED that if a lifetime exists for a token 772 that this element be included in the response. 773

4.3.1 wsp:AppliesTo in RST and RSTR 774

Both the requestor and the issuer can specify a scope for the issued token using the 775 <wsp:AppliesTo> element. If a token issuer cannot provide a token with a scope that is at 776 least as broad as that requested by the requestor then it SHOULD generate a fault. This 777 section defines some rules for interpreting the various combinations of provided scope: 778

• If neither the requestor nor the issuer specifies a scope then the scope of the issued 779 token is implied. 780

• If the requestor specifies a scope and the issuer does not then the scope of the token 781 is assumed to be that specified by the requestor. 782

• If the requestor does not specify a scope and the issuer does specify a scope then 783 the scope of the token is as defined by the issuers scope 784

• If both requestor and issuer specify a scope then there are two possible outcomes: 785 o If both the issuer and requestor specify the same scope then the issued token 786

has that scope. 787 o If the issuer specifies a wider scope than the requestor then the issued token 788

has the scope specified by the issuer. 789 790 The following table summarizes the above rules: 791

Requestor wsp:AppliesTo Issuer wsp:AppliesTo Results

Absent Absent OK. Implied scope.

Present Absent OK. Issued token has scope Deleted: 5

Deleted: 26

Deleted: April


specified by requestor.

Absent Present OK. Resulting token has scope specified by issuer.

Present Present and matches Requestor

OK.

Present Present and specifies a scope greater than specified by the requestor

OK. Issuer scope.

4.3.2 Requested References 792

The token issuer can optionally provide <wst:RequestedAttachedReference> and/or 793 <wst:RequestedUnattachedReference> elements in the RSTR. It is assumed that all token 794 types can be referred to directly when present in a message. This section outlines the 795 expected behaviour on behalf of clients and servers with respect to various permutations: 796

• If a <wst:RequestedAttachedReference> element is NOT returned in the RSTR then the 797 client SHOULD assume that the token can be referenced by ID. Alternatively, the 798 client MAY use token-specific knowledge to construct an STR. 799

• If a <wst:RequestedAttachedReference> element is returned in the RSTR then the 800 token cannot be referred to by ID. The supplied STR MUST be used to refer to the 801 token. 802

• If a <wst:RequestedUnattachedReference> element is returned then the server MAY 803 reference the token using the supplied STR when sending responses back to the 804 client. Thus the client MUST be prepared to resolve the supplied STR to the 805 appropriate token. Note: the server SHOULD NOT send the token back to the client 806 as the token is often tailored specifically to the server (i.e. it may be encrypted for 807 the server). References to the token in subsequent messages, whether sent by the 808 client or the server, that omit the token MUST use the supplied STR. 809

4.3.3 Keys and Entropy 810

The keys resulting from a request are determined in one of three ways: specific, partial, and 811 omitted. 812

• In the case of specific keys, a <wst:RequestedProofToken> element is included in 813 the response which indicates the specific key(s) to use unless the key was provided 814 by the requestor (in which case there is no need to return it). 815

• In the case of partial, the <wst:Entropy> element is included in the response, which 816 indicates partial key material from the issuer (not the full key) that is combined (by 817 each party) with the requestor's entropy to determine the resulting key(s). In this 818 case a <wst:ComputedKey> element is returned inside the 819 <wst:RequestedProofToken> to indicate how the key is computed. 820

• In the case of omitted, an existing key is used or the resulting token is not directly 821 associated with a key. 822

823 The decision as to which path to take is based on what the requestor provides, what the 824 issuer provides, and the issuer's policy. 825 Deleted: 5

Deleted: 26

Deleted: April


• If the requestor does not provide entropy or issuer rejects the requestor's entropy, a 826 proof-of-possession token MUST be returned with an issuer-provided key. 827

• If the requestor provides entropy and the responder doesn't (issuer uses the 828 requestor's key), then a proof-of-possession token need not be returned. 829

• If both the requestor and the issuer provide entropy, then the partial form is used. 830 Ideally both entropies are specified as encrypted values and the resultant key is 831 never used (only keys derived from it are used). As noted above, the 832 <wst:ComputedKey> element is returned inside the <wst:RequestedProofToken> to 833 indicate how the key is computed. 834

835 The following table illustrates the rules described above: 836

Requestor Issuer Results

Uses requestor entropy as key

No proof-of-possession token is returned.

Provides entropy

No keys returned, key(s) derived using entropy from both sides according to method identified in response

Provide Entropy

Issues own key (rejects requestor's entropy)

Proof-of-possession token contains issuer's key(s)

Issues own key Proof-of-possession token contains issuer's key(s) No Entropy

provided Does not issue key No proof-of-possession token

4.3.4 Returning Computed Keys 837

As previously described, in some scenarios the key(s) resulting from a token request are not 838 directly returned and must be computed. One example of this is when both parties provide 839 entropy that is combined to make the shared secret. To indicate a computed key, the 840 <wst:ComputedKey> element MUST be returned inside the <wst:RequestedProofToken> to 841 indicate how the key is computed. The following is a syntax overview of the 842 <wst:ComputedKey> element: 843

... 844 <wst:RequestSecurityTokenResponseCollection> 845 <wst:RequestSecurityTokenResponse> 846 <wst:RequestedProofToken> 847 <wst:ComputedKey>...</wst:ComputedKey> 848 </wst:RequestedProofToken> 849 </wst:RequestSecurityTokenResponse> 850 </wst:RequestSecurityTokenResponseCollection> 851 ... 852

853 The following describes the attributes and elements listed in the schema overview above: 854 /wst:RequestSecurityTokenResponse/wst:RequestedProofToken/wst:ComputedKey 855

The value of this element is a URI describing how to compute the key. While this can be 856 extended by defining new URIs in other bindings and profiles, the following URI pre-defines one 857 computed key mechanism: 858

Deleted: 5

Deleted: 26

Deleted: April


URI Meaning

http://docs.oasis-open.org/ws-sx/ws-trust/200512/CK/PSHA1

The key is computed using P_SHA1 from the TLS specification to generate a bit stream using entropy from both sides. The exact form is: key = P_SHA1 (EntREQ, EntRES)

It is RECOMMENDED that EntREQ be a string of length at least 128 bits.

This element MUST be returned when key(s) resulting from the token request are computed. 859

4.3.5 Sample Response with Encrypted Secret 860

The following is a sample security token response. In this example the token requested in 861 section 4.1 is returned. Additionally a proof-of-possession token element is returned 862 containing the secret key associated with the <wst:RequestedSecurityToken> encrypted 863 for the requestor (note that this assumes that the requestor has a shared secret with the 864 issuer or a public key). 865

... 866 <wst:RequestSecurityTokenResponseCollection> 867 <wst:RequestSecurityTokenResponse> 868 <wst:RequestedSecurityToken> 869 <xyz:CustomToken xmlns:xyz="..."> 870 ... 871 </xyz:CustomToken> 872 </wst:RequestedSecurityToken> 873 <wst:RequestedProofToken> 874 <xenc:EncryptedKey Id="newProof"> 875 ... 876 </xenc:EncryptedKey> 877 </wst:RequestedProofToken> 878 </wst:RequestSecurityTokenResponse> 879 </wst:RequestSecurityTokenResponseCollection> 880 ... 881

4.3.6 Sample Response with Unencrypted Secret 882

The example below is an alternative form where the secret is passed in the clear because 883 the transport is providing confidentiality: 884

... 885 <wst:RequestSecurityTokenResponseCollection> 886 <wst:RequestSecurityTokenResponse> 887 <wst:RequestedSecurityToken> 888 <xyz:CustomToken xmlns:xyz="..."> 889 ... 890 </xyz:CustomToken> 891 </wst:RequestedSecurityToken> 892 <wst:RequestedProofToken> 893 <wst:BinarySecret>...</wst:BinarySecret> 894 </wst:RequestedProofToken> 895 </wst:RequestSecurityTokenResponse> 896 </wst:RequestSecurityTokenResponseCollection> 897 ... 898

Deleted: 5

Deleted: 26

Deleted: April


4.3.7 Sample Response with Token Reference 899

If the returned token doesn't allow the use of the wsu:Id attribute, then a 900 <wst:RequestedTokenReference> is returned as illustrated below. In this example, the 901 returned token has a URI which is referenced. 902

... 903 <wst:RequestSecurityTokenResponseCollection> 904 <wst:RequestSecurityTokenResponse> 905 <wst:RequestedSecurityToken> 906 <xyz:CustomToken ID="urn:fabrikam123:5445" xmlns:xyz="..."> 907 ... 908 </xyz:CustomToken> 909 </wst:RequestedSecurityToken> 910 <wst:RequestedTokenReference> 911 <wsse:SecurityTokenReference> 912 <wsse:Reference URI="urn:fabrikam123:5445"/> 913 </wsse:SecurityTokenReference> 914 </wst:RequestedTokenReference> 915 ... 916 </wst:RequestSecurityTokenResponse> 917 </wst:RequestSecurityTokenResponseCollection> 918 ... 919

920 In the example above, the recipient may place the returned custom token directly into a 921 message and include a signature using the provided proof-of-possession token. The 922 specified reference is then placed into the <ds:KeyInfo> of the signature and directly 923 references the included token without requiring the requestor to understand the details of 924 the custom token format. 925

4.3.8 Sample Response without Proof-of-Possession Token 926

The example below illustrates a response that doesn't include a proof-of-possession token. 927 For example, if the basis of the request were a public key token and another public key 928 token is returned with the same public key, the proof-of-possession token from the original 929 token is reused (no new proof-of-possession token is required). 930

... 931 <wst:RequestSecurityTokenResponseCollection> 932 <wst:RequestSecurityTokenResponse> 933 <wst:RequestedSecurityToken> 934 <xyz:CustomToken xmlns:xyz="..."> 935 ... 936 </xyz:CustomToken> 937 </wst:RequestedSecurityToken> 938 </wst:RequestSecurityTokenResponse> 939 </wst:RequestSecurityTokenResponseCollection> 940 ... 941

942

4.3.9 Zero or One Proof-of-Possession Token Case 943

In the zero or single proof-of-possession token case, a primary token and one or more tokens are 944 returned. The returned tokens either use the same proof-of-possession token (one is returned), or no 945 proof-of-possession token is returned. The tokens are returned (one each) in the response. The 946 following example illustrates this case. In this example a supporting security token is returned 947 that has no separate proof-of-possession token as it is secured using the same proof-of-948 possession token that was returned. 949

Deleted: 5

Deleted: 26

Deleted: April


950


4.3.10 More Than One Proof-of-Possession Tokens Case 967

The second case is where multiple security tokens are returned that have separate proof-of-968 possession tokens. As a result, the proof-of-possession tokens, and possibly lifetime and 969 other key parameters elements, may be different. To address this scenario, the body MAY 970 be specified using the syntax illustrated below: 971

<wst:RequestSecurityTokenResponseCollection> 972 <wst:RequestSecurityTokenResponse> 973 ... 974 </wst:RequestSecurityTokenResponse> 975 <wst:RequestSecurityTokenResponse> 976 ... 977 </wst:RequestSecurityTokenResponse> 978 ... 979 </wst:RequestSecurityTokenResponseCollection> 980

The following describes the attributes and elements listed in the schema overview above: 981 /wst:RequestSecurityTokenResponseCollection 982

This element is used to provide multiple RSTR responses, each of which has separate key 983 information. One or more RSTR elements are returned in the collection. This MUST always be 984 used on the final response to the RST. 985

/wst:RequestSecurityTokenResponseCollection/wst:RequestSecurityTokenResponse 986 Each RequestSecurityTokenResponse element is an individual RSTR. 987

/wst:RequestSecurityTokenResponseCollection/{any} 988 This is an extensibility mechanism to allow additional elements, based on schemas, to be added. 989

/wst:RequestSecurityTokenResponseCollection/@{any} 990 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added. 991

The following example illustrates a response that includes multiple tokens each, in a 992 separate RSTR, each with their own proof-of-possession token. 993

... 994 <wst:RequestSecurityTokenResponseCollection> 995 <wst:RequestSecurityTokenResponse> 996 <wst:RequestedSecurityToken> 997 <xyz:CustomToken xmlns:xyz="..."> 998 ... 999 </xyz:CustomToken> 1000

Deleted: 5

Deleted: 26

Deleted: April


</wst:RequestedSecurityToken> 1001 <wst:RequestedProofToken> 1002 <xenc:EncryptedKey Id="newProofA"> 1003 ... 1004 </xenc:EncryptedKey> 1005 </wst:RequestedProofToken> 1006 </wst:RequestSecurityTokenResponse> 1007 <wst:RequestSecurityTokenResponse> 1008 <wst:RequestedSecurityToken> 1009 <abc:CustomToken xmlns:abc="..."> 1010 ... 1011 </abc:CustomToken> 1012 </wst:RequestedSecurityToken> 1013 <wst:RequestedProofToken> 1014 <xenc:EncryptedKey Id="newProofB> 1015 ... 1016 </xenc:EncryptedKey> 1017 </wst:RequestedProofToken> 1018 </wst:RequestSecurityTokenResponse> 1019 </wst:RequestSecurityTokenResponseCollection> 1020 ... 1021

4.4 Returning Security Tokens in Headers 1022

In certain situations it is useful to issue one or more security tokens as part of a protocol 1023 other than RST/RSTR. This typically requires that the tokens be passed in a SOAP header. 1024 The tokens present in that element can then be referenced from elsewhere in the message. 1025 This section defines a specific header element, whose type is the same as that of the 1026 <wst:RequestSecurityTokenCollection> element (see Section 4.3), that can be used to carry 1027 issued tokens (and associated proof tokens, references etc.) in a message. 1028

... 1029 <wst:IssuedTokens> 1030 <wst:RequestSecurityTokenResponse> 1031 ... 1032 </wst:RequestSecurityTokenResponse>+ 1033 </wst:IssuedTokens> 1034

1035 The following describes the attributes and elements listed in the schema overview above: 1036 /wst:IssuedTokens 1037

This header element carries one or more issued security tokens. This element schema is 1038 defined using the RequestSecurityTokenResponse schema type. 1039

/wst:IssuedTokens/wst:RequestSecurityTokenResponse 1040 This element MUST appear at least once. Its meaning and semantics are as defined in 1041 Section 4.2. 1042

/wst:IssuedTokens/{any} 1043 This is an extensibility mechanism to allow additional elements, based on schemas, to be added. 1044

/wst:IssuedTokens/@{any} 1045 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added. 1046

1047 There MAY be multiple instances of the <wst:IssuedTokens> header in a given message. Such 1048 instances MAY be targeted at the same actor/role. Intermediaries MAY add additional 1049

Deleted: 5

Deleted: 26

Deleted: April


<wst:IssuedTokens> header elements to a message. Intermediaries SHOULD NOT modify any 1050 <wst:IssuedTokens> header already present in a message. 1051 1052 It is RECOMMENDED that the <wst:IssuedTokens> header be signed to protect the integrity 1053 of the issued tokens and of the issuance itself. If confidentiality protection of the 1054 <wst:IssuedTokens> header is required then the entire header MUST be encrypted using the 1055 <wsse11:EncryptedHeader> construct. This helps facilitate re-issuance by the receiving party 1056 as that party can re-encrypt the entire header for another party rather than having to 1057 extract and re-encrypt portions of the header. 1058 1059 The following example illustrates a response that includes multiple <wst:IssuedTokens> 1060 headers. 1061

<S:Envelope> 1062 <S:Header> 1063 <wst:IssuedTokens> 1064 <wst:RequestSecurityTokenResponse> 1065 <wsp:AppliesTo> 1066 <x:SomeContext1 /> 1067 </wsp:AppliesTo> 1068 <wst:RequestedSecurityToken> 1069 ... 1070 </wst:RequestedSecurityToken> 1071 ... 1072 </wst:RequestSecurityTokenResponse> 1073 <wst:RequestSecurityTokenResponse> 1074 <wsp:AppliesTo> 1075 <x:SomeContext1 /> 1076 </wsp:AppliesTo> 1077 <wst:RequestedSecurityToken> 1078 ... 1079 </wst:RequestedSecurityToken> 1080 ... 1081 </wst:RequestSecurityTokenResponse> 1082 </wst:IssuedTokens> 1083 <wst:IssuedTokens s:role='http://example.org/somerole' > 1084 <wst:RequestSecurityTokenResponse> 1085 <wsp:AppliesTo> 1086 <x:SomeContext2 /> 1087 </wsp:AppliesTo> 1088 <wst:RequestedSecurityToken> 1089 ... 1090 </wst:RequestedSecurityToken> 1091 ... 1092 </wst:RequestSecurityTokenResponse> 1093 </wst:IssuedTokens> 1094 </S:Header> 1095 <S:Body> 1096 ... 1097 </S:Body> 1098 </S:Envelope> 1099

Deleted: 5

Deleted: 26

Deleted: April


5 Renewal Binding 1100

Using the token request framework, this section defines bindings for requesting security 1101 tokens to be renewed: 1102

Renew – A previously issued token with expiration is presented (and possibly proven) and the 1103 same token is returned with new expiration semantics. 1104

1105 For this binding, the following actions are defined to enable specific processing context to be 1106 conveyed to the recipient: 1107

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Renew 1108 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Renew 1109 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/RenewFinal 1110

For this binding, the <RequestType> element uses the following URI: 1111

http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew 1112

For this binding the token to be renewed is identified in the <RenewTarget> element and the 1113 optional <Lifetime> element MAY be specified to request a specified renewal duration. 1114 1115 Other extensions MAY be specified in the request (and the response), but the key semantics 1116 (size, type, algorithms, scope, etc.) MUST NOT be altered during renewal. Token services 1117 MAY use renewal as an opportunity to rekey, so the renewal responses MAY include a new 1118 proof-of-possession token as well as entropy and key exchange elements. 1119 1120 The request MUST prove authorized use of the token being renewed unless the recipient 1121 trusts the requestor to make third-party renewal requests. In such cases, the third-party 1122 requestor MUST prove its identity to the issuer so that appropriate authorization occurs. 1123 1124 The original proof information SHOULD be proven during renewal. 1125 1126 The renewal binding allows the use of exchanges during the renewal process. Subsequent 1127 profiles MAY define restriction around the usage of exchanges. 1128 1129 During renewal, all key bearing tokens used in the renewal request MUST have an 1130 associated signature. All non-key bearing tokens MUST be signed. Signature confirmation 1131 is RECOMMENDED on the renewal response. 1132 1133 The renewal binding also defines several extensions to the request and response elements. 1134 The syntax for these extension elements is as follows (note that the base elements 1135 described above are included here italicized for completeness): 1136

<wst:RequestSecurityToken> 1137 <wst:TokenType>...</wst:TokenType> 1138 <wst:RequestType>...</wst:RequestType> 1139 ... 1140 <wst:RenewTarget>...</wst:RenewTarget> 1141 <wst:AllowPostdating/> 1142

Deleted: 5

Deleted: 26

Deleted: April


<wst:Renewing Allow=... OK=.../> 1143 </wst:RequestSecurityToken> 1144

/wst:RequestSecurityToken/wst:RenewTarget 1145 This required element identifies the token being renewed. This MAY contain a 1146 <wsse:SecurityTokenReference> pointing at the token to be renewed or it MAY directly contain 1147 the token to be renewed. 1148

/wst:RequestSecurityToken/wst:AllowPostdating 1149 This optional element indicates that returned tokens should allow requests for postdated tokens. 1150 That is, this allows for tokens to be issued that are not immediately valid (e.g., a token that can be 1151 used the next day). 1152

/wst:RequestSecurityToken/wst:Renewing 1153 This optional element is used to specify renew semantics for types that support this operation. 1154

/wst:RequestSecurityToken/wst:Renewing/@Allow 1155 This optional Boolean attribute is used to request a renewable token. If not specified, the default 1156 value is true. A renewable token is one whose lifetime can be extended. This is done using a 1157 renewal request. The recipient MAY allow renewals without demonstration of authorized use of 1158 the token or they MAY fault. 1159

/wst:RequestSecurityToken/wst:Renewing/@OK 1160 This optional Boolean attribute is used to indicate that a renewable token is acceptable if the 1161 requested duration exceeds the limit of the issuance service. That is, if true then tokens can be 1162 renewed after their expiration. It should be noted that the token is NOT valid after expiration for 1163 any operation except renewal. The default for this attribute is false. It NOT RECOMMENDED to 1164 use this as it can leave you open to certain types of security attacks. Issuers MAY restrict the 1165 period after expiration during which time the token can be renewed. This window is governed by 1166 the issuer's policy. 1167

The following example illustrates a request for a custom token that can be renewed. 1168

<wst:RequestSecurityToken> 1169 <wst:TokenType> 1170 http://example.org/mySpecialToken 1171 </wst:TokenType> 1172 <wst:RequestType> 1173 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 1174 </wst:RequestType> 1175 <wst:Renewing/> 1176 </wst:RequestSecurityToken> 1177

1178 The following example illustrates a subsequent renewal request and response (note that for 1179 brevity only the request and response are illustrated). Note that the response includes an 1180 indication of the lifetime of the renewed token. 1181

<wst:RequestSecurityToken> 1182 <wst:TokenType> 1183 http://example.org/mySpecialToken 1184 </wst:TokenType> 1185 <wst:RequestType> 1186 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew 1187 </wst:RequestType> 1188 <wst:RenewTarget> 1189 ... reference to previously issued token ... 1190 </wst:RenewTarget> 1191 </wst:RequestSecurityToken> 1192 1193

Deleted: 5

Deleted: 26

Deleted: April


<wst:RequestSecurityTokenResponse> 1194 <wst:TokenType> 1195 http://example.org/mySpecialToken 1196 </wst:TokenType> 1197 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 1198 <wst:Lifetime>...</wst:Lifetime> 1199 ... 1200 </wst:RequestSecurityTokenResponse> 1201

Deleted: 5

Deleted: 26

Deleted: April


6 Cancel Binding 1202

Using the token request framework, this section defines bindings for requesting security 1203 tokens to be cancelled: 1204

Cancel – When a previously issued token is no longer needed, the Cancel binding can be used 1205 to cancel the token, terminating its use. After canceling a token at the issuer, a STS MUST not 1206 validate or renew the token. A STS MAY initiate the revocation of a token, however, revocation is 1207 out of scope of this specification and a client MUST NOT rely on it. If a client needs to ensure the 1208 validity of a token, it must validate the token at the issuer. 1209


http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel 1213 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Cancel 1214

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/CancelFinal 1215


http://docs.oasis-open.org/ws-sx/ws-trust/200512/Cancel 1217

Extensions MAY be specified in the request (and the response), but the semantics are not 1218 defined by this binding. 1219 1220 The request MUST prove authorized use of the token being cancelled unless the recipient 1221 trusts the requestor to make third-party cancel requests. In such cases, the third-party 1222 requestor MUST prove its identity to the issuer so that appropriate authorization occurs. 1223 In a cancel request, all key bearing tokens specified MUST have an associated signature. All 1224 non-key bearing tokens MUST be signed. Signature confirmation is RECOMMENDED on the 1225 closure response. 1226 1227 A cancelled token is no longer valid for authentication and authorization usages. 1228 On success a cancel response is returned. This is an RSTR message with the 1229 <wst:RequestedTokenCancelled> element in the body. On failure, a Fault is raised. It 1230 should be noted that the cancel RSTR is informational. That is, the security token is 1231 cancelled once the cancel request is processed. 1232 1233 The syntax of the request is as follows: 1234

<wst:RequestSecurityToken> 1235 <wst:RequestType>...</wst:RequestType> 1236 ... 1237 <wst:CancelTarget>...</wst:CancelTarget> 1238 </wst:RequestSecurityToken> 1239

/wst:RequestSecurityToken/wst:CancelTarget 1240 This required element identifies the token being cancelled. Typically this contains a 1241 <wsse:SecurityTokenReference> pointing at the token, but it could also carry the token 1242 directly. 1243

The following example illustrates a request to cancel a custom token. 1244

Deleted: 5

Deleted: 26

Deleted: April


<S11:Envelope> 1245 <S11:Header> 1246 <wsse:Security> 1247 ... 1248 </wsse:Security> 1249 </S11:Header> 1250 <S11:Body> 1251 <wst:RequestSecurityToken> 1252 <wst:RequestType> 1253 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Cancel 1254 </wst:RequestType> 1255 <wst:CancelTarget> 1256 ... 1257 </wst:CancelTarget> 1258 </wst:RequestSecurityToken> 1259 </S11:Body> 1260 </S11:Envelope> 1261

The following example illustrates a response to cancel a custom token. 1262

<S11:Envelope> 1263 <S11:Header> 1264 <wsse:Security> 1265 ... 1266 </wsse:Security> 1267 </S11:Header> 1268 <S11:Body> 1269 <wst:RequestSecurityTokenResponse> 1270 <wst:RequestedTokenCancelled/> 1271 </wst:RequestSecurityTokenResponse> 1272 </S11:Body> 1273 </S11:Envelope> 1274

6.1 STS-initiated Cancel Binding 1275

Using the token request framework, this section defines an optional binding for requesting 1276 security tokens to be cancelled by the STS: 1277

STS-initiated Cancel – When a previously issued token becomes invalid on the STS, the STS-1278 initiated Cancel binding can be used to cancel the token, terminating its use. After canceling a 1279 token, a STS MUST not validate or renew the token. This binding can be only used when STS 1280 can send one-way messages to the original token requestor. 1281


http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/STSCancel 1285


http://docs.oasis-open.org/ws-sx/ws-trust/200512/STSCancel 1287

Extensions MAY be specified in the request, but the semantics are not defined by this 1288 binding. 1289 1290 The request MUST prove authorized use of the token being cancelled unless the recipient 1291 trusts the requestor to make third-party cancel requests. In such cases, the third-party 1292 requestor MUST prove its identity to the issuer so that appropriate authorization occurs. 1293 In a cancel request, all key bearing tokens specified MUST have an associated signature. All 1294 non-key bearing tokens MUST be signed. 1295

Comment [MJG1]: We only need the RST action because there is no response message in this binidng

Deleted: 5

Deleted: 26

Deleted: April


1296 A cancelled token is no longer valid for authentication and authorization usages. 1297 This is a one-way operation, no response is returned from the recipient of the message. 1298 1299 The syntax of the request is as follows: 1300

<wst:RequestSecurityToken> 1301 <wst:RequestType>...</wst:RequestType> 1302 ... 1303 <wst:CancelTarget>...</wst:CancelTarget> 1304 </wst:RequestSecurityToken> 1305

/wst:RequestSecurityToken/wst:CancelTarget 1306 This required element identifies the token being cancelled. Typically this contains a 1307 <wsse:SecurityTokenReference> pointing at the token, but it could also carry the token 1308 directly. 1309

The following example illustrates a request to cancel a custom token. 1310

<S11:Envelope> 1311 <S11:Header> 1312 <wsse:Security> 1313 ... 1314 </wsse:Security> 1315 </S11:Header> 1316 <S11:Body> 1317 <wst:RequestSecurityToken> 1318 <wst:RequestType> 1319 http://docs.oasis-open.org/ws-sx/ws-trust/200512/STSCancel 1320 </wst:RequestType> 1321 <wst:CancelTarget> 1322 ... 1323 </wst:CancelTarget> 1324 </wst:RequestSecurityToken> 1325 </S11:Body> 1326 </S11:Envelope> 1327

Deleted: 5

Deleted: 26

Deleted: April


7 Validation Binding 1328

Using the token request framework, this section defines bindings for requesting security 1329 tokens to be validated: 1330

Validate – The validity of the specified security token is evaluated and a result is returned. The 1331 result may be a status, a new token, or both. 1332

1333 It should be noted that for this binding, a SOAP Envelope MAY be specified as a "security 1334 token" if the requestor desires the envelope to be validated. In such cases the recipient 1335 SHOULD understand how to process a SOAP envelope and adhere to SOAP processing 1336 semantics (e.g., mustUnderstand) of the version of SOAP used in the envelope. Otherwise, 1337 the recipient SHOULD fault. 1338 For this binding, the following actions are defined to enable specific processing context to be 1339 conveyed to the recipient: 1340

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Validate 1341 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Validate 1342

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/ValidateFinal 1343

1344 For this binding, the <RequestType> element contains the following URI: 1345

http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate 1346

1347 The request provides a token upon which the request is based and optional tokens. As well, 1348 the optional <wst:TokenType> element in the request can indicate desired type response 1349 token. This may be any supported token type or it may be the following URI indicating that 1350 only status is desired: 1351

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status 1352

1353 For some use cases a status token is returned indicating the success or failure of the 1354 validation. In other cases a security token MAY be returned and used for authorization. 1355 This binding assumes that the validation requestor and provider are known to each other 1356 and that the general issuance parameters beyond requesting a token type, which is 1357 optional, are not needed (note that other bindings and profiles could define different 1358 semantics). 1359 1360 For this binding an applicability scope (e.g., <wsp:AppliesTo>) need not be specified. It is 1361 assumed that the applicability of the validation response relates to the provided information 1362 (e.g. security token) as understood by the issuing service. 1363 1364 The validation binding does not allow the use of exchanges. 1365 1366 The RSTR for this binding carries the following element even if a token is returned (note 1367 that the base elements described above are included here italicized for completeness): 1368

<wst:RequestSecurityToken> 1369

Deleted: 5

Deleted: 26

Deleted: April


<wst:TokenType>...</wst:TokenType> 1370 <wst:RequestType>...</wst:RequestType> 1371 <wst:ValidateTarget>... </wst:Validatetarget> 1372 ... 1373 </wst:RequestSecurityToken> 1374 1375 <wst:RequestSecurityTokenResponse> 1376 <wst:TokenType>...</wst:TokenType> 1377 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 1378 ... 1379 <wst:Status> 1380 <wst:Code>...</wst:Code> 1381 <wst:Reason>...</wst:Reason> 1382 </wst:Status> 1383 <wst:RequestSecurityTokenResponse> 1384

1385 /wst:RequestSecurityToken/wst:ValidateTarget 1386

This required element identifies the token being validated. Typically this contains a 1387 <wsse:SecurityTokenReference> pointing at the token, but could also carry the token 1388 directly. 1389

/wst:RequestSecurityTokenResponse/wst:Status 1390 When a validation request is made, this element MUST be in the response. The code value 1391 indicates the results of the validation in a machine-readable form. The accompanying text 1392 element allows for human textual display. 1393

/wst:RequestSecurityTokenResponse/wst:Status/wst:Code 1394 This required URI value provides a machine-readable status code. The following URIs are 1395 predefined, but others MAY be used. 1396

URI Description

http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid

The Trust service successfully validated the input

http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/invalid

The Trust service did not successfully validate the input

/wst:RequestSecurityTokenResponse/wst:Status/wst:Reason 1397 This optional string provides human-readable text relating to the status code. 1398

1399 The following example illustrates a validation request and response. In this example no 1400 token is requested, just a status. 1401

<wst:RequestSecurityToken> 1402 <wst:TokenType> 1403 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status 1404 </wst:TokenType> 1405 <wst:RequestType> 1406 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate 1407 </wst:RequestType> 1408 </wst:RequestSecurityToken> 1409 1410 <wst:RequestSecurityTokenResponse> 1411 <wst:TokenType> 1412 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status 1413 </wst:TokenType> 1414

Deleted: 5

Deleted: 26

Deleted: April


<wst:Status> 1415 <wst:Code> 1416 http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid 1417 </wst:Code> 1418 </wst:Status> 1419 ... 1420 </wst:RequestSecurityTokenResponse> 1421

1422 The following example illustrates a validation request and response. In this example a 1423 custom token is requested indicating authorized rights in addition to the status. 1424

<wst:RequestSecurityToken> 1425 <wst:TokenType> 1426 http://example.org/mySpecialToken 1427 </wst:TokenType> 1428 <wst:RequestType> 1429 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate 1430 </wst:RequestType> 1431 </wst:RequestSecurityToken> 1432 1433 <wst:RequestSecurityTokenResponse> 1434 <wst:TokenType> 1435 http://example.org/mySpecialToken 1436 </wst:TokenType> 1437 <wst:Status> 1438 <wst:Code> 1439 http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid 1440 </wst:Code> 1441 </wst:Status> 1442 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 1443 ... 1444 </wst:RequestSecurityTokenResponse> 1445

Deleted: 5

Deleted: 26

Deleted: April


8 Negotiation and Challenge Extensions 1446

The general security token service framework defined above allows for a simple request and 1447 response for security tokens (possibly asynchronous). However, there are many scenarios 1448 where a set of exchanges between the parties is required prior to returning (e.g., issuing) a 1449 security token. This section describes the extensions to the base WS-Trust mechanisms to 1450 enable exchanges for negotiation and challenges. 1451 1452 There are potentially different forms of exchanges, but one specific form, called 1453 "challenges", provides mechanisms in addition to those described in [WS-Security] for 1454 authentication. This section describes how general exchanges are issued and responded to 1455 within this framework. Other types of exchanges include, but are not limited to, negotiation, 1456 tunneling of hardware-based processing, and tunneling of legacy protocols. 1457 1458 The process is straightforward (illustrated here using a challenge): 1459 1460

1461

1. A requestor sends, for example, a <wst:RequestSecurityToken> message with a 1462 timestamp. 1463

2. The recipient does not trust the timestamp and issues a 1464 <wst:RequestSecurityTokenResponse> message with an embedded challenge. 1465

3. The requestor sends a <wst:RequestSecurityTokenReponse> message with an 1466 answer to the challenge. 1467

4. The recipient issues a <wst:RequestSecurityTokenResponseCollection> message 1468 with the issued security token and optional proof-of-possession token. 1469

1470 It should be noted that the requestor might challenge the recipient in either step 1 or step 1471 3. In which case, step 2 or step 4 contains an answer to the initiator's challenge. Similarly, 1472 it is possible that steps 2 and 3 could iterate multiple times before the process completes 1473 (step 4). 1474 1475 Deleted: 5

Deleted: 26

Deleted: April


The two services can use [WS-SecurityPolicy] to state their requirements and preferences 1476 for security tokens and encryption and signing algorithms (general policy intersection). This 1477 section defines mechanisms for legacy and more sophisticated types of negotiations. 1478

8.1 Negotiation and Challenge Framework 1479

The general mechanisms defined for requesting and returning security tokens are 1480 extensible. This section describes the general model for extending these to support 1481 negotiations and challenges. 1482 1483 The exchange model is as follows: 1484

1. A request is initiated with a <wst:RequestSecurityToken> that identifies the details 1485 of the request (and may contain initial negotiation/challenge information) 1486

2. A response is returned with a <wst:RequestSecurityTokenResponse> that contains 1487 additional negotiation/challenge information. Optionally, this may return token 1488 information in the form of a <wst:RequestSecurityTokenResponseCollection> (if 1489 the exchange is two legs long). 1490

3. If the exchange is not complete, the requestor uses a 1491 <wst:RequestSecurityTokenResponse> that contains additional 1492 negotiation/challenge information. 1493

4. The process repeats at step 2 until the negotiation/challenge is complete (a token is 1494 returned or a Fault occurs). In the case where token information is returned in the 1495 final leg, it is returned in the form of a 1496 <wst:RequestSecurityTokenResponseCollection>. 1497

1498 The negotiation/challenge information is passed in binding/profile-specific elements that are 1499 placed inside of the <wst:RequestSecurityToken> and 1500 <wst:RequestSecurityTokenResponse> elements. 1501 1502 It is RECOMMENDED that at least the <wsu:Timestamp> element be included in messages 1503 (as per [WS-Security]) as a way to ensure freshness of the messages in the exchange. 1504 Other types of challenges MAY also be included. For example, a <wsp:Policy> element 1505 may be used to negotiate desired policy behaviors of both parties. Multiple challenges and 1506 responses MAY be included. 1507

8.2 Signature Challenges 1508

Exchange requests are issued by including an element that describes the exchange (e.g. 1509 challenge) and responses contain an element describing the response. For example, 1510 signature challenges are processed using the <SignChallenge> element. The response is 1511 returned in a <SignChallengeResponse> element. Both the challenge and the response 1512 elements are specified within the <wst:RequestSecurityTokenResponse> element. Some 1513 forms of negotiation MAY specify challenges along with responses to challenges from the 1514 other party. It should be noted that the requestor MAY provide exchange information (e.g. 1515 a challenge) to the recipient in the initial request. Consequently, these elements are also 1516 allowed within a <wst:RequestSecurityToken> element. 1517 1518 The syntax of these elements is as follows: 1519

Deleted: 5

Deleted: 26

Deleted: April


<wst:SignChallenge> 1520 <wst:Challenge ...>...</wst:Challenge> 1521 </wst:SignChallenge> 1522 1523 <wst:SignChallengeResponse> 1524 <wst:Challenge ...>...</wst:Challenge> 1525 </wst:SignChallengeResponse> 1526

1527 The following describes the attributes and tags listed in the schema above: 1528 .../wst:SignChallenge 1529

This optional element describes a challenge that requires the other party to sign a specified set of 1530 information. 1531

.../wst:SignChallenge/ws:Challenge 1532 This required string element describes the value to be signed. In order to prevent certain types of 1533 attacks (such as man-in-the-middle), it is strongly RECOMMENDED that the challenge be bound 1534 to the negotiation. For example, the challenge SHOULD track (such as using a digest of) any 1535 relevant data exchanged such as policies, tokens, replay protection, etc. As well, if the challenge 1536 is happening over a secured channel, a reference to the channel SHOULD also be included. 1537 Furthermore, the recipient of a challenge SHOULD verify that the data tracked (digested) 1538 matches their view of the data exchanged. The exact algorithm MAY be defined in profiles or 1539 agreed to by the parties. 1540

.../SignChallenge/{any} 1541 This is an extensibility mechanism to allow additional negotiation types to be used. 1542

.../wst:SignChallenge/@{any} 1543 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added 1544 to the element. 1545

.../wst:SignChallengeResponse 1546 This optional element describes a response to a challenge that requires the signing of a specified 1547 set of information. 1548

.../wst:SignChallengeResponse/wst:Challenge 1549 If a challenge was issued, the response MUST contain the challenge element exactly as 1550 received. As well, while the RSTR response SHOULD always be signed, if a challenge was 1551 issued, the RSTR MUST be signed (and the signature coupled with the message to prevent 1552 replay). 1553

.../wst:SignChallengeResponse/{any} 1554 This is an extensibility mechanism to allow additional negotiation types to be used. 1555

.../wst:SignChallengeResponse/@{any} 1556 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added 1557 to the element. 1558

8.3 Binary Exchanges and Negotiations 1559

Exchange requests may also utilize existing binary formats passed within the WS-Trust 1560 framework. A generic mechanism is provided for this that includes a URI attribute to 1561 indicate the type of binary exchange. 1562 1563 The syntax of this element is as follows: 1564

Deleted: 5

Deleted: 26

Deleted: April


<wst:BinaryExchange ValueType="..." EncodingType="..."> 1565 ... 1566 </wst:BinaryExchange> 1567

The following describes the attributes and tags listed in the schema above (note that the 1568 ellipses below indicate that this element may be placed in different containers. For this 1569 specification, these are limited to <wst:RequestSecurityToken> and 1570 <wst:RequestSecurityTokenResponse>): 1571 .../wst:BinaryExchange 1572

This optional element is used for a security negotiation that involves exchanging binary blobs as 1573 part of an existing negotiation protocol. The contents of this element are blob-type-specific and 1574 are encoded using base64 (unless otherwise specified). 1575

.../wst:BinaryExchange/@ValueType 1576 This required attribute specifies a URI to identify the type of negotiation (and the value space of 1577 the blob – the element's contents). 1578

.../wst:BinaryExchange/@EncodingType 1579 This required attribute specifies a URI to identify the encoding format (if different from base64) of 1580 the negotiation blob. Refer to [WS-Security] for sample encoding format URIs. 1581

.../wst:BinaryExchange/@{any} 1582 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added 1583 to the element. 1584

Some binary exchanges result in a shared state/context between the involved parties. It is 1585 RECOMMENDED that at the conclusion of the exchange, a new token and proof-of-1586 possession token be returned. A common approach is to use the negotiated key as a 1587 "secure channel" mechanism to secure the new token and proof-of-possession token. 1588 For example, an exchange might establish a shared secret Sx that can then be used to sign 1589 the final response and encrypt the proof-of-possession token. 1590

8.4 Key Exchange Tokens 1591

In some cases it may be necessary to provide a key exchange token so that the other party 1592 (either requestor or issuer) can provide entropy or key material as part of the exchange. 1593 Challenges may not always provide a usable key as the signature may use a signing-only 1594 certificate. 1595 1596 The section describes two optional elements that can be included in RST and RSTR elements 1597 to indicate that a Key Exchange Token (KET) is desired, or to provide a KET. 1598 The syntax of these elements is as follows (Note that the ellipses below indicate that this 1599 element may be placed in different containers. For this specification, these are limited to 1600 <wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse>): 1601

<wst:RequestKET/> 1602 <wst:KeyExchangeToken>...</wst:KeyExchangeToken> 1603

1604 The following describes the attributes and tags listed in the schema above: 1605 .../wst:RequestKET 1606

This optional element is used to indicate that the receiving party (either the original requestor or 1607 issuer) should provide a KET to the other party on the next leg of the exchange. 1608

Deleted: 5

Deleted: 26

Deleted: April


.../wst:KeyExchangeToken 1609 This optional element is used to provide a key exchange token. The contents of this element 1610 either contain the security token to be used for key exchange or a reference to it. 1611

8.5 Custom Exchanges 1612

Using the extensibility model described in this specification, any custom XML-based 1613 exchange can be defined in a separate binding/profile document. In such cases elements 1614 are defined which are carried in the RST and RSTR elements. 1615 1616 It should be noted that it is NOT REQUIRED that exchange elements be symmetric. That is, 1617 a specific exchange mechanism MAY use multiple elements at different times, depending on 1618 the state of the exchange. 1619

8.6 Signature Challenge Example 1620

Here is an example exchange involving a signature challenge. In this example, a service 1621 requests a custom token using a X.509 certificate for authentication. The issuer uses the 1622 exchange mechanism to challenge the requestor to sign a random value (to ensure message 1623 freshness). The requestor provides a signature of the requested data and, once validated, 1624 the issuer then issues the requested token. 1625 1626 The first message illustrates the initial request that is signed with the private key associated 1627 with the requestor's X.509 certificate: 1628

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." 1629 xmlns:wsu="..." xmlns:wst="..."> 1630 <S11:Header> 1631 ... 1632 <wsse:Security> 1633 <wsse:BinarySecurityToken 1634 wsu:Id="reqToken" 1635 ValueType="...X509v3"> 1636 MIIEZzCCA9CgAwIBAgIQEmtJZc0... 1637 </wsse:BinarySecurityToken> 1638 <ds:Signature xmlns:ds="..."> 1639 ... 1640 <ds:KeyInfo> 1641 <wsse:SecurityTokenReference> 1642 <wsse:Reference URI="#reqToken"/> 1643 </wsse:SecurityTokenReference> 1644 </ds:KeyInfo> 1645 </ds:Signature> 1646 </wsse:Security> 1647 ... 1648 </S11:Header> 1649 <S11:Body> 1650 <wst:RequestSecurityToken> 1651 <wst:TokenType> 1652 http://example.org/mySpecialToken 1653 </wst:TokenType> 1654 <wst:RequestType> 1655 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 1656 </wst:RequestType> 1657 </wst:RequestSecurityToken> 1658 </S11:Body> 1659 </S11:Envelope> 1660

Deleted: 5

Deleted: 26

Deleted: April


1661 The issuer (recipient) service doesn't trust the sender's timestamp (or one wasn't specified) 1662 and issues a challenge using the exchange framework defined in this specification. This 1663 message is signed using the private key associated with the issuer's X.509 certificate and 1664 contains a random challenge that the requestor must sign: 1665

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..." 1666 xmlns:wst="..."> 1667 <S11:Header> 1668 ... 1669 <wsse:Security> 1670 <wsse:BinarySecurityToken 1671 wsu:Id="issuerToken" 1672 ValueType="...X509v3"> 1673 DFJHuedsujfnrnv45JZc0... 1674 </wsse:BinarySecurityToken> 1675 <ds:Signature xmlns:ds="..."> 1676 ... 1677 </ds:Signature> 1678 </wsse:Security> 1679 ... 1680 </S11:Header> 1681 <S11:Body> 1682 <wst:RequestSecurityTokenResponse> 1683 <wst:SignChallenge> 1684 <wst:Challenge>Huehf...</wst:Challenge> 1685 </wst:SignChallenge> 1686 </wst:RequestSecurityTokenResponse> 1687 </S11:Body> 1688 </S11:Envelope> 1689

1690 The requestor receives the issuer's challenge and issues a response that is signed using the 1691 requestor's X.509 certificate and contains the challenge. The signature only covers the non-1692 mutable elements of the message to prevent certain types of security attacks: 1693

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..." 1694 xmlns:wst="..."> 1695 <S11:Header> 1696 ... 1697 <wsse:Security> 1698 <wsse:BinarySecurityToken 1699 wsu:Id="reqToken" 1700 ValueType="...X509v3"> 1701 MIIEZzCCA9CgAwIBAgIQEmtJZc0... 1702 </wsse:BinarySecurityToken> 1703 <ds:Signature xmlns:ds="..."> 1704 ... 1705 </ds:Signature> 1706 </wsse:Security> 1707 ... 1708 </S11:Header> 1709 <S11:Body> 1710 <wst:RequestSecurityTokenResponse> 1711 <wst:SignChallengeResponse> 1712 <wst:Challenge>Huehf...</wst:Challenge> 1713 </wst:SignChallengeResponse> 1714 </wst:RequestSecurityTokenResponse> 1715 </S11:Body> 1716 </S11:Envelope> 1717

1718 Deleted: 5

Deleted: 26

Deleted: April


The issuer validates the requestor's signature responding to the challenge and issues the 1719 requested token(s) and the associated proof-of-possession token. The proof-of-possession 1720 token is encrypted for the requestor using the requestor's public key. 1721

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..." 1722 xmlns:wst="..." xmlns:xenc="..."> 1723 <S11:Header> 1724 ... 1725 <wsse:Security> 1726 <wsse:BinarySecurityToken 1727 wsu:Id="issuerToken" 1728 ValueType="...X509v3"> 1729 DFJHuedsujfnrnv45JZc0... 1730 </wsse:BinarySecurityToken> 1731 <ds:Signature xmlns:ds="..."> 1732 ... 1733 </ds:Signature> 1734 </wsse:Security> 1735 ... 1736 </S11:Header> 1737 <S11:Body> 1738 <wst:RequestSecurityTokenResponseCollection> 1739 <wst:RequestSecurityTokenResponse> 1740 <wst:RequestedSecurityToken> 1741 <xyz:CustomToken xmlns:xyz="..."> 1742 ... 1743 </xyz:CustomToken> 1744 </wst:RequestedSecurityToken> 1745 <wst:RequestedProofToken> 1746 <xenc:EncryptedKey Id="newProof"> 1747 ... 1748 </xenc:EncryptedKey> 1749 </wst:RequestedProofToken> 1750 </wst:RequestSecurityTokenResponse> 1751 </wst:RequestSecurityTokenResponseCollection> 1752 </S11:Body> 1753 </S11:Envelope> 1754

8.7 Custom Exchange Example 1755

Here is another example illustrating a token request using a custom XML exchange. For 1756 brevity, only the RST and RSTR elements are illustrated. Note that the framework allows 1757 for an arbitrary number of exchanges, although this example illustrates the use of four legs. 1758 The request uses a custom exchange element and the requestor signs only the non-mutable 1759 element of the message: 1760

<wst:RequestSecurityToken> 1761 <wst:TokenType> 1762 http://example.org/mySpecialToken 1763 </wst:TokenType> 1764 <wst:RequestType> 1765 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 1766 </wst:RequestType> 1767 <xyz:CustomExchange xmlns:xyz="..."> 1768 ... 1769 </xyz:CustomExchange> 1770 </wst:RequestSecurityToken> 1771

1772 The issuer service (recipient) responds with another leg of the custom exchange and signs 1773 the response (non-mutable aspects) with its token: 1774

Deleted: 5

Deleted: 26

Deleted: April


... 1775 <wst:RequestSecurityTokenResponse> 1776 <xyz:CustomExchange xmlns:xyz="..."> 1777 ... 1778 </xyz:CustomExchange> 1779 </wst:RequestSecurityTokenResponse> 1780 ... 1781

1782 The requestor receives the issuer's exchange and issues a response that is signed using the 1783 requestor's token and continues the custom exchange. The signature covers all non-1784 mutable aspects of the message to prevent certain types of security attacks: 1785

... 1786 <wst:RequestSecurityTokenResponse> 1787 <xyz:CustomExchange xmlns:xyz="..."> 1788 ... 1789 </xyz:CustomExchange> 1790 </wst:RequestSecurityTokenResponse> 1791 ... 1792

1793 The issuer processes the exchange and determines that the exchange is complete and that 1794 a token should be issued. Consequently it issues the requested token(s) and the associated 1795 proof-of-possession token. The proof-of-possession token is encrypted for the requestor 1796 using the requestor's public key. 1797

... 1798 <wst:RequestSecurityTokenResponseCollection> 1799 <wst:RequestSecurityTokenResponse> 1800 <wst:RequestedSecurityToken> 1801 <xyz:CustomToken xmlns:xyz="..."> 1802 ... 1803 </xyz:CustomToken> 1804 </wst:RequestedSecurityToken> 1805 <wst:RequestedProofToken> 1806 <xenc:EncryptedKey Id="newProof"> 1807 ... 1808 </xenc:EncryptedKey> 1809 </wst:RequestedProofToken> 1810 <wst:RequestedProofToken> 1811 <xenc:EncryptedKey>...</xenc:EncryptedKey> 1812 </wst:RequestedProofToken> 1813 </wst:RequestSecurityTokenResponse> 1814 <wst:RequestSecurityTokenResponseCollection> 1815 ... 1816

It should be noted that other example exchanges include the issuer returning a final custom 1817 exchange element, and another example where a token isn't returned. 1818

8.8 Protecting Exchanges 1819

There are some attacks, such as forms of man-in-the-middle, that can be applied to token 1820 requests involving exchanges. It is RECOMMENDED that the exchange sequence be 1821 protected. This may be built into the exchange messages, but if metadata is provided in the 1822 RST or RSTR elements, then it is subject to attack. 1823 1824 Consequently, it is RECOMMENDED that keys derived from exchanges be linked 1825 cryptographically to the exchange. For example, a hash can be computed by computing the 1826

Deleted: 5

Deleted: 26

Deleted: April


SHA1 of the exclusive canonicalization of all RST and RSTR elements in messages 1827 exchanged. This value can then be combined with the exchanged secret(s) to create a new 1828 master secret that is bound to the data both parties sent/received. 1829 1830 To this end, the following computed key algorithm is defined to be optionally used in these 1831 scenarios: 1832

URI Meaning

http://docs.oasis-open.org/ws-sx/ws-trust/200512/CK/HASH

The key is computed using P_SHA1 as follows:

H=SHA1(ExclC14N(RST...RSTRs))

X=encrypting H using negotiatied key and mechanism

Key=P_SHA1(X,H+"CK-HASH")

The octets for the "CK-HASH" string are the UTF-8 octets.

8.9 Authenticating Exchanges 1833

After an exchange both parties have a shared knowledge of a key (or keys) that can then be 1834 used to secure messages. However, in some cases it may be desired to have the issuer 1835 prove to the requestor that it knows the key (and that the returned metadata is valid) prior 1836 to the requestor using the data. However, until the exchange is actually completed it may 1837 (and is often) inappropriate to use the computed keys. As well, using a token that hasn't 1838 been returned to secure a message may complicate processing since it crosses the 1839 boundary of the exchange and the underlying message security. This means that it may not 1840 be appropriate to sign the final leg of the exchange using the key derived from the 1841 exchange. 1842 1843 For this reason an authenticator is defined that provides a way for the issuer to verify the 1844 hash as part of the token issuance. Specifically, when an authenticator is returned, the 1845 <wst:RequestSecurityTokenResponseCollection> element is returned. This contains one 1846 RSTR with the token being returned as a result of the exchange and a second RSTR that 1847 contains the authenticator (this order SHOULD be used). When an authenticator is used, 1848 RSTRs MUST use the @Context element so that the authenticator can be correlated to the 1849 token issuance. The authenticator is separated from the RSTR because otherwise 1850 computation of the RST/RSTR hash becomes more complex. The authenticator is 1851 represented using the <wst:Authenticator> element as illustrated below: 1852

... 1853 <wst:RequestSecurityTokenResponseCollection> 1854 <wst:RequestSecurityTokenResponse Context="..."> 1855 ... 1856 </wst:RequestSecurityTokenResponse> 1857 <wst:RequestSecurityTokenResponse Context="..."> 1858 <wst:Authenticator> 1859 <wst:CombinedHash>...</wst:CombinedHash> 1860 ... 1861 </wst:Authenticator> 1862 </wst:RequestSecurityTokenResponse> 1863 </wst:RequestSecurityTokenResponseCollection> 1864 ... 1865

Deleted: 5

Deleted: 26

Deleted: April


1866 The following describes the attributes and elements listed in the schema overview above 1867 (the ... notation below represents the path RSTRC/RSTR and is used for brevity): 1868 .../wst:Authenticator 1869

This optional element provides verification (authentication) of a computed hash. 1870

.../wst:Authenticator/wst:CombinedHash 1871 This optional element proves the hash and knowledge of the computed key. This is done by 1872 providing the base64 encoding of the first 256 bits of the P_SHA1 digest of the computed key and 1873 the concatenation of the hash determined for the computed key and the string "AUTH-HASH". 1874 Specifically, P_SHA1(computed-key, H + "AUTH-HASH")0-255. The octets for the "AUTH-HASH" 1875 string are the UTF-8 octets. 1876

1877 This <wst:CombinedHash> element is optional (and an open content model is used) to allow 1878 for different authenticators in the future. 1879

Deleted: 5

Deleted: 26

Deleted: April


9 Key and Token Parameter Extensions 1880

This section outlines additional parameters that can be specified in token requests and 1881 responses. Typically they are used with issuance requests, but since all types of requests 1882 may issue security tokens they could apply to other bindings. 1883

9.1 On-Behalf-Of Parameters 1884

In some scenarios the requestor is obtaining a token on behalf of another party. These 1885 parameters specify the issuer and original requestor of the token being used as the basis of 1886 the request. The syntax is as follows (note that the base elements described above are 1887 included here italicized for completeness): 1888

<wst:RequestSecurityToken> 1889 <wst:TokenType>...</wst:TokenType> 1890 <wst:RequestType>...</wst:RequestType> 1891 ... 1892 <wst:OnBehalfOf>...</wst:OnBehalfOf> 1893 <wst:Issuer>...</wst:Issuer> 1894 </wst:RequestSecurityToken> 1895

1896 The following describes the attributes and elements listed in the schema overview above: 1897 /wst:RequestSecurityToken/wst:OnBehalfOf 1898

This optional element indicates that the requestor is making the request on behalf of another. 1899 The identity on whose behalf the request is being made is specified by placing a security token, 1900 <wsse:SecurityTokenReference> element, or <wsa:EndpointReference> element 1901 within the <wst:OnBehalfOf> element. The requestor MAY provide proof of possession of the 1902 key associated with the OnBehalfOf identity by including a signature in the RST security header 1903 generated using the OnBehalfOf token that signs the primary signature of the RST (i.e. endorsing 1904 supporting token concept from WS-SecurityPolicy). Additional signed supporting tokens 1905 describing the OnBehalfOf context MAY also be included within the RST security header. 1906

/wst:RequestSecurityToken/wst:Issuer 1907 This optional element specifies the issuer of the security token that is presented in the message. 1908 This element's type is an endpoint reference as defined in [WS-Addressing]. 1909

1910 In the following example a proxy is requesting a security token on behalf of another 1911 requestor or end-user. 1912

<wst:RequestSecurityToken> 1913 <wst:TokenType>...</wst:TokenType> 1914 <wst:RequestType>...</wst:RequestType> 1915 ... 1916 <wst:OnBehalfOf>endpoint-reference</wst:OnBehalfOf> 1917 </wst:RequestSecurityToken> 1918

9.2 Key and Encryption Requirements 1919

This section defines extensions to the <wst:RequestSecurityToken> element for requesting 1920 specific types of keys or algorithms or key and algorithms as specified by a given policy in 1921 the return token(s). In some cases the service may support a variety of key types, sizes, 1922 and algorithms. These parameters allow a requestor to indicate its desired values. It 1923

Deleted: 5

Deleted: 26

Deleted: April


should be noted that the issuer's policy indicates if input values must be adhered to and 1924 faults generated for invalid inputs, or if the issuer will provide alterative values in the 1925 response. 1926 1927 Although illustrated using the <wst:RequestSecurityToken> element, these options can 1928 also be returned in a <wst:RequestSecurityTokenResponse> element. 1929 The syntax for these optional elements is as follows (note that the base elements described 1930 above are included here italicized for completeness): 1931

<wst:RequestSecurityToken> 1932 <wst:TokenType>...</wst:TokenType> 1933 <wst:RequestType>...</wst:RequestType> 1934 ... 1935 <wst:AuthenticationType>...</wst:AuthenticationType> 1936 <wst:KeyType>...</wst:KeyType> 1937 <wst:KeySize>...</wst:KeySize> 1938 <wst:SignatureAlgorithm>...</wst:SignatureAlgorithm> 1939 <wst:EncryptionAlgorithm>...</wst:EncryptionAlgorithm> 1940 <wst:CanonicalizationAlgorithm>...</wst:CanonicalizationAlgorithm> 1941 <wst:ComputedKeyAlgorithm>...</wst:ComputedKeyAlgorithm> 1942 <wst:Encryption>...</wst:Encryption> 1943 <wst:ProofEncryption>...</wst:ProofEncryption> 1944 <wst:UseKey Sig=...>...</wst:UseKey> 1945 <wst:SignWith>...</wst:SignWith> 1946 <wst:EncryptWith>...</wst:EncryptWith> 1947 </wst:RequestSecurityToken> 1948

1949 The following describes the attributes and elements listed in the schema overview above: 1950 /wst:RequestSecurityToken/wst:AuthenticationType 1951

This optional URI element indicates the type of authentication desired, specified as a URI. This 1952 specification does not predefine classifications; these are specific to token services as is the 1953 relative strength evaluations. The relative assessment of strength is up to the recipient to 1954 determine. That is, requestors should be familiar with the recipient policies. For example, this 1955 might be used to indicate which of the four U.S. government authentication levels is required. 1956

/wst:RequestSecurityToken/wst:KeyType 1957 This optional URI element indicates the type of key desired in the security token. The predefined 1958 values are identified in the table below. Note that some security token formats have fixed key 1959 types. It should be noted that new algorithms can be inserted by defining URIs in other 1960 specifications and profiles. 1961

URI Meaning

http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey

A public key token is requested

http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey

A symmetric key token is requested (default)

http://docs.oasis-open.org/ws-sx/wstrust/200512/Bearer

A bearer token is requested. This key type can be used by requestors to indicate that they want a security token to be issued that does not require proof of possession.

/wst:RequestSecurityToken/wst:KeySize 1962

Deleted: 5

Deleted: 26

Deleted: April


This optional integer element indicates the size of the key required specified in number of bits. 1963 This is a request, and, as such, the requested security token is not obligated to use the requested 1964 key size. That said, the recipient SHOULD try to use a key at least as strong as the specified 1965 value if possible. The information is provided as an indication of the desired strength of the 1966 security. 1967

/wst:RequestSecurityToken/wst:SignatureAlgorithm 1968 This optional URI element indicates the desired signature algorithm used within the returned 1969 token. This is specified as a URI indicating the algorithm (see [XML Signature] for typical signing 1970 algorithms). 1971

/wst:RequestSecurityToken/wst:EncryptionAlgorithm 1972 This optional URI element indicates the desired encryption algorithm used within the returned 1973 token. This is specified as a URI indicating the algorithm (see [XML-Encrypt] for typical 1974 encryption algorithms). 1975

/wst:RequestSecurityToken/wst:CanonicalizationAlgorithm 1976 This optional URI element indicates the desired canonicalization method used within the returned 1977 token. This is specified as a URI indicating the method (see [XML Signature] for typical 1978 canonicalization methods). 1979

/wst:RequestSecurityToken/wst:ComputedKeyAlgorithm 1980 This optional URI element indicates the desired algorithm to use when computed keys are used 1981 for issued tokens. 1982

/wst:RequestSecurityToken/wst:Encryption 1983 This optional element indicates that the requestor desires any returned secrets in issued security 1984 tokens to be encrypted for the specified token. That is, so that the owner of the specified token 1985 can decrypt the secret. Normally the security token is the contents of this element but a security 1986 token reference MAY be used instead. If this element isn't specified, the token used as the basis 1987 of the request (or specialized knowledge) is used to determine how to encrypt the key. 1988

/wst:RequestSecurityToken/wst:ProofEncryption 1989 This optional element indicates that the requestor desires any returned secrets in proof-of-1990 possession tokens to be encrypted for the specified token. That is, so that the owner of the 1991 specified token can decrypt the secret. Normally the security token is the contents of this element 1992 but a security token reference MAY be used instead. If this element isn't specified, the token 1993 used as the basis of the request (or specialized knowledge) is used to determine how to encrypt 1994 the key. 1995

/wst:RequestSecurityToken/wst:UseKey 1996 If the requestor wishes to use an existing key rather than create a new one, then this optional 1997 element can be used to reference the security token containing the desired key. This element 1998 either contains a security token or a <wsse:SecurityTokenReference> element that 1999 references the security token containing the key that should be used in the returned token. If 2000 <wst:KeyType> is not defined and a key type is not implicitly known to the service, it MAY be 2001 determined from the token (if possible). Otherwise this parameter is meaningless and is ignored. 2002 Requestors SHOULD demonstrate authorized use of the public key provided. 2003

/wst:RequestSecurityToken/wst:UseKey/@Sig 2004 In order to authenticate the key referenced, a signature MAY be used to prove the referenced 2005 token/key. If specified, this optional attribute indicates the ID of the corresponding signature (by 2006 URI reference). When this attribute is present, a key need not be specified inside the element 2007 since the referenced signature will indicate the corresponding token (and key). 2008

/wst:RequestSecurityToken/wst:SignWith 2009 Deleted: 5

Deleted: 26

Deleted: April


This optional URI element indicates the desired signature algorithm to be used with the issued 2010 security token (typically from the policy of the target site for which the token is being requested. 2011 While any of these optional elements MAY be included in RSTRs, this one is a likely candidate if 2012 there is some doubt (e.g., an X.509 cert that can only use DSS). 2013

/wst:RequestSecurityToken/wst:EncryptWith 2014 This optional URI element indicates the desired encryption algorithm to be used with the issued 2015 security token (typically from the policy of the target site for which the token is being requested.) 2016 While any of these optional elements MAY be included in RSTRs, this one is a likely candidate if 2017 there is some doubt. 2018

The example below illustrates a request that utilizes several of these parameters. A request 2019 is made for a custom token using a username and password as the basis of the request. 2020 For security, this token is encrypted (see "encUsername") for the recipient using the 2021 recipient's public key and referenced in the encryption manifest. The message is protected 2022 by a signature using a public key from the sender and authorized by the username and 2023 password. 2024 2025 The requestor would like the custom token to contain a 1024-bit public key whose value can 2026 be found in the key provided with the "proofSignature" signature (the key identified by 2027 "requestProofToken"). The token should be signed using RSA-SHA1 and encrypted for the 2028 token identified by "requestEncryptionToken". The proof should be encrypted using the 2029 token identified by "requestProofToken". 2030

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..." 2031 xmlns:wst="..." xmlns:ds="..." xmlns:xenc="..."> 2032 <S11:Header> 2033 ... 2034 <wsse:Security> 2035 <xenc:ReferenceList>...</xenc:ReferenceList> 2036 <xenc:EncryptedData Id="encUsername">...</xenc:EncryptedData> 2037 <wsse:BinarySecurityToken wsu:Id="requestEncryptionToken" 2038 ValueType="...SomeTokenType" xmlns:x="..."> 2039 MIIEZzCCA9CgAwIBAgIQEmtJZc0... 2040 </wsse:BinarySecurityToken> 2041 <wsse:BinarySecurityToken wsu:Id="requestProofToken" 2042 ValueType="...SomeTokenType" xmlns:x="..."> 2043 MIIEZzCCA9CgAwIBAgIQEmtJZc0... 2044 </wsse:BinarySecurityToken> 2045 <ds:Signature Id="proofSignature"> 2046 ... signature proving requested key ... 2047 ... key info points to the "requestedProofToken" token ... 2048 </ds:Signature> 2049 </wsse:Security> 2050 ... 2051 </S11:Header> 2052 <S11:Body wsu:Id="req"> 2053 <wst:RequestSecurityToken> 2054 <wst:TokenType> 2055 http://example.org/mySpecialToken 2056 </wst:TokenType> 2057 <wst:RequestType> 2058 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 2059 </wst:RequestType> 2060 <wst:KeyType> 2061 http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey 2062 </wst:KeyType> 2063 <wst:KeySize>1024</wst:KeySize> 2064 <wst:SignatureAlgorithm> 2065 http://www.w3.org/2000/09/xmldsig#rsa-sha1 2066

Deleted: 5

Deleted: 26

Deleted: April


</wst:SignatureAlgorithm> 2067 <wst:Encryption> 2068 <Reference URI="#requestEncryptionToken"> 2069 </wst:Encryption> 2070 <wst:ProofEncryption> 2071 <wsse:Reference URI="#requestProofToken"/> 2072 </wst:ProofEncryption> 2073 <wst:UseKey Sig="#proofSignature"/> 2074 </wst:RequestSecurityToken> 2075 </S11:Body> 2076 </S11:Envelope> 2077

9.3 Delegation and Forwarding Requirements 2078

This section defines extensions to the <wst:RequestSecurityToken> element for indicating 2079 delegation and forwarding requirements on the requested security token(s). 2080 The syntax for these extension elements is as follows (note that the base elements 2081 described above are included here italicized for completeness): 2082

<wst:RequestSecurityToken> 2083 <wst:TokenType>...</wst:TokenType> 2084 <wst:RequestType>...</wst:RequestType> 2085 ... 2086 <wst:DelegateTo>...</wst:DelegateTo> 2087 <wst:Forwardable>...</wst:Forwardable> 2088 <wst:Delegatable>...</wst:Delegatable> 2089 </wst:RequestSecurityToken> 2090

/wst:RequestSecurityToken/wst:DelegateTo 2091 This optional element indicates that the requested or issued token be delegated to another 2092 identity. The identity receiving the delegation is specified by placing a security token or 2093 <wsse:SecurityTokenReference> element within the <wst:DelegateTo> element. 2094

/wst:RequestSecurityToken/wst:Forwardable 2095 This optional element, of type xs:boolean, specifies whether the requested security token should 2096 be marked as "Forwardable". In general, this flag is used when a token is normally bound to the 2097 requestor's machine or service. Using this flag, the returned token MAY be used from any source 2098 machine so long as the key is correctly proven. The default value of this flag is true. 2099

/wst:RequestSecurityToken/wst:Delegatable 2100 This optional element, of type xs:boolean, specifies whether the requested security token should 2101 be marked as "Delegatable". Using this flag, the returned token MAY be delegated to another 2102 party. This parameter SHOULD be used in conjunction with <wst:DelegateTo>. The default 2103 value of this flag is false. 2104

2105 The following example illustrates a request for a custom token that can be delegated to the 2106 indicated recipient (specified in the binary security token) and used in the specified interval. 2107

<wst:RequestSecurityToken> 2108 <wst:TokenType> 2109 http://example.org/mySpecialToken 2110 </wst:TokenType> 2111 <wst:RequestType> 2112 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 2113 </wst:RequestType> 2114 <wst:DelegateTo> 2115 <wsse:BinarySecurityToken>...</wsse:BinarySecurityToken> 2116 </wst:DelegateTo> 2117 <wst:Delegatable>true</wst:Delegatable> 2118

Deleted: 5

Deleted: 26

Deleted: April


</wst:RequestSecurityToken> 2119

9.4 Policies 2120

This section defines extensions to the <wst:RequestSecurityToken> element for passing 2121 policies. 2122 2123 The syntax for these extension elements is as follows (note that the base elements 2124 described above are included here italicized for completeness): 2125

<wst:RequestSecurityToken> 2126 <wst:TokenType>...</wst:TokenType> 2127 <wst:RequestType>...</wst:RequestType> 2128 ... 2129 <wsp:Policy>...</wsp:Policy> 2130 <wsp:PolicyReference>...</wsp:PolicyReference> 2131 </wst:RequestSecurityToken> 2132

2133 The following describes the attributes and elements listed in the schema overview above: 2134 /wst:RequestSecurityToken/wsp:Policy 2135

This optional element specifies a policy (as defined in [WS-Policy]) that indicates desired settings 2136 for the requested token. The policy specifies defaults that can be overridden by the elements 2137 defined in the previous sections. 2138

/wst:RequestSecurityToken/wsp:PolicyReference 2139 This optional element specifies a reference to a policy (as defined in [WS-Policy]) that indicates 2140 desired settings for the requested token. The policy specifies defaults that can be overridden by 2141 the elements defined in the previous sections. 2142

2143 The following example illustrates a request for a custom token that provides a set of policy 2144 statements about the token or its usage requirements. 2145

<wst:RequestSecurityToken> 2146 <wst:TokenType> 2147 http://example.org/mySpecialToken 2148 </wst:TokenType> 2149 <wst:RequestType> 2150 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 2151 </wst:RequestType> 2152 <wsp:Policy xmlns:wsp="..."> 2153 ... 2154 </wsp:Policy> 2155 </wst:RequestSecurityToken> 2156

9.5 Authorized Token Participants 2157

This section defines extensions to the <wst:RequestSecurityToken> element for passing 2158 information about which parties are authorized to participate in the use of the token. This 2159 parameter is typically used when there are additional parties using the token or if the 2160 requestor needs to clarify the actual parties involved (for some profile-specific reason). 2161 It should be noted that additional participants will need to prove their identity to recipients 2162 in addition to proving their authorization to use the returned token. This typically takes the 2163 form of a second signature or use of transport security. 2164

Deleted: 5

Deleted: 26

Deleted: April


2165 The syntax for these extension elements is as follows (note that the base elements 2166 described above are included here italicized for completeness): 2167

<wst:RequestSecurityToken> 2168 <wst:TokenType>...</wst:TokenType> 2169 <wst:RequestType>...</wst:RequestType> 2170 ... 2171 <wst:Participants> 2172 <wst:Primary>...</wst:Primary> 2173 <wst:Participant>...</wst:Participant> 2174 </wst:Participants> 2175 </wst:RequestSecurityToken> 2176

2177 The following describes elements and attributes used in a <wsc:SecurityContextToken> 2178 element. 2179 /wst:RequestSecurityToken/wst:Participants/ 2180

This optional element specifies the participants sharing the security token. Arbitrary types may be 2181 used to specify participants, but a typical case is a security token or an endpoint reference (see 2182 [WS-Addressing]). 2183

/wst:RequestSecurityToken/wst:Participants/wst:Primary 2184 This optional element specifies the primary user of the token (if one exists). 2185

/wst:RequestSecurityToken/wst:Participants/wst:Participant 2186 This optional element specifies participant (or multiple participants by repeating the element) that 2187 play a (profile-dependent) role in the use of the token or who are allowed to use the token. 2188

/wst:RequestSecurityToken/wst:Participants/{any} 2189 This is an extensibility option to allow other types of participants and profile-specific elements to 2190 be specified. 2191

Deleted: 5

Deleted: 26

Deleted: April


10 Key Exchange Token Binding 2192

Using the token request framework, this section defines a binding for requesting a key 2193 exchange token (KET). That is, if a requestor desires a token that can be used to encrypt 2194 key material for a recipient. 2195 2196 For this binding, the following actions are defined to enable specific processing context to be 2197 conveyed to the recipient: 2198

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KET 2199 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/KET 2200

http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/KETFinal 2201

2202 For this binding, the RequestType element contains the following URI: 2203

http://docs.oasis-open.org/ws-sx/ws-trust/200512/KET 2204

2205 For this binding very few parameters are specified as input. Optionally the 2206 <wst:TokenType> element can be specified in the request can indicate desired type 2207 response token carrying the key for key exchange; however, this isn't commonly used. 2208 The applicability scope (e.g. <wsp:AppliesTo>) MAY be specified if the requestor desires a 2209 key exchange token for a specific scope. 2210 2211 It is RECOMMENDED that the response carrying the key exchange token be secured (e.g., 2212 signed by the issuer or someone who can speak on behalf of the target for which the KET 2213 applies). 2214 2215 Care should be taken when using this binding to prevent possible man-in-the-middle and 2216 substitution attacks. For example, responses to this request SHOULD be secured using a 2217 token that can speak for the desired endpoint. 2218 2219 The RSTR for this binding carries the <RequestedSecurityToken> element even if a token is 2220 returned (note that the base elements described above are included here italicized for 2221 completeness): 2222

<wst:RequestSecurityToken> 2223 <wst:TokenType>...</wst:TokenType> 2224 <wst:RequestType>...</wst:RequestType> 2225 ... 2226 </wst:RequestSecurityToken> 2227 2228 <wst:RequestSecurityTokenResponseCollection> 2229 <wst:RequestSecurityTokenResponse> 2230 <wst:TokenType>...</wst:TokenType> 2231 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken> 2232 ... 2233 </wst:RequestSecurityTokenResponse> 2234 </wst:RequestSecurityTokenResponseCollection> 2235

2236 Deleted: 5

Deleted: 26

Deleted: April


The following example illustrates requesting a key exchange token. In this example, the 2237 KET is returned encrypted for the requestor since it had the credentials available to do that. 2238 Alternatively the request could be made using transport security (e.g. TLS) and the key 2239 could be returned directly using <wst:BinarySecret>. 2240

<wst:RequestSecurityToken> 2241 <wst:RequestType> 2242 http://docs.oasis-open.org/ws-sx/ws-trust/200512/KET 2243 </wst:RequestType> 2244 </wst:RequestSecurityToken> 2245 2246 <wst:RequestSecurityTokenResponseCollection> 2247 <wst:RequestSecurityTokenResponse> 2248 <wst:RequestedSecurityToken> 2249 <xenc:EncryptedKey>...</xenc:EncryptedKey> 2250 </wst:RequestedSecurityToken> 2251 </wst:RequestSecurityTokenResponse> 2252 </wst:RequestSecurityTokenResponseCollection> 2253 2254

Deleted: 5

Deleted: 26

Deleted: April


11 Error Handling 2255

There are many circumstances where an error can occur while processing security 2256 information. Errors use the SOAP Fault mechanism. Note that the reason text provided 2257 below is RECOMMENDED, but alternative text MAY be provided if more descriptive or 2258 preferred by the implementation. The tables below are defined in terms of SOAP 1.1. For 2259 SOAP 1.2, the Fault/Code/Value is env:Sender (as defined in SOAP 1.2) and the 2260 Fault/Code/Subcode/Value is the faultcode below and the Fault/Reason/Text is the 2261 faultstring below. It should be noted that profiles MAY provide second-level detail fields, but 2262 they should be careful not to introduce security vulnerabilities when doing so (e.g., by 2263 providing too detailed information). 2264

Error that occurred (faultstring) Fault code (faultcode)

The request was invalid or malformed wst:InvalidRequest

Authentication failed wst:FailedAuthentication

The specified request failed wst:RequestFailed

Security token has been revoked wst:InvalidSecurityToken

Insufficient Digest Elements wst:AuthenticationBadElements

The specified RequestSecurityToken is not understood.

wst:BadRequest

The request data is out-of-date wst:ExpiredData

The requested time range is invalid or unsupported

wst:InvalidTimeRange

The request scope is invalid or unsupported wst:InvalidScope

A renewable security token has expired wst:RenewNeeded

The requested renewal failed wst:UnableToRenew

Deleted: 5

Deleted: 26

Deleted: April


12 Security Considerations 2265

As stated in the Goals section of this document, this specification is meant to provide 2266 extensible framework and flexible syntax, with which one could implement various security 2267 mechanisms. This framework and syntax by itself does not provide any guarantee of 2268 security. When implementing and using this framework and syntax, one must make every 2269 effort to ensure that the result is not vulnerable to any one of a wide range of attacks. 2270 2271 It is not feasible to provide a comprehensive list of security considerations for such an 2272 extensible set of mechanisms. A complete security analysis must be conducted on specific 2273 solutions based on this specification. Below we illustrate some of the security concerns that 2274 often come up with protocols of this type, but we stress that this is not an exhaustive list of 2275 concerns. 2276 2277 The following statements about signatures and signing apply to messages sent on 2278 unsecured channels. 2279 2280 It is critical that all the security-sensitive message elements must be included in the scope 2281 of the message signature. As well, the signatures for conversation authentication must 2282 include a timestamp, nonce, or sequence number depending on the degree of replay 2283 prevention required as described in [WS-Security] and the UsernameToken Profile. Also, 2284 conversation establishment should include the policy so that supported algorithms and 2285 algorithm priorities can be validated. 2286 2287 It is required that security token issuance messages be signed to prevent tampering. If a 2288 public key is provided, the request should be signed by the corresponding private key to 2289 prove ownership. As well, additional steps should be taken to eliminate replay attacks 2290 (refer to [WS-Security] for additional information). Similarly, all token references should be 2291 signed to prevent any tampering. 2292 2293 Security token requests are susceptible to denial-of-service attacks. Care should be taken 2294 to mitigate such attacks as is warranted by the service. 2295 2296 For security, tokens containing a symmetric key or a password should only be sent to 2297 parties who have a need to know that key or password. 2298 2299 For privacy, tokens containing personal information (either in the claims, or indirectly by 2300 identifying who is currently communicating with whom) should only be sent according to the 2301 privacy policies governing these data at the respective organizations. 2302 2303 For some forms of multi-message exchanges, the exchanges are susceptible to attacks 2304 whereby signatures are altered. To address this, it is suggested that a signature 2305 confirmation mechanism be used. In such cases, each leg should include the confirmation 2306 of the previous leg. That is, leg 2 includes confirmation for leg 1, leg 3 for leg 2, leg 4 for 2307

Deleted: 5

Deleted: 26

Deleted: April


leg 3, and so on. In doing so, each side can confirm the correctness of the message outside 2308 of the message body. 2309 2310 There are many other security concerns that one may need to consider in security protocols. 2311 The list above should not be used as a "check list" instead of a comprehensive security 2312 analysis. 2313 2314 It should be noted that use of unsolicited RSTRs implies that the recipient is prepared to 2315 accept such issuances. Recipients should ensure that such issuances are properly 2316 authorized and recognize their use could be used in denial-of-service attacks. 2317 In addition to the consideration identified here, readers should also review the security 2318 considerations in [WS-Security]. 2319 2320 Both token cancellation bindings defined in this specification require that the STS MUST NOT 2321 validate or renew the token after it has been successfully canceled. The STS must take care 2322 to ensure that the token is properly invalidated before confirming the cancel request or 2323 sending the cancel notification to the client. This can be more difficult if the token validation 2324 or renewal logic is physically separated from the issuance and cancellation logic. It is out of 2325 scope of this spec how the STS propagates the token cancellation to its other components. 2326 If STS cannot ensure that the token was properly invalidated it MUST NOT send the cancel 2327 notification or confirm the cancel request to the client. 2328

Deleted: 5

Deleted: 26

Deleted: April

Formatted: Font: Verdana, 10 pt,Font color: Black

Formatted


A. Key Exchange 2329

Key exchange is an integral part of token acquisition. There are several mechanisms by 2330 which keys are exchanged using [WS-Security] and WS-Trust. This section highlights and 2331 summarizes these mechanisms. Other specifications and profiles may provide additional 2332 details on key exchange. 2333 2334 Care must be taken when employing a key exchange to ensure that the mechanism does 2335 not provide an attacker with a means of discovering information that could only be 2336 discovered through use of secret information (such as a private key). 2337 2338 It is therefore important that a shared secret should only be considered as trustworthy as 2339 its source. A shared secret communicated by means of the direct encryption scheme 2340 described in section I.1 is acceptable if the encryption key is provided by a completely 2341 trustworthy key distribution center (this is the case in the Kerberos model). Such a key 2342 would not be acceptable for the purposes of decrypting information from the source that 2343 provided it since an attacker might replay information from a prior transaction in the hope 2344 of learning information about it. 2345 2346 In most cases the other party in a transaction is only imperfectly trustworthy. In these 2347 cases both parties should contribute entropy to the key exchange by means of the 2348 <wst:entropy> element. 2349

A.1 Ephemeral Encryption Keys 2350

The simplest form of key exchange can be found in [WS-Security] for encrypting message 2351 data. As described in [WS-Security] and [XML-Encrypt], when data is encrypted, a 2352 temporary key can be used to perform the encryption which is, itself, then encrypted using 2353 the <xenc:EncryptedKey> element. 2354 2355 The example below illustrates encrypting a temporary key using the public key in an issuer 2356 name and serial number: 2357

<xenc:EncryptedKey xmlns:xenc="..."> 2358 ... 2359 <ds:KeyInfo xmlns:ds="..."> 2360 <wsse:SecurityTokenReference xmlns:wsse="..."> 2361 <ds:X509IssuerSerial> 2362 <ds:X509IssuerName> 2363 DC=ACMECorp, DC=com 2364 </ds:X509IssuerName> 2365 <ds:X509SerialNumber>12345678</ds:X509SerialNumber> 2366 </ds:X509IssuerSerial> 2367 </wsse:SecurityTokenReference> 2368 </ds:KeyInfo> 2369 ... 2370 </xenc:EncryptedKey> 2371

Deleted: 5

Deleted: 26

Deleted: April


A.2 Requestor-Provided Keys 2372

When a request sends a message to an issuer to request a token, the client can provide 2373 proposed key material using the <wst:Entropy> element. If the issuer doesn't contribute 2374 any key material, this is used as the secret (key). This information is encrypted for the 2375 issuer either using <xenc:EncryptedKey> or by using a transport security. If the requestor 2376 provides key material that the recipient doesn't accept, then the issuer should reject the 2377 request. Note that the issuer need not return the key provided by the requestor. 2378 2379 The following example illustrates a request for a custom security token and includes a secret 2380 that is to be used for the key. In this example the entropy is encrypted for the issuer (if 2381 transport security was used for confidentiality then the <wst:Entropy> element would 2382 contain a <wst:BinarySecret> element): 2383

... 2384 <wst:RequestSecurityToken> 2385 <wst:TokenType> 2386 http://example.org/mySpecialToken 2387 </wst:TokenType> 2388 <wst:RequestType> 2389 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue 2390 </wst:RequestType> 2391 <wst:Entropy> 2392 <xenc:EncryptedData>...</xenc:EncryptedData> 2393 </wst:Entropy> 2394 </wst:RequestSecurityToken> 2395 ... 2396

A.3 Issuer-Provided Keys 2397

If a requestor fails to provide key material, then issued proof-of-possession tokens contain 2398 an issuer-provided secret that is encrypted for the requestor (either using 2399 <xenc:EncryptedKey> or by using a transport security). 2400 2401 The following example illustrates a token being returned with an associated proof-of-2402 possession token that is encrypted using the requestor's public key. 2403


Deleted: 5

Deleted: 26

Deleted: April


A.4 Composite Keys 2420

The safest form of key exchange/generation is when both the requestor and the issuer 2421 contribute to the key material. In this case, the request sends encrypted key material. The 2422 issuer then returns additional encrypted key material. The actual secret (key) is computed 2423 using a function of the two pieces of data. Ideally this secret is never used and, instead, 2424 keys derived are used for message protection. 2425 2426 The following example illustrates a server, having received a request with requestor entropy 2427 returning its own entropy, which is used in conjunction with the requestor's to generate a 2428 key. In this example the entropy is not encrypted because the transport is providing 2429 confidentiality (otherwise the <wst:Entropy> element would have an 2430 <xenc:EncryptedData> element). 2431

... 2432 <wst:RequestSecurityTokenResponseCollection> 2433 <wst:RequestSecurityTokenResponse> 2434 <wst:RequestedSecurityToken> 2435 <xyz:CustomToken xmlns:xyz="..."> 2436 ... 2437 </xyz:CustomToken> 2438 </wst:RequestedSecurityToken> 2439 <wst:Entropy> 2440 <wst:BinarySecret>UIH...</wst:BinarySecret> 2441 </wst:Entropy> 2442 </wst:RequestSecurityTokenResponse> 2443 </wst:RequestSecurityTokenResponseCollection> 2444 ... 2445

A.5 Key Transfer and Distribution 2446

There are also a few mechanisms where existing keys are transferred to other parties. 2447

A.5.1 Direct Key Transfer 2448

If one party has a token and key and wishes to share this with another party, the key can 2449 be directly transferred. This is accomplished by sending an RSTR (either in the body or 2450 header) to the other party. The RSTR contains the token and a proof-of-possession token 2451 that contains the key encrypted for the recipient. 2452 2453 In the following example a custom token and its associated proof-of-possession token are 2454 known to party A who wishes to share them with party B. In this example, A is a member 2455 in a secure on-line chat session and is inviting B to join the conversation. After 2456 authenticating B, A sends B an RSTR. The RSTR contains the token and the key is 2457 communicated as a proof-of-possession token that is encrypted for B: 2458

... 2459 <wst:RequestSecurityTokenResponseCollection> 2460 <wst:RequestSecurityTokenResponse> 2461 <wst:RequestedSecurityToken> 2462 <xyz:CustomToken xmlns:xyz="..."> 2463 ... 2464 </xyz:CustomToken> 2465 </wst:RequestedSecurityToken> 2466 <wst:RequestedProofToken> 2467 <xenc:EncryptedKey Id="newProof"> 2468 ... 2469

Deleted: 5

Deleted: 26

Deleted: April


</xenc:EncryptedKey> 2470 </wst:RequestedProofToken> 2471 </wst:RequestSecurityTokenResponse> 2472 </wst:RequestSecurityTokenResponseCollection> 2473 ... 2474

A.5.2 Brokered Key Distribution 2475

A third party may also act as a broker to transfer keys. For example, a requestor may 2476 obtain a token and proof-of-possession token from a third-party STS. The token contains a 2477 key encrypted for the target service (either using the service's public key or a key known to 2478 the STS and target service). The proof-of-possession token contains the same key 2479 encrypted for the requestor (similarly this can use public or symmetric keys). 2480 2481 In the following example a custom token and its associated proof-of-possession token are 2482 returned from a broker B to a requestor R for access to service S. The key for the session is 2483 contained within the custom token encrypted for S using either a secret known by B and S 2484 or using S's public key. The same secret is encrypted for R and returned as the proof-of-2485 possession token: 2486

... 2487 <wst:RequestSecurityTokenResponseCollection> 2488 <wst:RequestSecurityTokenResponse> 2489 <wst:RequestedSecurityToken> 2490 <xyz:CustomToken xmlns:xyz="..."> 2491 ... 2492 <xenc:EncryptedKey xmlns:xenc="..."> 2493 ... 2494 </xenc:EncryptedKey> 2495 ... 2496 </xyz:CustomToken> 2497 </wst:RequestedSecurityToken> 2498 <wst:RequestedProofToken> 2499 <xenc:EncryptedKey Id="newProof"> 2500 ... 2501 </xenc:EncryptedKey> 2502 </wst:RequestedProofToken> 2503 </wst:RequestSecurityTokenResponse> 2504 </wst:RequestSecurityTokenResponseCollection> 2505 ... 2506

A.5.3 Delegated Key Transfer 2507

Key transfer can also take the form of delegation. That is, one party transfers the right to 2508 use a key without actually transferring the key. In such cases, a delegation token, e.g. 2509 XrML, is created that identifies a set of rights and a delegation target and is secured by the 2510 delegating party. That is, one key indicates that another key can use a subset (or all) of its 2511 rights. The delegate can provide this token and prove itself (using its own key – the 2512 delegation target) to a service. The service, assuming the trust relationships have been 2513 established and that the delegator has the right to delegate, can then authorize requests 2514 sent subject to delegation rules and trust policies. 2515 2516 In this example a custom token is issued from party A to party B. The token indicates that 2517 B (specifically B's key) has the right to submit purchase orders. The token is signed using a 2518 secret key known to the target service T and party A (the key used to ultimately authorize 2519

Deleted: 5

Deleted: 26

Deleted: April


the requests that B makes to T), and a new session key that is encrypted for T. A proof-of-2520 possession token is included that contains the session key encrypted for B. As a result, B is 2521 effectively using A's key, but doesn't actually know the key. 2522

... 2523 <wst:RequestSecurityTokenResponseCollection> 2524 <wst:RequestSecurityTokenResponse> 2525 <wst:RequestedSecurityToken> 2526 <xyz:CustomToken xmlns:xyz="..."> 2527 ... 2528 <xyz:DelegateTo>B</xyz:DelegateTo> 2529 <xyz:DelegateRights> 2530 SubmitPurchaseOrder 2531 </xyz:DelegatedRights> 2532 <xenc:EncryptedKey xmlns:xenc="..."> 2533 ... 2534 </xenc:EncryptedKey> 2535 <ds:Signature xmlns:ds="...">...</ds:Signature> 2536 ... 2537 </xyz:CustomToken> 2538 </wst:RequestedSecurityToken> 2539 <wst:RequestedProofToken> 2540 <xenc:EncryptedKey Id="newProof"> 2541 ... 2542 </xenc:EncryptedKey> 2543 </wst:RequestedProofToken> 2544 </wst:RequestSecurityTokenResponse> 2545 </wst:RequestSecurityTokenResponseCollection> 2546 ... 2547

A.5.4 Authenticated Request/Reply Key Transfer 2548

In some cases the RST/RSTR mechanism is not used to transfer keys because it is part of a 2549 simple request/reply. However, there may be a desire to ensure mutual authentication as 2550 part of the key transfer. The mechanisms of [WS-Security] can be used to implement this 2551 scenario. 2552 2553 Specifically, the sender wishes the following: 2554

• Transfer a key to a recipient that they can use to secure a reply 2555 • Ensure that only the recipient can see the key 2556 • Provide proof that the sender issued the key 2557

2558 This scenario could be supported by encrypting and then signing. This would result in 2559 roughly the following steps: 2560

1. Encrypt the message using a generated key 2561 2. Encrypt the key for the recipient 2562 3. Sign the encrypted form, any other relevant keys, and the encrypted key 2563

2564 However, if there is a desire to sign prior to encryption then the following general process is 2565 used: 2566

1. Sign the appropriate message parts using a random key (or ideally a key derived 2567 from a random key) 2568 Deleted: 5

Deleted: 26

Deleted: April


2. Encrypt the appropriate message parts using the random key (or ideally another key 2569 derived from the random key) 2570

3. Encrypt the random key for the recipient 2571 4. Sign just the encrypted key 2572

2573 This would result in a <wsse:Security> header that looks roughly like the following: 2574

... 2575 <wsse:Security xmlns:wsse="..." xmlns:wsu="..." 2576 xmlns:ds="..." xmlns:xenc="..."> 2577 <wsse:BinarySecurityToken wsu:Id="myToken" ...> 2578 ... 2579 </wsse:BinarySecurityToken> 2580 <ds:Signature> 2581 ...signature over #secret using token #myToken... 2582 </ds:Signature> 2583 <xenc:EncryptedKey Id="secret"> 2584 ... 2585 </xenc:EncryptedKey> 2586 <xenc:RefrenceList> 2587 ...manifest of encrypted parts using token #secret... 2588 </xenc:RefrenceList> 2589 <ds:Signature> 2590 ...signature over key message parts using token #secret... 2591 </ds:Signature> 2592 </wsse:Security> 2593 ... 2594

2595 As well, instead of an <xenc:EncryptedKey> element, the actual token could be passed 2596 using <xenc:EncryptedData>. The result might look like the following: 2597

... 2598 <wsse:Security xmlns:wsse="..." xmlns:wsu="..." 2599 xmlns:ds="..." xmlns:xenc="..."> 2600 <wsse:BinarySecurityToken wsu:Id="myToken" ...> 2601 ... 2602 </wsse:BinarySecurityToken> 2603 <ds:Signature> 2604 ...signature over #secret or #Esecret using token #myToken... 2605 </ds:Signature> 2606 <xenc:EncryptedData Id="Esecret> 2607 ...Encrypted version of a token with Id="secret"... 2608 </xenc:EncryptedData> 2609 <xenc:RefrenceList> 2610 ...manifest of encrypted parts using token #secret... 2611 </xenc:RefrenceList> 2612 <ds:Signature> 2613 ...signature over key message parts using token #secret... 2614 </ds:Signature> 2615 </wsse:Security> 2616 ... 2617

A.6 Perfect Forward Secrecy 2618

In some situations it is desirable for a key exchange to have the property of perfect forward 2619 secrecy. This means that it is impossible to reconstruct the shared secret even if the private 2620 keys of the parties are disclosed. 2621 2622

Deleted: 5

Deleted: 26

Deleted: April


The most straightforward way to attain perfect forward secrecy when using asymmetric key 2623 exchange is to dispose of one's key exchange key pair periodically (or even after every key 2624 exchange), replacing it with a fresh one. Of course, a freshly generated public key must still 2625 be authenticated (using any of the methods normally available to prove the identity of a 2626 public key's owner). 2627 2628 The perfect forward secrecy property may be achieved by specifying a <wst:entropy> 2629 element that contains an <xenc:EncryptedKey> that is encrypted under a public key pair 2630 created for use in a single key agreement. The public key does not require authentication 2631 since it is only used to provide additional entropy. If the public key is modified, the key 2632 agreement will fail. Care should be taken, when using this method, to ensure that the now-2633 secret entropy exchanged via the <wst:entropy> element is not revealed elsewhere in the 2634 protocol (since such entropy is often assumed to be publicly revealed plaintext, and treated 2635 accordingly). 2636 2637 Although any public key scheme might be used to achieve perfect forward secrecy (in either 2638 of the above methods) it is generally desirable to use an algorithm that allows keys to be 2639 generated quickly. The Diffie-Hellman key exchange is often used for this purpose since 2640 generation of a key only requires the generation of a random integer and calculation of a 2641 single modular exponent. 2642

Deleted: 5

Deleted: 26

Deleted: April

B. WSDL 2643

The WSDL below does not fully capture all the possible message exchange patterns, but 2644 captures the typical message exchange pattern as described in this document. 2645

<?xml version="1.0"?> 2646 <wsdl:definitions 2647 targetNamespace="http://docs.oasis-open.org/ws-sx/ws-2648 trust/200512/wsdl" 2649 xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl" 2650 xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" 2651 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 2652 xmlns:xs="http://www.w3.org/2001/XMLSchema" 2653 > 2654  2655 <wsdl:types> 2656 <xs:schema> 2657 <xs:import 2658 namespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512" 2659 schemaLocation="http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-2660 trust.xsd"/> 2661 </xs:schema> 2662 </wsdl:types> 2663 2664  2665 <wsdl:message name="RequestSecurityTokenMsg"> 2666 <wsdl:part name="request" element="wst:RequestSecurityToken" /> 2667 </wsdl:message> 2668 <wsdl:message name="RequestSecurityTokenResponseMsg"> 2669 <wsdl:part name="response" 2670 element="wst:RequestSecurityTokenResponse" /> 2671 </wsdl:message> 2672 <wsdl:message name="RequestSecurityTokenResponseCollectionMsg"> 2673 <wsdl:part name="responseCollection" 2674 element="wst:RequestSecurityTokenResponseCollection"/> 2675 </wsdl:message> 2676 2677  2679 2680 <wsdl:portType name="WSSecurityRequestor"> 2681 <wsdl:operation name="SecurityTokenResponse"> 2682 <wsdl:input 2683 message="tns:RequestSecurityTokenResponseMsg"/> 2684 </wsdl:operation> 2685 <wsdl:operation name="SecurityTokenResponse2"> 2686 <wsdl:input 2687 message="tns:RequestSecurityTokenResponseCollectionMsg"/> 2688 </wsdl:operation> 2689 <wsdl:operation name="Challenge"> 2690 <wsdl:input message="tns:RequestSecurityTokenResponseMsg"/> 2691 <wsdl:output message="tns:RequestSecurityTokenResponseMsg"/> 2692 </wsdl:operation> 2693 <wsdl:operation name="Challenge2"> 2694 <wsdl:input message="tns:RequestSecurityTokenResponseMsg"/> 2695 <wsdl:output 2696 message="tns:RequestSecurityTokenResponseCollectionMsg"/> 2697 </wsdl:operation> 2698 </wsdl:portType> 2699 2700  2701

Deleted: 5

Deleted: 26

Deleted: April


2702 <wsdl:portType name="SecurityTokenRequestService"> 2703 <wsdl:operation name="RequestSecurityToken"> 2704 <wsdl:input message="tns:RequestSecurityTokenMsg"/> 2705 </wsdl:operation> 2706 </wsdl:portType> 2707 2708 <wsdl:portType name="SecurityTokenService"> 2709 <wsdl:operation name="RequestSecurityToken"> 2710 <wsdl:input message="tns:RequestSecurityTokenMsg"/> 2711 <wsdl:output message="tns:RequestSecurityTokenResponseMsg"/> 2712 </wsdl:operation> 2713 <wsdl:operation name="RequestSecurityToken2"> 2714 <wsdl:input message="tns:RequestSecurityTokenMsg"/> 2715 <wsdl:output 2716 message="tns:RequestSecurityTokenResponseCollectionMsg"/> 2717 </wsdl:operation> 2718 </wsdl:portType> 2719 </wsdl:definitions> 2720 2721

Deleted: 5

Deleted: 26

Deleted: April


C. Acknowledgements 2722

The following individuals have participated in the creation of this specification and are gratefully 2723 acknowledged: 2724 Original Authors: 2725

Steve Anderson, OpenNetwork 2726 Jeff Bohren, OpenNetwork 2727 Toufic Boubez, Layer 7 2728 Marc Chanliau, Computer Associates 2729 Giovanni Della-Libera, Microsoft 2730 Brendan Dixon, Microsoft 2731 Praerit Garg, Microsoft 2732 Martin Gudgin (Editor), Microsoft 2733 Phillip Hallam-Baker, VeriSign 2734 Maryann Hondo, IBM 2735 Chris Kaler, Microsoft 2736 Hal Lockhart, BEA 2737 Robin Martherus, Oblix 2738 Hiroshi Maruyama, IBM 2739 Anthony Nadalin (Editor), IBM 2740 Nataraj Nagaratnam, IBM 2741 Andrew Nash, Reactivity 2742 Rob Philpott, RSA Security 2743 Darren Platt, Ping Identity 2744 Hemma Prafullchandra, VeriSign 2745 Maneesh Sahu, Actional 2746 John Shewchuk, Microsoft 2747 Dan Simon, Microsoft 2748 Davanum Srinivas, Computer Associates 2749 Elliot Waingold, Microsoft 2750 David Waite, Ping Identity 2751 Doug Walter, Microsoft 2752 Riaz Zolfonoon, RSA Security 2753

2754 Original Acknowledgments: 2755

Paula Austel, IBM 2756 Keith Ballinger, Microsoft 2757 Bob Blakley, IBM 2758 John Brezak, Microsoft 2759 Tony Cowan, IBM 2760 Cédric Fournet, Microsoft 2761 Vijay Gajjala, Microsoft 2762 HongMei Ge, Microsoft 2763 Satoshi Hada, IBM 2764 Heather Hinton, IBM 2765 Slava Kavsan, RSA Security 2766 Scott Konersmann, Microsoft 2767 Leo Laferriere, Computer Associates 2768

Deleted: 5

Deleted: 26

Deleted: April


Paul Leach, Microsoft 2769 Richard Levinson, Computer Associates 2770 John Linn, RSA Security 2771 Michael McIntosh, IBM 2772 Steve Millet, Microsoft 2773 Birgit Pfitzmann, IBM 2774 Fumiko Satoh, IBM 2775 Keith Stobie, Microsoft 2776 T.R. Vishwanath, Microsoft 2777 Richard Ward, Microsoft 2778 Hervey Wilson, Microsoft 2779

Deleted: 5

Deleted: 26

Deleted: April


D. Non-Normative Text 2780

Deleted: 5

Deleted: 26

Deleted: April


E. Revision History 2781

[optional; should not be included in OASIS Standards] 2782 2783

Revision Date Editor Changes Made

0.1 12-06-2005 Anthony Nadalin Initial convergence to OASIS template

0.2 01-09-2006 Martin Gudgin Updated TOC. Namespaces.

0.3 01-17-2006 Marc Goodner Updated artifact identifier per AIR guidelines, corrected version number, 2005 updated to 2006, added resolution of i001, changed status to editor draft

0.4 03-28-2006 Marc Goodner Issue 10 – Lines 1718 to 1722 Issue 34 – Lines as indicated in proposal Issue 36 – Line 226 Issue 37 – Lines 873-4, 928-9 Issue 38 – Lines 738, 754 Issue 40 – Lines 525 to 531 Corrected section misnumbering from OASIS template: Lines 88, 298, 320, 547, 628, 666, 910, 927

0.5 04-17-2006 Anthony Nadalin Accepted previous changes Issues 44, 52, 56, 57, 58, 59, 60

0.6 04-26-06 Anthony Nadalin Accepted previous changes Fix spelling errors Fix errors in Issue 52

0.7 05-09-06 Anthony Nadalin Accepted previous changes Issues 20, 68

2784

Deleted: /

Deleted: 5

Deleted: 26

Deleted: April

WS-Trust V1 - OASIS€¦ · ws-trust-1.3-spec-ed-07 09 May 2006 ... [WS-Security] to provide a ......

Documents

Transcript of WS-Trust V1 - OASIS€¦ · ws-trust-1.3-spec-ed-07 09 May 2006 ... [WS-Security] to provide a ......