Configuring hardware cryptographic devices for Web Services Security

Before you can use a hardware cryptographic device, you must configure and enable it. You must first configure a hardware cryptographic device using the Secure Sockets Layer (SSL) certificate and key management panels in the administrative console. The key for the cryptographic operation can be stored in an ordinary Java keystore file and need not be stored on the hardware devices. You enable cryptographic operations by performing specific file setup procedures to ensure that the cryptographic device can be used.

Before you begin

You must first configure a hardware cryptographic device using the Secure Sockets Layer (SSL) certificate and key management panels in the administrative console.
Note: Fix packs that include updates to the Software Development Kit (SDK) might overwrite unrestricted policy files. Back up unrestricted policy files before you apply a fix pack and reapply these files after the fix pack is applied.

Procedure

  1. Stop the application server.
  2. Download and install the new policy files.
    Important: Your country of origin might have restrictions on the import, possession, use, or re-export to another country, of encryption software. Before downloading or using the unrestricted policy files, you must check the laws of your country, its regulations, and its policies concerning the import, possession, use, and re-export of encryption software, to determine if it is permitted.
    1. Click Java SE 6
    2. Scroll down the page then click IBM SDK Policy files.

      The Unrestricted JCE Policy files for SDK 6 Web site displays.

    3. Click Sign in and provide your IBM®.com ID and password.
    4. Select Unrestricted JCE Policy files for SDK 6 and click Continue.
    5. View the license and click I Agree to continue.
    6. Click Download Now.
    7. Extract the unlimited jurisdiction policy files that are packaged in the ZIP file. The ZIP file contains a US_export_policy.jar file and a local_policy.jar file.
    8. In your WebSphere® Application Server installation, mount your product HFS as read/write. Go to the $JAVA_HOME/lib/security directory and back up your US_export_policy.jar and local_policy.jar files.
    9. Replace your US_export_policy.jar and local_policy.jar files with the two files that you downloaded from the IBM.com Web site.
    10. Re-mount your product HFS as read/only.
    Following is an example of this copy operation.
    $JAVA_HOME/demo/jce/policy-files/unrestricted/* to
    $JAVA_HOME/lib/security

    The embedded Software Development Kit (SDK) ships with the unrestricted jurisdiction policy Java archive (JAR) files. Therefore, instead of downloading these files from the Web site, you can symbolically link to the files as allowed by your local country regulations. These unrestricted policy files are located in the install_root/java/demo/jce/policy-files/unrestricted/ directory. The following UNIX-based commands enable you to symbolically link to these files:

    # Export the paths. You can find the values of the following
    # variables in the joblog by searching for was.install.root,
    # java.home, and so on:
    export was.install.root=<was.install.root>
    export java.home=<java.home>
    # The previous paths apply to both 31- and 64-bit configurations
    # of WebSphere Application Server for z/OS. For a 64-bit 
    # configuration, the java.home path points to the 64-bit embedded
    # Java virtual machine (JVM).
    
    # Delete the original policy .jar files. Because a backup is
    # automatically present in the smpe.home HFS, an explicit
    # backup is not needed:
    cd $java.home/lib/security
    rm US_export_policy.jar
    rm local_policy.jar
    
    # Issue the following commands on separate lines to create
    # the symbolic links to the unrestricted policy files:
    ln -s $java.home/demo/jce/policy-files/unrestricted/US_export_po licy.jar US_export_policy.jar
    ln -s $java.home/demo/jce/policy-files/unrestricted/local_policy .jar local_policy.jar

    Issue the following UNIX-based commands to remove the symbolic links to the unrestricted policy files in the demo directory and link to the original files:

    # Export the paths. You can find the values of the following
    # variables in the joblog by searching for was.install.root,
    # java.home, and so on:
    export was.install.root=<was.install.root>
    export java.home=<java.home>
    export smpe.install.root=<smpe.install.root>
    # The previous paths apply to both 31- and 64-bit configurations
    # of WebSphere Application Server for z/OS. For a 64-bit 
    # configuration, the java.home path points to the 64-bit embedded
    # Java virtual machine (JVM).
    
    # Delete the current policy .jar files. You might want
    # to back up the following files:
    cd $java.home/lib/security
    rm US_export_policy.jar
    rm local_policy.jar
    
    # Issue the following commands on separate lines to create 
    # symbolic links to the smpe HFS where the original files 
    # are kept: 
    ln -s $smpe.install.root/java/lib/security/US_export_policy.jar US_export_policy.jar
    ln -s $smpe.install.root/java/lib/security/local_policy.jar local_policy.jar
  3. Alter the java.security file.

    The java.security file is located in the app_server_root/properties directory.

    The following changes need to be made to this file:

    1. Uncomment the following line of the file:
       #security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
    2. Reorder the list of providers and preference orders as follows:
      security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
      #security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS
      security.provider.2=com.ibm.crypto.provider.IBMJCE
      security.provider.3=com.ibm.jsse.IBMJSSEProvider
      security.provider.4=com.ibm.jsse2.IBMJSSEProvider2
      security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
      security.provider.6=com.ibm.security.cert.IBMCertPath
      security.provider.7=com.ibm.security.sasl.IBMSASL
      security.provider.8=com.ibm.security.cmskeystore.CMSProvider
      security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
       [Updated in July 2011] security.provider.9=com.ibm.xml.crypto.IBMXMLCryptoProvider [Updated in July 2011]
      jul2011
      [Updated in July 2011] security.provider.10=com.ibm.xml.enc.IBMXMLEncProvider [Updated in July 2011]
      jul2011
      [Updated in July 2011] security.provider.11=org.apache.harmony.security.provider.PolicyProvider [Updated in July 2011]
      jul2011
    The file structure and content are ready for use.
  4. Start the application server. The cryptographic device is enabled for all Web service security applications that run on this application server.

Results

This procedure configures and enables a hardware cryptographic device for all Web Services Security applications running on this application server.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms of Use | Feedback

Last updatedLast updated: Sep 19, 2011 3:08:41 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-nd-zos&topic=twbs_enable_hardacc
File name: twbs_enable_hardacc.html