IVOA single-sign-on profile: message protocol
Version 0.1

IVOA WG Internal Draft 2004 July 04

Working Group:

http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices

Author(s):

Guy Rixon

---

Abstract

The IVOA standard for single-sign-on authentication with web services requires SOAP message-level security using the WS-Security standard of OASIS. This document specifies the set of XML elements from WS-Security that must be used in secured messages to IVOA services. The required actions by the sender and receiver of the messages are also specified.

Contents

1. Introduction

The IVOA profile for single-sign-on authentication with web services, of which this document is a part, requires that authentication be done by digital signature of SOAP messages plus the inclusion of identity warrants signed by a certificate authortity. The profile further requires that the credentials for authentication be carried in the SOAP header of messages in accordance with the WS-Security standard of OASIS [WS-Security, WS-Security-TC, OASIS]. The background for these requirements is described in the introduction to the IVOA profile.

The current document specifies the exact elements from WS-Security [WS-Security] that must be used in secured messages to IVOA services. The actions by the sender in composing the message and by the receiver in verifying it are also specified.

In the following sections, types of XML elements are specified by namespace-qualified names, e.g. wss:Security. The namespaces used are as follows.

2. Message contents

2.1 Location of security elements

All material relating to the security of a SOAP message shall be carried in the SOAP header of the message. The sole exception to this rule is that the soap-env:Body element carrying the message body shall have a wsu:Id attribute used in the writing of the digital signature.

All the security material shall be contained in an element of type wss:Security.

2.2 Message timestamp

The message shall include tokens to prove uniqueness and thus to guard against 'replay' attacks. There shall be a wsu:Timestamp element directly inside the wss:Security element. The wsu:Timestamp must have a wsu:Id attribute to allow it to be digitally signed.

The wsu:Timestamp shall contain a wss:Nonce and a wsu:Created. The value of the former shall be random such that the chance of two messages to the same service, within the lifetime of that service, having the same nonce is negligible. The value of the latter shall be the absolute time at which the message was written; the sender shall use this datum to determine the age of the message.

2.3 Identity warrants

The message shall contain one or more identity warrants that bind an identity to a public cryptographic key and thus link the identity to the signed parts of the message.

The sender may use multiple warrants either to express mutiple identities; or to express one identity vouched for by more than one certficate authority; or some combination of these two uses. On receiving multiple warrants, a service must use the union of the identities in determining authorization.

A message may be constructed with a digital signature according to WS-Security but no identity warrants. Such a message is effectively anonymous, since there is no way of authenticating any identity in the message. It may sometimes be useful to send a anonymous message whose integratity is protected by signatire, but such a message is not part of the IVOA SSO profile.

Identity warrants must be X.509v3 certficates. Contrary to what has been written in the introduction to the IVOA SSO profile, warrants may not at this time be SAML assertions; however, SAML assertions may be included in a later version of this standard. At present, the proper use of SAML with WS-Security is very unclear and trying to support SAML might slow down standardization. It is of more benefit to support X.509 quickly than delay until SAML is understood.

X.509 certificates must be included as wss:BinarySecurityToken elements inside the wss:Security element. The attributes and content of these elements must follow the rules of the WSS-Security profile for X.509 certificates [WS-Security-X509].

2.4 Signature for body of message

The body of the message shall be digitally signed by the sender using the private key of a public-private key-pair. This key-pair must be the one associated with the identity to be authenticated by the accompanying identity warrants.

The signature shall be written as a ds:Signature element. It shall follow the rules of WS-Security section 8 [WS-Security] and standards referenced therein. The signature shall include a ds:SignedInfo element and the latter shall include a ds:Reference element in which the value of the URI attribute matches the value of the wsu:Id attribute on the message body.

2.5 Signature for timestamp

The signature shall be written as a ds:Signature element. It shall follow the rules of WS-Security section 8 [WS-Security] and standards referenced therein. The signature shall include a ds:SignedInfo element and the latter shall include a ds:Reference element in which the value of the URI attribute matches the value of the wsu:Id attribute on the timestamp.

3. Sending a message

The sender of a message should follow this procedure in adding a security header to the message. (Note that any alternative procedure is valid if it achieves a header following the rules defined and quoted above for the content of the message.)

1. Compose the body of the SOAP message.
2. Include a wss:Security element in the SOAP header of the message.
3. Add the X.509 certificate(s) to the wss:Security.
4. Compute the digital signature for the message body and writes the signature into the wsse:Security as a ds:Signature element.
5. Add the wsu:Timestamp element to the wss:Security, computing a random value for the nonce.
6. Compute the digital signature for the wsu:UsernameToken and writes the signature into the wss:Security as a ds:signature element.
7. Send the message to the service.

Note that the receiver of the message will reject messages whose timestamp preceeds the time of reception by more than a certain interval, and that this time-out interval may be as short as a few minutes. Therefore, the message must be sent promptly after its timestamp is created.

4. Receiving a message

The receiver of a message shall determine the identity of the sender from the identity or identities bound in the included warrants. The receiver should consider those identities valid for access control only if they can be authenticated, and shall consider an identity authenticated only if the following list of checks are all passed. Note that the order of the checks is unimportant.

1. The wss:Security element is valid according to its XML schemata.
2. The message elements specified above are all present. (Note that the wss:Security may be valid according to schema when elements specified by this profile are missing.)
3. The body of the message is digitally signed. (If the body is not signed, then an attacker could have intercepted the message and replaced its body.)
4. The digital signature for the message body is mathematically valid.
5. The public key used in the message-body signature matches that in the accompanying warrant where the identity in question is asserted.
6. The warrant is correctly, digitally signed by a certificate authority (CA).
7. The CA who signed the warrant is one that the receiver trusts.
8. The receiver has not seen the nonce value before. (I.e. the message has not been recorded and replayed by an attacker.)
9. The creation time of the message is more recent than that of the last message for which the receiver would remember the nonce. (See below for more details of nonce handling.)
10. The wsu:Timestamp element is digitally signed. (If it were not, an attcker could change it to enable a replay attack.)
11. The timestamp signature is mathematically valid.
12. The timestamp signature relates to the same warrant as the signature of the message body (and hence to a warrant that was validated when the body signature was checked).

The receiver must then remember the nonce of the message for use in checking the uniqueness of subsequent messages. The receiver need not remember nonces for ever, but may forget them after some fixed duration. However, the receiver must not accept any messages so old that it would have forgotten the nonce. The receiver may choose the length of its memory for nonces. However, general services should remember nonces for at least five minutes.

References

OASIS

Organization for the Advancement of Structured Information Standards, Home page
http://www.oasis-open.org/

WS-Security

Organization for the Advancement of Structured Information Standards, Web Services Security SOAP Message Security 1.0
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

WS-Security-TC

Organization for the Advancement of Structured Information Standards, Web Services Security Technical Committee web-page
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss

WS-Security-X.509

Organization for the Advancement of Structured Information Standards, Web Services Security X.509 Certificate Token Profile
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf