test

Sun Java System Web Server 6.1 SP9 Administrator's Guide

Installing the PKCS#11Module

The Sun Java System Web 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.

Procedure To Install a PKCS#11 Module using the modutil

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

To install the PKCS#11 module using modutil, perform the following steps:

  1. Make sure all servers, including the Administration server, are turned off.

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

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

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

  5. Set the environment. For example:

    • On UNIX: setenv

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

      • On IBM-AIX: LIBPATH

      • On HP-UX: SHLIB_PATH

      • On Windows, add it to the PATH

        LD_LIBRARY_PATH server_root/bin/https/bin

        You can find the PATH for your machine listed under: server_root/https-admin/start.

  6. Enter the modutil command.

    The options are listed.

  7. Perform the required actions required.

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

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

Using pk12util

The 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 export certificates and keys to your internal database, but many external tokens do not let you export certificates and keys. By default, the pk12util uses the cert8.db and key3.db certificate and key databases.

Exporting with pk12util

To export a certificate and key from an internal database, perform the following steps:

ProcedureTo export a certificate and key from an internal database

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

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

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

  4. Set the environment. For example:

    • On UNIX: setenv

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

      • On IBM-AIX: LIBPATH

      • On HP-UX: SHLIB_PATH

      • On Windows, add it to the PATH

        LD_LIBRARY_PATH server_root/bin/https/bin

        You can find the PATH for your machine listed under: server_root/https-admin/start.

  5. Enter the pk12util command.

    The options are listed.

  6. Perform required actions.

    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 command password.

Importing with pk12util

To import a certificate and key into an internal or external PKCS#11 module, perform the following steps:

ProcedureTo import a certificate and key into an internal PKCS#11 module

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

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

  3. Locate the pk12util in the server_root/bin/https/admin/bin.

  4. Set the environment. For example:

    • On UNIX, use the setenv command

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

      • On IBM-AIX, use the LIBPATH command

      • On HP-UX, use the SHLIB_PATH command

      • On Windows, add it to the PATH

        LD_LIBRARY_PATH server_root/bin/https/bin

        The PATH for your machine is listed under the server_root/https-admin/start.

  5. Enter pk12util command.

    The options are listed.

  6. Perform required actions.

    For example, in UNIX enter:

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

    -P must follow the -h option 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 command password. Starting the Server with an External Certificate

    If you install a certificate into an external PKCS#11 module (for example, a hardware accelerator), the server is unable to start using the certificate until you edit the server.xml file, or specify the certificate name.

    The server always tries to start with the “Server-Cert” certificate. Certificates in external PKCS#11 modules contains 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 need to specify the certificate name for the listen socket it runs on.

Selecting the Certificate Name for a Listen Socket

To select the certificate name for the listen socket, perform the following steps:

Note –

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

ProcedureTo select the certificate name for the listen socket

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

    For the Server Manager you must first select the server instance from the drop-down list.

  2. Select the Preferences tab.

  3. Click the Edit Listen Sockets link.

    The Edit Listen Sockets page appears.

  4. Click the Listen Socket Id link corresponding to the listen socket that you want to associate with a certificate.

    The Edit Listen Socket page appears.

  5. Select a server certificate from the drop-down Server Certificate Name list for the listen socket.

    The list contains all internal and external certificates installed.

    Note –

    If no server certificates are installed, a warning to this effect is displayed in place of the Server Certificate Name drop-down list.

  6. Click OK

  7. From the Server Manager, click Apply, and then Restart for changes to take effect.

    You could also tell the server to start with that server certificate 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 have not created a trust database, it is created for you when you request or install a certificate for an external PKCS#11 module. The default database that is created has no password and cannot be accessed. Although your external module works, you cannot request and install server certificates. If a default database has been created without a password, use the Security Tab Create Database page to set a password.