Print-friendly Version

Configuring Solaris Cryptographic Framework and Sun Java System Web Server 7 on Systems With UltraSPARC T1 Processors

Jyri J. Virkki, September 2006

Abstract: This document gives a quick overview of several technologies that can provide an optimal platform for hosting Secure Socket Layer (SSL)-enabled web servers: Sun Java System Web Server 7, Solaris Cryptographic Framework, and servers using UltraSPARC T1 processors.

1. Sun Java System Web Server 7

Sun Java System Web Server is known for its performance and particularly for its ability to scale when run on multiple CPUs or, as seen in recent industry trends, on multiple cores.

As of the date of this writing, the Sun Java System Web Server 7 product is in a technology preview phase. It is scheduled to be released for production in the coming months. More information, including download links for the preview, is available from the main product page for Sun Java System Web Server.

2. Network Security Services (NSS)

To make use of SSL/TLS, NSS needs access to a number of cryptographic algorithm implementations. Providers that implement the PKCS#11 Cryptographic Token Interface can be plugged into NSS to provide access to these concrete algorithm implementations. NSS includes a built-in "soft token" library that implements all the necessary algorithms in the software. This is the default provider used by NSS and is the one most commonly used in deployments of Sun Java System Web Server.

It is also possible to plug external PKCS#11 libraries into NSS in order to use alternate algorithm implementations. The most common use of this is to delegate computationally expensive crypto operations to a hardware accelerator such as the Sun Cryptographic Accelerators. While this has been the most common use case, it is also possible to plug in software-only PKCS#11 libraries.

For general information about NSS, refer to the Overview of NSS.

You should also become familiar with the NSS CLI tools from Mozilla.org:

• Certificate Database Tool (certutil)
• Security Module Database (modutil)
• PKCS#12 utility (pk12util)

3. Solaris Cryptographic Framework

Solaris Cryptographic Framework (SCF) provides a common operating system-level framework for providing, consuming, and administering cryptographic services. Various providers (as user space libraries, kernel modules, or hardware drivers) can be plugged into SCF.

• System Administration Guide: Security Services: Chapter 13. Solaris Cryptographic Framework (Overview)
• Solaris Security for Developers Guide: Chapter 8. Introduction to the Solaris Cryptographic Framework

Solaris Cryptographic Framework also implements the PKCS#11 API. This means that it is possible to use the SCF PKCS#11 interface as the crypto provider for NSS -- see libpkcs11(3LIB). As with NSS, SCF includes a software-only implementation of the necessary crypto algorithms, which is useful when you don't have a hardware accelerator available; see pkcs11_softtoken(5) for details.

The cryptoadm command is the main administrative interface to the SCF. Read its manual page cryptoadm(1M) for details.

The manual pages are also available online if you don't have immediate access to a machine running the Solaris 10 OS:

• libpkcs11(3LIB) in man pages section 3: Library Interfaces and Headers
• pkcs11_softtoken(5) in man pages section 5: Standards, Environments, and Macros
• cryptoadm (cryptographic framework administration) in man pages section 1M: System Administration Commands

4. UltraSPARC T1 Processor

Much has been written about the revolutionary UltraSPARC T1 CPU, with up to eight cores and each core supporting four hardware execution threads. Since most applications perform both computation and I/O, it is possible to scale well past the eight physical cores. An additional benefit is that the UltraSPARC T1 consumes significantly less power than equivalent processors, an increasingly important consideration in modern data centers.

A web server, with its mixture of computation and I/O, turns out to be a good fit for the UltraSPARC T1 processor. The Java System Web Server with its highly optimized threaded architecture appears to be a particularly good match.

You can find more information on the UltraSPARC T1 processor under sun.com's Detailed View page.

4.1 ncp -- Niagara Crypto Provider Device Driver

Less talked about is that each of the cores contains a Modular Arithmetic Unit (MAU), a hardware accelerator for modular operations such as those heavily used by public key crypto algorithms like RSA. So, in effect, if you run your web server on a system using the UltraSPARC T1 processor, you already have a built-in hardware crypto accelerator.

ncp is a driver for this hardware and it plugs into the SCF as any other provider.

You can list available and configured providers with cryptoadm list. Here's partial output from the Solaris 10 OS running on a system with an UltraSPARC T1 processor, showing the NCP hardware device:

% cryptoadm list

User-level providers:
Provider: /usr/lib/security/$ISA/pkcs11_kernel.so
Provider: /usr/lib/security/$ISA/pkcs11_softtoken.so
[...]
Kernel hardware providers:
           ncp/0

Additional information can be found under ncp(7D) in Solaris 10 Reference Manual Collection, man pages section 7: Device and Network Interfaces.

5. Putting the Pieces Together

The best part is that making all these complementary technologies work together is fairly straightforward. This section will go over the necessary steps. The examples are based on Sun Java System Web Server 7.

These steps assume you already have a server instance installed and configured to use SSL using the default NSS soft token. (A private key has been generated and a certificate issued.)

5.1 Initialize the SCF Soft Token

As with the NSS built-in token, the SCF software token is protected by a password since it can contain private key material. Start by setting a password for it with the pktool(1) command:

% pktool setpin
Enter new PIN:
Re-enter new PIN:
%

You may notice that this initializes the soft token data store in the $HOME/.sunw/pkcs11_softtoken/ directory. These files are created so they are accessible only to the owner in order to protect their contents. This also means that you need to perform this initialization as the same user that will be used to run the web server, so you will have access to the right data store.

More information can be found at the pktool(1) man page.

5.2 Configure NSS to Use SCF libpkcs11

Next you need to plug in the Solaris libpkcs11 library as a PKCS#11 provider for NSS in order to have NSS delegate the appropriate operations to it. Configuration of PKCS#11 modules in NSS is done with the modutil command (from the SUNWtlsu package).

Start by checking the usage of modutil by entering it without any options:

% modutil
ERROR: No command was specified.

Netscape Cryptographic Module Utility
Usage: modutil [command] [options]

                            COMMANDS
---------------------------------------------------------------------------
-add MODULE_NAME                 Add the named module to the module database
   -libfile LIBRARY_FILE         The name of the file (.so or .dll)
                                 containing the implementation of PKCS #11
   [-ciphers CIPHER_LIST]        Enable the given ciphers on this module
   [-mechanisms MECHANISM_LIST]  Make the module a default provider of the
                                 given mechanisms
[...deleted...]
Mechanism lists are colon-separated.  The following mechanisms are recognized:
RSA, DSA, RC2, RC4, RC5, DES, DH, FORTEZZA, SHA1, MD5, MD2, SSL, TLS, 
RANDOM, FRIENDLY
[...deleted...]

Before adding new modules, let's take a look at the default setup. Start with a Sun Java System Web Server 7 installation where SSL/TLS has been configured with the usual default settings, to use the NSS built-in soft token. Before typing the following I changed to the config/ directory of the server instance I will be operating on. (You could issue the command from elsewhere by giving the appropriate path to -dbdir instead.)

% modutil -list -dbdir .
Using database directory ....

Listing of PKCS #11 Modules
-----------------------------------------------------------
  1. NSS Internal PKCS #11 Module
         slots: 2 slots attached
        status: loaded

         slot: NSS Internal Cryptographic Services
        token: NSS Generic Crypto Services

         slot: NSS User Private Key and Certificate Services
        token: NSS Certificate DB

  2. Root Certs
        library name: libnssckbi.so
         slots: There are no slots attached to this module
        status: Not loaded
-----------------------------------------------------------

The output tells us that only one PKCS#11 module is installed, the internal one. (The second entry is a special module that contains only data; specifically, it contains the well-known CA root certs that are included with NSS.)

Now let's add the SCF provider; I'll call it scf. (For a 64-bit server use /usr/lib/64/libpkcs11.so instead.)

% modutil -dbdir . -add "Solaris Crypto Framework" -libfile \
/usr/lib/libpkcs11.so 
-mechanisms RSA

WARNING: Performing this operation while the browser is running could cause
corruption of your security databases. If the browser is currently running,
you should exit browser before continuing this operation. Type
'q <enter>' to abort, or <enter> to continue:

Using database directory ....
Module "Solaris Crypto Framework" added to database.

% modutil -enable "Solaris Crypto Framework" -dbdir .
[...]
Slot "Sun Metaslot" enabled.
Slot "ncp/0 Crypto Accel Asym 1.0" enabled.

The warning about browsers is probably due to the historical origins of NSS and is not meaningful in this context as we are not modifying files that are used by any browser. The web server does not write to the NSS database files so there is no corresponding danger. However, you will need to restart the web server after all this configuration work so you might as well stop it meanwhile.

The mechanism option deserves some comment. From the modutil help output you can see the list of mechanisms recognized by NSS. Adding the scf provider as the default provider for a given mechanism (via the -mechanism option) requests that this module should be used for operations that use that mechanism. However, operations involving private keys or material derived from private or secret data are "sticky" to the module containing the private key. So if the server commences a sequence of cryptographic operations that uses a private key from a given module, subsequent related operations will continue to be performed by that module even if they use mechanisms that would otherwise go to a different module. This is why I say that the default mechanism hints, rather than mandates, which module will perform those operations.

The reason for this "sticky" behavior is that many PKCS#11 modules are based on hardware that is used to protect sensitive key data. This is done to avoid exporting either key bits or intermediate results from the secure hardware device into the insecure RAM of the computer. In fact some hardware devices do not support exporting such data, so if the library attempted to do it it would simply fail.

Using the list command now shows the newly installed module:

% modutil -list -dbdir . 

Using database directory ....

Listing of PKCS #11 Modules
-----------------------------------------------------------
 [...]

  2. Solaris Crypto Framework
        library name: /usr/lib/libpkcs11.so
         slots: 2 slots attached
        status: loaded

         slot: Sun Metaslot
        token: Sun Metaslot

         slot: ncp/0 Crypto Accel Asym 1.0
        token: ncp/0 Crypto Accel Asym 1.0

[...]
-----------------------------------------------------------

Next we will disable the following mechanisms in the soft token, forcing them to be performed in the NCP. (Note: This is done as root.)

# cryptoadm disable provider=/usr/lib/security/\$ISA/pkcs11_softtoken.so \
mechanism=CKM_SSL3_PRE_MASTER_KEY_GEN,\
CKM_SSL3_MASTER_KEY_DERIVE,\
CKM_SSL3_KEY_AND_MAC_DERIVE,\
CKM_SSL3_MASTER_KEY_DERIVE_DH,\
CKM_SSL3_MD5_MAC,\
CKM_SSL3_SHA1_MAC

# cryptoadm list -p

User-level providers:
=====================
/usr/lib/security/$ISA/pkcs11_kernel.so: all mechanisms are enabled.
random is enabled.
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled, except
CKM_SSL3_SHA1_MAC,CKM_SSL3_MD5_MAC,CKM_SSL3_MASTER_KEY_DERIVE_DH,
CKM_SSL3_KEY_AND_MAC_DERIVE,CKM_SSL3_MASTER_KEY_DERIVE,
CKM_SSL3_PRE_MASTER_KEY_GEN.
random is enabled.
[...]

5.3 Migrate Key and Certificate Data

Since we started with an instance configured to use SSL via the built-in "internal" token (the NSS soft token), next we need to migrate the server's keypair and certificate into SCF. We can do this by exporting the data from the "internal" token and importing it into the SCF token, using pk12util.

The -o option gives a file name where the data will be stored, and the -n option is used to select the nickname associated with the desired server keypair/cert. (This is the same nickname referenced by the <server-cert-nickname> element in server.xml for this listener.) Check your configuration for the appropriate nickname.

% pk12util -o key-cert-data.pk12 -n cert-hostname  -d .
Enter password for PKCS12 file:
Re-enter password:
pk12util: PKCS12 EXPORT SUCCESSFUL

% pk12util -i key-cert-data.pk12 -d . -h "Sun Metaslot"
Enter Password or Pin for "Sun Metaslot":
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL

% certutil -L -d . -h "Sun Metaslot"
Enter Password or Pin for "Sun Metaslot":
Sun Metaslot:cert-hostname                                u,u,u

Now that the key and cert data is available in the Sun Metaslot, we need to switch the listener to use this token instead of the built-in one. The <server-cert-nickname> value can be prefixed with a token name to indicate which token to use.

In server.xml, I modified this line:

<server-cert-nickname>cert-hostname</server-cert-nickname>

I changed it to:

<server-cert-nickname>Sun Metaslot:cert-hostname</server-cert-nickname>

5.4 Start the Server

Now you can start the server instance through any of the usual means (CLI or GUI).

Note that since the "Sun Metaslot" has a password (the one you set earlier with pktool setpin), starting the server will require this password. You will be prompted:

Please enter the PIN for the "Sun Metaslot" token: 

As with any NSS tokens, you can bypass this prompt (to enable automated server start) by storing the password in server.xml. (Refer to the <token> sub-element of <pkcs11>, which you can set with the wadm set-token-pin command.)

Now you can use the kstat command to observe some statistics on the use of NCP:

% kstat -n ncp0 | grep rsa
      rsaprivate                      10
      rsapublic                       10

As NCP processes RSA operations, these counters will increase. You should see the rsaprivate value increase on every new SSL session that is established. (This occurs only during the initial handshake where these operations are invoked; subsequent client requests from the same client will reuse the same SSL session.)

For More Information

• System Administration Guide: Security Services: Chapter 13. Solaris Cryptographic Framework (Overview)
• Solaris Security for Developers Guide: Chapter 8. Introduction to the Solaris Cryptographic Framework
• ncp in Solaris 10 Reference Manual Collection, man pages section 7: Device and Network Interfaces
• Sun Java System Web Server
• Overview of NSS
• UltraSPARC Processors Documentation

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.