Instructions for Enabling WebSphere for z/os V8 for Hardware Cryptography

Transcription

1 OVERVIEW This paper is intended to document the steps needed to enable the Case 3 configuration described in Techdocs paper TD That paper was originally published for WebSphere for z/os V6.1. Numerous enhancements to WebSphere for z/os V8 have streamlined and improved the process. The new process is described here. BEFORE YOU BEGIN: The Deployment Manager and all Node Agents must be started and synchronized. ICSF and at least one CEX2, CEX3 or CEX4S card configured as a coprocessor are required to be active on the LPAR where the Deployment Manager and/or Node Agents run. Additional CEX2, CEX3 or CEX4S cards configured as either accelerators or coprocessors may be used in addition to supplement the required coprocessor card. STEP 1: Enable the IBMJCECCA provider on the Deployment Manager node. In order to use the admin console to configure any other node for hardware cryptography, you must first enable the Deployment Manager node to use the IBMJCECCA provider. To do this: a.) Locate the java.security file for the Deployment Manager. It is located in the Deployment Manager node's: /DeploymentManager/properties/java.security. Notice that this is a symlink. Using ishell, type A next to /DeploymentManager/properties/java.security and note the location of the file that the symlink points to. /wasv8config/s4cell/s4dmnode/deploymentmanager/properties/java.security is a symlink that points to /wasv8config/s4cell/s4dmnode/wasinstall/properties/java.security b.) Delete the java.security symlink from the Deployment Manager node's: /DeploymentManager/properties/ directory, and copy the java.security file from the directory that the symlink pointed to. Delete /wasv8config/s4cell/s4dmnode/deploymentmanager/properties/java.security Then copy /wasv8config/s4cell/s4dmnode/wasinstall/properties/java.security to /wasv8config/s4cell/s4dmnode/deploymentmanager/properties/java.security After you copy the file, set the ownership of the new /DeploymentManager/properties/java.security file to the cell admin userid and config group, just like the java.security file that it was copied from. The file permission bits should be 775. COPYRIGHT IBM CORPORATION, 2012 Page 1 of 7

2 STEP 2: c.) Using ISPF option 3.17 (the EA option), modify the new /DeploymentManager/properties/java.security file to enable the IBMJCECCA provider. To do this: - Locate the line: #security.provider.1=com.ibm.crypto.hdwrcca.provider.ibmjcecca - Remove the comment character # from column 1. - Renumber the remaining uncommented security providers so they become security.provider.2 to security provider Save your changes. d.) Stop and restart the Deployment Manager for your cell. It should come up and communicate normally with the Node Agents. In the admin console, System administration > Nodes, and Node agents should display as synchronized. Enable the IBMJCECCA provider on each node of your cell that you want to use hardware cryptography. This process is equivalent to the process you performed for the Deployment Manager in Step 1. If you enable the IBMJCECCA provider on a node, then ICSF must be active on that LPAR or the cell components on that LPAR will NOT work correctly. The details are: a.) Following the process described in steps 1.a and 1.b, locate the java.security symlink at the node level, note the location of the java.security file that the symlink points to, then delete the symlink and copy the file. /wasv8config/s4cell/s4nodec/appserver/properties/java.security is a symlink that points to /wasv8config/s4cell/s4nodec/wasinstall/properties/java.security Delete /wasv8config/s4cell/s4nodec/appserver/properties/java.security After you delete the symlink, you can copy the java.security file for the node and modify it, as in step 1.c. Or you can just copy the newly modified Deployment Manager's java.security file (from step 1.c) to anywhere you need a modified copy. Copy /wasv8config/s4cell/s4dmnode/deploymentmanager/properties/java.security to /wasv8config/s4cell/s4nodec/appserver/properties/java.security After you copy the file, set the ownership of the new /AppServer/properties/java.security file to the cell admin userid and config group, just like the java.security file that it was copied from. COPYRIGHT IBM CORPORATION, 2012 Page 2 of 7

3 STEP 3: The file permission bits should be 775. Define the optimized keystore/truststore and SSL configuration to be used by the cell components which you have enabled with the IBMJCECCA provider in steps 1 and 2. To do this: a.) Add a new keystore definition: Security > SSL Certificate and key management > Key stores and certificates > New Adding a new keystore: Name: Case3_KeyStore Management scope: (cell): cell name Path: safkeyringhw:///<your cell keyring name> (Note the use of safkeyringhw instead of safkeyring.) Control region user: leave this blank Servant region user: leave this blank Password: password Confirm password: password (Note: SAF keyrings do not have a password. The software expects one however. The only correct value for password is password) Type: JCECCARACFKS b.) Add a new truststore definition: Security > SSL Certificate and key management > Key stores and certificates > New Adding a new truststore: Name: Case3_TrustStore Management scope: (cell): cell name Path: safkeyringhw:///<your cell keyring name> (Note the use of safkeyringhw instead of safkeyring.) Control region user: leave this blank Servant region user: leave this blank Password: password Confirm password: password Type: JCECCARACFKS COPYRIGHT IBM CORPORATION, 2012 Page 3 of 7

4 STEP 4: c.) Add a new SSL configuration: Security > SSL Certificate and key management > SSL Configurations > New JSSE Configuration Name: Case3_SSLConfig Trust store name: Case3_TrustStore Keystore name: Case3_KeyStore Default server certificate alias : (none) Default client certificate alias : (none) Management scope: (cell): cell name d.) Modify the new SSL configuration to use a specific cipher suite. The System z crypto hardware supports the RSA, AES and Triple DES algorithms. Selecting cipher suites which use other algorithms (for example RC4) will result in the operations being performed in software. Not setting the new SSL configuration to use only hardware enabled cipher suites will allow the browser to choose between the various cipher suites, increasing the probability that encryption will be performed in software. For instance, Internet Explorer will choose the RC4 algorithm, which will be performed in software. Example: forcing the use of SSL_RSA_WITH_AES_128_CBC_SHA: Security > SSL Certificate and key management > SSL Configurations Click on Case3_SSLConfig Click on Quality of protection (QoP) settings Set Cipher suite groups to Custom. Holding down the Ctrl key on your keyboard and using the left mouse button, highlight all ciphers in the Selected ciphers column, then click <<Remove, to removed them from the Selected ciphers. Then click SSL_RSA_WITH_AES_128_CBC_SHA in the Cipher suites column and click the Add>> button to move it to the Selected ciphers column. The ciphers in the Selected ciphers column are the ciphers that will be used. Assign the new Case3_SSLConfig to the server, Node, etc. that you enabled with the IBMJCECCA provider in Step 2. a.) Use the admin console to assign the SSL configuration: Security > SSL certificate and key management > Manage endpoint security configurations COPYRIGHT IBM CORPORATION, 2012 Page 4 of 7

5 STEP 5: Expand the Inbound setting, then expand the nodes folder. To assign the SSL configuration at the Node level, click the node name you wish to set. To assign the SSL configuration at the Server level, click the + sign next to the appropriate Node name to expand it. Then click the servers folder to expand it. Then click the server name you wish to set. b.) Repeat Step 4.a for the Outbound setting: Security > SSL certificate and key management > Manage endpoint security configurations Expand the Outbound setting, then expand the nodes folder. To assign the SSL configuration at the Node level, click the node name you wish to set. To assign the SSL configuration at the Server level, click the + sign next to the appropriate Node name to expand it. Then click the servers folder to expand it. Then click the server name you wish to set. On servers where crypto hardware has been enabled in the previous steps, the following Java properties are necessary to ensure the best performance. -Dibm.DES.usehdwr.size=0 -Dibm.hwrandom.usessl=true To define these properties: In the admin console, Environment > WebSphere variables > set Scope to the appropriate level. COPYRIGHT IBM CORPORATION, 2012 Page 5 of 7

6 Click New, to define a new environment variable For Name: IBM_JAVA_OPTIONS For Value: -Dibm.DES.usehdwr.size=0 -Dibm.hwrandom.usessl=true Save and sync. Stop and restart all components of your cell that you have configured to use crypto hardware in the above steps. The components should come up and communicate normally with the Deployment Manager. In the admin console, System administration > Nodes, and Node agents should display as synchronized. STEP 6: RACF and other SAF-compliant external security managers can protect the use of ICSF cryptographic services through the use of resource rules in the CSFSERV class. If your installation has the CSFSERV class active and rules defined to prevent use of ICSF services by default, your WebSphere server will be unable to support SSL until it has been permitted to the required CSFSERV rules by the security administrator. If ICSF services are protected, and the WebSphere server does not have permission to use them required ICSF services, the admin console and other SSL protected resources will not be accessible. On a RACF system, you should see ICH408I messages in the system log indicating which CSFSERV permissions the server lacks. On non-racf systems there are typically no ICH408I equivalent messages in the system log, but running a violation report against the WebSphere control and servant region userids may uncover similar permission failure information. If the CSFSERV class is active, the specific CSFSERV rules which your WebSphere server must be permitted to will depend upon the value of the CHECKAUTH option in the ICSF installation options dataset. CHECKAUTH controls whether ICSF bypasses CSFSERV rule checking for processes that run in supervisor state (the WebSphere control region runs in supervisor state). If CHECKAUTH(NO), which is the default value, the servant region userid will need READ access to these CSFSERV class profiles: CSFIQA,CSFOWH, CSFPKI, CSFDSG, CSFDSV and CSFRNGL. If CHECKAUTH(YES), the servant region will need READ access to the six CSFSERV class profiles just mentioned, and the control region will need READ access to these CSFSERV class profiles: CSFIQA,CSFOWH, CSFPKI, CSFDSG, CSFDSV, CSFRNGL, CSFPKE and CSFPKD. In addition, RACF and other SAF-compliant external security managers can protect the use of ICSF keys through the use of resource rules in the CSFKEYS class. If the certificates used by your WebSphere server were created with private keys in ICSF (by using the RACDCERT GENCERT command with the ICSF, PCICC or FROMICSF option), and the RACF CSFKEYS class is active, your WebSphere control region will need permission to use its private key. Again, ICH408I messages or a violation report will provide indications if this is the case. COPYRIGHT IBM CORPORATION, 2012 Page 6 of 7

7 TROUBLESHOOTING NOTES: Components of the cell that use a java.security file enabled for IBMJCECCA support require that hardware cryptography be available and ICSF up and ready. Components that are enabled to use IBMJCECCA support will not work correctly if ICSF is not up and ready on that LPAR. In order to use the Case3_SSLConfig, the component must also use a java.security file enabled for IBMJCECCA support. If this is not true, the component will start, but SSL will fail, and the server will include messages indicating that certificates are missing from the trust chain. Accessing the component using https will result in an SSL protocol error message on the browser. If ICSF is stopped after the hardware cryptography enabled cell components are started, the components will continue running but SSL connections will stop. If ICSF is started again, the components will rediscover ICSF and SSL will begin functioning again. COPYRIGHT IBM CORPORATION, 2012 Page 7 of 7