ncipher modules Integration Guide for IBM Tivoli Access Manager for e-business 6.1 Windows Server 2003 32-bit and 64-bit Windows Server 2008 32-bit and 64-bit
Version: 1.2 Date: 22 December 2009 Copyright 2009 ncipher Corporation Ltd. All rights reserved. These installation instructions are intended to provide step-by-step instructions for installing ncipher software with third-party software. These instructions do not cover all situations and are intended as a supplement to the ncipher documentation provided with ncipher products. Disclaimer: ncipher Corporation Ltd disclaims all liabilities regarding third-party products and only provides warranties and liabilities with its own products as addressed in the Terms and Conditions for Sale. ncipher is a registered trademark of ncipher Corporation Limited. Any other trademarks referenced in this document are the property of the respective trademark owners. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 2
Contents 1. Introduction 4 2. Supported ncipher functionality 6 3. Requirements 6 4. Procedures 7 5. Installing the HSM 7 6. Installing the ncipher support software and creating the security world 8 7. Installing and configuring IBM TAM for e-business 6.1 9 7.1. Tivoli Access Manager Base components 9 7.2. Installing and configuring IBM Tivoli Access Manager WebSEAL 10 8. Configuring WebSEAL to use the HSM for Acceleration Only 11 9. Configuring WebSEAL to use the HSM for Key Management and Acceleration 11 9.1. Configuring the ikeyman utility to use the ncipher PKCS #11 library and request a certificate 11 9.2. Configuring WebSEAL to use the ncipher PKCS #11 library 12 10. Testing the WebSEAL 13 11. Key import using GSKit 14 11.1. Creating a signed certificate and CMS key database (for software keys) 14 11.2. Importing keys using non-fips and FIPS Security Worlds 15 12. Troubleshooting 16 13. Addresses 18 Integration Guide for IBM Tivoli Access Manager for e-business 6.1 3
1. Introduction IBM Tivoli Access Manager (TAM) for e-business is a versatile solution for authentication and authorization problems. It manages growth and complexity, controls management costs, and addresses the difficulty of executing security policies across a wide range of Web and application resources. In particular, it: Defines and manages centralized authentication, access, and the audit policy for a broad range of business initiatives. Establishes new audit and reporting services that collect audit data from multiple enforcement points, platforms, and security applications. Enables flexible single sign-on (SSO) to Web-based applications that can span multiple sites or domains with a range of SSO options in order to eliminate help-desk calls and other security problems associated with multiple passwords. Leverages the common security policy model with the IBM TAM family of products to extend support to other resources. Provides a modular authorization architecture that separates security code from application code. Below is the architecture overview of how IBM TAM for e-business works: Integration Guide for IBM Tivoli Access Manager for e-business 6.1 4
The Hardware Security Module (HSM) secures the keys generated and used by the IBM TAM for e-business. You can integrate the IBM TAM for e-business with an HSM by using the ncipher PKCS #11 interface. The benefits of using an HSM with the IBM TAM for e-business are: Secure storage of the private key. FIPS 140-2 level 3 validated hardware. Improved server performance through offloading of cryptographic processing. Full life cycle management of the keys. Failover support. Load balancing between modules. This document explains how to set up and configure the IBM TAM for e-business with an HSM. The instructions in this document have been thoroughly tested and provide a straightforward integration process. There may be other untested ways to achieve interoperability. This document may not cover every step in the process of setting up all the software. This document assumes that you have read your HSM documentation and that you are familiar with the documentation and setup process for the IBM TAM for e-business. For more information about installing the IBM TAM for e-business, refer to the IBM TAM for e-business documentation. The integration between the HSM and the IBM TAM for e-business has been tested for the following combinations: Operating system IBM TAM version ncipher version PCI support nethsm support Windows Server 2003 SP2 32-bit Windows Server 2003 SP1 64-bit Windows Server 2008 SP1 32-bit Windows Server 2008 SP1 64-bit 6.1 11.11 Yes Yes 6.1 11.11 Yes Yes 6.1 11.11 Yes Yes 6.1 11.11 Yes Yes For more information about OS support, contact your IBM sales representative or Thales Support. For more information about contacting Thales, see Addresses at the end of this guide. Additional documentation produced to support your ncipher product can be found in the document directory of the CD-ROM or DVD-ROM for that product. Note Throughout this guide, the term HSM refers to nshield PCI modules, nethsm units, and nshield Connect units. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 5
2. Supported ncipher functionality Soft Cards Key Management Strict FIPS Support Key Recovery Module Only Key K-of-N Card Set Key Generation Key Import Fail Over Fall Back Load Balancing Preload support 3. Requirements Before attempting to install the software, we recommend that you familiarize yourself with the IBM TAM for e- business documentation and setup process and that you have the ncipher documentation available. You also need to know the following: The number and quorum of Administrator Cards in the Administrator Card Set (ACS), and the policy for managing these cards. Whether the application keys are protected by the module or an Operator Card Set (OCS). The number and quorum of Operator Cards in the OCS, and the policy for managing these cards. Whether the security world should be compliant with FIPS 140-2 level 3. Key attributes such as the key size, persistence, and time-out. Whether there is any need for auditing key usage. For more information, refer to the User Guide for the HSM. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 6
4. Procedures To set up and configure the IBM TAM for e-business with an HSM: 1. Install the ncipher Support Software, and configure the ncipher HSM. 2. Install and configure IBM TAM for e-business 6.1. 3. Configure WebSEAL to either: a. Use the ncipher HSM for Acceleration Only. b. Use the ncipher HSM for Key Management and Acceleration. 4. Test the WebSEAL 5. Import keys using GSKit. These procedures are described in the following sections. 5. Installing the HSM Install the HSM using the instructions in the Hardware Installation Guide for the HSM. We recommend that you install the HSM before configuring the ncipher software and before installing and configuring the IBM TAM for e-business 6.1. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 7
6. Installing the ncipher support software and creating the security world To install the ncipher Software and create the security world: 1. Install the latest version of the ncipher support software with the PKCS #11 components selected as described in the User Guide for the HSM. Note We recommend that you always uninstall any existing ncipher software before installing the new ncipher software. 2. Open the file named cknfastrc in the directory where the ncipher software is installed. The default directory is: 32-bit: C:\Program Files\nCipher\nfast 64-bit: C:\Program Files (x86)\ncipher\nfast 3. Add the following environment variable to the file: CKNFAST_NO_UNWRAP=1 For multiple module support, using a 1/N card set or a softcard, also add the following environment variables to the file: CKNFAST_NO_REMOVABLE=1 CKNFAST_LOADSHARING=1 CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all For a FIPS 140-2 level 3-complaint security world, also add the following environment variable to the file: CKNFAST_NO_SYMMETRIC=1 If module/accelerator-protected keys are supported, also add the following environment variable to the file: CKNFAST_FAKE_ACCELERATOR_LOGIN=1 4. Initialize a security world and create a 1/N Operator Card Set or softcards with a pass phrase. For more information about the environment variables used in cknfastrc, refer to the ncipher PKCS #11 library environment variables section in the User Guide for the HSM. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 8
7. Installing and configuring IBM TAM for e-business 6.1 To install and configure IBM TAM for e-business 6.1: 1. Install IBM Java (ibm-java2-sdk-50-win-i386.exe). 2. Install the GSKit ikeyman utility. 3. Install Tivoli Security Utility 6.1 (included in the IBM TAM package). A number of base components are installed; see Tivoli Access Manager Base components below. 4. Install IBM DB2. 5. Install the Tivoli Directory Server. 6. Configure the installed base components using the Access Manager Configuration window (Start > All Programs > IBM Tivoli Access Manager > Configuration). For each package in turn, select the package, and click Configure. 7. Ensure that the following services are running: Access Manager Authorization Server. Access Manager Auto-Start Service. Access Manager Policy Server. 8. Install IBM Tivoli Access Manager WebSEAL. 9. Check the default SSL connection by opening the following URL in a Web browser: https://<machinename>:443. If you are prompted to enter the WebSEAL Administrator ID and Administrator password, this means that the connection is working. 7.1. Tivoli Access Manager Base components The following components are required to establish a management domain: IBM Global Security Kit (GSKit), which provides Secure Sockets Layer (SSL) data encryption between IBM Tivoli Access Manager systems and supported directories. The GSKit package provides the ikeyman key management utility, gsk7ikm, which is used to create key databases, public-private key pairs, and certificate requests to establish the secure socket layer. IBM DB2 Universal Database, Enterprise Server Edition, also referred as the Authorization Database in Tivoli Access Manager environment. The Authorization Database authorizes or gives permission to the user to access the requested resource. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 9
IBM Tivoli Directory Server (client, server, and proxy server), also known as the Registry Server, which provides a database of the user identities known to Tivoli Access Manager and a representation of groups in Tivoli Access Manager roles that are associated with users. Other Tivoli Access Manager components that must be installed include: Access Manager Runtime, which contains runtime libraries and supporting files that applications use to access Tivoli Access Manager servers. Access Manager Policy Server, which maintains the master authorization database for the management domain and the policy databases associated with other secure domains. This server has a central role in the processing of access control, authentication, and authorization requests. Access Manager Policy Proxy Server, a proxy server used to isolate and protect the IBM Tivoli Access Manager Policy Server from direct access. It acts as a client to the policy server and runs on behalf of the policy server for a number of authorization applications and administrative functions. Access Manager Authorization Server, which provides access to the authorization service for third-party applications that use the Tivoli Access Manager authorization API in remote cache mode. The authorization server also acts as a logging and auditing collection server, storing records of server activity. Access Manager Web Portal Manager, a Web-based graphical user interface (GUI) used for Tivoli Access Manager administration. Similar to the pdadmin command-line interface, this GUI provides management of users, groups, roles, permissions, policies, and other Tivoli Access Manager tasks. Access Manager Java Runtime Environment, a reliable environment for developing and deploying Java applications in a Tivoli Access Manager secure domain. 7.2. Installing and configuring IBM Tivoli Access Manager WebSEAL IBM Tivoli Access Manager Access Manager WebSEAL is a security manager for Web-based resources. WebSEAL is a high performance, multithreaded Web server that applies fine-grained security policy to the protected Web object space. WebSEAL can provide single sign-on solutions and incorporate backend Web application server resources into its security policy. WebSEAL functions as a policy enforcer, deciding whether a user has been appropriately authenticated (at the user registry) and authorized by the database. Before installing WebSEAL ensure that Access Manager Authorization Server, Access Manager Auto-Start Service, Access Manager Policy Proxy Server and Access Manager Policy Server services are running. To install and configure WebSEAL, run the installer setup.exe located in the following directory on the CD windows\policydirector\disk Images\Disk1. Note Note This installer also installs the Tivoli Access Manager Access Manager Web Security Runtime as requisite for the WebSEAL. By default, the WebSEAL server instance name created during the installation and configuration is default. You can choose to enter a different name during the installation and configuration process. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 10
8. Configuring WebSEAL to use the HSM for Acceleration Only By default, the HSM is configured and enabled for acceleration with WebSEAL. To configure WebSEAL to use the HSM for acceleration only, disable the HSM s key management functionality: 1. Open the WebSEAL configuration file. The default location is C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf. 2. Locate [ssl] section, and set the disable-ncipher-bsafe variable to yes: disable-ncipher-bsafe = yes 9. Configuring WebSEAL to use the HSM for Key Management and Acceleration 9.1. Configuring the ikeyman utility to use the ncipher PKCS #11 library and request a certificate To configure the ikeyman utility to use the ncipher PKCS #11 library (cknfast.dll) and request a certificate: 1. Insert the Operator Card in the card reader. 2. Open the IBM Key Management window by running C:\Program Files\ibm\gsk7\bin\gsk7ikm.exe. 3. Select Key Database File > Open. 4. For Key database type, select CMS Cryptographic Token. 5. Navigate to C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll, and click OK. The Open Cryptographic Token window appears. 6. For Cryptographic Token Label, select <Token Name>, then enter the Cryptographic Token Password. 7. Ensure that Open existing key database is selected. 8. Navigate to and select the default WebSEAL Key database file C:\Program Files\Tivoli\pdweb\www\certs\pdsrv.kdb, and click OK. 9. When prompted, enter the default password (pdsrv), and click OK to return to the main IBM Key Management window. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 11
10. For key database content, select Personal Certificate Requests, and click New. 11. Enter the Key Label and other details in Create New Certificate Request, and click OK. 12. Send the certificate request to any Certificate Authority (CA), and obtain the signed certificate and CA root certificate. 13. For key database content, select Signer Certificates. Click Add to add the Signer Certificate for the Trust which is downloaded from certificate Authority to ikeyman, navigate to CA root certificate, and click OK. 14. For key database content, select Personal Certificates. Click Receive to receive the signed certificate (Server Certificate) that protects the WebSEAL in SSL mode with Token Authentication, navigate to signed certificate, and click OK. IBM Key Management window shows the token name with the certificate label (<TokenName>:<Certificate Label>). Note If a new database file is created instead of the default WebSEAL key database file (pdsrv.kdb), ensure that the same paths (for key and stash files) are reflected in the WebSEAL configuration file. 9.2. Configuring WebSEAL to use the ncipher PKCS #11 library To configure WebSEAL to use the ncipher PKCS #11 library: 1. Open the WebSEAL configuration file. The default location is C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf. 2. Locate [ssl] section, and identify the location of the shared library by adding the appropriate path (all on one line): pkcs11-driver-path = C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll 3. Also in the [ssl] section of the WebSEAL configuration file, enter the names of the token label and password (such as the OCS pass phrase): pkcs11-token-label = <token name> pkcs11-token-pwd = <password> For example: [ssl] pkcs11-token-label = websealtoken pkcs11-token-pwd = 123456 4. Save your changes, and close the WebSEAL configuration file. 5. Configure WebSEAL to use the new hardware-based key (instead of the default key in its communications with browser clients): a. Open the webseald.conf configuration file. b. Locate the [ssl] section, and set the webseal-cert-keyfilelabel parameter to the new key label: webseal-cert-keyfile-label = <token-name>:<key-label> For example: Integration Guide for IBM Tivoli Access Manager for e-business 6.1 12
webseal-cert-keyfile-label = websealtoken:webseal 6. Restart the WebSEAL server using Windows Services to make all of the cryptographic hardware configurations take effect. 10. Testing the WebSEAL WebSEAL uses the following default ports: 80 for HTTP. 443 for HTTPS. To test the WebSEAL: 1. Open a Web browser, and enter one of the following: https://<systemname>:443 https://<systemname> For example: https://machinename:443 2. Check the certificate when it is displayed. 3. To view the page, enter the WebSEAL Administrator ID and Password. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 13
11. Key import using GSKit This section describes how to import the software-protected keys into the hardware-protected key database using the ncipher PKCS #11 library. This process involves: 1. Creating a signed certificate and CMS key database (for software keys). 2. Importing keys using non-fips and FIPS Security Worlds. 11.1. Creating a signed certificate and CMS key database (for software keys) To create a signed certificate and CMS key database: 1. Open the IBM Key Management window by running C:\Program Files\ibm\gsk7\bin\gsk7ikm.exe. 2. Select Key Database File > New. 3. For Key database type, select CMS. 4. Save the key database to the default file name and location: C:\Program Files\ibm\gsk7\bin\key.db. 5. When prompted enter the password, then enter it again to confirm. 6. Select Stash the password to a file? in the Password Prompt window, and click OK. 7. For key database content in the IBM Key Management window, select Personal Certificate Requests, and then select the New tab. 8. For Create New Certificate Request, enter the Key label, and click OK. 9. Send the certificate request to any Certificate Authority (CA), and obtain the signed certificate and CA root certificate. 10. For key database content, select the Signer Certificates, and then click Add to add the Signer Certificate for the Trust store (which is obtained from the CA to the gsk7ikeyman). 11. For key database content, select Personal Certificate, and then click Receive to receive the signed certificate (Server Certificate) to protect the WebSEAL in SSL mode with software-based keys of type CMS. The certificate label (* Certificate Label>) is displayed. 12. Close the IBM Key Management window. 13. Configure the WebSEAL in software key protection mode, and then restart the WebSEAL. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 14
11.2. Importing keys using non-fips and FIPS Security Worlds To import keys using non-fips and FIPS Security Worlds: 1. Insert the OCS in card reader. 2. Open the IBM Key Management window by running C:\Program Files\ibm\gsk7\bin\gsk7ikm.exe. 3. Select Key Database File > New. 4. For Key database type, select CMS Cryptographic Token. 5. Navigate to the location of the PKCS #11 library (by default, C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll), and click OK. The Open Cryptographic Token window appears. 6. For Cryptographic Token Label, select <Token Name>, and enter the Cryptographic Token Password. 7. Ensure both Create new secondary key database file and Open existing secondary key database file are not selected, and click OK. 8. Click Import. 9. For Key file type, select CMS, and enter the location of the software key database. 10. Enter the password that protects the software key database. 11. From the list of keys in the key database to import into the hardware-protected key database, select Softkey label, and click OK. The token name with certificate label (<TokenName>:<Certificate Label>) is displayed. 12. Configure the WebSEAL for hardware protection by entering the token name, the certificate label name, and the path to the PKCS #11 library in the SSL section. Note This process allows key importation to both non-fips and FIPS Security Worlds. Normally, it is not possible to import keys to FIPS Security Worlds. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 15
12. Troubleshooting Problem The IBM Tivoli Directory server is installed in configuration mode (The attribute value ibmslapdisconfigurationmode is set as TRUE). Resolution Solution 1: It does not show any suffix in namingcontexts when you connect it through any client, even though the console shows the required suffixes. There is an error in ibmslapd.log that states GLPSRV114E Server failed to start normally with SSL; starting in configuration only mode without SSL. The proxy server is not configured in this mode because it is unable to obtain the secauthority=default suffix. 1. Check the installation of GSKit or uninstall the previous version. 2. Delete the GSKit registry entry. 3. Install GSKit and restart the Directory Server. 4. Check for the required suffixes. Solution 2: 1. Using the IBM TAM Dir Server Instance Admin Tool, delete the directory instance and the associated database. 2. Create a New Directory Server instance without default values, but do not create the Default Dir Server. 3. Add the required suffixes, for example: secauthority=default o=ibm. Problem Resolution There is a file not found error (for example: HPDHZ0021E this file could not be found C:\Program) during the installation of TAM Dir Server while specifying the second CD-ROM path. 1. Uninstall the previous installation. 2. Delete all the associated folders and registry entries. 3. Change the installation directory path from C:\Program files\ibm to C:\IBM. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 16
Problem Resolution The authentication mechanism is not available during the configuration of the proxy server (HPDIA0119W). Check that the Directory Server is started and the required suffixes are available from namingcontext. Integration Guide for IBM Tivoli Access Manager for e-business 6.1 17
13. Addresses Americas 2200 North Commerce Parkway Suite 200 Weston Florida 33326 USA Tel: +1 888 744 4976 or + 1 954 888 6200 sales@thalesesec.com Asia Pacific Units 2205-06 22/F Vicwood Plaza 199 Des Voeux Road Central Hong Kong PRC Tel: + 852 2815 8633 asia.sales@thales-esecurity.com Australia 103-105 Northbourne Avenue Turner ACT 2601 Australia Tel: +61 2 6120 5148 sales.australasia@thales-esecurity.com Europe, Middle East, Africa Meadow View House Long Crendon Aylesbury Buckinghamshire HP18 9EQ UK Tel: + 44 (0)1844 201800 emea.sales@thales-esecurity.com Internet addresses Web site: Support: Online documentation: International sales offices: www.thalesgroup.com/iss http://iss.thalesgroup.com/en/support.aspx http://iss.thalesgroup.com/resources.aspx http://iss.thalesgroup.com/en/company/contact%20us.aspx Integration Guide for IBM Tivoli Access Manager for e-business 6.1 18