Level: Intermediate Deepak Kaul (deepakkaul@in.ibm.com), System Software Engineer, IBM India
Sunil K. Verma (sunverma@in.ibm.com), System Software Engineer, IBM India
Eric YH Huang (yhhuang@tw.ibm.com), Advisory IT Specialist, IBM Taiwan
04 Oct 2007 The most computationally expensive part of establishing an SSL session is decryption of the SSL session's public key sent to an SSL server. By offloading SSL operations to a dedicated hardware device, like the IBM 4960 SSL accelerator, customers can achieve greater performance throughput using fewer CPU cycles. This article outlines the detailed configuration steps to enable SSL acceleration for IBM® Tivoli® Access Manager for e-Business (TAMeB) WebSEAL using the IBM 4960 crypto card PKCS#11 interface on the IBM AIX® platform.
Introduction
WebSEAL uses IBM Global Security Kit (GSKit) for all SSL communication. This includes connections between the browser and WebSEAL, WebSEAL and the junctioned backend servers, WebSEAL and the LDAP servers and WebSEAL and the Policy Server. Figure 1 shows the GSKit deployed within the software stack of Tivoli Directory Server and TAMeB WebSEAL. The GSKit provides data encryption, key management and cryptographic services, and it is mandated as the IBM Software Group component used when products are to be delivered requiring this functionality. The GSKit provides the iKeyman key management utility to manage certificate lifecycle management, including creating and managing key databases, public-private key pairs, and creating certificate requests.
Figure 1: GSKit deployed within the software stack of Tivoli Directory Server and TAMeB WebSEAL
IBM 4960 crypto card: In the case of crypto card for acceleration like IBM 4960, WebSEAL and the GSKit pass the private key into the card to be used for the SSL operations. The private key is stored in the WebSEAL/GSKit key database. WebSEAL and the GSKit support the PKCS#11 (Public Key Cryptographic Standard) interface for cryptographic hardware.
The PKCS#11 interface pre-requisite libraries are shipped as shared libraries by IBM. If these libraries are present and WebSEAL and GSKit are configured to use IBM 4960, the GSKit will load the correct library for IBM 4960.
You can use this page, http://www.ibm.com/developerworks/tivoli/library/t-gsk7/index.html, to find the GSKit list of supported crypto devices.
This list shows the crypto cards that are available for WebSEAL use.
The following sections outline the configuration steps that are required to install and configure the IBM 4960 card on AIX with TAMeB WebSEAL. The following high-level steps are required
- Install and configure the IBM 4960 SSL accelerator card
- Set up the GSKit environment
- Configure a self-signed certificate on the PKCS11 token
- Configure the operating system properties
- Add configuration into webseald-default.conf
- Restart WebSEAL Server
- Verify that IBM 4960 is being used by WebSEAL
You can learn more about the benefits of using cryptographic hardware by reading the article “Cryptographic Hardware Use with Tivoli Access Manager for e-Business: SSL Acceleration in WebSEAL with a Hardware Security Module”
1. Install and configure the IBM 4960
Follow the instructions provided by the vendor to install the cryptographic accelerator card and its device driver for IBM 4960. The PKCS #11 subsystem automatically detects cryptographic accelerator devices supporting PKCS#11. However, in order for WebSEAL to use IBM 4960, some initial set up is necessary. . You can find more information about the GSKit device integration in “Resources”.
2. Set up GSKit
a) Set up JAVA™ Environment
JDK™ 1.3.1 is the default JDK for AIX 5L. GSKit 7 only works with JDK 1.4. The purpose of setting the PATH and JAVA_HOME environment variable is so that GSKIT can use JDK 1.4. JDK 1.4 should be the default JDK
Verify current JDK version
# which java
/usr/java131/jre/bin/java
Add JDK 1.4 into PATH if it is not the default JDK
# export PATH=/usr/java14/jre/bin:$PATH
Verify current JDK version
# which java
/usr/java14/jre/bin/java
Set JAVA_HOME
# export JAVA_HOME=/usr/java14
Verify JAVA_HOME
# echo $JAVA_HOME
/usr/java14 |
b) Set up ikeyman configuration
Check the gskit environment
WebSEAL 6.0 works with GSKit version 7.0-3.17 or above. Make sure GSKit version 7.0-3.17 is installed. (GSKit version 7.0-3.17 is shipped with TAMeB 6.0)
# which gsk7ikm
/usr/bin/gsk7ikm
# ls -l /usr/bin/gsk7ikm
lrwxrwxrwx 1 root system 30 Sep 13 10:39 /usr/bin/gsk7ikm -> \
/usr/opt/ibm/gskta/bin/gsk7ikm
|
Perform the following steps to inform the iKeyman utility of the name of the module for managing the IBM 4960 cryptographic card.:
# cd /usr/opt/ibm/gskta/classes
# cp -pr ikmuser.sample ikmuser.properties
# vi ikmuser.properties
-------add following line in ikmuser.properties------------
DEFAULT_CRYPTOGRAPHIC_MODULE=/usr/lib/pkcs11/PKCS11_API.so
----------------------------------------------------------- |
Save the ikmuser.properties file. The configuration steps above need only be performed one time. Every time the iKeyman utility is started, it will read the contents of your ikmuser.properties file. If you place your accelerator card in the card reader and then start the iKeyman utility, the IBM Key Management window will have an additional menu item, the Cryptographic Token.
3. Configure a self-signed certificate on the PKCS11 token
a) Create a new key database
- Start iKeyman by executing gsk7ikm. The IBM Key Management window is displayed.
- Click Key Database File -> New. The New window is displayed.
- Select the CMS key database file for the Key database type field.
- Type a filename, such as pdsrv.kdb
- Accept the default value, "/var/pdweb/www/certs", for Location field or type a new value.
Figure 2: Create a new CMS key database file
- Click OK, The Password Prompt window is displayed.
- Enter a password in the password field, and confirm it again in the Confirm Password field. Click OK.
- A confirmation window is displayed, verifying that you have created a key database. Click OK.
Figure 3: Password Prompt
- After successful key database creation, the IBM Key Management window is displayed which should now reflect your new CMS key database file (for example, /var/pdweb/www/certs/pdsrv.kdb).
b) Open the PKCS11 cryptographic token.
- Launch iKeyman, by executing gsk7ikm
- Select key database type "CMS Cryptographic Token"
- Select File Name = PKCS11_API.so
- Select Location = /usr/lib/pkcs11
Figure 4: Open the PKCS11 cryptographic token
- Click Ok.
- Select Cryptographic Token Label = tokenlabel
- Enter Cryptographic Token Password = passw0rd (this is the user PIN from PKCS11 setup)
- Select Open existing secondary key database file
- Select File Name = pdsrv.kdb
- Select Location = /var/pdweb/www-default/certs
Figure 5: Provide PKCS11 cryptographic token details
- • Verify that the filename and location are correct as generated in Step a). In the Password Prompt window, insert the password of pdsrv.kdb:
Password = pdsrv (default password of pdsrv.kdb)
Figure 6: Password prompt
c) Create a self-signed certificate "www".
- Select Personal Certificates under the drop down menu above the white box.
- Click on the New Self-Signed... button.
- Key Label =
www
(Provide a unique label for this certificate)
- Common Name = tivl2in.ibm.com
- Organization = OPTIONAL
- Country or region = IN
- Validity Period = 3650
Figure 7: Create a self-signed certificate
You should have a certificate in the white box that says <tokenlabel>:<keylabel> when you're finished. At this point, you have a self-signed certificate that is ready for use with IBM 4960.
Figure 8: Self-signed certificate
4. Configuring the operating system properties
The following sections will outline each of these configuration steps in detail.
a) On the WebSEAL host, create a UNIX® user called pkcs11. Also create a UNIX group called pkcs11. Add the ivmgr user to this group.
- Login as root
- Invoke the AIX administration program
- Select Change / Show Characteristics of a Group
- Input pkcs11 in Group NAME
- Input root,ivmgr in User list
-----------user and group info--------------------
[Entry Fields]
Group NAME [pkcs11]
Group ID [209] #
ADMINISTRATIVE group? false +
USER list [root,ivmgr] +
ADMINISTRATOR list [] +
---------------------------------------------------
|
On the WebSEAL servers, modify the ownership of the Tivoli Common Logging sub-directory and the WebSEAL configuration file:
#chown -R ivmgr:pkcs11 /var/ibm/tivoli/common/DPW
#chown ivmgr:pkcs11 /opt/pdweb/etc/webseald-default.conf
|
c) Set the AIX environment variable
The number of data segments that a process is allowed to use on AIX systems limits the process memory size. By increasing the number of data segments, process memory size can also be increased. We suggest that you set the LDR_CNTRL=MAXDATA environment variable before starting WebSEAL." If the above environment variable is not set, WebSEAL might
fail to start. The WebSEAL log file will contain the references to the following error: GSK_ERROR_PKCS11_TOKEN_NOTPRESENT. You can set the environment variable as follows:
#export LDR_CNTRL=MAXDATA=0x60000000
|
5. Add configuration into webseald-default.conf
In the WebSEAL configuration file, modify the WebSEAL instance UNIX group account configuration to specify group pkcs11. This allows WebSEAL to access the PKCS token. Add 4960 related configuration into webseald-default.conf.
- Modify following attributes in the configuration file:
-----------webseal-default.conf------------------
[server]
# WebSEAL instance UNIX user account
unix-user = ivmgr
# WebSEAL instance UNIX group account
unix-group = pkcs11
[ssl]
# Label of key to use other than the default
webseal-cert-keyfile-label = tokenlabel:www (default is WebSEAL-Test-Only)
# The following four entries allow configuration of GSKit support
# for external PKCS#11 libraries. For added protection the pkcs11-token-pwd
# can alternatively be specified obfuscated using:
# # pdadmin -l
# pdadmin local> config modify keyvalue set -obfuscate config-file \
# ssl pkcs11-token-pwd token-password
# Warning: The plaintext value for pkcs11-token-pwd in this file will
# override the obfuscated value.
pkcs11-driver-path = /usr/lib/pkcs11/PKCS11_API.so
pkcs11-token-label = tokenlabel
pkcs11-token-pwd = passw0rd
pkcs11-symmetric-cipher-support = no
# The following two entries allow disabling of GSKit's automatic use
# of nCipher nForce/nFast or Rainbow CryptoSwift Hardware Accelerators via
# their RSA BSAFE interface.
disable-ncipher-bsafe = yes (default is no)
disable-rainbow-bsafe = yes (default is no)
---------------------------------------------------
|
6. Restart the WebSEAL Server
You must restart WebSEAL for SSL Acceleration configuration to take effect.
#/opt/pdweb/bin/pdweb_start start
|
7. Verify that IBM 4960 is being used by WebSEAL
You can verify that WebSEAL is using the cryptographic hardware by examining entries contained in the msg_webseald.log file. If it does not configure properly, the GSKit will show an error message in the msg__webseald-default.log
Also, in the Web browser, you can verify the Web site certificate by clicking the lock in the status bar. You can see the certificate information retrieved from the IBM 4960 crpto card used by WebSEAL
Conclusion
This article describes using a cryptographic hardware device in the Tivoli Access Manager for e-Business environment. It provides the configuration steps for WebSEAL to use crypto card IBM 4960 and verify successful configuration.
Resources
About the authors  | 
| | Deepak Kaul is a System Software Engineer in ISL Pune, working as Tivoli L2 Support. His Focus is on Tivoli Access Manager for e-Business. Deepak holds a Bachelor of Computer Systems Engineering from University of Mumbai. |
| 
| | Sunil is a Software Engineer, currently working with Level 2 Tivoli Security Team, IBM India Software Labs and holds Bachelor of Engineering (Information Technology). His areas of interest are enterprise level security, Single Sign-on (SSO), and Service Oriented Architecture (SOA). He is ITIL foundation-certified and Tivoli Access Manager for e-business V6.0 Implementation-certified. |
| 
| | Eric YH Huang works for Middleware Services of Global Technology Services in IBM Taiwan. He leads a team to deliver middleware services on open system. Focus on J2EE™ and eBusiness Reference Architecture (eBRA) infrastructure design, implementation, testing and maintenance. |
Rate this page
| 
