3. Create a property in thebuild.propertiesfile to specify a security con- figuration 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 inHow 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 inXWS-Security Configuration File Schema. The formal schema definition (XSD) for XWS-Security Configura- tion can be viewed in the appendixA 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 con- figuration 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 inXWS-Security APIs Sample Application.
Within these declaration elements are elements that specify which type of secu- rity 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 config- uration 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 anxwsselement with the value
Sign(to do the signing first), and then create anxwsselement 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 config- uration 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 thexwss:RequireEncryptionelement in a client configura- tion file indicates that the client expects an encrypted response. In the second example, a RequireEncryptionand aRequireSignatureelement specified in
that order implies that the client expects the response to be signed and then encrypted.
Thexwss:RequireSignatureandxwss:RequireEncryptionelements appear- ing 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 formxwss:RequireSignature
orxwss:RequireEncryptionis to throw an exception if the requirement is not met by the received response or request.
The xwss:SecurityEnvironmentHandler element appearing under
xwss:SecurityConfigurationis a compulsory child element that needs to be specified. The value of this element is the name of a Java class that implements thejavax.security.auth.callback.CallbackHandlerinterface and handles a set ofCallbacks defined by XWS-Security. There are a set of callbacks that are mandatory and that everyCallbackHandlerneeds to implement. A few call- backs are optional and can be used to supply some finer-grained information to the XWS-Security run-time. TheSecurityEnvironmentHandlerand theCall- backsare described inWriting SecurityEnvironmentHandlers. TheSecurityEnviron- mentHandler 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/apidirectory, to find the list of mandatory and optional callbacks and the details of theCallback classes.
When XWS-Security is used in a stand-alone SAAJ environment, the developer can choose to implement the com.sun.xml.wss.SecurityEnvironment inter- face instead of a callback handler that handles XWS-Security callbacks. In this situation, an instance of the SecurityEnvironment implementation can be set into theProcessingContextinstance. For an example application that demon- strates 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 config- uration 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 isUsernameToken. On the server-side, refer to the documenta- tion for your server regarding how to set up a user/password database for the server, or readSetting Up To Use XWS-Security With the Sample Applicationsfor a sum-
mary. 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>
Thesimplesample application includes a number of example security configu- ration 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 inSimple Sample Security Con- figuration Files.
Other sample configuration files that are provided in this release include: • Simple Sample Security Configuration Files
• JAAS Sample Security Configuration Files
• SwA Sample Configuration Files
• SAML Interop Sample Configuration Files
• Security Configuration Files for Enabling Dynamic Policy
• Security Configuration Files for Enabling Dynamic Response