Installing the PKCS #11 Module

Proxy Server supports Public Key Cryptography Standard (PKCS) #11, which defines the interface used for communication between SSL and PKCS #11 modules. PKCS #11 modules are used for standards-based connectivity to SSL hardware accelerators. Imported certificates and keys for external hardware accelerators are stored in the secmod.db file, which is generated when the PKCS #11 module is installed. The file is located in the server_root/alias directory.

Using modutil to Install PKCS #11 Modules

You can install PKCS #11 modules in the form of .jar files or object files using the modutil tool.

To install PKCS #11 modules using modutil

Steps

1. Make sure all servers, including the Administration Server, have been stopped.

2. Go to the server_root/alias directory containing the databases.

3. Add server_root/bin/proxy/admin/bin to your PATH.

4. Locate modutil in server_root/bin/proxy/admin/bin.

5. Set the environment. For example:

   • On UNIX: setenv

     LD_LIBRARY_PATH server_root/bin/proxy/lib:${LD_LIBRARY_PATH}

     • On Windows, add it to the PATH

       LD_LIBRARY_PATH server_root/bin/proxy/bin

       You can find the PATH for your computer listed under: server_root/proxy-admserv/start.

6. Enter the command: modutil. The options will be listed.

7. Perform the actions required.

   For example, to add the PKCS #11 module in UNIX, enter:

   modutil -add (name of PKCS#11 file) -libfile (your libfile for PKCS #11) -nocertdb -dbdir . (your db directory)

Exporting with pk12util

Using pk12util allows you to export certificates and keys from your internal database and import them into an internal or external PKCS #11 module. You can always export certificates and keys to your internal database, but most external tokens will not allow you to export certificates and keys. By default, pk12util uses certificate and key databases named cert8.db and key3.db.

To export a certificate and key from an internal database

Steps

1. Go to the server_root/alias directory containing the databases.

2. Add server_root/bin/proxy/admin/bin to your PATH.

3. Locate pk12util in server_root/bin/proxy/admin/bin.

4. Set the environment. For example:

   • On UNIX: setenv

     LD_LIBRARY_PATH/server_root/bin/proxy/lib:${LD_LIBRARY_PATH}

     • On Windows, add it to the PATH

       LD_LIBRARY_PATH server_root/bin/proxy/bin

       You can find the PATH for your computer listed under: server_root/proxy-admserv/start.

5. Enter the command: pk12util.

   The options will be listed.

6. Perform the actions required.

   For example, in UNIX enter:

   pk12util -o certpk12 -n Server-Cert [-d /server/alias] [-P https-test-host]

7. Enter the database password.

8. Enter the pkcs12 password.

Importing with pk12util

To import a certificate and key into an internal or external PKCS #11 module

Steps

1. Go to the server_root/alias directory containing the databases.

2. Add server_root/bin/proxy/admin/bin to your PATH.

3. Locate pk12util in server_root/bin/proxy/admin/bin.

4. Set the environment.

   For example:

   • On UNIX: setenv

     LD_LIBRARY_PATH/server_root/bin/proxy/lib:${LD_LIBRARY_PATH}

     • On Windows, add it to the PATH

       LD_LIBRARY_PATH server_root/bin/proxy/bin

       You can find the PATH for your computer listed under: server_root/proxy-admserv/start.

5. Enter the command: pk12util.

   The options will be listed.

6. Perform the actions required.

   For example, in UNIX enter:

   pk12util -i pk12_sunspot [-d certdir][-h “nCipher”][-P https-jones.redplanet.com-jones-]

   -P must follow the -h and be the last argument.

   Enter the exact token name including capital letters and spaces between quotation marks.

7. Enter the database password.

8. Enter the pkcs12 password.

Starting the Server with an External Certificate

If you install a certificate for your server into an external PKCS #11 module (for example, a hardware accelerator), the server will not be able to start using that certificate until you edit the server.xml file or specify the certificate name as described below.

The server always tries to start with the certificate named Server-Cert. However, certificates in external PKCS #11 modules include one of the module’s token names in their identifier. For example, a server certificate installed on an external smartcard reader called smartcard0 would be named smartcard0:Server-Cert.

To start a server with a certificate installed in an external module, you must specify the certificate name for the listen socket on which it runs.

Selecting the Certificate Name for a Listen Socket

To select the certificate name for a listen socket

If security is not enabled on the listen socket, certificate information will not be listed. To select a certificate name for a listen socket, you must first ensure that security is enabled on the listen socket. For more information, see Enabling Security for Listen Sockets.

Steps

1. Access either the Administration Server or the Server Manager and click the Preferences tab.

2. Click the Edit Listen Sockets link.

3. Click the link for the listen socket you want to associate with a certificate.

4. Select a server certificate from the Server Certificate Name drop-down list for the listen socket and click OK.

   The list contains all internal and external certificates installed.

   You could also tell the server to start with that server certificate instead, by manually editing the server.xml file. Change the servercertnickname attribute in the SSLPARAMS to:

   $TOKENNAME:Server-Cert

   To find what value to use for$TOKENNAME, go to the server’s Security tab and select the Manage Certificates link. When you log in to the external module where Server-Cert is stored, its certificates are displayed in the list in the $TOKENNAME:$NICKNAME form.

   ---

   Note –

   If you did not create a trust database, one will be created for you when you request or install a certificate for an external PKCS #11 module. The default database created has no password and cannot be accessed. Your external module will work, but you will not be able to request and install server certificates. If a default database has been created without a password, use the Create Database page on the Security tab to set the password.

   ---