What is the XWS-Security Framework?

The XWS-Security framework is used to secure JAX-RPC and stand-alone SAAJ applications. Use XWS-Security to secure SOAP messages (requests and responses) through signing some parts, or encrypting some parts, or sending username-password authentication info, or some combination of these. Some example applications that use the technology are discussed in Are There Any Sample Applications Demonstrating XWS-Security?.

Use the XWS-Security framework to secure JAX-RPC applications by using the -security option of the wscompile tool. When you create an asant (or ant) target for JAX-RPC clients and services, the wscompile utility generates stubs, ties, serializers, and WSDL files.

Note: For the 2.0 release of JAX-RPC, JAX-RPC will be renamed to JAX-WS. JAX-WS will be part of the XWS-Security 2.0 FCS later this year. When this renaming occurs, the wscompile tool will be replaced, and these steps and the build.xml files for the sample applications will need to be modified accordingly.

XWS-Security has been integrated into JAX-RPC through the use of security configuration files. The code for performing the security operations on the client and server is generated by supplying the security configuration files to the JAX-RPC wscompile tool. The wscompile tool is instructed to generate security code via the -security option which specifies the security configuration file. See Configuring Security Configuration Files for more information on creating and using security configuration files.

To use the XWS-Security framework, set up the client and server-side infrastructure. A critical component of setting up your system for XWS-Security is to set up the appropriate database for the type of security (DSig, XML-Enc, UserName Token) to be used. Depending on the structure of your application, these databases could be any combination of keystore files, truststore files, and username-password files.

Configuring Security Configuration Files

XWS-Security makes it simple to specify client and server-side configurations describing security settings using security configuration files. In this tutorial, build, package, and deploy targets are defined and run using the asant tool. The asant tool is version of the Apache Ant Java-based build tool used specifically with the Sun Java System Application Server (Application Server). If you are deploying to a different container, you can use the Apache Ant tool instead.

To configure a security configuration file, follow these steps:

  1. Create a security configuration file. Creating security configuration files is discussed in more detail in Understanding Security Configuration Files. Sample security configuration files are located in the directory <JWSDP_HOME>/xws-security/samples/simple/config/.
  2. Create an asant (or ant) target in the build.xml file for your application that passes in and uses the security configuration file(s). This step is discussed in more detail in How Do I Specify the Security Configuration for the Build Files?
  3. Create a property in the build.properties file to specify a security configuration file to be used on the client side and a security configuration file to be used on the server side. This step is discussed in more detail in How Do I Specify the Security Configuration for the Build Files?

Understanding Security Configuration Files

Security configuration files are written in XML. The elements within the XML file that specify the security mechanism(s) to use for an application are enclosed within <xwss:SecurityConfiguration></xwss:SecurityConfiguration> tags. The complete set of child elements along with the attributes that can be placed within these elements are described informally in XWS-Security Configuration File Schema. The formal schema definition (XSD) for XWS-Security Configuration can be viewed in the appendix A XWS-Security Formal Schema Definition. Many example security configuration files, along with descriptions each, are described in Simple Sample Security Configuration Files. This section describes a few of these options.

If you are using XWS-Security under JAX-RPC, the first set of elements of the security configuration file contain the declaration that this file is a security configuration file. The elements that provide this declaration look like this: 

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">
   <xwss:Service>
      <xwss:SecurityConfiguration>

Note: If you are using XWS-Security in a stand-alone SAAJ environment, the root element of the security configuration file is <xwss:SecurityConfiguration>. An example application that uses XWS-Security in a stand-alone SAAJ environment is described in XWS-Security APIs Sample Application.

Within these declaration elements are elements that specify which type of security mechanism is to be applied to the SOAP message. For example, to apply XML Digital Signature, the security configuration file would include an xwss:Sign element, along with a keystore alias that identifies the private key/certificate associated with the sender's signature. A simple client security configuration file that requires digital signatures would look like this: 

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Note that in the <Sign> operation, a Timestamp is 
exported
              in the security header and signed by default.
            -->
            <xwss:Sign>
                <xwss:X509Token certificateAlias="xws-security-
client"/>
            </xwss:Sign>
            <!--
              Signature requirement. No target is specified, 
hence the 
              soap body is expected to be signed. Also, by 
default, a
              Timestamp is expected to be signed.
            -->
            <xwss:RequireSignature/>
        </xwss:SecurityConfiguration>
   </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>

The xwss elements can be listed sequentially so that more than one security mechanism can be applied to the SOAP message. For example, for a client to first sign a message and then encrypt it, create an xwss element with the value Sign (to do the signing first), and then create an xwss element with the value of Encrypt (to encrypt after the signing). Building on the previous example, to add encryption to the message after the message has been signed, the security configuration file would be written like this example: 

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Sign/>
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Identifier"/>
            </xwss:Encrypt>
            <!-- 
              Requirements on messages received:
            -->
            <xwss:RequireEncryption/>
            <xwss:RequireSignature/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>

The xwss:RequireSignature element present in the two examples shown is used by the client to indicate that it expects the Response to be a signed response. Similarly the xwss:RequireEncryption element in a client configuration file indicates that the client expects an encrypted response. In the second example, a RequireEncryption and a RequireSignature element specified in that order implies that the client expects the response to be signed and then encrypted.

The xwss:RequireSignature and xwss:RequireEncryption elements appearing in a server configuration file similarly indicate that the server expects the request to be signed and encrypted respectively. The normal behavior of a client or server when it specifies a requirement of the form xwss:RequireSignature or xwss:RequireEncryption is to throw an exception if the requirement is not met by the received response or request.

The xwss:SecurityEnvironmentHandler element appearing under xwss:SecurityConfiguration is a compulsory child element that needs to be specified. The value of this element is the name of a Java class that implements the javax.security.auth.callback.CallbackHandler interface and handles a set of Callbacks defined by XWS-Security. There are a set of callbacks that are mandatory and that every CallbackHandler needs to implement. A few callbacks are optional and can be used to supply some finer-grained information to the XWS-Security run-time. The SecurityEnvironmentHandler and the Callbacks are described in Writing SecurityEnvironmentHandlers. The SecurityEnvironmentHandler is essentially a CallbackHandler which is used by the XWS-Security run-time to obtain the private-keys, certificates, symmetric keys, etc. to be used in the signing and encryption operations from the application. For more information, refer to the API documentation for the com.sun.xml.wss.impl.callback package, which is located in the <JWSDP_HOME>/xws-security/docs/api directory, to find the list of mandatory and optional callbacks and the details of the Callback classes.

When XWS-Security is used in a stand-alone SAAJ environment, the developer can choose to implement the com.sun.xml.wss.SecurityEnvironment interface instead of a callback handler that handles XWS-Security callbacks. In this situation, an instance of the SecurityEnvironment implementation can be set into the ProcessingContext instance. For an example application that demonstrates this, refer to the XWS-Security APIs Sample Application. For more details on the SecurityEnvironment interface, refer to the javadocs at <JWSDP_HOME>/xws-security/docs/api/com/sun/xml/wss/SecurityEnvironment.html.

Another type of security mechanism that can be specified in the security configuration file is user name authentication. In the case of user name authentication, the user name and password of a client need to be authenticated against the user/password database of the server. The xwss element specifies that the security mechanism to use is UsernameToken. On the server-side, refer to the documentation for your server regarding how to set up a user/password database for the server, or read Setting Up To Use XWS-Security With the Sample Applications for a summary. A client-side security configuration file that specifies UsernameToken authentication would look like this: 

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Default: Digested password will be sent.
            -->
            <xwss:UsernameToken name="Ron" password="noR"/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>

The simple sample application includes a number of example security configuration files. The sample configuration files are located in the directory <JWSDP_HOME>/xws-security/samples/simple/config/. Further discussion of the example security configurations can be found in Simple Sample Security Configuration Files.

Other sample configuration files that are provided in this release include:

XWS-Security Configuration File Schema

When creating a security configuration file, there is a hierarchy within which the XML elements must be listed. This section contains an abstract sketch of the schema for the data for security configuration files. The formal schema definition can be viewed at A XWS-Security Formal Schema Definition.

Figure 4-1 shows the XML schema. The tables in Semantics of Security Configuration File Elements provide more information on the elements contained within the schema. The following notations are used to describe the schema:

Figure 4-1 XWS-Security Abstract Configuration File Schema 

<JAXRPCSecurity>
      +<Service/>
      <SecurityEnvironmentHandler/>
</JAXRPCSecurity>

 <Service ?name=service_identifier
            ?id=unique_identifier
            ?conformance="bsp" 
            ?useCache=("false") | "true">
      ?<SecurityConfiguration/>
      *<Port/>
      ?<SecurityEnvironmentHandler/>
</Service>

<SecurityConfiguration
            ?dumpMessages=("false")|"true" 
            ?enableDynamicPolicy=("false")|"true">
      *SecurityConfigurationElements
</SecurityConfiguration>

*SecurityConfigurationElements =  
      ?<Timestamp/> |
      ?<SAMLAssertion type="SV"/> |
      ?<RequireSAMLAssertion type="SV"/> |
      ?<UsernameToken/> |
      ?<RequireUsernameToken /> |
      ?<RequireTimestamp /> |
       ?<OptionalTargets /> |
      <Sign/> |
      <Encrypt/> |
      <RequireSignature/> |
      <RequireEncryption/> 

<Port name="port-name" ?conformance="bsp">
      *<Operation ?name="op-name">
            *<SecurityConfiguration/>
      </Operation>
</Port>

<SecurityEnvironmentHandler>
      handler-classname
</SecurityEnvironmentHandler>

<Operation name="operation_name" >
      *<SecurityConfiguration/>
</Operation>

<Timestamp ?id=unique_policy_identifier
            ?timeout=("300")/> 

<UsernameToken ?id=unique_policy_identifier
            ?name=user_name // User name and password can also 
be  
                                //obtained dynamically from the                  
                                //SecurityEnvironment
            ?password=password
            ?useNonce=("true")|"false"
            ?digestPassword=("true")|"false"/>

 <RequireUsernameToken 
            ?id=unique_policy_identifier
            ?nonceRequired=("true")|"false"
            ?passwordDigestRequired=("true")|"false"
            ?maxClockSkew=("60")
            ?timestampFreshnessLimit=("300")
            ?maxNonceAge=("900")/>

<Encrypt
      ?id=unique_policy_identifier >
      ?Key-Bearing-Token
      ?<KeyEncryptionMethod 
            algorithm=("http://www.w3.org/2001/04/xmlenc#rsa-
oaep-mgf1p")|
                        "http://www.w3.org/2001/04/xmlenc#kw-
tripledes"|
                        "http://www.w3.org/2001/04/xmlenc#kw-
aes128" |
                        "http://www.w3.org/2001/04/xmlenc#kw-
aes256" |
                        "http://www.w3.org/2001/04/xmlenc#rsa-
1_5" />
      ?<DataEncryptionMethod
            algorithm=("http://www.w3.org/2001/04/
xmlenc#aes128-cbc")|
                        "http://www.w3.org/2001/04/
xmlenc#tripledes-cbc"|
                        "http://www.w3.org/2001/04/
xmlenc#aes256-cbc" />
      *<Target/>  // of type Target or EncryptionTarget
</Encrypt>

<EncryptionTarget 
            ?type=("qname")|"uri"|"xpath"
            ?contentOnly=("true")|"false"
            ?enforce=("true")|"false"
            value=an_appropriate_ target_identifier>
      *<Transform/>
</EncryptionTarget>

<RequireEncryption
            ?id=unique_policy_identifier />
      ?Key-Bearing-Token
      ?<KeyEncryptionMethod 
            algorithm=("http://www.w3.org/2001/04/xmlenc#rsa-
oaep-mgf1p") |
                        "http://www.w3.org/2001/04/xmlenc#kw-
tripledes" |
                        "http://www.w3.org/2001/04/xmlenc#kw-
aes128" | 
                        "http://www.w3.org/2001/04/xmlenc#kw-
aes256" |
                        "http://www.w3.org/2001/04/xmlenc#rsa-
1_5" />
      ?<DataEncryptionMethod
            algorithm=("http://www.w3.org/2001/04/
xmlenc#aes128-cbc") |
                        "http://www.w3.org/2001/04/
xmlenc#tripledes-cbc" |
                        "http://www.w3.org/2001/04/
xmlenc#aes128-cbc" |
                        "http://www.w3.org/2001/04/
xmlenc#aes256-cbc" />
      *<Target/>//of type Target and/or EncryptionTarget
</RequireEncryption>

Key-Bearing-Token=
      <X509Token/> |
      <SAMLAssertion type="HOK"/> |
      <SymmetricKey/>

<X509Token 
      ?id=any_legal_id //Must be unique within the resulting 
XML
      ?strId=legal_id
      ?certificateAlias=alias_SecurityEnvironment_understands
      ?keyReferenceType=("Direct")|"Identifier"|"IssuerSerialN
umber"
      ?encodingType=("http://docs.oasis-open.org/wss/2004/01/
                  oasis-200401-wss-soap-message-security-
1.0#Base64Binary")
      ?valueType>

<SAMLAssertion 
      ?id=unique_policy_identifier
      ?authorityId=URI_of_Issuing_Authority}
      ?strId=unique_policy_identifier
      ?keyIdentifier=identifier_for_Attester_Key
      ?keyReferenceType=("Identifier")|"Embedded" 
      type="HOK"|"SV"
</SAMLAssertion>

<RequireSAMLAssertion
      ?id=unique_policy_identifier
      ?authorityId=URI_of_Issuing_Authority>
      ?strId=unique_policy_identifier
      type="SV"
      ?keyReferenceType=("Identifier")|"Embedded" 
</RequireSAMLAssertion>

<SymmetricKey keyAlias= alias/keyname_of_a_shared_key />

keyReferenceType=
             "Direct"|"Identifier"|"IssuerSerialNumber"| 
"Embedded"

EncodingType=(#Base64Binary |
                         other-wss-defined-encoding-type

ValueType=token-profile-specific-value-types

<Sign ?id=unique_policy_identifier
      ?includeTimestamp=("true")|"false">
      ?Key-Bearing-Token
      ?<CanonicalizationMethod 
                  algorithm="http://www.w3.org/2001/10/xml-
exc-c14n#" | others/>
      ?<SignatureMethod 
                  algorithm=("http://www.w3.org/2000/09/
xmldsig#rsa-sha1") | others/>
      *<Target/> //of type Target or SignatureTarget
</Sign>

<SignatureTarget
            ?type=("qname")|"uri"|"xpath"
            ?enforce=("true")|"false"
            value=an_appropriate_target_identifier>
      ?<DigestMethod algorithm=("http://www.w3.org/2000/09/
xmldsig#sha1") | others/>
      *<Transform/>
</SignatureTarget>

<RequireSignature
            ?id=unique_policy_identifier
            ?requireTimestamp=("true")|"false">
      ?Key-Bearing-Token
      ?<CanonicalizationMethod 
                        algorithm=("http://www.w3.org/2001/10/
xml-exc-c14n#") | others/>
      ?<SignatureMethod 
                        algorithm=("http://www.w3.org/2000/09/
xmldsig#rsa-sha1") | others/>
      *<Target/> //of type Target and/or SignatureTarget
</RequireSignature>

<Transform algorithm=supported-algorithms>
      *<AlgorithmParameter name="name" value="value"/>
</Transform>

<RequireTimestamp 
      ?id=unique_policy_id
      ?maxClockSkew=("60")
      ?timestampFreshnessLimit=("300")/>

<RequireUsernameToken
      ?id=unique_policy_id
      ?nonceRequired=("true")|"false"
      ?passwordDigestRequired=("true")|"false" 
      ?maxClockSkew=("60")
      ?timestampFreshnessLimit=("300")
      ?maxNonceAge=("900") >
</RequireUsernameToken>

<OptionalTargets>
      *<Target>
</OptionalTargets>

<Target ?type=("qname")|"uri"|"xpath"
      ?contentOnly=("true")|"false"
      ?enforce=("true")|"false">
      value
</Target>

Semantics of Security Configuration File Elements

This section contains a discussion regarding the semantics of security configuration file elements.

JAXRPCSecurity

The <JAXRPCSecurity> element is the top-level XML element for XWS-Security configuration files for applications that use JAX-RPC. The top-level XML element for stand-alone SAAJ applications is <SecurityConfiguration>. Table 4-3 provides a description of the sub-elements of <JAXRPCSecurity>.

Table 4-3 Sub-elements of JAXRPCSecurity element 
Sub-elements of JAXRPCSecurity
Description
Service
Indicates a JAX-RPC service within the XWS-Security environment for which XWS-Security can be configured. In this release, multiple services per configuration file are supported.
SecurityEnvironmentHandler
Specifies the implementation class name of the security environment handler (Required).

Service

The <Service> element indicates a JAX-RPC service within the XWS-Security environment for which XWS-Security can be configured.

Note: Although the XWS-Security configuration schema allows multiple <Service> elements to appear under a <JAXRPCSecurity> element, the current release does not support this feature. The configuration reader will throw an IllegalStateException if multiple services are specified.

Table 4-4 provides a description of its attributes, Table 4-5 provides a description of its sub-elements.

Table 4-4 Attributes of Service element 
Attributes of Service
Description
name
The name of the JAX-RPC service (optional).
id
The id of the JAX-RPC service (optional).
conformance
Type of conformance. In this release, the choice for this attribute is restricted to bsp (optional).
useCache
Determines whether caching is enabled. Default is false (optional). This flag is unused in the current release and has been introduced for future enhancements.

Table 4-5 Sub-elements of Service element 
Sub-elements of Service
Description
SecurityConfiguration
Indicates that what follows is the security configuration for the service.
Port
A port within a JAX-RPC service. Any (including zero) number of these elements may be specified.
SecurityEnvironmentHandler
Specifies the implementation class name of the security environment handler. If specified, overrides the SecurityEnvironmentHandler specified at the parent level. (Optional)

Port

The <Port> element represents a port within a JAX-RPC service. Table 4-6 provides a description of its attributes, Table 4-7 provides a description of its sub-elements.

Table 4-6 Attributes of Port element 
Attributes of Port
Description
name
Name of the port as specified in the wsdl (Required).
conformance
Type of conformance. In this release, the choice for this attribute is restricted to bsp. In this release, XWS-Security is conformant to Basic Security Profile (BSP) for messages that are created and sent. When conformance is set to bsp, messages are checked for BSP compliance before being sent. For more information on BSP, read What is Basic Security Profile (BSP)?
This EA implementation of this feature will be more complete in the FCS release (optional).

Table 4-7 Sub-elements of Port element 
Sub-elements of Port
Description
SecurityConfiguration
Indicates that what follows is security configuration for the port. This over-rides any security configured for the service.
Operation
Indicates a port within a JAX-RPC service. Any (including zero) number of these elements may be specified.

Operation

The <Operation> element creates a security configuration at the operation level, which takes precedence over port and service-level security configurations. Table 4-8 provides a description of its attributes, Table 4-9 provides a description of its sub-elements.

Table 4-8 Attributes of Operation  
Attributes of Operation
Description
name
Name of the operation as specified in the WSDL file, for example, name="{http://xmlsoap.org/Ping}Ping0". (Required)

Table 4-9 Sub-elements of Operation  
Sub-elements of Operation
Description
SecurityConfiguration
This element indicates that what follows is security configuration for the operation. This overrides any security configured for the port and the service.

SecurityConfiguration

The <SecurityConfiguration> element specifies a security configuration. Table 4-10 provides a description of its attributes, Table 4-11 provides a description of its sub-elements. The sub-elements of SecurityConfiguration can appear in any order. The order in which they appear determines the order in which they are executed, with the exception of the OptionalTargets element.

Table 4-10 Attributes of SecurityConfiguration  
Attributes of SecurityConfiguration
Description
dumpMessages
If dumpMessages is set to true, all incoming and outgoing messages are printed at the standard output. The default value is false (Optional).
enableDynamicPolicy
If enableDynamicPolicy is set to true, all incoming and outgoing messages use a dynamic security policy. The default value is false (Optional). For an example that uses this attribute, see Dynamic Policy Sample Application.

Table 4-11 Sub-elements of SecurityConfiguration
Sub-elements of SecurityConfiguration
Description
Timestamp
Indicates that a timestamp must be sent in the outgoing messages.
UsernameToken
Indicates that a username token must be sent in the outgoing messages.
Sign
Indicates that a sign operation needs to be performed on the outgoing messages.
Encrypt
Indicates that an encrypt operation needs to be performed on the outgoing messages.
SAMLAssertion
Indicates that a SAML assertion of subject confirmation type Sender-Vouches (SV) must be sent in the security header of the outgoing messages.
RequireTimestamp
Indicates that a timestamp must be present in the incoming messages.
RequireUsernameToken
Indicates that a username token must be present in the incoming messages.
RequireSignature
Indicates that the incoming messages must contain a signature.
RequireEncryption
Indicates that the incoming messages must be encrypted.
RequireSAMLAssertion
Indicates that the incoming message must contain a SAML assertion of subject confirmation type Sender-Vouches (SV).
OptionalTargets
Specifies a list of elements on which security operations are not required in the incoming messages, but are allowed.

Timestamp

The <Timestamp> element specifies that a timestamp must be sent in outgoing messages. For a discussion of using the Timestamp element with the includeTimestamp attribute of Sign, see Using Timestamp and includeTimestamp. Table 4-12 provides a description of its attributes.

Table 4-12 Attributes of Timestamp  
Attributes of Timestamp
Description
timeout
Value in seconds after which the timestamp should be considered expired. Default value is 300.

UsernameToken

The <UsernameToken> element is used when a UsernameToken should be sent with outgoing messages. This UsernameToken contains the sender's user and password information. Table 4-13 provides a description of its attributes.

Table 4-13 Attributes of UsernameToken  
Attributes of UsernameToken
Description
name
The name of the user. If not specified, security environment handler must provide it at runtime.
password
The password of the user. If not specified, attempt would be made to obtain it from the security environment handler at runtime.
digestPassword
Indicates whether to send password in digest form or not. Default value is true.
useNonce
Indicates whether to send a nonce inside the username token or not. Sending a nonce helps in preventing replay attacks. Default value is true.
id
The id to be set on the username token in the message to be sent. This is also useful in referring to the token from other places in the security configuration file.

Sign

The <Sign> element is used to indicate that a sign operation needs to be performed on the outgoing messages. Table 4-14 provides a description of its attributes, Table 4-15 provides a description of its sub-elements.

Table 4-14 Attributes of Sign  
Attributes of Sign
Description
id
The id to be set on the signature of the message to be sent. This is also useful in referring to the signature from other places in the security configuration file.
includeTimestamp
Indicates whether to also sign a timestamp as part of this signature or not. This is a mechanism useful in preventing replay attacks. The default value is true. Note that a true value for this attribute makes sure that a timestamp will be sent in the outgoing messages even if the <Timestamp> element has not been specified. Also note that at most one timestamp is sent in a message.
When includeTimestamp is true, a Timestamp element with the default value is added and is signed (i.e., Timestamp is added as one of the targets in the corresponding signature element.)

Table 4-15 Sub-elements of Sign  
Sub-elements of Sign
Description
X509Token
Indicates the certificate corresponding to the private key used for signing. If this element is not present, attempt is made to get the default certificate from the security environment handler. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SAMLAssertion
Indicates the certificate corresponding to the SAML assertion used for signing. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SymmetricKey
Indicates the symmetric key corresponding to the private key used for signing. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time. (SymmetricKey signatures are not supported for signatures in this release.)
CanonicalizationMethod
Indicates the canonicalization algorithm applied to the <SignedInfo> element prior to performing signature calculations.
SignatureMethod
Indicates the algorithm used for signature generation and validation.
Target
Specifies the target message part to be signed. Target has been deprecated and is included only for backward compatibility.
SignatureTarget
Specifies the target message part to be signed.

Using Timestamp and includeTimestamp

The following configurations of Timestamp and the includeTimestamp attribute of the Sign element have the following effect:

  1. If a <Timestamp> element is configured, a timestamp will be sent in the message.
  2. If the includeTimestamp attribute on <Sign> has value true and <Timestamp> is not configured, a timestamp (with default timeout value) will be sent in the message and included in the signature.
  3. If the includeTimestamp attribute on <Sign> has value true and <Timestamp> is configured, a timestamp with the properties (e.g, timeout) specified on the <Timestamp> will be sent in the message and also be included in the signature.
  4. If the includeTimestamp attribute on <Sign> has value false, a timestamp is not included in the signature.
Encrypt

The <Encrypt> element is used to indicate that an encrypt operation needs to be performed on the outgoing messages. Table 4-16 provides a description of its sub-elements.

Table 4-16 Sub-elements of Encrypt  
Sub-elements of Encrypt
Description
X509Token
Indicates the certificate to be used for encryption. If this element is not present, attempt is made to get the default certificate from the security environment handler. This element must not be specified if the <SymmetricKey> or <SAMLAssertion> sub-element of <Encrypt> is specified.
SymmetricKey
Indicates the symmetric key to be used for encryption. This element must not be specified if the <X509Token> or <SAMLAssertion> sub-element of <Encrypt> is present.
SAMLAssertion
Indicates the SAML assertion to be used for encryption. This element must not be specified if the <X509Token> or <SymmetricKey> sub-element of <Encrypt> is present.
KeyEncryptionMethod
Specifies the public key encryption algorithm to be used for encrypting and decrypting keys.
DataEncryptionMethod
Specifies the encryption algorithm to be applied to the cipher data.
Target
Identifies the resource that needs to be encrypted. The Target element has been deprecated and is provided only for backward compatibility.
EncryptionTarget
Identifies the resource that needs to be encrypted.

SAMLAssertion

The <SAMLAssertion> element is used to define the SAML assertion to be transferred from identity providers to service providers. These assertions include statements that service providers use to make access control decisions. The SAML Sample Application provides some examples of using this element. Table 4-17 provides a description of attributes of the <SAMLAssertion> element.

Table 4-17 Attributes of SAMLAssertion 
Attributes of SAMLAssertion
Description
id
Identifier for an assertion.
authorityId
Defines the ID that may be used to acquire the identified assertion at a SAML assertion authority or responder.
strID
Element content of the string identifier for the keyIdentifier.
keyIdentifier
The ID for a token reference for the key identifier that references a local SAML assertion.
encodingType
A parameter used to identify the security reference. When the keyIdentifier is used, this attribute is prohibited. (Prohibited)
keyReferenceType
Indicates whether the token reference identifies a token by URI (Identifier) or by an embedded reference (Embedded). The default value is Identifier.
type
Indicates the type of SAML assertion to use. The choices are Holder-of-Key (HOK) and Sender-Vouches (SV). The SV confirmed assertion may not be contained in the message. The Security Token Reference (STR) identified in strID becomes a remote reference to the SV confirmed assertion. The HOK assertion contained in the message identifies the attesting entity and its signing key.
 
Whether you choose type HOK or SV depends on where this token is located in the configuration file. A standalone <SAMLAssertion> element under <SecurityConfiguration> should be of type SV. An assertion of type HOK can appear as a child of a <Sign> or <Encrypt> element, indicating the presence of a confirmation key that can be used for the operation. (Required)

RequireTimestamp

If the <RequireTimestamp> element is present, a timestamp, in the form of a wsu:Timestamp element, must be present in the incoming messages. If the RequireTimestamp element is not specified, a Timestamp is not required. A timestamp specifies the particular point in time it marks. You may also want to consider using a nonce, which is a value that you should never receive more than once. Table 4-18 provides a description of its attributes.

Table 4-18 Attributes of RequireTimestamp  
Attributes of RequireTimestamp
Description
id
The id assigned to the timestamp.
maxClockSkew
The maximum number of seconds the sending clock can deviate from the receiving clock. Default is 60.
timestampFreshnessLimit
The maximum number of seconds the time stamp remains valid. Default is 300.

RequireUsernameToken

The <RequireUsernameToken> element is used to specify that a username token must be present in the incoming messages. Table 4-19 provides a description of its attributes.

Table 4-19 Attributes of RequireUsernameToken  
Attributes of RequireUsernameToken
Description
id
The identifier for the UsernameToken.
passwordDigestRequired
Indicates whether the username tokens in the incoming messages are required to contain the passwords in digest form or not. Default value is true. (See also: digestPassword attribute on <UsernameToken>)
nonceRequired
Indicates whether a nonce is required to be present in the username tokens in the incoming messages. Default value is true. (See also: useNonce attribute on <UsernameToken>)
maxClockSkew
The maximum number of seconds the sending clock can deviate from the receiving clock. Default is 60.
timestampFreshnessLimit
The maximum number of seconds the time stamp remains valid. Default is 300.
maxNonceAge
The maximum number of seconds the nonce is cached by the server for detecting a nonce replay. Default is 900.

RequireSignature

The <RequireSignature> element is specified when a digital signature is required for all specified targets. If no signature is present, an exception is thrown. In this release, the only sub-elements of RequireSignature that are verified while validating an incoming message are Target and SignatureTarget. Table 4-20 provides a description of its attributes, Table 4-21 provides a description of its sub-elements.

Table 4-20 Attributes of RequireSignature  
Attributes of RequireSignature
Description
id
The id to be set on the signature of the message to be sent. This is also useful in referring to the signature from other places in the security configuration file.
requireTimestamp
Indicates whether a timestamp must be included in the signatures in the incoming messages. Default value is true. (See also: includeTimestamp attribute on <Sign>)

Table 4-21 Sub-elements of RequireSignature  
Sub-elements of RequireSignature
Description
X509Token
Indicates the certificate corresponding to the private key used for signing. If this element is not present, attempt is made to get the default certificate from the security environment handler. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SAMLAssertion
Indicates the certificate corresponding to the SAML assertion used for signing. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SymmetricKey
Indicates the symmetric key corresponding to the private key used for signing. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
CanonicalizationMethod
Indicates the canonicalization algorithm applied to the <SignedInfo> element prior to performing signature calculations.
SignatureMethod
Indicates the algorithm used for signature generation and validation.
Target
Specifies the target message part which was expected to be signed. Target has been deprecated and is only provided for backward compatibility.
SignatureTarget
Specifies the target message part which was expected to be signed.

RequireEncryption

The <RequireEncryption> element is used when encryption is required for all incoming messages. If encryption is not present, an exception is thrown. In this release, the only sub-elements of RequireEncryption that are verified during validation of encrypted data in incoming messages are Target and EncryptionTarget. Table 4-22 provides a description of its attributes, Table 4-23 provides a description of its sub-elements.

Table 4-22 Attributes of RequireEncryption  
Attributes of RequireEncryption
Description
id
The id to be set on the message to be sent.

Table 4-23 Sub-elements of RequireEncryption  
Sub-elements of RequireEncryption
Description
X509Token
Indicates the certificate to be used for encryption. If this element is not present, attempt is made to get the default certificate from the security environment handler. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SAMLAssertion
Indicates the certificate corresponding to the SAML assertion used for encryption. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
SymmetricKey
Indicates the symmetric key corresponding to the private key used for encryption. Only one of the X509Token, SAMLAssertion, and SymmetricKey elements may be present at a time.
CanonicalizationMethod
Indicates the canonicalization algorithm applied to the <Encrypt> element prior to performing encrypt calculations.
DataEncryptionMethod
Indicates the encryption algorithm to be applied to the cipher data.
Target
Identifies the resource that was expected to be encrypted. Target has been deprecated and is only provided for backward compatibility.
EncryptionTarget
Identifies the resource that was expected to be encrypted.

RequireSAMLAssertion

The <RequireSAMLAssertion> element is used when a Sender-Vouches (SV) SAML assertion is required for all incoming messages. If a SAML assertion is not present, an exception is thrown. Table 4-24 provides a description of its attributes.

Table 4-24 Attributes of RequireSAMLAssertion  
Attributes of RequireSAMLAssertion
Description
id
Identifier for an assertion. (Optional)
authorityId
Defines an abstract identifier for the assertion-issuing authority.
strID
Element content of the string identifier for the keyIdentifier.
keyReferenceType
Indicates whether the token reference identifies a token by AssertionId (Identifier) or by an embedded reference (Embedded). The default value is Identifier.
type
Indicates to use the SV type of SAML assertion. The SV confirmed assertion is not contained in the message. (Required)

OptionalTargets

The <OptionalTargets> element is used when an operation is optional for a specific target. Table 4-25 provides a description of its sub-elements.

Table 4-25 Sub-elements of OptionalTargets  
Sub-elements of OptionalTargets
Description
Target
Indicates that a security operation is allowed to be performed on this target, but it is not required. One or more of these elements can be specified. The augmented cid:* syntax is not allowed as the value of the Target when Target is a sub-element of OptionalTargets.

Transform

The <Transform> element is an optional ordered list of processing steps to be applied to the resource's content before it is digested. Transforms can include operations such as canonicalization, encoding/decoding, XSLT, XPath, XML schema validation, or XInclude. The recommendation that discusses this method is the W3C XML-Signature Syntax and Processing recommendation, which can be viewed at http://www.w3.org/TR/xmldsig-core/#sec-Transforms. The following types of transform algorithms can be used: canonicalization, Base64, xpath filtering, envelope signature transform, and XSLT transform. The XWS-Security APIs Sample Application provides some examples of configuration files that use this element.

Table 4-26 provides a description of its attributes, Table 4-27 provides a description of its sub-elements.

Table 4-26 Attributes of Transform  
Attributes of Transform
Description
algorithm
The algorithm to be used for signing. (Required)

Table 4-27 Sub-elements of Transform  
Sub-elements of Transform
Description
AlgorithmParameter
Identifies the parameters to be supplied to the transform algorithm.

AlgorithmParameter

Algorithms are identified by URIs that appear as an attribute to the element that identifies the algorithms' role (DigestMethod, Transform, SignatureMethod, or CanonicalizationMethod). All algorithms used herein take parameters but in many cases the parameters are implicit. Explicit additional parameters to an algorithm appear as content elements within the algorithm role element. Such parameter elements have a descriptive element name, which is frequently algorithm specific, and MUST be in the XML Signature namespace or an algorithm specific namespace. The XWS-Security APIs Sample Application provides some examples of configuration files that use this element.

Table 4-28 provides a description of its attributes.

Table 4-28 Attributes of AlgorithmParameter  
Attributes of AlgorithmParameter
Description
name
The name of the algorithm parameter. (Required)
value
The value of the algorithm parameter. (Required)

X509Token

The <X509Token> element is used to specify the certificate to be used for encryption (for the case of encryption) or the certificate corresponding to the private key used for signing (for the case of signature). This element must not be specified if the <SymmetricKey> or <SAMLAssertion> sub-elements are present. Table 4-29 provides a description of its attributes.

Table 4-29 Attributes of X509Token  
Attributes of X509Token
Description
id
The id to be assigned to this token in the message. This attribute is useful in referring the token from other places in the security configuration file. (Optional)
strID
If specified, it denotes the wsu:Id to be assigned to the Security Token Reference (STR) to be generated and inserted into the message. The inserted STR would reference the X509 token.
certificateAlias
The alias associated with the token (certificate).
keyReferenceType
The reference mechanism to be used for referring to the X509 token (certificate) which was involved in the security operation, in the outgoing messages. The default value is Direct. The list of allowed values for this attribute and their description is as follows:
1. Direct - certificate is sent along with the message.
2. Identifier - subject key identifier extension value of the certificate is sent in the message.
3. IssuerSerialNumber - issuer name and serial number of the certificate are sent in the message.
encodingType
The type of encoding to be used for the token. The default value is http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary.
valueType
The type of value to expect. The valueType can be #X509v3, #X509PKIPathv1, or #PKCS7. This release does not support #PKCS7.

Target

Note: In this release the Target sub-element is deprecated and is supported only for backward compatibility. The Target sub-element is being replaced with SignatureTarget and EncryptionTarget.

The <Target>target_value</Target> sub-element contains a string that can be used to identify the resource that needs to be signed or encrypted. If a Target sub-element is not specified, the default value is a target that points to the contents of the SOAP body of the message. The value of this element is specified as a text node inside this element.

You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid:<part-name>, which specifies the value of the Content-ID (CID) header of the attachment. When the Content-ID is not know until runtime, such as when auto-generated CIDs are run under JAX-RPC, the attachment can be referenced by setting the type attribute to uri and specifying the target value as attachmentRef:<part-name>, where part-name is the WSDL part name of the AttachmentPart. Auto-generated CIDs in JAX-RPC following the form <partname>=<UUID>@<Domain>. The special value cid:* can be used to refer to all attachments of a SOAPMessage.

The attributes of the <Target> element are described in Table 4-30.

Table 4-30 Attributes of Target  
Attributes of Target
Description
type
Indicates the type of the target value. Default value is qname. The list of allowed values for this attribute and their description is as follows:
1. qname - If the target element has a local name Name and a namespace URI some-uri, the target value is {some-uri}Name.
2. xpath - Indicates that the target value is the xpath of the target element.
3. uri - If the target element has an id some-id, then the target value is #some-id.
contentOnly
Indicates whether the complete element or only the contents needs to be encrypted (or is required to be encrypted). The default value is true. (Relevant only for <Encrypt> and <RequireEncryption> targets)
enforce
If true, indicates that the security operation on the target element is definitely required. Default value is true. (Relevant only for <RequireSignature> and <RequireEncryption> targets)

SignatureTarget

The <SignatureTarget> sub-element is called by the <SignatureMethod> element to identify the resource that needs to be signed. If neither the <SignatureTarget> nor <Target> sub-element are specified, the default value is a target that points to the contents of the SOAP body of the message. The target value is a string that specifies the object to be signed, and which is specified between the <SignatureTarget>target_value</SignatureTarget> elements. The XWS-Security APIs Sample Application provides some examples of configuration files that use this element.

You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid:<part-name>, which specifies the value of the Content-ID (CID) header of the attachment. When the Content-ID is not know until runtime, such as when auto-generated CIDs are run under JAX-RPC, the attachment can be referenced by setting the type attribute to uri and specifying the target value as attachmentRef:<part-name>, where part-name is the WSDL part name of the AttachmentPart. Auto-generated CIDs in JAX-RPC following the form <partname>=<UUID>@<Domain>. The special value cid:* can be used to refer to all attachments of a SOAPMessage.

The attributes of <SignatureTarget> are described in Table 4-31, its sub-elements are described in Table 4-32.

Table 4-31 Attributes of SignatureTarget  
Attributes of SignatureTarget
Description
type
Indicates the type of the target value. Default value is qname. The list of allowed values for this attribute and their description is as follows:
1. qname - If the target element has a local name Name and a namespace URI some-uri, the target value is {some-uri}Name.
2. xpath - Indicates that the target value is the xpath of the target element.
3. uri - If the target element has an id some-id, then the target value is #some-id. This is the option that is used to secure message attachments.
value
Indicates whether the value needs to be encrypted (or is required to be encrypted). The default value is true. (Relevant only for <Encrypt> and <RequireEncryption> targets)
enforce
If true, indicates that the security operation on the target element is definitely required. Default value is true. (Relevant only for <RequireSignature> and <RequireEncryption> targets)

Table 4-32 Sub-elements of SignatureTarget  
Sub-elements of SignatureTarget
Description
DigestMethod
Identifies the digest algorithm to be applied for signing the object.
Transform
Identifies the transform algorithm to be applied before signing the object.

EncryptionTarget

The <EncryptionTarget> sub-element identifies the type of encrypted structure being described. If neither the <EncryptionTarget> nor <Target> sub-elements are specified, the default value is a target that points to the contents of the SOAP body of the message. The target value is a string that specifies the object to be encrypted, and which is specified between the <EncryptionTarget>target_value</EncryptionTarget> elements.

You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid:<part-name>, which specifies the value of the Content-ID (CID) header of the attachment. When the Content-ID is not know until runtime, such as when auto-generated CIDs are run under JAX-RPC, the attachment can be referenced by setting the type attribute to uri and specifying the target value as attachmentRef:<part-name>, where part-name is the WSDL part name of the AttachmentPart. Auto-generated CIDs in JAX-RPC following the form <partname>=<UUID>@<Domain>. The special value cid:* can be used to refer to all attachments of a SOAPMessage.

The attributes of <EncryptionTarget> are described in Table 4-33, its sub-elements are described in Table 4-34.

Table 4-33 Attributes of EncryptionTarget  
Attributes of EncryptionTarget
Description
type
Indicates the type of the target value. Default value is qname. The list of allowed values for this attribute and their description is as follows:
1. qname - If the target element has a local name Name and a namespace URI some-uri, the target value is {some-uri}Name.
2. xpath - Indicates that the target value is the xpath of the target element.
3. uri - If the target element has an id some-id, then the target value is #some-id. This option is used to secure message attachments.
contentOnly
Indicates whether the complete element or only the contents need to be encrypted (or is required to be encrypted). The default value is true. (Relevant only for <Encrypt> and <RequireEncryption> targets)
value
Indicates whether the value needs to be encrypted (or is required to be encrypted). The default value is true. (Required)
enforce
If true, indicates that the security operation on the target element is definitely required. Default value is true. (Relevant only for <RequireSignature> and <RequireEncryption> targets)

Table 4-34 Sub-elements of EncryptionTarget  
Sub-elements of EncryptionTarget
Description
Transform
Identifies the transform algorithm to be applied to the object to be encrypted.

SymmetricKey

The <SymmetricKey> element indicates the symmetric key to be used for encryption. This element must not be specified if the <X509Token> or <SAMLAssertion> sub-elements are present. Its attributes are discussed in Table 4-35.

Table 4-35 Attributes of SymmetricKey  
Attributes of SymmetricKey
Description
keyAlias
The alias of the symmetric key to be used for encryption. This attribute is required.

CanonicalizationMethod

The <CanonicalizationMethod> element specifies the canonicalization algorithm to be applied to the <SignedInfo> element prior to performing signature calculations. When specified, the canonical XML [XML-C14N] standard, which is an algorithm that standardizes the way XML documents should be ordered and structured, should be applied. The recommendation that discusses this method is the W3C XML-Signature Syntax and Processing recommendation, which can be viewed at http://www.w3.org/TR/xmldsig-core/#sec-CanonicalizationMethod. Its attributes are discussed in Table 4-36.

Table 4-36 Attributes of CanonicalizationMethod  
Attributes of CanonicalizationMethod
Description
algorithm
The algorithm to be used for signing. There is no default value. You must explicitly add
http://www.w3.org/2001/10/xml-exc-c14n#
to the transforms list in the configuration file if you want to use it. The prefix list is computed by the implementation and does not need to be specified in the configuration file. This transform will be added as the last transform regardless of its placement in the configuration file.

SignatureMethod

The <SignatureMethod> element specifies the algorithm used for signature generation and validation. A SignatureMethod is implicitly given two parameters: the keying info and the output of CanonicalizationMethod. The recommendation that discusses this method is the W3C XML-Signature Syntax and Processing recommendation, which can be viewed at http://www.w3.org/TR/xmldsig-core/#sec-SignatureMethod. Its attributes are discussed in Table 4-37.

Table 4-37 Attributes of SignatureMethod 
Attributes of SignatureMethod
Description
algorithm
The algorithm to be used for signing. The default value is
http://www.w3.org/2000/09/xmldsig#rsa-sha1.

DigestMethod

The <DigestMethod> element specifies the algorithm used for generating the digest of the object to be signed. The recommendation that discusses this method is the W3C XML-Signature Syntax and Processing recommendation, which can be viewed at http://www.w3.org/TR/xmldsig-core/#sec-DigestMethod. The attributes of <DigestMethod> are discussed in Table 4-38.

Table 4-38 Attributes of DigestMethod 
Attributes of DigestMethod
Description
algorithm
Identifies the digest algorithm to be applied to the signed object. The default value is
http://www.w3.org/2000/09/xmldsig#sha1.

DataEncryptionMethod

The <DataEncryptionMethod> element specifies the encryption algorithm to be applied to the cipher data. The recommendation that discusses this method is the W3C XML Encryption Syntax and Processing recommendation, which can be viewed at http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/#sec-EncryptionMethod. The attributes of <DataEncryptionMethod> are discussed in Table 4-39.

Table 4-39 Attributes of DataEncryptionMethod 
Attributes of DataEncryptionMethod
Description
algorithm
The algorithm to be used for encrypting data. The default value is
"http://www.w3.org/2001/04/xmlenc#aes128-cbc"). Other options include:
"http://www.w3.org/2001/04/xmlenc#aes256-cbc"; and
"http://www.w3.org/2001/04/xmlenc#tripledes-cbc".

Note: Although the schema indicates that http://www.w3.org/2001/04/xmlenc#aes128-cbc is the default algorithm for <DataEncryptionMethod>, for backward compatibility this implementation still uses http://www.w3.org/2001/04/xmlenc#tripledes-cbc as the default.

KeyEncryptionMethod

The <KeyEncryptionMethod> element specifies the public key encryption algorithm to be used for encrypting and decrypting keys. Its attributes are discussed in Table 4-40.

Table 4-40 Attributes of KeyEncryptionMethod 
Attributes of KeyEncryptionMethod
Description
algorithm
Specifies the KeyTransport/KeyWrap algorithms to be used to encrypt/decrypt a public key or secret key (key used to encrypt the data) respectively. The default value is
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p. Other options include: "http://www.w3.org/2001/04/xmlenc#rsa-1_5";
"http://www.w3.org/2001/04/xmlenc#kw-tripledes";
"http://www.w3.org/2001/04/xmlenc#kw-aes128"; and
"http://www.w3.org/2001/04/xmlenc#kw-aes256".

SecurityEnvironmentHandler

The <SecurityEnvironmentHandler> element specifies the implementation class name of the security environment handler. Read Writing SecurityEnvironmentHandlers for more information on SecurityEnvironmentHandlers.

How Do I Specify the Security Configuration for the Build Files?

After the security configuration files are created, you can easily specify which of the security configuration files to use for your application. In the build.properties file for your application, create a property to specify which security configuration file to use for the client, and which security configuration file to use for the server. An example from the simple sample application does this by listing all of the alternative security configuration files, and uncommenting only the configuration to be used. The simple sample uses the following properties: 

# #look in config directory for alternate security 
configurations
# Client Security Config. file
client.security.config=config/dump-client.xml
#client.security.config=config/user-pass-authenticate-
client.xml
#client.security.config=config/encrypted-user-pass-client.xml
#client.security.config=config/encrypt-usernameToken-
client.xml
#client.security.config=config/sign-client.xml
#client.security.config=config/encrypt-client.xml
#client.security.config=config/encrypt-using-symmkey-
client.xml
#client.security.config=config/sign-encrypt-client.xml
#client.security.config=config/encrypt-sign-client.xml
#client.security.config=config/sign-ticket-also-client.xml
#client.security.config=config/timestamp-sign-client.xml
#client.security.config=config/flexiblec.xml
#client.security.config=config/method-level-client.xml

# Server Security Config. file
server.security.config=config/dump-server.xml
#server.security.config=config/user-pass-authenticate-
server.xml
#server.security.config=config/encrypted-user-pass-server.xml
#server.security.config=config/encrypt-usernameToken-
server.xml
#server.security.config=config/sign-server.xml
#server.security.config=config/encrypt-server.xml
#server.security.config=config/sign-encrypt-server.xml
#server.security.config=config/encrypt-sign-server.xml
#server.security.config=config/sign-ticket-also-server.xml
#server.security.config=config/timestamp-sign-server.xml
#server.security.config=config/flexibles.xml
#server.security.config=config/method-level-server.xml

As you can see from this example, several security scenarios are listed in the build.properties file. To run a particular security configuration option, simply uncomment one of the entries for a client configuration file, uncomment the corresponding entry for the server configuration file, and comment all of the other options.

In general, the client and server configuration files should match. However, in some cases, more than one client configuration can be used with a server configuration. For example, either encrypt-using-symmkey-client.xml or encrypt-client.xml can be used with encrypt-server.xml. This combination works because the server requirement is the same (the body contents must be encrypted) when the client-side security configuration is either encrypt-using-symmkey-client.xml or encrypt-client.xml. The difference in the two client configurations is the key material used for encryption.

After the property has been defined in the build.properties file, you can refer to it from the file that contains the asant (or ant) targets, which is build.xml.

When you create an asant (or ant) target for JAX-RPC clients and services, you use the wscompile utility to generate stubs, ties, serializers, and WSDL files. XWS-Security has been integrated into JAX-RPC through the use of security configuration files. The code for performing the security operations on the client and server is generated by supplying the configuration files to the JAX-RPC wscompile tool. The wscompile tool can be instructed to generate security code by making use of the -security option and supplying the security configuration file.

Note: For the 2.0 release of JAX-RPC, JAX-RPC will be renamed to JAX-WS. JAX-WS will become part of the XWS-Security 2.0 FCS later this year. When this renaming occurs, the wscompile tool will be replaced, and these steps and the build.xml files for the sample applications will need to be modified accordingly.

An example of the target that runs the wscompile utility with the -security option pointing to the security configuration file specified in the build.properties file to generate server artifacts, from the simple sample application, looks like this: 

<target name="gen-server" depends="prepare"
          description="Runs wscompile to generate server 
artifacts">
    <echo message="Running wscompile...."/>
    <wscompile verbose="${jaxrpc.tool.verbose}" 
               xPrintStackTrace="true"    
               keep="true" fork="true" 
               security="${server.security.config}"
               import="true"
               model="${build.home}/server/WEB-INF/
${model.rpcenc.file}"
               base="${build.home}/server/WEB-INF/classes"
               classpath="${app.classpath}"
               config="${config.rpcenc.file}">
      <classpath>
        <pathelement location="${build.home}/server/WEB-INF/
classes"/>
        <path refid="app.classpath"/>
      </classpath>
    </wscompile>
  </target>

An example of the target that runs the wscompile utility with the security option pointing to the security configuration file specified in the build.properties file to generate the client-side artifacts, from the simple sample application, looks like this: 

<target name="gen-client" depends="prepare"
          description="Runs wscompile to generate client side 
artifacts">
    <echo message="Running wscompile...."/>
    <wscompile fork="true" verbose="${jaxrpc.tool.verbose}" 
keep="true"
               client="true"
               security="${client.security.config}"
               base="${build.home}/client"
               features=" "
               config="${client.config.rpcenc.file}">
      <classpath>
        <fileset dir="${build.home}/client">
            <include name="secenv-handler.jar"/>
        </fileset>
        <path refid="app.classpath"/>
      </classpath>
    </wscompile>
  </target>

Refer to the documentation for the wscompile utility in Useful XWS-Security Command-Line Tools for more information on wscompile options.

Are There Any Sample Applications Demonstrating XWS-Security?

This release of the Java WSDP includes many example applications that illustrate how a JAX-RPC or stand-alone SAAJ application developer can use the XML and Web Services Security framework and APIs. The example applications can be found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/ directory. Before you can run the sample applications, you must follow the setup instructions in Setting Up To Use XWS-Security With the Sample Applications.

The sample applications print out both the client and server request and response
SOAP messages. The output from the server may be viewed in the appropriate container's log file. The output from the client is sent to stdout or whichever stream is used by the configured log handler. Messages are logged at the INFO level.

Note: In some of the sample security configuration files, no security is specified for either a request or a response. In this case, the response is a simple JAX-RPC response. When XWS-Security is enabled for an application by providing the -security option to wscompile, and a request or response not containing a wsse:Security Header is received, the message WSS0202: No Security element in the message will display in the output to warn that a nonsecure response was received.

In these examples, the server-side code is found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/server/src/<sample_name>/ directory. Client-side code is found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/client/src/<sample_name>/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

These examples can be deployed onto any of the following containers. For the purposes of this tutorial, only deployment to the Sun Java System Application Server Platform Edition 8.1 will be discussed. The README.txt file for each example provides more information on deploying to the other containers. The following containers can be downloaded from http://java.sun.com/webservices/containers/index.html.

These examples use keystore and truststore files that are included in the <JWSDP_HOME>/xws-security/etc/ directory. For more information on using keystore and truststore files, read the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html. Refer to the application's README.txt file if deploying on the Web Server or Tomcat.

The following list provides the name, a short description, and a link to further discussion of each of the sample applications available in this release: