Instructions for Enabling WebSphere for z/os V7 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 V7 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/java64/lib/security/java.security. b.) Rather than modify the java.security file shipped with WebSphere, copy the java.security file to a new location, update the copy, and configure WebSphere to use the new copy. Copy the java security.file from the above location to the Deployment Manager node's: /DeploymentManager/dmnode.java.security After you copy the file, set the ownership of the new file to the cell admin userid and config group, just like the original java.security file. The file permission bits should be 775, just like the original java.security file. If you create a directory for this file (e.g., /DeploymentManager/etc), place it in the Deployment Manager's configuration file system and make certain it has the correct ownership and permission bits set. c.) Using ISPF option 3.17 (the EA option), modify the new dmnode.java.security file to enable the IBMJCECCA provider for the Deployment Manager node: - 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. Remember this file must be in the ASCII code page to be usable. COPYRIGHT IBM CORPORATION, 2012 Page 1 of 7

2 STEP 2: d.) Using the admin console, configure the Deployment Manager node to use the new dmnode.java.security file. Click: Environment > WebSphere variables > set Scope to Node=your DM node, Server=your DM Click New, to define a new environment variable (value on one line). For Name: IBM_JAVA_OPTIONS For Value: -Djava.security.properties=<path_to_dmnode.java.security_file> -Dibm.DES.usehdwr.size=0 -Dibm.hwrandom.usessl=true For example, in our k7 cell the Value is: -Djava.security.properties=/wasv7config/k7cell/k7dmnode/DeploymentManager/dmnode.java.s ecurity -Dibm.DES.usehdwr.size=0 -Dibm.hwrandom.usessl=true The second and third -D values in the above example should be included with the first as one long line, separated by spaces. Save and sync. e.) 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. If you search the DM Controller or Servant sysout for the string java.security.properties, you should find this message indicating that the Deployment manager is using your new modified java.security file: BBOJ0077I: java.security.properties = <location of the modified java.security file> Enable the IBMJCECCA provider on each component of your cell that you want to use hardware cryptography. You can enable the IBMJCECCA provider at the application server level, at the Node level or at the cell level. This process is equivalent to the process you performed for the Deployment Manager in Step 1. If you enable the IBMJCECCA provider on a server or a node, then ICSF must be active on the LPAR containing the node or the cell components on that system will NOT start or work correctly. The details are: a.) Following the process described in steps 1.b and 1.c, create one or more modified java.security file(s). For one or more application servers, you can create a single new java.security file at the Node level of the file system. For multiple Nodes in a shared file system, you can create a single java.security file that can be used by all of the Nodes or even the entire cell. Choose a name for the new java.security file that will remind you of the scope of the cell that it applies to. For example, k7sr01b.java.security for just the k7sr01b server, k7nodeb.java.security for Node B or k7cell.java.security for the whole cell. COPYRIGHT IBM CORPORATION, 2012 Page 2 of 7

3 STEP 3: The original java.security files are identical on the Deployment Manager and all Nodes. This means you can just copy the newly created Deployment Manager's modified java.security file to anywhere you want a modified copy. b.) Using the process described in step 1.d, use the admin console to define the IBM_JAVA_OPTIONS variable at the Scope appropriate to the level you want to enable the IBMJCECCA provider to. You can set the Scope to the cell, Node or Server level. By setting the Scope to a given level, all components of the server at that level will use the modified java.security file you have created. For example, for k7 cell server k7sr01b: Environment > WebSphere variables > set Scope to Node=k7nodeb, Server=k7sr01b Click New, to define a new environment variable. For Name: IBM_JAVA_OPTIONS For Value: -Djava.security.properties=/wasv7config/k7cell/k7nodeb/AppServer/k7sr01b.java.security -Dibm.DES.usehdwr.size=0 -Dibm.hwrandom.usessl=true Save and sync. The -Djava.security.properties variable indicates the location of the modified java.security file. The Scope determines which cell components will use the modified java.security file. All components within the Scope that you set will use the modified java.security file and will require that hardware cryptography be available and ICSF up and ready. Components outside that Scope will continue to use the original unmodified java.security file and will use software encryption. 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: (Note: this management scope indicates the availability of the keystore, not what component it is assigned to. Cell level is a safe choice.) Path: safkeyringhw:///<your cell keyring name> (Note: the path name will be the same as your other cell SAF keyrings, except this one will be COPYRIGHT IBM CORPORATION, 2012 Page 3 of 7

4 safkeyringhw instead of safkeyring.) 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: (Note: this management scope indicates the availability of the truststore, not what component it is assigned to. Cell level is a safe choice.) Path: safkeyringhw:///<your cell keyring name> (Note: the path name will be the same as your other cell SAF keyrings, except this one will be safkeyringhw instead of safkeyring.) Password: password Confirm password: password Type: JCECCARACFKS 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 Management scope: (Note: this management scope indicates the availability of the SSL configuration, not what component it is assigned to. Cell level is a safe choice.) d.) Modify the new SSL configuration to use a specific cipher suite: Security > SSL Certificate and key management > SSL Configurations COPYRIGHT IBM CORPORATION, 2012 Page 4 of 7

5 STEP 4: Click on Case3_SSLConfig Click on Quality of protection (QoP) settings Here you can specify individual Cipher suite settings. For example, to force the use of one cipher suite: Set Cipher suite groups to Custom. Holding down the Ctrl key and using the left mouse button, highlight any cipher in the Selected ciphers column, then click <<Remove, to removed them from the Selected ciphers. Similarly you can highlight ciphers in the Cipher suites column and use the Add>> button to move them to the Selected ciphers column. The ciphers in the Selected ciphers column are the ciphers that will be used. Note: The 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. Leaving the Cipher suite groups set to Strong will allow the browser to choose between the various strong cipher suites, increasing the probability that encryption will be performed in software. For instance, Internet Explorer 8 will choose the RC4 algorithm, which will be performed in software. 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 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. COPYRIGHT IBM CORPORATION, 2012 Page 5 of 7

6 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. c.) Stop and restart the components of your cell that you configured to use a modified java.security file in Step 2. It is not necessary to stop and restart the Deployment Manager again. 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. For any component that you restart, if you search the sysout for the string java.security.properties, you should find this message indicating that the component is using a modified java.security file: BBOJ0077I: java.security.properties = <location of the modified java.security file> STEP 5: 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. COPYRIGHT IBM CORPORATION, 2012 Page 6 of 7

7 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. 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 abend shortly after startup if ICSF is not up and ready. 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