Web Services Security
UsernameToken
Profile 1.1
OASIS Public Review Draft -
28 June 2005
OASIS identifier:
{product-productVersion-artifactType-stage-descriptiveName-revision.form
(Word)
(PDF)
(HTML)}
Location:
http://docs.oasis-open.org/wss/2005/xx/wss-v1.1-spec-pr-UsernameTokenProfile-01
Technical Commitee:
Web Service Security (WSS)
Chairs:
Kelvin
Lawrence, IBM
Chris
Kaler, Microsoft
Editors:
Anthony
Nadalin, IBM
Chris
Kaler, Microsoft
Ronald
Monzillo, Sun
Phillip Hallam-Baker, Verisign
Abstract:
This document describes how to use the UsernameToken with the Web Services Security (WSS) specification.
Status:
This is a technical committee document submitted for consideration by the OASIS Web Services Security (WSS) technical committee. Please send comments to the editors.
If you are on the wss@lists.oasis-open.org list for committee members, send comments there. If you are not on that list, subscribe to the wss-comment@lists.oasis-open.org list and send comments there. To subscribe, send an email message to wss-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.
For patent disclosure information that may be essential to the implementation of this specification, and any offers of licensing terms, refer to the Intellectual Property Rights section of the OASIS Web Services Security Technical Committee (WSS TC) web page at http://www.oasis-open.org/committees/wss/ipr.php. General OASIS IPR information can be found at http://www.oasis-open.org/who/intellectualproperty.shtml.
Notices
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.
Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 2002-2005. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Table of Contents
2.3
Acronyms and Abbreviations
This document describes how to use the UsernameToken with
the WSS: SOAP Message Security specification [WSS]. More specifically, it describes how a web service consumer can supply a UsernameToken
as a means of identifying the requestor by “username”, and optionally using a
password (or shared secret, or password equivalent) to authenticate that
identity to the web service producer.
This section specifies the notations, namespaces, and terminology used in this specification.
2.1 Notational Conventions
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].
When describing abstract data models, this specification uses the notational convention used by the XML Infoset. Specifically, abstract property names always appear in square brackets (e.g., [some property]).
When describing concrete XML schemas [XML-Schema], this specification uses the notational convention of WSS: SOAP Message Security. Specifically, each member of an element’s [children] or [attributes] property is described using an XPath-like [XPath] notation (e.g., /x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates the presence of an element wildcard (<xs:any/>). The use of @{any} indicates the presence of an attribute wildcard (<xs:anyAttribute/>).
Commonly used security terms are defined in the Internet Security Glossary [SECGLO]. Readers are presumed to be familiar with the terms in this glossary as well as the definition in the Web Services Security specification.
2.2 Namespaces
Namespace URIs (of the general form "some-URI") represents some application-dependent or context-dependent URI as defined in RFC 3986 [URI]. This specification is designed to work with the general SOAP [SOAP11, SOAP12] message structure and message processing model, and should be applicable to any version of SOAP. The current SOAP 1.1 namespace URI is used herein to provide detailed examples, but there is no intention to limit the applicability of this specification to a single version of SOAP.
The namespaces used in this document are shown in the following table (note that for brevity, the examples use the prefixes listed below but do not include the URIs – those listed below are assumed).
|
Prefix |
Namespace |
|
S11 |
|
|
S12 |
|
|
wsse |
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd |
|
wsse11 |
http://docs.oasis-open.org/wss/2005/xx/oasis-2005xx-wss-wssecurity-secext-1.1.xsd |
|
wsu |
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd |
The URLs provided for the wsse and wsu namespaces
can be used to obtain the schema files. URI fragments defined in this specification are relative to a base
URI of the following unless otherwise stated:
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0
The following table lists the full URI for each URI fragment referred to in this specification.
|
URI Fragment |
Full URI |
|
#PasswordDigest |
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest |
|
#PasswordText |
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText |
|
#UsernameToken |
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0
#UsernameToken |
2.3 Acronyms and Abbreviations
The following (non-normative) table defines acronyms and abbreviations for this document.
|
Term |
Definition |
|
SHA |
Secure Hash Algorithm |
|
SOAP |
Simple Object Access Protocol |
|
URI |
Uniform Resource Identifier |
|
XML |
Extensible Markup Language |
3.1 Usernames and Passwords
The <wsse:UsernameToken> element is introduced in the WSS: SOAP Message Security documents as a way of providing a username.
Within <wsse:UsernameToken> element, a <wsse:Password> element may be specified. Passwords of type
PasswordText and PasswordDigest are not
limited to actual passwords, although this is a common case. Any password equivalent such as a derived
password or S/KEY (one time password) can be used. Having a type of PasswordText merely
implies that the information held in the password is “in the clear”, as opposed
to holding a “digest” of the information. For example, if a server does not have access to the clear text of a
password but does have the hash, then the hash is considered a password equivalent and can be used
anywhere where a "password" is indicated in this specification. It is not the intention of this specification
to require that all implementations have access to clear text passwords.
Passwords of type PasswordDigest are
defined as being the Base64 [XML-Schema]
encoded, SHA-1 hash value, of the UTF8 encoded password (or equivalent). However, unless this digested password is sent on a secured channel or
the token is encrypted, the digest offers no real additional security over use
of wsse:PasswordText.
Two optional elements are introduced in the <wsse:UsernameToken>
element to provide a countermeasure for replay attacks: <wsse:Nonce> and <wsu:Created>. A nonce is a random value that the sender
creates to include in each UsernameToken that it sends. Although using a nonce
is an effective countermeasure against replay attacks, it requires a server to
maintain a cache of used nonces, consuming server resources. Combining a nonce
with a creation timestamp has the advantage of allowing a server to limit the cache
of nonces to a "freshness" time period, establishing an upper bound on resource
requirements. If either or both of <wsse:Nonce> and <wsu:Created> are present they MUST be included in the
digest value as follows:
Password_Digest = Base64 ( SHA-1 ( nonce + created + password ) )
That is, concatenate the nonce, creation timestamp, and the
password (or shared secret or password equivalent), digest the combination using the SHA-1
hash algorithm, then include the Base64 encoding of that result as the password
(digest). This helps obscure the password and offers a basis for
preventing replay attacks. For web service producers to effectively thwart replay
attacks, three counter measures are RECOMMENDED:
1.
It is RECOMMENDED that web service producers reject any
UsernameToken not using both nonce and creation
timestamps.
2.
It is RECOMMENDED that web service producers provide a
timestamp “freshness” limitation, and that any UsernameToken with “stale”
timestamps be rejected. As a guideline,
a value of five minutes can be used as a minimum to detect, and thus reject,
replays.
3. It is RECOMMENDED that used nonces be cached for a period at least as long as the timestamp freshness limitation period, above, and that UsernameToken with nonces that have already been used (and are thus in the cache) be rejected.
Note that the nonce is hashed using the octet sequence of its decoded value while the timestamp is hashed using the octet sequence of its UTF8 encoding as specified in the contents of the element.
Note that PasswordDigest can only be
used if the plain text password (or password equivalent) is available to both
the requestor and the recipient.
Note that the secret is put at the end of the input and not the front.