Fuse ESB

Web Services Security Guide

Version 4.4.1

Sept. 2011
Trademark Disclaimer
Third Party Acknowledgements

Updated: 06 Jun 2013

Table of Contents

1. Security for HTTP-Compatible Bindings
2. Managing Certificates
What is an X.509 Certificate?
Certification Authorities
Choice of CAs
Commercial Certification Authorities
Private Certification Authorities
Certificate Chaining
PKCS#12 Files
Special Requirements on HTTPS Certificates
Creating Your Own Certificates
Prerequisites
Set Up Your Own CA
Use the CA to Create Signed Certificates in a Java Keystore
Use the CA to Create Signed PKCS#12 Certificates
3. Configuring HTTPS
Authentication Alternatives
Target-Only Authentication
Mutual Authentication
Specifying Trusted CA Certificates
When to Deploy Trusted CA Certificates
Specifying Trusted CA Certificates for HTTPS
Specifying an Application’s Own Certificate
Deploying Own Certificate for HTTPS
4. Configuring HTTPS Cipher Suites
Supported Cipher Suites
Cipher Suite Filters
SSL/TLS Protocol Version
5. The WS-Policy Framework
Introduction to WS-Policy
Policy Expressions
6. Message Protection
Transport Layer Message Protection
SOAP Message Protection
Introduction to SOAP Message Protection
Basic Signing and Encryption Scenario
Specifying an AsymmetricBinding Policy
Specifying a SymmetricBinding Policy
Specifying Parts of Message to Encrypt and Sign
Providing Encryption Keys and Signing Keys
Specifying the Algorithm Suite
7. Authentication
Introduction to Authentication
Specifying an Authentication Policy
Providing Client Credentials
Authenticating Received Credentials
8. WS-Trust
Introduction to WS-Trust
Basic Scenarios
WS-Trust Single Sign-On Demonstration
Overview of the Demonstration
Configure the Security Token Service
Define the Security Policy
Configure the Client-STS Connection
Configure the Server-Side Interceptor
Build and Run the Demonstration
Sample Message Exchanges
Defining an IssuedToken Policy
Creating an STSClient Instance
A. ASN.1 and Distinguished Names
ASN.1
Distinguished Names
B. OpenSSL Utilities
Using OpenSSL Utilities
Utilities Overview
The x509 Utility
The req Utility
The rsa Utility
The ca Utility
The s_client Utility
The s_server Utility
The OpenSSL Configuration File
Configuration Overview
[req] Variables
[ca] Variables
[policy] Variables
Example openssl.cnf File
C. Licenses
OpenSSL License
Index

List of Figures

2.1. A Certificate Chain of Depth 2
2.2. A Certificate Chain of Depth 3
2.3. Elements in a PKCS#12 File
3.1. Target Authentication Only
3.2. Mutual Authentication
6.1. Basic Signing and Encryption Scenario
8.1. WS-Trust Architecture
8.2. Server-Vouches Scenario
8.3. Bearer Scenario
8.4. Holder-of-Key Scenario
8.5. WS-Trust Single Sign-On Scenario
8.6. Installing Requisite Certificates and WSDL File
8.7. Injecting Parameters into the Outgoing RequestSecurityToken Message

List of Tables

4.1. Namespaces Used for Configuring Cipher Suite Filters
4.2. SSL/TLS Protocols Supported by SUN’s JSSE Provider
6.1. Encryption and Signing Properties
6.2. WSS4J Keystore Properties
6.3. Properties for Specifying Crypto Objects
6.4. Algorithm Suites
6.5. Key Length Properties
7.1. Client Credentials Properties
8.1. XML Namespaces used with IssuedToken
8.2. Token Type URIs
A.1. Commonly Used Attribute Types

List of Examples

1.1. Specifying HTTPS in the WSDL
1.2. Specifying HTTPS in the Server Code
1.3. Sample HTTPS Client with No Certificate
1.4. Sample HTTPS Client with Certificate
1.5. Sample HTTPS Server Configuration
4.1. Structure of a sec:cipherSuitesFilter Element
5.1. The Empty Policy
5.2. The Null Policy
5.3. Normal Form Syntax
6.1. Client HTTPS Configuration in Spring
6.2. Server HTTPS Configuration in Spring
6.3. Example of a Transport Binding
6.4. Example of an Asymmetric Binding
6.5. Example of a Symmetric Binding
6.6. Integrity and Encryption Policy Assertions
6.7. WSS4J Crypto Interface
7.1. Example of a Supporting Tokens Policy
7.2. Callback Handler for UsernameToken Passwords
8.1. Sample Security Policy for Single Sign-On

A prerequisite for enabling HTTPS on a WSDL endpoint is that the endpoint address must be specified as a HTTPS URL. There are two different locations where the endpoint address is set and both must be modified to use a HTTPS URL:

For example, consider the configuration for a secure HTTPS client with no certificate, as shown in Example 1.3.

Example 1.3. Sample HTTPS Client with No Certificate

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:sec="http://cxf.apache.org/configuration/security"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
       xsi:schemaLocation="...">
                    
1    <http:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit">
2      <http:tlsClientParameters>
3        <sec:trustManagers>
          <sec:keyStore type="JKS" password="password"
                        file="certs/truststore.jks"/>
        </sec:trustManagers>
4        <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
  </http:conduit>
  
</beans>

The preceding client configuration is described as follows:

1

The TLS security settings are defined on a specific WSDL port. In this example, the WSDL port being configured has the QName, {http://apache.org/hello_world_soap_http}SoapPort.

2

The http:tlsClientParameters element contains all of the client’s TLS configuration details.

3

The sec:trustManagers element is used to specify a list of trusted CA certificates (the client uses this list to decide whether or not to trust certificates received from the server side).

The file attribute of the sec:keyStore element specifies a Java keystore file, truststore.jks, containing one or more trusted CA certificates. The password attribute specifies the password required to access the keystore, truststore.jks. See Specifying Trusted CA Certificates for HTTPS.

Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute. You must be extremely careful not to load the truststore from an untrustworthy source.

4

The sec:cipherSuitesFilter element can be used to narrow the choice of cipher suites that the client is willing to use for a TLS connection. See Configuring HTTPS Cipher Suites for details.

Consider a secure HTTPS client that is configured to have its own certificate. Example 1.4 shows how to configure such a sample client.

Example 1.4. Sample HTTPS Client with Certificate

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:sec="http://cxf.apache.org/configuration/security"
 xmlns:http="http://cxf.apache.org/transports/http/configuration"
 xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
 xsi:schemaLocation="...">

  <http:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit">
    <http:tlsClientParameters>
      <sec:trustManagers>
          <sec:keyStore type="JKS" password="password"
               file="certs/truststore.jks"/>
      </sec:trustManagers>
1      <sec:keyManagers keyPassword="password">
2           <sec:keyStore type="JKS" password="password"
                file="certs/wibble.jks"/>
      </sec:keyManagers>
      <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
   </http:conduit>
  
    <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"/>
</beans>

The preceding client configuration is described as follows:

1

The sec:keyManagers element is used to attach an X.509 certificate and a private key to the client. The password specified by the keyPasswod attribute is used to decrypt the certificate’s private key.

2

The sec:keyStore element is used to specify an X.509 certificate and a private key that are stored in a Java keystore. This sample declares that the keystore is in Java Keystore format (JKS).

The file attribute specifies the location of the keystore file, wibble.jks, that contains the client’s X.509 certificate chain and private key in a key entry. The password attribute specifies the keystore password which is required to access the contents of the keystore. It is expected that the keystore file contains just one key entry, so it is not necessary to specify a key alias to identify the entry.

For details of how to create such a keystore file, see Use the CA to Create Signed Certificates in a Java Keystore.

Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute. You must be extremely careful not to load the truststore from an untrustworthy source.

Consider a secure HTTPS server that requires clients to present an X.509 certificate. Example 1.5 shows how to configure such a server.

Example 1.5. Sample HTTPS Server Configuration

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sec="http://cxf.apache.org/configuration/security"
xmlns:http="http://cxf.apache.org/transports/http/configuration"
xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
xsi:schemaLocation="...">

  <httpj:engine-factory bus="cxf">
1   <httpj:engine port="9001">
2    <httpj:tlsServerParameters>
3      <sec:keyManagers keyPassword="password">
4           <sec:keyStore type="JKS" password="password" 
                file="certs/cherry.jks"/>
      </sec:keyManagers>
5      <sec:trustManagers>
          <sec:keyStore type="JKS" password="password"
               file="certs/truststore.jks"/>
      </sec:trustManagers>
6      <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
7      <sec:clientAuthentication want="true" required="true"/>
    </httpj:tlsServerParameters>
   </httpj:engine>
  </httpj:engine-factory>
  
  <!-- We need a bean named "cxf" -->
  <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"/>
</beans>

The preceding server configuration is described as follows:

1

On the server side, TLS is not configured for each WSDL port. Instead of configuring each WSDL port, the TLS security settings are applied to a specific IP port, which is 9001 in this example. All of the WSDL ports that share this IP port are therefore configured with the same TLS security settings.

2

The http:tlsServerParameters element contains all of the server’s TLS configuration details.

3

The sec:keyManagers element is used to attach an X.509 certificate and a private key to the server. The password specified by the keyPasswod attribute is used to decrypt the certificate’s private key.

4

The sec:keyStore element is used to specify an X.509 certificate and a private key that are stored in a Java keystore. This sample declares that the keystore is in Java Keystore format (JKS).

The file attribute specifies the location of the keystore file, cherry.jks, that contains the client’s X.509 certificate chain and private key in a key entry. The password attribute specifies the keystore password, which is needed to access the contents of the keystore. It is expected that the keystore file contains just one key entry, so there is no need to specify a key alias.

Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute. You must be extremely careful not to load the truststore from an untrustworthy source.

For details of how to create such a keystore file, see Use the CA to Create Signed Certificates in a Java Keystore.

5

The sec:trustManagers element is used to specify a list of trusted CA certificates (the server uses this list to decide whether or not to trust certificates presented by clients).

The file attribute of the sec:keyStore element specifies a Java keystore file, truststore.jks, containing one or more trusted CA certificates. The password attribute specifies the password required to access the keystore, truststore.jks. See Specifying Trusted CA Certificates for HTTPS.

Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute.

6

The sec:cipherSuitesFilter element can be used to narrow the choice of cipher suites that the server is willing to use for a TLS connection. See Configuring HTTPS Cipher Suites for details.

7

The sec:clientAuthentication element determines the server’s disposition towards the presentation of client certificates. The element has the following attributes:

  • want attribute—If true (the default), the server requests the client to present an X.509 certificate during the TLS handshake; if false, the server does not request the client to present an X.509 certificate.

  • required attribute—If true, the server raises an exception if a client fails to present an X.509 certificate during the TLS handshake; if false (the default), the server does not raise an exception if the client fails to present an X.509 certificate.

One software package that allows you to set up a private CA is OpenSSL, http://www.openssl.org. OpenSSL is derived from SSLeay, an implementation of SSL developed by Eric Young (). Complete license information can be found in Appendix C . The OpenSSL package includes basic command line utilities for generating and signing certificates. Complete documentation for the OpenSSL command line utilities is available at http://www.openssl.org/docs.

Using the subject DN’s Common Name for the certificate identity has the disadvantage that only one host name can be specified at a time. If you deploy a certificate on a multi-homed host, however, you might find it is practical to allow the certificate to be used with any of the multi-homed host names. In this case, it is necessary to define a certificate with multiple, alternative identities, and this is only possible using the subjectAltName certificate extension.

For example, if you have a multi-homed host that supports connections to either of the following host names:

www.progress.com
fusesource.com

Then you can define a subjectAltName that explicitly lists both of these DNS host names. If you generate your certificates using the openssl utility, edit the relevant line of your openssl.cnf configuration file to specify the value of the subjectAltName extension, as follows:

subjectAltName=DNS:www.progress.com,DNS:fusesource.com

Where the HTTPS protocol matches the server host name against either of the DNS host names listed in the subjectAltName (the subjectAltName takes precedence over the Common Name).

The HTTPS protocol also supports the wildcard character, *, in host names. For example, you can define the subjectAltName as follows:

subjectAltName=DNS:*.progress.com

This certificate identity matches any three-component host name in the domain progress.com. For example, the wildcarded host name matches either www.progress.com or fusesource.com, but does not match www.fusesource.com.

For details of how to set up the openssl.cnf configuration file to generate certificates with the subjectAltName certificate extension, see Use the CA to Create Signed PKCS#12 Certificates .

Create a new self-signed CA certificate and private key with the following command:

openssl req -x509 -new -config X509CA/openssl.cnf -days 365 -out X509CA/ca/new_ca.pem -keyout X509CA/ca/new_ca_pk.pem

The command prompts you for a pass phrase for the CA private key and details of the CA distinguished name. For example:

Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
....+++++
.+++++
writing new private key to 'new_ca_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Progress
Organizational Unit Name (eg, section) []:Finance
Common Name (eg, YOUR name) []:Gordon Brown
Email Address []:gbrown@progress.com 

Note

The security of the CA depends on the security of the private key file and the private key pass phrase used in this step.

You must ensure that the file names and location of the CA certificate and private key, new_ca.pem and new_ca_pk.pem, are the same as the values specified in openssl.cnf (see the preceding step).

You are now ready to sign certificates with your CA.

Sign the CSR using your CA, as follows:

openssl ca -config X509CA/openssl.cnf -days 365 -in CertName_csr.pem -out CertName.pem

To sign the certificate successfully, you must enter the CA private key pass phrase (see Set Up Your Own CA).

Note

If you want to sign the CSR using a CA certificate other than the default CA, use the -cert and -keyfile options to specify the CA certificate and its private key file, respectively.

Perform this step, if the certificate is intended for a HTTPS server whose clients enforce URL integrity check, and if you plan to deploy the server on a multi-homed host or a host with several DNS name aliases (for example, if you are deploying the certificate on a multi-homed Web server). In this case, the certificate identity must match multiple host names and this can be done only by adding a subjectAltName certificate extension (see Special Requirements on HTTPS Certificates).

To configure the subjectAltName extension, edit your CA’s openssl.cnf file as follows:

  1. Add the following req_extensions setting to the [req] section (if not already present in your openssl.cnf file):

    # openssl Configuration File
    ...
    [req]
    req_extensions=v3_req
  2. Add the [v3_req] section header (if not already present in your openssl.cnf file). Under the [v3_req] section, add or modify the subjectAltName setting, setting it to the list of your DNS host names. For example, if the server host supports the alternative DNS names, www.progress.com and fusesource.com, set the subjectAltName as follows:

    # openssl Configuration File
    ...
    [v3_req]
    subjectAltName=DNS:www.progress.com,DNS:fusesource.com
  3. Add a copy_extensions setting to the appropriate CA configuration section. The CA configuration section used for signing certificates is one of the following:

    • The section specified by the -name option of the openssl ca command,

    • The section specified by the default_ca setting under the [ca] section (usually [CA_default]).

    For example, if the appropriate CA configuration section is [CA_default], set the copy_extensions property as follows:

    # openssl Configuration File
    ...
    [CA_default]
    copy_extensions=copy

    This setting ensures that certificate extensions present in the certificate signing request are copied into the signed certificate.

Create a new certificate signing request (CSR) for the CertName.p12 certificate, as shown:

openssl req -new -config X509CA/openssl.cnf -days 365 -out X509CA/certs/CertName_csr.pem -keyout X509CA/certs/CertName_pk.pem

This command prompts you for a pass phrase for the certificate’s private key, and for information about the certificate’s distinguished name.

Some of the entries in the CSR distinguished name must match the values in the CA certificate (specified in the CA Policy section of the openssl.cnf file). The default openssl.cnf file requires that the following entries match:

The certificate subject DN’s Common Name is the field that is usually used to represent the certificate owner’s identity. The Common Name must comply with the following conditions:

Note

For the purpose of the HTTPS URL integrity check, the subjectAltName extension takes precedence over the Common Name.

Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
.+++++
.+++++
writing new private key to
      'X509CA/certs/CertName_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Progress
Organizational Unit Name (eg, section) []:Systems
Common Name (eg, YOUR name) []:Artix
Email Address []:info@progress.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:password
An optional company name []:Progress

On the client side, there are no policy settings required for target-only authentication. Simply configure your client without associating an X.509 certificate with the HTTPS port. You must provide the client with a list of trusted CA certificates, however (see Specifying Trusted CA Certificates).

On the server side, in the server’s XML configuration file, make sure that the sec:clientAuthentication element does not require client authentication. This element can be omitted, in which case the default policy is to not require client authentication. However, if the sec:clientAuthentication element is present, it should be configured as follows:

<http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ...
 
  <sec:clientAuthentication want="false" required="false"/>
  </http:tlsServerParameters>
</http:destination>

Where the want attribute is set to false (the default), specifying that the server does not request an X.509 certificate from the client during a TLS handshake. The required attribute is also set to false (the default), specifying that the absence of a client certificate does not trigger an exception during the TLS handshake.

Note

The want attribute can be set either to true or to false. If set to true, the want setting causes the server to request a client certificate during the TLS handshake, but no exception is raised for clients lacking a certificate, so long as the required attribute is set to false.

It is also necessary to associate an X.509 certificate with the server’s HTTPS port (see Specifying an Application’s Own Certificate ) and to provide the server with a list of trusted CA certificates (see Specifying Trusted CA Certificates ).

Note

The choice of cipher suite can potentially affect whether or not target-only authentication is supported (see Configuring HTTPS Cipher Suites).

On the client side, there are no policy settings required for mutual authentication. Simply associate an X.509 certificate with the client’s HTTPS port (see Specifying an Application’s Own Certificate). You also need to provide the client with a list of trusted CA certificates (see Specifying Trusted CA Certificates).

On the server side, in the server’s XML configuration file, make sure that the sec:clientAuthentication element is configured to require client authentication. For example:

<http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ... 
    <sec:clientAuthentication want="true" required="true"/>
  </http:tlsServerParameters>
</http:destination>
      

Where the want attribute is set to true, specifying that the server requests an X.509 certificate from the client during a TLS handshake. The required attribute is also set to true, specifying that the absence of a client certificate triggers an exception during the TLS handshake.

It is also necessary to associate an X.509 certificate with the server’s HTTPS port (see Specifying an Application’s Own Certificate) and to provide the server with a list of trusted CA certificates (see Specifying Trusted CA Certificates).

Note

The choice of cipher suite can potentially affect whether or not mutual authentication is supported (see Configuring HTTPS Cipher Suites).

To deploy one or more trusted root CAs for the HTTPS transport, perform the following steps:

  1. Assemble the collection of trusted CA certificates that you want to deploy. The trusted CA certificates can be obtained from public CAs or private CAs (for details of how to generate your own CA certificates, see Set Up Your Own CA). The trusted CA certificates can be in any format that is compatible with the Java keystore utility; for example, PEM format. All you need are the certificates themselves—the private keys and passwords are not required.

  2. Given a CA certificate, cacert.pem, in PEM format, you can add the certificate to a JKS truststore (or create a new truststore) by entering the following command:

    keytool -import -file cacert.pem -alias CAAlias -keystore truststore.jks -storepass StorePass 

    Where CAAlias is a convenient tag that enables you to access this particular CA certificate using the keytool utility. The file, truststore.jks, is a keystore file containing CA certificates—if this file does not already exist, the keytool utility creates one. The StorePass password provides access to the keystore file, truststore.jks.

  3. Repeat step 2 as necessary, to add all of the CA certificates to the truststore file, truststore.jks.

  4. Edit the relevant XML configuration files to specify the location of the truststore file. You must include the sec:trustManagers element in the configuration of the relevant HTTPS ports.

    For example, you can configure a client port as follows:

    <!-- Client port configuration -->
    <http:conduit id="{Namespace}PortName.http-conduit"> 
      <http:tlsClientParameters>
        ...
        <sec:trustManagers>
          <sec:keyStore type="JKS"
                        password="StorePass"
                        file="certs/truststore.jks"/>
        </sec:trustManagers>
        ...
      </http:tlsClientParameters>
    </http:conduit>
              

    Where the type attribute specifes that the truststore uses the JKS keystore implementation and StorePass is the password needed to access the truststore.jks keystore.

    Configure a server port as follows:

    <!-- Server port configuration -->
    <http:destination id="{Namespace}PortName.http-destination"> 
      <http:tlsServerParameters>
        ...
        <sec:trustManagers>
          <sec:keyStore type="JKS"
                        password="StorePass"
                        file="certs/truststore.jks"/>
        </sec:trustManagers>
        ...
      </http:tlsServerParameters>
    </http:destination>
              

    Warning

    The directory containing the truststores (for example, X509Deploy/truststores/) should be a secure directory (that is, writable only by the administrator).

To deploy an application’s own certificate for the HTTPS transport, perform the following steps:

  1. Obtain an application certificate in Java keystore format, CertName.jks. For instructions on how to create a certificate in Java keystore format, see Use the CA to Create Signed Certificates in a Java Keystore.

    Note

    Some HTTPS clients (for example, Web browsers) perform a URL integrity check, which requires a certificate’s identity to match the hostname on which the server is deployed. See Special Requirements on HTTPS Certificates for details.

  2. Copy the certificate’s keystore, CertName.jks, to the certificates directory on the deployment host; for example, X509Deploy/certs.

    The certificates directory should be a secure directory that is writable only by administrators and other privileged users.

  3. Edit the relevant XML configuration file to specify the location of the certificate keystore, CertName.jks. You must include the sec:keyManagers element in the configuration of the relevant HTTPS ports.

    For example, you can configure a client port as follows:

    <http:conduit id="{Namespace}PortName.http-conduit"> 
      <http:tlsClientParameters>
        ...
        <sec:keyManagers keyPassword="CertPassword">
          <sec:keyStore type="JKS"
                        password="KeystorePassword"
                        file="certs/CertName.jks"/>
        </sec:keyManagers>
        ...
      </http:tlsClientParameters>
    </http:conduit>

    Where the keyPassword attribute specifies the password needed to decrypt the certificate’s private key (that is, CertPassword), the type attribute specifes that the truststore uses the JKS keystore implementation, and the password attribute specifies the password required to access the CertName.jks keystore (that is, KeystorePassword).

    Configure a server port as follows:

    <http:destination id="{Namespace}PortName.http-destination"> 
      <http:tlsServerParameters>
        ...
        <sec:keyManagers keyPassword="CertPassword">
          <sec:keyStore type="JKS"
                        password="KeystorePassword"
                        file="certs/CertName.jks"/>
        </sec:keyManagers>
        ...
      </http:tlsServerParameters>
    </http:destination>

    Warning

    The directory containing the application certificates (for example, X509Deploy/certs/) should be a secure directory (that is, readable and writable only by the administrator).

    Warning

    The directory containing the XML configuration file should be a secure directory (that is, readable and writable only by the administrator), because the configuration file contains passwords in plain text.

The following cipher suites are supported by SUN’s JSSE provider in the J2SE 1.5.0 Java development kit (see also Appendix A of SUN’s JSSE Reference Guide):

  • Standard ciphers:

    SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
    SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
    SSL_DHE_DSS_WITH_DES_CBC_SHA
    SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
    SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
    SSL_DHE_RSA_WITH_DES_CBC_SHA
    SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
    SSL_RSA_EXPORT_WITH_RC4_40_MD5
    SSL_RSA_WITH_3DES_EDE_CBC_SHA
    SSL_RSA_WITH_DES_CBC_SHA
    SSL_RSA_WITH_RC4_128_MD5
    SSL_RSA_WITH_RC4_128_SHA
    TLS_DHE_DSS_WITH_AES_128_CBC_SHA
    TLS_DHE_DSS_WITH_AES_256_CBC_SHA
    TLS_DHE_RSA_WITH_AES_128_CBC_SHA
    TLS_DHE_RSA_WITH_AES_256_CBC_SHA
    TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
    TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
    TLS_KRB5_EXPORT_WITH_RC4_40_MD5
    TLS_KRB5_EXPORT_WITH_RC4_40_SHA
    TLS_KRB5_WITH_3DES_EDE_CBC_MD5
    TLS_KRB5_WITH_3DES_EDE_CBC_SHA
    TLS_KRB5_WITH_DES_CBC_MD5
    TLS_KRB5_WITH_DES_CBC_SHA
    TLS_KRB5_WITH_RC4_128_MD5
    TLS_KRB5_WITH_RC4_128_SHA
    TLS_RSA_WITH_AES_128_CBC_SHA
    TLS_RSA_WITH_AES_256_CBC_SHA
  • Null encryption, integrity-only ciphers:

    SSL_RSA_WITH_NULL_MD5
    SSL_RSA_WITH_NULL_SHA
  • Anonymous Diffie-Hellman ciphers (no authentication):

    SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
    SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
    SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
    SSL_DH_anon_WITH_DES_CBC_SHA
    SSL_DH_anon_WITH_RC4_128_MD5
    TLS_DH_anon_WITH_AES_128_CBC_SHA
    TLS_DH_anon_WITH_AES_256_CBC_SHA

The WS-Policy specification provides a general framework for applying policies that modify the semantics of connections and communications at runtime in a Web services application. Fuse Services Framework security uses the WS-Policy framework to configure message protection and authentication requirements.

The simplest way to specify a policy is to embed it directly where you want to apply it. For example, to associate a policy with a specific port in the WSDL contract, you can specify it as follows:

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:service name="PingService10">
    <wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
      <wsp:Policy>
        <!-- Policy expression comes here! -->
      </wsp:Policy>
      <soap:address location="SOAPAddress"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

An alternative way to specify a policy is to insert a policy reference element, wsp:PolicyReference, at the point where you want to apply the policy and then insert the policy element, wsp:Policy, at some other point in the XML file. For example, to associate a policy with a specific port using a policy reference, you could use a configuration like the following:

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:service name="PingService10">
    <wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
      <wsp:PolicyReference URI="#PolicyID"/>
      <soap:address location="SOAPAddress"/>
    </wsdl:port>
  </wsdl:service>
  ...
  <wsp:Policy wsu:Id="PolicyID">
    <!-- Policy expression comes here ... -->
  </wsp:Policy>
</wsdl:definitions>

Where the policy reference, wsp:PolicyReference, locates the referenced policy using the ID, PolicyID (note the addition of the # prefix character in the URI attribute). The policy itself, wsp:Policy, must be identified by adding the attribute, wsu:Id="PolicyID".

Transport layer message protection refers to the message protection (encryption and signing) that is provided by the transport layer. For example, HTTPS provides encryption and message signing features using SSL/TLS. In fact, WS-SecurityPolicy does not add much to the HTTPS feature set, because HTTPS is already fully configurable using Spring XML configuration (see Configuring HTTPS). An advantage of specifying a transport binding policy for HTTPS, however, is that it enables you to embed security requirements in the WSDL contract. Hence, any client that obtains a copy of the WSDL contract can discover what the transport layer security requirements are for the endpoints in the WSDL contract.

If you use WS-SecurityPolicy to configure the HTTPS transport, you must also configure HTTPS security appropriately in the Spring configuration.

Example 6.1 shows how to configure a client to use the HTTPS transport protocol. The sec:keyManagers element specifies the client's own certificate, alice.pfx, and the sec:trustManagers element specifies the trusted CA list. Note how the http:conduit element's name attribute uses wildcards to match the endpoint address. For details of how to configure HTTPS on the client side, see Configuring HTTPS.


Example 6.2 shows how to configure a server to use the HTTPS transport protocol. The sec:keyManagers element specifies the server's own certificate, bob.pfx, and the sec:trustManagers element specifies the trusted CA list. For details of how to configure HTTPS on the server side, see Configuring HTTPS.


A transport binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the transport binding policy with ID, UserNameOverTransport_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="UserNameOverTransport_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#UserNameOverTransport_IPingService_policy"/>
  ...
</wsdl:binding>

As described in the WS-SecurityPolicy specification, one of the following binding types can be used to protect SOAP messages:

Figure 6.1 shows an overview of the basic signing and encryption scenario, which is specified by associating an asymmetric binding policy with an endpoint in the WSDL contract.


When the client in Figure 6.1 invokes a synchronous operation on the recipient's endpoint, the request and reply message are processed as follows:

  1. As the outgoing request message passes through the WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the client’s asymmetric binding policy. In this example, the handler performs the following processing:

    1. Encrypt the SOAP body of the message using Bob’s public key.

    2. Sign the encrypted SOAP body using Alice’s private key.

  2. As the incoming request message passes through the server's WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the server’s asymmetric binding policy. In this example, the handler performs the following processing:

    1. Verify the signature using Alice’s public key.

    2. Decrypt the SOAP body using Bob’s private key.

  3. As the outgoing reply message passes back through the server's WS-SecurityPolicy handler, the handler performs the following processing:

    1. Encrypt the SOAP body of the message using Alice’s public key.

    2. Sign the encrypted SOAP body using Bob’s private key.

  4. As the incoming reply message passes back through the client's WS-SecurityPolicy handler, the handler performs the following processing:

    1. Verify the signature using Bob’s public key.

    2. Decrypt the SOAP body using Alice’s private key.

An asymmetric binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the asymmetric binding policy with ID, MutualCertificate10SignEncrypt_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#MutualCertificate10SignEncrypt_IPingService_policy"/>
  ...
</wsdl:binding>

Example 6.4 shows an example of an asymmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using pairs of public/private keys (that is, using asymmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Specifying Parts of Message to Encrypt and Sign.


The initiator token refers to the public/private key-pair owned by the initiator. This token is used as follows:

Confusingly, this token is used both by the initiator and by the recipient. However, only the initiator has access to the private key so, in this sense, the token can be said to belong to the initiator. In Basic Signing and Encryption Scenario, the initiator token is the certificate, Alice.

This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to AlwaysToRecipient, which instructs the runtime to include Alice's public key with every message sent to the recipient. This option is useful, in case the recipient wants to use the initiator's certificate to perform authentication. The most deeply nested element, WssX509V3Token10 is optional. It specifies what specification version the X.509 certificate should conform to. The following alternatives (or none) can be specified here:

sp:WssX509V3Token10

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token10

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token10

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

sp:WssX509V1Token11

This optional element is a policy assertion that indicates that an X509 Version 1 token should be used.

sp:WssX509V3Token11

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token11

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token11

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

This element specifies that the message signature must be encrypted (by the encryption token, specified as described in Providing Encryption Keys and Signing Keys). Default is false.

Note

The message signature is the signature obtained directly by signing various parts of the message, such as message body, message headers, or individual elements (see Specifying Parts of Message to Encrypt and Sign). Sometimes the message signature is referred to as the primary signature, because the WS-SecurityPolicy specification also supports the concept of an endorsing supporting token, which is used to sign the primary signature. Hence, if an sp:EndorsingSupportingTokens element is applied to an endpoint, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature.

For more details about the various kinds of endorsing supporting token, see SupportingTokens assertions.

A symmetric binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the symmetric binding policy with ID, SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="SecureConversation_MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy"/>
  ...
</wsdl:binding>

Encryption and signing provide two kinds of protection: confidentiality and integrity, respectively. The WS-SecurityPolicy protection assertions are used to specify which parts of a message are subject to protection. Details of the protection mechanisms, on the other hand, are specified separately in the relevant binding policy (see xSpecifying an AsymmetricBinding Policy, Specifying a SymmetricBinding Policy, and Transport Layer Message Protection).

The protection assertions described here are really intended to be used in combination with SOAP security, because they apply to features of a SOAP message. Nonetheless, these policies can also be satisfied by a transport binding (such as HTTPS), which applies protection to the entire message, rather than to specific parts.

A protection assertion must be applied to a message policy subject (see Message policy subject). In other words, it must be placed inside a wsdl:input, wsdl:output, or wsdl:fault element in a WSDL binding. For example, given the protection policy with ID, MutualCertificate10SignEncrypt_IPingService_header_Input_policy, you could apply the policy to a wsdl:input message part as follows:

<wsdl:operation name="header">
  <soap:operation soapAction="http://InteropBaseAddress/interop/header" style="document"/>
  <wsdl:input name="headerRequest">
    <wsp:PolicyReference
        URI="#MutualCertificate10SignEncrypt_IPingService_header_Input_policy"/>
      <soap:header message="i0:headerRequest_Headers" part="CustomHeader" use="literal"/>
      <soap:body use="literal"/>
    </wsdl:input>
    ...
</wsdl:operation>

You can specify an application's encryption keys and signing keys by setting properties on a client's request context or on an endpoint context (see Add encryption and signing properties to Spring configuration). The properties you can set are shown in Table 6.1.


Tip

The names of the preceding properties are not so well chosen, because they do not accurately reflect what they are used for. The key specified by ws-security.signature.properties is actually used both for signing and decrypting. The key specified by ws-security.encryption.properties is actually used both for encrypting and for validating signatures.

Before you can use any WS-Policy policies in a Fuse Services Framework application, you must add the policies feature to the default CXF bus. Add the p:policies element to the CXF bus, as shown in the following Spring configuration fragment:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xmlns:cxf="http://cxf.apache.org/core"
       xmlns:p="http://cxf.apache.org/policy" ... >

    <cxf:bus>
        <cxf:features>
            <p:policies/>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>
    ...
</beans>

The following example shows how to add signature and encryption properties to proxies of the specified service type (where the service name is specified by the name attribute of the jaxws:client element). The properties are stored in WSS4J property files, where alice.properties contains the properties for the signature key and bob.properties contains the properties for the encryption key.

<beans ... >
    <jaxws:client name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.signature.properties" value="etc/alice.properties"/>
            <entry key="ws-security.encryption.properties" value="etc/bob.properties"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

In fact, although it is not obvious from the property names, each of these keys is used for two distinct purposes on the client side:

If you find this confusing, see Basic Signing and Encryption Scenario for a more detailed explanation.

The following example shows how to add signature and encryption properties to a JAX-WS endpoint. The properties file, bob.properties, contains the properties for the signature key and the properties file, alice.properties, contains the properties for the encryption key (this is the inverse of the client configuration).

<beans ... >
    <jaxws:endpoint 
       name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService"
       id="MutualCertificate10SignEncrypt"
       address="http://localhost:9002/MutualCertificate10SignEncrypt" 
       serviceName="interop:PingService10"
       endpointName="interop:MutualCertificate10SignEncrypt_IPingService"
       implementor="interop.server.MutualCertificate10SignEncrypt">
        
        <jaxws:properties>
            <entry key="ws-security.signature.properties" value="etc/bob.properties"/>
            <entry key="ws-security.encryption.properties" value="etc/alice.properties"/>
        </jaxws:properties> 

    </jaxws:endpoint> 
    ...
</beans>

Each of these keys is used for two distinct purposes on the server side:

  • bob.properties (that is, the key specified by ws-security.signature.properties) is used on the server side as follows:

    • For signing outgoing messages.

    • For decrypting incoming messages.

  • alice.properties (that is, the key specified by ws-security.encryption.properties) is used on the server side as follows:

    • For encrypting outgoing messages.

    • For verifying signatures on incoming messages.

Fuse Services Framework uses WSS4J property files to load the public keys and the private keys needed for encryption and signing. Table 6.2 describes the properties that you can set in these files.

Table 6.2. WSS4J Keystore Properties

PropertyDescription

org.apache.ws.security. crypto.provider

Specifies an implementation of the Crypto interface (see WSS4J Crypto interface). Normally, you specify the default WSS4J implementation of Crypto, org.apache.ws.security.components.crypto.Merlin.

The rest of the properties in this table are specific to the Merlin implementation of the Crypto interface.

org.apache.ws.security. crypto.merlin.keystore.provider

(Optional) The name of the JSSE keystore provider to use. The default keystore provider is Bouncy Castle. You can switch provider to Sun's JSSE keystore provider by setting this property to SunJSSE.

org.apache.ws.security. crypto.merlin.keystore.type

The Bouncy Castle keystore provider supports the following types of keystore: JKS and PKCS12. In addition, Bouncy Castle supports the following proprietary keystore types: BKS and UBER.

org.apache.ws.security. crypto.merlin.keystore.file

Specifies the location of the keystore file to load, where the location is specified relative to the Classpath.

org.apache.ws.security. crypto.merlin.keystore.alias

(Optional) If the keystore type is JKS (Java keystore), you can select a specific key from the keystore by specifying its alias. If the keystore contains only one key, there is no need to specify an alias.

org.apache.ws.security. crypto.merlin.keystore.password

The password specified by this property is used for two purposes: to unlock the keystore (keystore password) and to decrypt a private key that is stored in the keystore (private key password). Hence, the keystore password must be same as the private key password.

For example, the etc/alice.properties file contains property settings to load the PKCS#12 file, certs/alice.pfx, as follows:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

org.apache.ws.security.crypto.merlin.keystore.type=PKCS12
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.file=certs/alice.pfx

The etc/bob.properties file contains property settings to load the PKCS#12 file, certs/bob.pfx, as follows:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

org.apache.ws.security.crypto.merlin.keystore.password=password

# for some reason, bouncycastle has issues with bob.pfx
org.apache.ws.security.crypto.merlin.keystore.provider=SunJSSE
org.apache.ws.security.crypto.merlin.keystore.type=PKCS12
org.apache.ws.security.crypto.merlin.keystore.file=certs/bob.pfx

Example 6.7 shows the definition of the Crypto interface that you can implement, if you want to provide encryption keys and signing keys by programming. For more information, see the WSS4J home page.

Example 6.7. WSS4J Crypto Interface

// Java
package org.apache.ws.security.components.crypto;

import org.apache.ws.security.WSSecurityException;

import java.io.InputStream;
import java.math.BigInteger;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.Certificate;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;

public interface Crypto {
    X509Certificate loadCertificate(InputStream in)
    throws WSSecurityException;

    X509Certificate[] getX509Certificates(byte[] data, boolean reverse)
    throws WSSecurityException;

    byte[] getCertificateData(boolean reverse, X509Certificate[] certs)
    throws WSSecurityException;

    public PrivateKey getPrivateKey(String alias, String password)
    throws Exception;

    public X509Certificate[] getCertificates(String alias)
    throws WSSecurityException;

    public String getAliasForX509Cert(Certificate cert)
    throws WSSecurityException;

    public String getAliasForX509Cert(String issuer)
    throws WSSecurityException;

    public String getAliasForX509Cert(String issuer, BigInteger serialNumber)
    throws WSSecurityException;

    public String getAliasForX509Cert(byte[] skiBytes)
    throws WSSecurityException;

    public String getDefaultX509Alias();

    public byte[] getSKIBytesFromCert(X509Certificate cert)
    throws WSSecurityException;
 
    public String getAliasForX509CertThumb(byte[] thumb)
    throws WSSecurityException;
 
    public KeyStore getKeyStore();

    public CertificateFactory getCertificateFactory()
    throws WSSecurityException;

    public boolean validateCertPath(X509Certificate[] certs)
    throws WSSecurityException;

    public String[] getAliasesForDN(String subjectDN)
    throws WSSecurityException;
}

Table 6.4 provides a summary of the algorithm suites supported by WS-SecurityPolicy. The column headings refer to different types of cryptographic algorithm, as follows: [Dig] is the digest algorithm; [Enc] is the encryption algorithm; [Sym KW] is the symmetric key-wrap algorithm; [Asym KW] is the asymmetric key-wrap algorithm; [Enc KD] is the encryption key derivation algorithm; [Sig KD] is the signature key derivation algorithm.


If you want an endpoint to support authentication, associate a supporting tokens policy assertion with the relevant endpoint binding. There are several different kinds of supporting tokens policy assertions, whose elements all have names of the form *SupportingTokens (for example, SupportingTokens, SignedSupportingTokens, and so on). For a complete list, see SupportingTokens assertions.

Associating a supporting tokens assertion with an endpoint has the following effects:

  • Messages to or from the endpoint are required to include the specified token type (where the token's direction is specified by the sp:IncludeToken attribute).

  • Depending on the particular type of supporting tokens element you use, the endpoint might be required to sign and/or encrypt the token.

The supporting tokens assertion implies that the runtime will check that these requirements are satisified. But the WS-SecurityPolicy policies do not define the mechanism for providing credentials to the runtime. You must use Spring XML configuration to specify the credentials (see Providing Client Credentials).

The *SupportingTokens elements (that is, all elements with the SupportingTokens suffix—see SupportingTokens assertions) have the following syntax:

<sp:SupportingTokensElement xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
    [Token Assertion]+
    <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> ?
    (
      <sp:SignedParts ... > ... </sp:SignedParts> |
      <sp:SignedElements ... > ... </sp:SignedElements> |
      <sp:EncryptedParts ... > ... </sp:EncryptedParts> |
      <sp:EncryptedElements ... > ... </sp:EncryptedElements> |
    ) *
    ...
  </wsp:Policy>
  ...
</sp:SupportingTokensElement>

Where SupportingTokensElement stands for one of the supporting token elements, *SupportingTokens.Typically, if you simply want to include a token (or tokens) in the security header, you would include one or more token assertions, [Token Assertion], in the policy. In particular, this is all that is required for authentication.

If the token is of an appropriate type (for example, an X.509 certificate or a symmetric key), you could theoretically also use it to sign or encrypt specific parts of the current message using the sp:AlgorithmSuite, sp:SignedParts, sp:SignedElements, sp:EncryptedParts, and sp:EncryptedElements elements. This functionality is currently not supported by Fuse Services Framework, however.

Example 7.1 shows an example of a policy that requires a WS-Security UsernameToken token (which contains username/password credentials) to be included in the security header. In addition, because the token is specified inside an sp:SignedSupportingTokens element, the policy requires that the token is signed. This example uses a transport binding, so it is the underlying transport that is responsible for signing the message.

For example, if the underlying transport is HTTPS, the SSL/TLS protocol (configured with an appropriate algorithm suite) is responsible for signing the entire message, including the security header that contains the specified token. This is sufficient to satisfy the requirement that the supporting token is signed.


Where the presence of the sp:WssUsernameToken10 sub-element indicates that the UsernameToken header should conform to version 1.0 of the WS-Security UsernameToken specification.

The value of the sp:IncludeToken must match the WS-SecurityPolicy version from the enclosing policy. The current version is 1.2, but legacy WSDL might use version 1.1. Valid values of the sp:IncludeToken attribute are as follows:

Never

The token MUST NOT be included in any messages sent between the initiator and the recipient; rather, an external reference to the token should be used. Valid URI values are:

1.2

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

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Never

Once

The token MUST be included in only one message sent from the initiator to the recipient. References to the token MAY use an internal reference mechanism. Subsequent related messages sent between the recipient and the initiator may refer to the token using an external reference mechanism. Valid URI values are:

1.2

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

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Once

AlwaysToRecipient

The token MUST be included in all messages sent from initiator to the recipient. The token MUST NOT be included in messages sent from the recipient to the initiator. Valid URI values are:

1.2

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

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToRecipient

AlwaysToInitiator

The token MUST be included in all messages sent from the recipient to the initiator. The token MUST NOT be included in messages sent from the initiator to the recipient. Valid URI values are:

1.2

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

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToInitiator

Always

The token MUST be included in all messages sent between the initiator and the recipient. This is the default behavior. Valid URI values are:

1.2

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

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Always

If you want to use a callback handler to provide passwords for the UsernameToken header, you must first modify the client configuration in Spring XML, replacing the ws-security.password setting by a ws-security.callback-handler setting, as follows:

<beans ... >
    <jaxws:client name="{NamespaceName}LocalPortName"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

In the preceding example, the callback handler is implemented by the UTPasswordCallback class. You can write a callback handler by implementing the javax.security.auth.callback.CallbackHandler interface, as shown in Example 7.2.


The callback functionality is implemented by the CallbackHandler.handle() method. In this example, it assumed that the callback objects passed to the handle() method are all of org.apache.ws.security.WSPasswordCallback type (in a more realistic example, you would check the type of the callback objects).

A more realistic implementation of a client callback handler would probably consist of prompting the user to enter their password.

When a CallbackHandler is called in a Fuse Services Framework client for the purpose of setting a UsernameToken password, the corresponding WSPasswordCallback object has the USERNAME_TOKEN usage code.

For more details about the WSPasswordCallback class, see org.apache.ws.security.WSPasswordCallback.

The WSPasswordCallback class defines several different usage codes, as follows:

USERNAME_TOKEN

Obtain the password for UsernameToken credentials. This usage code is used both on the client side (to obtain a password to send to the server) and on the server side (to obtain a password in order to compare it with the password received from the client).

On the server side, this code is set in the following cases:

  • Digest password—if the UsernameToken contains a digest password, the callback must return the corresponding password for the given user name (given by WSPasswordCallback.getIdentifier()). Verification of the password (by comparing with the digest password) is done by the WSS4J runtime.

  • Plaintext password—implemented the same way as the digest password case (since Fuse Services Framework 2.4.0).

  • Custom password type—if getHandleCustomPasswordTypes() is true on org.apache.ws.security.WSSConfig, this case is implemented the same way as the digest password case (since Fuse Services Framework 2.4.0). Otherwise, an exception is thrown.

If no Password element is included in a received UsernameToken on the server side, the callback handler is not called (since Fuse Services Framework 2.4.0).

DECRYPT

Need a password to retrieve a private key from a Java keystore, where WSPasswordCallback.getIdentifier() gives the alias of the keystore entry. WSS4J uses this private key to decrypt the session (symmetric) key.

SIGNATURE

Need a password to retrieve a private key from a Java keystore, where WSPasswordCallback.getIdentifier() gives the alias of the keystore entry. WSS4J uses this private key to produce a signature.

SECRET_KEY

Need a secret key for encryption or signature on the outbound side, or for decryption or verification on the inbound side. The callback handler must set the key using the setKey(byte[]) method.

SECURITY_CONTEXT_TOKEN

Need the key for a wsc:SecurityContextToken, which you provide by calling the setKey(byte[]) method.

CUSTOM_TOKEN

Need a token as a DOM element. For example, this is used for the case of a reference to a SAML Assertion or SecurityContextToken that is not in the message. The callback handler must set the token using the setCustomToken(Element) method.

KEY_NAME

(Obsolete) Since Fuse Services Framework 2.4.0, this usage code is obsolete.

USERNAME_TOKEN_UNKNOWN

(Obsolete) Since Fuse Services Framework 2.4.0, this usage code is obsolete.

UNKNOWN

Not used by WSS4J.

To implement a callback handler for checking passwords on the server side, implement the javax.security.auth.callback.CallbackHandler interface. The general approach to implementing the CallbackHandler interface for a server is similar to implementing a CallbackHandler for a client. The interpretation given to the returned password on the server side is different, however: the password from the callback handler is compared against the received client password in order to verify the client's credentials.

For example, you could use the sample implementation shown in Example 7.2 to obtain passwords on the server side. On the server side, the WSS4J runtime would compare the password obtained from the callback with the password in the received client credentials. If the two passwords match, the credentials are successfully verified.

A more realistic implementation of a server callback handler would involve writing an integration with a third-party database that is used to store security data (for example, integration with an LDAP server).

Figure 8.1 shows a general overview of the WS-Trust architecture.


A SAML token is a particularly flexible kind of security token. The SAML specification defines a general-purpose XML schema that enables you to wrap almost any kind of security data and enables you to sign and encrypt part or all of the token.

SAML is a popular choice of token to use in the context of WS-Trust, because SAML has all of the necessary features to support typical WS-Trust authentication scenarios.

The WS-Trust single sign-on scenario shown in Figure 8.6 proceeds as follows:

  1. Before invoking an operation on the server for the first time, the client initiates SSO login by contacting the Issue binding on the STS.

  2. The client presents its own X.509 certificate, wibble, during the TLS handshake. On the STS side of the connection, the JAX-WS endpoint verifies the client certificate using the CA certificate, wibble_ca, and on the client side, the client verifies the STS certificate using a stored copy of the STS certificate, stsstore.jks.

  3. The STS creates a SAML 2.0 token and the token issuer private key is used to sign the SAML token (where the signature is shown as # in the figure). This enables relying parties (WS servers) to verify the integrity of the SAML token.

  4. The STS replies to the client, sending back the signed SAML token.

  5. The client initiates a connection to the server, in order to invoke an operation.

  6. During the TLS handshake, the client presents its own X.509 certificate, wibble. On the server side of the connection, the JAX-WS endpoint verifies the client certificate using the CA certificate, wibble_ca, and on the client side, the client verifies the server certificate also using the CA certificate, wibble_ca.

    After the connection is established, the client sends an invocation request to the server, which includes the SAML token embedded in a SOAP header.

  7. The server tests the integrity of the received SAML token using the token issuer public key (which complements the token issuer private key used by the STS). If this test is successful, it proves that the SAML token has not been modified or corrupted since it was issued by the STS.

The Fuse Services Framework samples include a demonstration implementation of a security token service. The functionality of this sample security token service is limited: it supports only the Issue operation and always returns a signed SAML token (which can conform either to SAML 1.1 or SAML 2.0).

In general, before a client can invoke operations on a given STS, a certain amount of setup preparation is required, as illustrated in Figure 8.6. The STS must provide its own X.509 certificate, enabling the client to authenticate the STS and to confirm signatures made by the STS, and the STS must provide a copy of its WSDL contract, which is a standard requirement for contacting any Web service. Assuming the client identifies itself using an X.509 certificate, it is also necessary for the client to provide a copy of its trusted CA certificate to the STS.


In general, whenever you are integrating a WS client with a security token service, you will need to perform some or all of the following actions:

Perform the following steps to configure the security token service:

  1. Configure the Maven Jetty plug-in with a secure SSL port.

    The result of building the sts_issue_operation sample is a WAR file, which can then be deployed into any Web container. You can also deploy the WAR file into a Jetty container, which can conveniently be started up using the Maven Jetty plug-in. By default, however, the Jetty configuration in the sts_issue_operation POM file exposes an insecure HTTP port. To change the Jetty configuration to use a secure HTTPS port, edit the pom.xml file in the samples/sts_issue_operation directory, adding the connectors element as shown in the following extract:

  2. Import the client's trusted CA certificate into the STS trust store file.

    Copy the cacert.pem file from the samples/wsdl_first_https/certs directory to the samples/sts_issue_operation/src/main/resources directory. Install this CA cert into the STS's trust store, stsstore.jks, by opening a new command prompt, changing directory to samples/sts_issue_operation/src/main/resources, and entering the following command:

    keytool -import -file cacert.pem -alias wibble_ca -keystore stsstore.jks -storepass stsspass

    This command uses the Java keytool utility to install the client's CA certificate, cacert.pem, into the STS trust store, stsstore.jks, and assigns the certificate alias, wibble_ca, to identify the new entry in the trust store.

    A convenient way of viewing and manipulating Java keystore files is to use the free Portecle tool, which implements a visual frontend to the keystore utility.

  3. Add the client's trusted CA to the list of trusted certificates in the STS.

    The demonstration STS checks received certificates using its CertificateVerifier class. This class does not automatically trust all of the certificates present in the STS trust store, stsstore.jks, however. In order to permit authentication using the client's trusted CA, you must explicitly add the certificate alias to the certificate verifier's list of trusted certificates.

    Edit the beans.xml file located in the following directory:

    CxfInstallDir/samples/sts_issue_operation/src/main/webapp/WEB-INF

    Look for the bean with the ID, certificateVerifierConfig, and add the wibble_ca certificate alias to the list of trusted aliases, as shown in the following fragment:

    <beans ...>
        ...
        <bean id="certificateVerifierConfig"
            class="demo.sts.provider.cert.CertificateVerifierConfig">
            <property name="storePath" value="/stsstore.jks"/>
            <property name="storePwd" value="stsspass"/>
            <!-- if false exception for self-signed cert will be thrown -->
            <property name="verifySelfSignedCert" value="true"/>
            <property name="trustCertAliases">
                <list>
                    <value>myclientkey</value>
                    <value>wibble_ca</value>
                </list>
            </property>        
            <property name="keySignAlias" value="mystskey"/>
            <property name="keySignPwd" value="stskpass"/>
        </bean>
    </beans>
  4. Install the STS certificate in the client.

    Create a new sts directory and a new sts/certs directory under the samples/wsdl_first_https directory. Copy the stsstore.jks file from this directory:

    CxfInstallDir/samples/sts_issue_operation/src/main/resources/

    To this directory:

    CxfInstallDir/samples/wsdl_first_https/sts/certs/
  5. Install the STS WSDL in the client.

    Create a new sts/wsdl directory under the samples/wsdl_first_https directory. Copy all of the files (.wsdl files and .xsd files) from this directory:

    CxfInstallDir/samples/sts_issue_operation/src/main/webapp/WEB-INF/wsdl/

    To this directory:

    CxfInstallDir/samples/wsdl_first_https/sts/wsdl/
  6. Customize the SOAP address in the client copy of the STS WSDL.

    Edit the ws-trust-1.4-service.wsdl file from the wsdl_first_https/sts/wsdl/ directory. Scroll down to the end of this file, where the wsdl:service element is defined. Change the value of the location attribute in the soap:address element as shown in the following fragment:

    <wsdl:definitions ... >
      ...
      <wsdl:service name="SecurityTokenServiceProvider">
        <wsdl:port binding="tns:SecurityTokenServiceSOAP" name="SecurityTokenServiceSOAP">
          <soap:address location="https://localhost:8181/sts/SecurityTokenService"/>
        </wsdl:port>
      </wsdl:service>
    
    </wsdl:definitions>

    The new address, https://localhost:8181/sts/SecurityTokenService, is consistent with the Jetty container configuration, as specified in step 1.

    Note

    Don't forget to specify the secure protocol scheme, https, instead of http in this address.

  7. To build and run the STS server using Maven, open a new command prompt, change directory to samples/sts_issue_operation/, and enter the following Maven command:

    mvn jetty:run

    The first time that you run this command, Maven will build the project before running STS in the Jetty container.

Perform the following steps to add the single sign-on security policy to the hello_world WSDL contract:

  1. Edit the hello_world.wsdl file from the wsdl_first_https/wsdl/ directory. Add the single sign-on policy shown in Example 8.1 as a child of the wsdl:definitions element.

  2. Continue editing the hello_world.wsdl file, in order to add a policy reference to the WSDL port. Search for the SOAPService wsdl:service element and then add the wsp:PolicyReference element as a child of the wsdl:port element, as shown in the following WSDL fragment:

    <wsdl:definitions ... >
        ...
        <wsdl:service name="SOAPService">
            <wsdl:port binding="tns:Greeter_SOAPBinding" name="SoapPort">
                <wsp:PolicyReference xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" URI="#STS_SAML_Token_policy"/>
                <soap:address location="https://localhost:9001/SoapContext/SoapPort"/>
            </wsdl:port>
        </wsdl:service>
        ...
    </wsdl:definitions>

    By inserting the wsp:PolicyReference element at this point, you are associating the WSDL port with the security policy referenced by the URI attribute value, #STS_SAML_Token_policy, (which matches the wsu:Id attribute of the single sign-on security policy).

  3. The server requires a separate copy of the WSDL file, which omits the IssuedToken policy. Copy hello_world.wsdl to hello_world_server.wsdl (in the same directory). Edit the new hello_world_server.wsdl file and delete the sp:SignedSupportingTokens element from the policy, so that the content of the hello_world_server.wsdl file now has the following outline:

    <wsdl:definitions ... >
        ...
        <wsp:Policy wsu:Id="STS_SAML_Token_policy"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <sp:TransportBinding xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
              ...
          </sp:TransportBinding>
          <!-- sp:SignedSupportingTokens element is omitted in server copy of the WSDL -->
        </wsp:Policy>
    
    </wsdl:definitions>

    Note

    If you completely omit the wsp:Policy element from the server's copy of the WSDL file, this would implicitly disable the auto-installation of the WSS4J interceptors. When you run the demonstration, the server would be unable to parse the security header and would therefore return a mustUnderstand fault.

An interesting point about the sample client code is that it illustrates how you can use XML to configure a client proxy that has already been created in Java. In other words, this example answers the question: what do you do, when the client proxy is created in Java, but you want to specify some of its properties in XML?

First of all, consider the typical approach for instantiating a client proxy in Java, using the generated Greeter stub code, as follows:

// Java
import org.apache.hello_world_soap_http.Greeter;
import org.apache.hello_world_soap_http.SOAPService;
...
// Instantiate 'Greeter' client proxy
SOAPService ss = new SOAPService(wsdlURL, SERVICE_NAME);
Greeter port = ss.getPort(PORT_NAME, Greeter.class);

Now, in the XML configuration, you cannot use the jaxws:client element in the normal way to instantiate and configure the client proxy, because the Greeter client proxy already exists. It turns out, however, that the jaxws:client element supports a special syntax that enables you to inject properties into an existing instance, as shown in the following XML fragment:

<beans ...>
  ...
  <jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort"
                createdFromAPI="true">
    <!-- Set jaxws:properties, and so on -->
    ...
  </jaxws:client>
  ...
</beans>

The special syntax for modifying an existing client proxy uses the following attributes:

Perform the following steps to configure the STSClient:

  1. Specify the ws-security.sts.client property on the client proxy. This property is used to reference an org.apache.cxf.ws.security.trust.STSClient instance, which is responsible for connecting to the STS. This property must be set, if the effective security policy contains an IssuedToken policy.

    Edit the WibbleClient.xml file from the wsdl_first_https/src/demo/hw_https/client directory. Add the following jaxws:client element as a child of the beans element:

  2. Create the STSClient bean as follows. Continue editing the WibbleClient.xml file. Add the following STSClient bean definition to the XML file as shown:

    <beans ...>
      ...
      <bean name="default.sts-client" 
        class="org.apache.cxf.ws.security.trust.STSClient">
        <constructor-arg ref="cxf"/>
        <property name="wsdlLocation" value="sts/wsdl/ws-trust-1.4-service.wsdl"/>
        <property name="serviceName" 
            value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceProvider"/>
        <property name="endpointName" 
            value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP"/>
      </bean>
      ...
    </beans>

    Notice how the STSClient constructor requires a reference to the root Bus object (identified by the string, cxf, in the constructor-arg element) and the wsdlLocation attribute points to the the client's copy of the STS WSDL contract.

  3. Secure the client-STS connection with SSL/TLS. Continue editing the WibbleClient.xml file. Add the following http:conduit element as a child of the beans element:

    Notice how the STSClient trust store is configured to use the sts/certs/stsstore.jks keystore file, enabling the STSClient to authenticate the remote STS.

    The name attribute of http:conduit follows the format, WSDLPortQName.http-conduit. Because WSDLPortQName matches the name of the STS WSDL port, these settings are automatically applied to the client proxy for the client-STS connection. For more details about the SSL/TLS security settings, see Security for HTTP-Compatible Bindings.

  4. Enable policy support and logging as follows. Continue editing the WibbleClient.xml file. Add the following cxf:bus element as a child of the beans element:

    <beans ...>
      ...
      <cxf:bus xmlns:cxf="http://cxf.apache.org/core">
         <cxf:features>
            <p:policies xmlns:p="http://cxf.apache.org/policy"/>
            <cxf:logging/>
         </cxf:features>
      </cxf:bus>
      ...
    </beans> 

    Note

    It is essential to include the <p:policies> feature in the client's XML configuration. Otherwise, the policies in the WSDL file would have no effect whatsoever.

  5. Add the requisite XML schema locations. Continue editing the WibbleClient.xml file. To support the jaxws, cxf, and p namespace prefixes, add the highlighted schema locations and define the jaxws namespace prefix, as follows:

    <beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:sec="http://cxf.apache.org/configuration/security"
      xmlns:http="http://cxf.apache.org/transports/http/configuration"
      xmlns:jaxws="http://cxf.apache.org/jaxws"
      xsi:schemaLocation="
           http://cxf.apache.org/configuration/security
           http://cxf.apache.org/schemas/configuration/security.xsd
           http://cxf.apache.org/transports/http/configuration
           http://cxf.apache.org/schemas/configuration/http-conf.xsd
           http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
           http://cxf.apache.org/policy http://cxf.apache.org/schemas/policy.xsd">
    ...
  6. Add the requisite Maven dependencies. In order to use WS-SecurityPolicy, you need to ensure that the requisite JARs are included on the classpath. For the Maven build system, this requires you to include additional dependencies in the POM file. Edit the wsdl_first_https/pom.xml file and add dependencies on the cxf-rt-ws-security artifact and on the cxf-rt-ws-policy artifact as highlighted in the following fragment:

    <project ...>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>org.apache.cxf</groupId>
                <artifactId>cxf-rt-ws-security</artifactId>
                <version>2.4.0-fuse-00-27</version>
            </dependency>
            <dependency>
                <groupId>org.apache.cxf</groupId>
                <artifactId>cxf-rt-ws-policy</artifactId>
                <version>2.4.0-fuse-00-27</version>
            </dependency>
        </dependencies>
    </project>

The underlying implementation of WS-Security and WS-Trust is provided by a set of WSS4J interceptors, based on the open source Apache WSS4J security toolkit. These interceptors are automatically installed into a server endpoint, if the endpoint is associated with a WS-SecurityPolicy policy in the server's WSDL file. In the absence of WSDL policies, it is also possible to install the WSS4J interceptors explicitly—see the WS-Security page.

In this example, the SAML token issued by the STS is signed by the STS certificate. The issued SAML token also declares the subject confirmation method to be bearer, which implies that the server should trust the bearer of the SAML token, only if the token's signature is confirmed.

Hence, the server must be configured so that it can confirm incoming signatures. The details of this type of configuration are given in Providing Encryption Keys and Signing Keys and, essentially, it consists of setting the ws-security.encryption.properties property in the relevant jaxws:endpoint element. Confusingly, although this property is named encryption, it is also used for confirming signatures. The ws-security.encryption.properties property accesses the STS certificate, which is used to confirm the token's signature.

Perform the following steps to configure the server-side interceptor:

  1. Comment out the Java code for instantiating the Web service endpoint (in this example, it is more convenient to instantiate the endpoint in XML, because it enables you to specify all of the endpoint's properties in one place).

    Edit the Server.java file from the wsdl_first_https/src/demo/hw_https/server directory. Look for the lines of Java code that instantiate the Web service endpoint (highlighted below) and enclose them between /* and */, so that the lines are commented out as shown.

    package demo.hw_https.server;
    ...
    public class Server {
    
        protected Server() throws Exception {
            System.out.println("Starting Server");
    
            SpringBusFactory bf = new SpringBusFactory();
            URL busFile = Server.class.getResource("CherryServer.xml");
            Bus bus = bf.createBus(busFile.toString());
            bf.setDefaultBus(bus);
    
    	/*
            Object implementor = new GreeterImpl();
            String address = "https://localhost:9001/SoapContext/SoapPort";
            Endpoint.publish(address, implementor);
    	*/
        }
        ...
  2. Create the Web service endpoint in XML. Edit the CherryServer.xml file from the wsdl_first_https/src/demo/hw_https/server directory. Add the following jaxws:endpoint element as a child of the beans element to instantiate the Web service endpoint.

    <beans ...>
      ...
      <jaxws:endpoint id="server"
        endpointName="s:SoapPort"
        serviceName="s:SOAPService"
        implementor="demo.hw_https.server.GreeterImpl"    
        address="https://localhost:9001/SoapContext/SoapPort"
        wsdlLocation="wsdl/hello_world_server.wsdl"
        xmlns:s="http://apache.org/hello_world_soap_http" >
        <jaxws:properties>
            <entry key="ws-security.encryption.properties" value="sts/sts.properties" />
        </jaxws:properties>
      </jaxws:endpoint>
      ...
    </beans>

    Notice how the wsdlLocation attribute points at the hello_world_server.wsdl file, which is the copy of the WSDL contract that excludes the IssuedToken policy. The ws-security.encryption.properties property points at the file, sts/sts.properties, which will be defined in a later step.

  3. Enable policy support and logging as follows. Continue editing the CherryServer.xml file. Add the following cxf:bus element as a child of the beans element:

    <beans ...>
      ...
      <cxf:bus xmlns:cxf="http://cxf.apache.org/core">
         <cxf:features>
            <p:policies xmlns:p="http://cxf.apache.org/policy"/>
            <cxf:logging/>
         </cxf:features>
      </cxf:bus>
      ...
    </beans> 
  4. Add the requisite XML schema locations. Continue editing the CherryServer.xml file. To support the jaxws and cxf namespace prefixes, add the highlighted schema locations and define the jaxws namespace prefix, as follows:

  5. Now define the sts.properties file, which specifies the WSS4J properties for accessing the STS certificate. In the wsdl_first_https/sts directory, use your favorite text editor to create the file, sts.properties, containing the following property settings:

    For more details on these WSS4J properties, see Providing Encryption Keys and Signing Keys.

  6. Add Maven instructions to copy the sts.properties file into the target/classes/sts directory (so that the sts.properties file gets included in the WAR package). Edit the pom.xml file from the wsdl_first_https/ directory and search for the copyxmlfiles target of the Maven antrun plug-in. Under configuration tasks, add the highlighted lines as shown in the following fragment:

    <project ...>
        ...
        <build>
            ...
            <plugins>
                <plugin>
                    <artifactId>maven-antrun-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>copyxmlfiles</id>
                            ...
                            <configuration>
                                <tasks>
                                    <copy file="${basedir}/src/demo/hw_https/server/CherryServer.xml" todir="${basedir}/target/classes/demo/hw_https/server" />
                                    <copy file="${basedir}/src/demo/hw_https/client/WibbleClient.xml" todir="${basedir}/target/classes/demo/hw_https/client" />
                                    <copy file="${basedir}/src/demo/hw_https/client/InsecureClient.xml" todir="${basedir}/target/classes/demo/hw_https/client" />
                                    <copy todir="${basedir}/target/classes/certs">
                                        <fileset dir="${basedir}/certs" />
                                    </copy>
                                    <copy todir="${basedir}/target/classes/sts">
                                        <fileset dir="${basedir}/sts" />
                                    </copy>
                                </tasks>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
        ...
    </project>

    Note

    This step is only necessary, because this wsdl_first_https Maven project is set up in a slightly unconventional way. Normally, in a Maven project, you put all of your resource files under src/main/resources/, which Maven automatically copies into the target package.

The security token service sends back the following RequestSecurityTokenResponse (RSTR) message, containing a signed SAML token, saml2:Assertion, back to the client:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <RequestSecurityTokenResponseCollection
            xmlns="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
            xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            xmlns:ns3="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:ns4="http://www.w3.org/2005/08/addressing">
            <RequestSecurityTokenResponse>
                <TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</TokenType>
                <RequestedSecurityToken>
                    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                        ID="_181835fb981efecaf71d80ecd5fc3c74"
                        IssueInstant="2011-05-09T09:36:37.359Z" Version="2.0">
                        <saml2:Issuer>http://www.sopera.de/SAML2</saml2:Issuer>
                        <saml2:Subject>
                            <saml2:NameID
                                Format="urn:oasis:names:tc:SAML:1.1:nameid-format:transient"/>
                            <saml2:SubjectConfirmation
                                Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/>
                        </saml2:Subject>
                        <saml2:Conditions NotBefore="2011-05-09T08:36:37.359Z"
                            NotOnOrAfter="2011-05-09T10:36:37.359Z"/>
                        <saml2:AuthnStatement AuthnInstant="2011-05-09T09:36:37.515Z">
                            <saml2:AuthnContext>
                                <saml2:AuthnContextClassRef>ac:classes:X509</saml2:AuthnContextClassRef>
                            </saml2:AuthnContext>
                        </saml2:AuthnStatement>
                        <Signature:Signature xmlns:Signature="http://www.w3.org/2000/09/xmldsig#"
                            xmlns="http://www.w3.org/2000/09/xmldsig#">
                            <SignedInfo>
                                <CanonicalizationMethod
                                    Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                                <SignatureMethod
                                    Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                                <Reference URI="#_181835fb981efecaf71d80ecd5fc3c74">
                                    <Transforms>
                                        <Transform
                                            Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                                        <Transform
                                            Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                                    </Transforms>
                                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                                    <DigestValue>Gpzf8TjPATPsQDAm2ojNdEpht1A=</DigestValue>
                                </Reference>
                            </SignedInfo>
                            <SignatureValue>jsbIP1Z25q4Qedn6OSid4QcV4cs6+lgwB+jDiImwMMEoyzp1BjWQWB+1SIbHfa9rtmmTszLdmeTqxSXiAy2CeVZcIDk1UAfySAhDrrmR5N6lJMJqsQgU4o1ysLsZMKwtR2FL+eya7hJ9e4UtQVH1KOa7Cx1rvl4Dr8u8FuN5Myg=</SignatureValue>
                            <KeyInfo>
                                <X509Data>
                                    <X509SubjectName>1.2.840.113549.1.9.1=#160b737473407374732e636f6d,CN=www.sts.com,OU=IT
                                        Department,O=Sample STS -- NOT FOR
                                        PRODUCTION,L=Baltimore,ST=Maryland,C=US</X509SubjectName>
                                    <X509Certificate>MIID5jCCA0+gAwIBAgIJAPahVdM2UPibMA0GCSqGSIb3DQEBBQUAMIGpMQswCQYDVQQGEwJVUzER
                                        MA8GA1UECBMITWFyeWxhbmQxEjAQBgNVBAcTCUJhbHRpbW9yZTEpMCcGA1UEChMgU2FtcGxlIFNU
                                        UyAtLSBOT1QgRk9SIFBST0RVQ1RJT04xFjAUBgNVBAsTDUlUIERlcGFydG1lbnQxFDASBgNVBAMT
                                        C3d3dy5zdHMuY29tMRowGAYJKoZIhvcNAQkBFgtzdHNAc3RzLmNvbTAeFw0xMTAyMDkxODM4MTNa
                                        Fw0yMTAyMDYxODM4MTNaMIGpMQswCQYDVQQGEwJVUzERMA8GA1UECBMITWFyeWxhbmQxEjAQBgNV
                                        BAcTCUJhbHRpbW9yZTEpMCcGA1UEChMgU2FtcGxlIFNUUyAtLSBOT1QgRk9SIFBST0RVQ1RJT04x
                                        FjAUBgNVBAsTDUlUIERlcGFydG1lbnQxFDASBgNVBAMTC3d3dy5zdHMuY29tMRowGAYJKoZIhvcN
                                        AQkBFgtzdHNAc3RzLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAo+f8gs4WcteLdSPW
                                        Pm8+ciyEz7zVmA7kcCGFQQvlO0smxRViWJ1x+yniT5Uu86UrAQjxRJyANBomQrirfE7KPrnCm6iV
                                        OsGDEntuIZAf7DFPnrv5p++jAZQuR3vm4ZHXFOFTXmI+/FD5AqLfNi17xiTxZCDYyDdD39CNFTrB
                                        2PkCAwEAAaOCARIwggEOMB0GA1UdDgQWBBRa0A38holQIbJMFW7m5ZSw+iVDHDCB3gYDVR0jBIHW
                                        MIHTgBRa0A38holQIbJMFW7m5ZSw+iVDHKGBr6SBrDCBqTELMAkGA1UEBhMCVVMxETAPBgNVBAgT
                                        CE1hcnlsYW5kMRIwEAYDVQQHEwlCYWx0aW1vcmUxKTAnBgNVBAoTIFNhbXBsZSBTVFMgLS0gTk9U
                                        IEZPUiBQUk9EVUNUSU9OMRYwFAYDVQQLEw1JVCBEZXBhcnRtZW50MRQwEgYDVQQDEwt3d3cuc3Rz
                                        LmNvbTEaMBgGCSqGSIb3DQEJARYLc3RzQHN0cy5jb22CCQD2oVXTNlD4mzAMBgNVHRMEBTADAQH/
                                        MA0GCSqGSIb3DQEBBQUAA4GBACp9yK1I9r++pyFT0yrcaV1m1Sub6urJH+GxQLBaTnTsaPLuzq2g
                                        IsJHpwk5XggB+IDe69iKKeb74Vt8aOe5usIWVASgi9ckqCwdfTqYu6KG9BlezqHZdExnIG2v/cD/
                                        3NkKr7O/a7DjlbE6FZ4G1nrOfVJkjmeAa6txtYm1Dm/f</X509Certificate>
                                </X509Data>
                            </KeyInfo>
                        </Signature:Signature>
                    </saml2:Assertion>
                </RequestedSecurityToken>
                <RequestedAttachedReference>
                    <ns3:SecurityTokenReference>
                        <ns3:KeyIdentifier>_181835fb981efecaf71d80ecd5fc3c74</ns3:KeyIdentifier>
                    </ns3:SecurityTokenReference>
                </RequestedAttachedReference>
                <RequestedUnattachedReference>
                    <ns3:SecurityTokenReference>
                        <ns3:KeyIdentifier>_181835fb981efecaf71d80ecd5fc3c74</ns3:KeyIdentifier>
                    </ns3:SecurityTokenReference>
                </RequestedUnattachedReference>
            </RequestSecurityTokenResponse>
        </RequestSecurityTokenResponseCollection>
    </soap:Body>
</soap:Envelope>

The client now embeds the signed SAML token, saml2:Assertion, in the WS-Security header, wsse:Security, when it invokes the greetMe operation on the server:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
        <wsse:Security
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            soap:mustUnderstand="1">
            <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                ID="_181835fb981efecaf71d80ecd5fc3c74" IssueInstant="2011-05-09T09:36:37.359Z"
                Version="2.0">
                <saml2:Issuer>http://www.sopera.de/SAML2</saml2:Issuer>
                <saml2:Subject>
                    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:transient"/>
                    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/>
                </saml2:Subject>
                <saml2:Conditions NotBefore="2011-05-09T08:36:37.359Z"
                    NotOnOrAfter="2011-05-09T10:36:37.359Z"/>
                <saml2:AuthnStatement AuthnInstant="2011-05-09T09:36:37.515Z">
                    <saml2:AuthnContext>
                        <saml2:AuthnContextClassRef>ac:classes:X509</saml2:AuthnContextClassRef>
                    </saml2:AuthnContext>
                </saml2:AuthnStatement>
                <Signature:Signature xmlns="http://www.w3.org/2000/09/xmldsig#"
                    xmlns:Signature="http://www.w3.org/2000/09/xmldsig#">
                    <SignedInfo>
                        <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                        <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                        <Reference URI="#_181835fb981efecaf71d80ecd5fc3c74">
                            <Transforms>
                                <Transform
                                    Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                            </Transforms>
                            <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                            <DigestValue>Gpzf8TjPATPsQDAm2ojNdEpht1A=</DigestValue>
                        </Reference>
                    </SignedInfo>
                    <SignatureValue>jsbIP1Z25q4Qedn6OSid4QcV4cs6+lgwB+jDiImwMMEoyzp1BjWQWB+1SIbHfa9rtmmTszLdmeTqxSXiAy2CeVZcIDk1UAfySAhDrrmR5N6lJMJqsQgU4o1ysLsZMKwtR2FL+eya7hJ9e4UtQVH1KOa7Cx1rvl4Dr8u8FuN5Myg=</SignatureValue>
                    <KeyInfo>
                        <X509Data>
                            <X509SubjectName>1.2.840.113549.1.9.1=#160b737473407374732e636f6d,CN=www.sts.com,OU=IT
                                Department,O=Sample STS -- NOT FOR
                                PRODUCTION,L=Baltimore,ST=Maryland,C=US</X509SubjectName>
                            <X509Certificate>MIID5jCCA0+gAwIBAgIJAPahVdM2UPibMA0GCSqGSIb3DQEBBQUAMIGpMQswCQYDVQQGEwJVUzER
                                MA8GA1UECBMITWFyeWxhbmQxEjAQBgNVBAcTCUJhbHRpbW9yZTEpMCcGA1UEChMgU2FtcGxlIFNU
                                UyAtLSBOT1QgRk9SIFBST0RVQ1RJT04xFjAUBgNVBAsTDUlUIERlcGFydG1lbnQxFDASBgNVBAMT
                                C3d3dy5zdHMuY29tMRowGAYJKoZIhvcNAQkBFgtzdHNAc3RzLmNvbTAeFw0xMTAyMDkxODM4MTNa
                                Fw0yMTAyMDYxODM4MTNaMIGpMQswCQYDVQQGEwJVUzERMA8GA1UECBMITWFyeWxhbmQxEjAQBgNV
                                BAcTCUJhbHRpbW9yZTEpMCcGA1UEChMgU2FtcGxlIFNUUyAtLSBOT1QgRk9SIFBST0RVQ1RJT04x
                                FjAUBgNVBAsTDUlUIERlcGFydG1lbnQxFDASBgNVBAMTC3d3dy5zdHMuY29tMRowGAYJKoZIhvcN
                                AQkBFgtzdHNAc3RzLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAo+f8gs4WcteLdSPW
                                Pm8+ciyEz7zVmA7kcCGFQQvlO0smxRViWJ1x+yniT5Uu86UrAQjxRJyANBomQrirfE7KPrnCm6iV
                                OsGDEntuIZAf7DFPnrv5p++jAZQuR3vm4ZHXFOFTXmI+/FD5AqLfNi17xiTxZCDYyDdD39CNFTrB
                                2PkCAwEAAaOCARIwggEOMB0GA1UdDgQWBBRa0A38holQIbJMFW7m5ZSw+iVDHDCB3gYDVR0jBIHW
                                MIHTgBRa0A38holQIbJMFW7m5ZSw+iVDHKGBr6SBrDCBqTELMAkGA1UEBhMCVVMxETAPBgNVBAgT
                                CE1hcnlsYW5kMRIwEAYDVQQHEwlCYWx0aW1vcmUxKTAnBgNVBAoTIFNhbXBsZSBTVFMgLS0gTk9U
                                IEZPUiBQUk9EVUNUSU9OMRYwFAYDVQQLEw1JVCBEZXBhcnRtZW50MRQwEgYDVQQDEwt3d3cuc3Rz
                                LmNvbTEaMBgGCSqGSIb3DQEJARYLc3RzQHN0cy5jb22CCQD2oVXTNlD4mzAMBgNVHRMEBTADAQH/
                                MA0GCSqGSIb3DQEBBQUAA4GBACp9yK1I9r++pyFT0yrcaV1m1Sub6urJH+GxQLBaTnTsaPLuzq2g
                                IsJHpwk5XggB+IDe69iKKeb74Vt8aOe5usIWVASgi9ckqCwdfTqYu6KG9BlezqHZdExnIG2v/cD/
                                3NkKr7O/a7DjlbE6FZ4G1nrOfVJkjmeAa6txtYm1Dm/f</X509Certificate>
                        </X509Data>
                    </KeyInfo>
                </Signature:Signature>
            </saml2:Assertion>
        </wsse:Security>
    </soap:Header>
    <soap:Body>
        <greetMe xmlns="http://apache.org/hello_world_soap_http/types">
            <requestType>JBLOGGS</requestType>
        </greetMe>
    </soap:Body>
</soap:Envelope>

An IssuedToken policy is specified using the following XML elements:

sp:IssuedToken

The element containing the IssuedToken policy assertion. The IncludeToken attribute specifies whether the issued token is meant to be included in the security header of the client's request messages. The allowed values of this attribute are given in sp:IncludeToken attribute.

On the client side, the presence of this assertion signals that the client should attempt to obtain a token by contacting a remote STS.

sp:IssuedToken/sp:Issuer

(Optional) Contains a reference to the issuer of the token, of wsa:EndpointReferenceType type.

There is no need to specify the issuer's endpoint reference using sp:Issuer in Fuse Services Framework, because the issuer endpoint (that is, the STS address) is taken directly from the STS WSDL file instead. See Step 2.

sp:IssuedToken/sp:IssuerName

(Optional) The name of the issuing service (that is, the STS), in the format of a URI.

sp:IssuedToken/wst:Claims

(Optional) Specifies the required claims that the issued token must contain in order to satisfy the IssuedToken policy assertion.

sp:IssuedToken/sp:RequestSecurityTokenTemplate

(Required) This element contains a list of WS-Trust policy assertions to be included in the outgoing RequestSecurityToken (RST) message that is sent to the STS. In other words, this element enables you to modify the Issue query that is sent to the STS to obtain the issued token. Thie element can contain any of the WS-Trust assertions that are valid children of the sp:RequestSecurityToken element, as specified by WS-Trust.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:TokenType

(Optional) The type of security token to issue, specified as a URI string. Although theoretically optional, this assertion is almost always specified. Table 8.2 shows the list of standard token type URIs for the following token types: SAML 1.1, SAML 2.0, UsernameToken, X.509v3 single certificate, X509v1 single certificate, X.509 PKI certificate chain, X.509 PKCS7, and Kerberos.


Consult the documentation for your third-party STS to find out what token types it supports. An STS can also support custom token types not listed in the preceding table.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wsp:AppliesTo

(Optional) This WS-PolicyAttachment assertion can be specified as an alternative to or in addition to the wst:TokenType assertion (in the latter case, it takes precedence over the wst:TokenType assertion). It is used to specify the policy scope for which this token is required. In practice, this enables you to refer to a service or group of services for which this token is issued. The STS can then be configured to specify what kind of token to issue for that service (or services).

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:OtherElements

(Optional) You can optionally include many other WS-Trust assertions in the RST template. The purpose of these assertions is to specify exactly what the content of the issued token should be and whether it is signed, encrypted, and so on. In practice, however, the details of the issued token are often configured in the STS, which makes it unnecessary to include all of these details in the RST template.

For a full list of of WS-Trust assertions that can be included in the RST template, see the OASIS WS-Trust 1.4 Specification.

sp:IssuedToken/sp:Policy

(Required) This element must be included in the IssuedToken, even if it is empty.

sp:IssuedToken/sp:Policy/sp:RequireDerivedKeys

(Optional) Only applicable when using WS-SecureConversation. The WS-SecureConversation specification enables you to establish a security context (analogous to a session), which is used for sending multiple secured messages to a given service. Normally, if you use the straightforward approach of authenticating every message sent to a particular service, the authentication adds a considerable overhead to secure communications. If you know in advance that a client will be sending multiple messages to a Web service, however, it makes sense to establish a security context between the client and the server, in order to cut the overheads of secure communication. This is the basic idea of WS-SecureConversation.

When a security context is established, the client and the server normally establish a shared secret. In order to prevent the shared secret being discovered, it is better to avoid using the shared secret directly and use it instead to generate the keys needed for encryption, signing, and so on—that is, to generate derived keys.

When the sp:RequireDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation and both implied derived keys and explicit derived keys are allowed.

Note

Only one of sp:RequireDerivedKeys, sp:RequireImpliedDerivedKeys, or sp:RequireExplicitDerivedKeys, can be included in sp:IssuedToken.

sp:IssuedToken/sp:Policy/sp:RequireImpliedDerivedKeys

(Optional) When the sp:RequireImpliedDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only implied derived keys are allowed.

sp:IssuedToken/sp:Policy/sp:RequireExplicitDerivedKeys

(Optional) When the sp:RequireExplicitDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only explicit derived keys are allowed.

sp:IssuedToken/sp:Policy/sp:RequireExternalReference

(Optional) When included, requires that external references to the issued token must be enabled.

sp:IssuedToken/sp:Policy/sp:RequireInternalReference

(Optional) When included, requires that internal references to the issued token must be enabled, where an internal reference uses one of the elements, wsse:Reference, wsse:KeyIdentifier, or wsse:Embedded.

In the case of indirect configuration, there is no need to set any property on the JAX-WS client proxy. Implicitly, if the IssuedToken policy assertion is applied to the relevant WSDL port, the runtime automatically searches for an STSClient bean named, WSDLPortQName.sts-client. To configure the STSClient bean indrectly, perform the following steps:

For example, the following XML configuration creates a JAX-WS client proxy, which is associated with the {http://apache.org/hello_world_soap_http}SoapPort port (this is specified in an annotation on the service class, Greeter). When the client proxy needs to fetch an issued token for the first time, the runtime automatically creates an STSClient instance, searches for the bean named WSDLPortQName.sts-client, and injects the properties from that bean into the STSClient instance.

<beans ...>
  ...
  <jaxws:client
    id="helloWorldProxy"
    serviceClass="org.apache.hello_world_soap_http.Greeter"
    address="https://localhost:9001/SoapContext/SoapPort"
    />
  ...
  <bean name="{http://apache.org/hello_world_soap_http}SoapPort.sts-client" 
    class="org.apache.cxf.ws.security.trust.STSClient"
    abstract="true">
    <constructor-arg ref="cxf"/>
    <property name="wsdlLocation" value="sts/wsdl/ws-trust-1.4-service.wsdl"/>
    <property name="serviceName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceProvider"/>
    <property name="endpointName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP"/>
  </bean>
  ...
</beans>

This section describes a version of the openssl program that is available with Eric Young’s OpenSSL package, which can be downloaded from the OpenSSL Web site, http://www.openssl.org. OpenSSL is a publicly available implementation of the SSL protocol. Consult Appendix C for information about the copyright terms of OpenSSL.

Note

For complete documentation of the OpenSSL utilities, consult the documentation at the OpenSSL web site http://www.openssl.org/docs.

This appendix describes the following openssl utilities:

x509Manipulates X.509 certificates.
reqCreates and manipulates certificate signing requests, and self-signed certificates.
rsaManipulates RSA private keys.
caImplements a Certification Authority (CA).
s_clientImplements a generic SSL/TLS client.
s_serverImplements a generic SSL/TLS server.

The options supported by the openssl x509 utility are as follows:

-inform arg

- input format - default PEM (one of DER, NET or PEM)

-outform arg

- output format - default PEM (one of DER, NET or PEM

-keyform arg

- private key format - default PEM

-CAform arg

- CA format - default PEM

-CAkeyform arg

- CA key format - default PEM

-in arg

- input file - default stdin

-out arg

- output file - default stdout

-serial

- print serial number value

-hash

- print serial number value

-subject

- print subject DN

-issuer

- print issuer DN

-startdate

- notBefore field

-enddate

- notAfter field

-dates

- both Before and After dates

-modulus

- print the RSA key modulus

-fingerprint

- print the certificate fingerprint

-noout

- no certificate output

-days arg

- Time till expiry of a signed certificate - def 30 days

-signkey arg

- self sign cert with arg

-x509toreq

- output a certification request object

-req

- input is a certificate request, sign and output

-CA arg

- set the CA certificate, must be PEM format

-CAkey arg

- set the CA key, must be PEM format. If missing it is assumed to be in the CA file

-CAcreateserial

- create serial number file if it does not exist

-CAserial

- serial file

-text

- print the certificate in text form

-C

- print out C code forms

-md2/-md5/-sha1/ -mdc2- digest algorithm used when signing certificates

The options supported by the openssl req utility are as follows:

-inform arg

input format - one of DER TXT PEM

-outform

arg output format - one of DER TXT PEM

-in arg

inout file

-out arg

output file

-text

text form of request

-noout

do not output REQ

-verify

verify signature on REQ

-modulus

RSA modulus

-nodes

do not encrypt the output key

-key file

use the private key contained in file

-keyform arg

key file format

-keyout arg

file to send the key to

-newkey rsa:bits

generate a new RSA key of ‘bits’ in size

-newkey dsa:file

generate a new DSA key, parameters taken from CA in ‘file’

-[digest]

Digest to sign with (md5, sha1, md2, mdc2)

-config file

request template file

-new

new request

-x509

output an x509 structure instead of a certificate req. (Used for creating self signed certificates)

-days

number of days an x509 generated by -x509 is valid for

-asn1-kludge

by default, the req command generates the correct PKCS#10 format for certificate requests that contain no attributes. However, certain CAs only accept requests containing no attributes in an invalid form: this option produces this invalid format.

The options supported by the openssl rsa utility are as follows:

-inform arg

input format - one of DER NET PEM

-outform arg

output format - one of DER NET PEM

-in arg

inout file

-out arg

output file

-des

encrypt PEM output with cbc des

-des3

encrypt PEM output with ede cbc des using 168 bit key

-text

print the key in text

-noout

do not print key out

-modulus

print the RSA key modulus

The options supported by the openssl ca utility are as follows:

-verbose

- Talk alot while doing things

-config file

- A config file

-name arg

- The particular CA definition to use

-gencrl

- Generate a new CRL

-crldays days

- Days is when the next CRL is due

-crlhours hours

- Hours is when the next CRL is due

-days arg

- number of days to certify the certificate for

-md arg

- md to use, one of md2, md5, sha or sha1

-policy arg

- The CA ‘policy’ to support

-keyfile arg

- PEM private key file

-key arg

- key to decode the private key if it is encrypted

-cert

- The CA certificate

-in file

- The input PEM encoded certificate request(s)

-out file

- Where to put the output file(s)

-outdir dir

- Where to put output certificates

-infiles....

- The last argument, requests to process

-spkac file

- File contains DN and signed public key and challenge

-preserveDN

- Do not re-order the DN

-batch

- Do not ask questions

-msie_hack

- msie modifications to handle all thos universal strings

Most of the above parameters have default values as defined in openssl.cnf.

The options supported by the openssl s_client utility are as follows:

-connect host[:port]

- Specify the host and (optionally) port to connect to. Default is local host and port 4433.

-cert certname

- Specifies the certificate to use, if one is requested by the server.

-certform format

- The certificate format, which can be either PEM or DER. Default is PEM.

-key keyfile

- File containing the client’s private key. Default is to extract the key from the client certificate.

-keyform format

- The private key format, which can be either PEM or DER. Default is PEM.

-pass arg

- The private key password.

-verify depth

- Maximum server certificate chain length.

-CApath directory

- Directory to use for server certificate verification.

-CAfile file

- File containing trusted CA certificates.

-reconnect

- Reconnects to the same server five times using the same session ID.

-pause

- Pauses for one second between each read and write call.

-showcerts

- Display the whole server certificate chain.

-prexit

- Print session information when the program exits.

-state

- Prints out the SSL session states.

-debug

- Log debug data, including hex dump of messages.

-msg

- Show all protocol messages with hex dump.

-nbio_test

- Tests non-blocking I/O.

-nbio

- Turns on non-blocking I/O.

-crlf

- Translates a line feed (LF) from the terminal into CR+LF, as required by some servers.

-ign_eof

- Inhibits shutting down the connection when end of file is reached in the input.

-quiet

- Inhibits printing of session and certificate information; implicitly turns on -ign_eof as well.

-ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1

- These options enable/disable the use of certain SSL or TLS protocols.

-bugs

- Enables workarounds to several known bugs in SSL and TLS implementations.

-cipher cipherlist

- Specifies the cipher list sent by the client. The server should use the first supported cipher from the list sent by the client.

-starttls protocol

- Send the protocol-specific message(s) to switch to TLS for communication, where the protocol can be either smtp or pop3.

-engine id

- Specifies an engine, by it's unique id string.

-rand file(s)

- A file or files containing random data used to seed the random number generator, or an EGD socket. The file separator is ; for MS-Windows, , for OpenVMS, and : for all other platforms.

The options supported by the openssl s_server utility are as follows:

-accept port

- Specifies the IP port to listen for incoming connections. Default is port 4433.

-context id

- Sets the SSL context id (any string value).

-cert certname

- Specifies the certificate to use for the server.

-certform format

- The certificate format, which can be either PEM or DER. Default is PEM.

-key keyfile

- File containing the server’s private key. Default is to extract the key from the server certificate.

-keyform format

- The private key format, which can be either PEM or DER. Default is PEM.

-pass arg

- The private key password.

-dcert filename, -dkey keyname

- Specifies an additional certificate and private key, enabling the server to have multiple credentials.

-dcertform format, -dkeyform format, -dpass arg

- Specifies additional certificate format, private key format, and passphrase respectively.

-nocert

- If this option is set, no certificate is used.

-dhparam filename

- The DH parameter file to use.

-no_dhe

- If this option is set, no DH parameters will be loaded, effectively disabling the ephemeral DH cipher suites.

-no_tmp_rsa

- Certain export cipher suites sometimes use a temporary RSA key. This option disables temporary RSA key generation.

-verify depth, -Verify depth

- Maximum client certificate chain length. With the -Verify option, the client must supply a certificate or an error occurs.

-CApath directory

- Directory to use for client certificate verification.

-CAfile file

- File containing trusted CA certificates.

-state

- Prints out the SSL session states.

-debug

- Log debug data, including hex dump of messages.

-msg

- Show all protocol messages with hex dump.

-nbio_test

- Tests non-blocking I/O.

-nbio

- Turns on non-blocking I/O.

-crlf

- Translates a line feed (LF) from the terminal into CR+LF, as required by some servers.

-quiet

- Inhibits printing of session and certificate information; implicitly turns on -ign_eof as well.

-ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1

- These options enable/disable the use of certain SSL or TLS protocols.

-bugs

- Enables workarounds to several known bugs in SSL and TLS implementations.

-hack

- Enables a further workaround for some some early Netscape SSL code.

-cipher cipherlist

- Specifies the cipher list sent by the client. The server should use the first supported cipher from the list sent by the client.

-www

- Sends a status message back to the client when it connects. The status message is in HTML format.

-WWW

- Emulates a simple web server, where pages are resolved relative to the current directory.

-HTTP

- Emulates a simple web server, where pages are resolved relative to the current directory.

-engine id

- Specifies an engine, by it's unique id string.

-id_prefix_arg

- Generate SSL/TLS session IDs prefixed by arg.

-rand file(s)

- A file or files containing random data used to seed the random number generator, or an EGD socket. The file separator is ; for MS-Windows, , for OpenVMS, and : for all other platforms.

When an SSL client is connected to the test server, you can enter any of the following single letter commands on the server side:

q

End the current SSL connection but still accept new connections.

Q

End the current SSL connection and exit.

r

Renegotiate the SSL session.

R

Renegotiate the SSL session and request a client certificate.

P

Send some plain text down the underlying TCP connection. This should cause the client to disconnect due to a protocol violation.

S

Print out some session cache status information.

The following shows the contents of an example openssl.cnf configuration file:

################################################################
# openssl example configuration file.
# This is mostly used for generation of certificate requests.
#################################################################
[ ca ]
default_ca= CA_default # The default ca section
#################################################################

[ CA_default ]
dir=/opt/iona/OrbixSSL1.0c/certs # Where everything is kept

certs=$dir # Where the issued certs are kept
crl_dir= $dir/crl # Where the issued crl are kept
database= $dir/index.txt # database index file
new_certs_dir= $dir/new_certs # default place for new certs
certificate=$dir/CA/OrbixCA # The CA certificate
serial= $dir/serial # The current serial number
crl= $dir/crl.pem # The current CRL
private_key= $dir/CA/OrbixCA.pk # The private key
RANDFILE= $dir/.rand # private random number file
default_days= 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md= md5 # which message digest to use
preserve= no # keep passed DN ordering

# A few different ways of specifying how closely the request should
# conform to the details of the CA

policy= policy_match 

# For the CA policy

[policy_match]
countryName= match
stateOrProvinceName= match
organizationName= match
organizationalUnitName= optional
commonName= supplied
emailAddress= optional

# For the ‘anything’ policy
# At this point in time, you must list all acceptable ‘object’
# types

[ policy_anything ]
countryName = optional
stateOrProvinceName= optional
localityName= optional
organizationName = optional
organizationalUnitName = optional
commonName= supplied
emailAddress= optional

[ req ]
default_bits = 1024
default_keyfile= privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes

[ req_distinguished_name ]
countryName= Country Name (2 letter code)
countryName_min= 2
countryName_max = 2
stateOrProvinceName= State or Province Name (full name)
localityName = Locality Name (eg, city)
organizationName = Organization Name (eg, company)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (eg. YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 40

[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
unstructuredName= An optional company name

The licence agreement for using the OpenSSL command line utility shipped with Fuse Services Framework SSL/TLS is as follows:

LICENSE ISSUES
==============
  The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
  the OpenSSL License and the original SSLeay license apply to the toolkit.
  See below for the actual license texts. Actually both licenses are BSD-style
  Open Source licenses. In case of any license issues related to OpenSSL
  please contact openssl-core@openssl.org.

  OpenSSL License
  ---------------

/* ========================================================
* Copyright (c) 1998-1999 The OpenSSL Project.  All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
*    notice, this list of conditions and the following disclaimer. 
*
* 2. Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in
*    the documentation and/or other materials provided with the
*    distribution.
*
* 3. All advertising materials mentioning features or use of this
*    software must display the following acknowledgment:
*    "This product includes software developed by the OpenSSL Project
*    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
*    endorse or promote products derived from this software without
*    prior written permission. For written permission, please contact
*    openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
*    nor may "OpenSSL" appear in their names without prior written
*    permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
*    acknowledgment:
*    "This product includes software developed by the OpenSSL Project
*    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* =========================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com).  This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/

Original SSLeay License
-----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.

* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to.  The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code.  The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).

* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.

* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the copyright
*    notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in the
*    documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
*    must display the following acknowledgement:
*    "This product includes cryptographic software written by
*     Eric Young (eay@cryptsoft.com)"
*    The word 'cryptographic' can be left out if the rouines from the library
*    being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof) from 
*    the apps directory (application code) you must include an acknowledgement:
*    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"

* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.

* The licence and distribution terms for any publically available version or
* derivative of this code cannot be changed.  i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/

A

Abstract Syntax Notation One (see ASN.1)
administration
OpenSSL command-line utilities, OpenSSL utilities
ASN.1, The contents of an X.509 certificate, ASN.1 and Distinguished Names
attribute types, Attribute types
AVA, AVA
OID, OID
ASN.1:
RDN, RDN
attribute value assertion, AVA
authentication
own certificate, specifying, Specifying an Application’s Own Certificate
SSL/TLS, Overview
mutual, Overview
trusted CA list, Overview
AVA, AVA

B

Basic Encoding Rules (see BER)
BER, BER

C

CA, Integrity of the public key
choosing a host, Choosing a host for a private certification authority
commercial CAs, Commercial Certification Authorities
index file, Initialize the CA database
list of trusted, Trusted CAs
multiple CAs, Certificates signed by multiple CAs
private CAs, Private Certification Authorities
private key, creating, Create a self-signed CA certificate and private key
security precautions, Security precautions
self-signed, Create a self-signed CA certificate and private key
serial file, Initialize the CA database
trusted list, Overview
ca utility, The ca Utility
CA, setting up, Substeps to perform
CAs, Substeps to perform
certificate signing request, Create a certificate signing request, Create a certificate signing request
signing, Sign the CSR, Sign the CSR
certificates
chaining, Certificate chain
creating and signing, Substeps to perform
importing and exporting, Importing and exporting PKCS#12 files
own, specifying, Specifying an Application’s Own Certificate
peer, Chain of trust
PKCS#12 file, Contents of a PKCS#12 file
public key, The contents of an X.509 certificate
security handshake, Security handshake, Security handshake
self-signed, Self-signed certificate, Create a self-signed CA certificate and private key
signing, Integrity of the public key, Sign the CSR, Sign the CSR
signing request, Create a certificate signing request, Create a certificate signing request
trusted CA list, Overview
X.509, Role of certificates
chaining of certificates, Certificate chain
configuration file, The OpenSSL Configuration File
CSR, Create a certificate signing request, Create a certificate signing request

D

DER, DER
Distinguished Encoding Rules (see DER)
distinguished names
definition, Overview
DN
definition, Overview
string representation, String representation of DN

M

multiple CAs, Certificates signed by multiple CAs
mutual authentication, Overview

O

OpenSSL, OpenSSL software package
openSSL
configuration file, The OpenSSL Configuration File
utilities, Using OpenSSL Utilities
OpenSSL command-line utilities, OpenSSL utilities
openSSL.cnf example file, Example openssl.cnf File

R

RDN, RDN
relative distinguished name, RDN
req utility, The req Utility
req Utility command, The req Utility
root certificate directory, Trusted CAs
rsa utility, The rsa Utility
rsa Utility command, The rsa Utility

T

target authentication, Overview
target only, Overview
trusted CA list policy, Overview
trusted CAs, Trusted CAs

X

X.500, ASN.1 and Distinguished Names
X.509 certificate
definition, Role of certificates
x509 utility, The x509 Utility