C H A P T E R 7 |
![]() |
This chapter describes how to configure the Sun Crypto Accelerator 6000 Board for use with Sun Java System servers on Oracle Solaris platforms. Additional instructions for Linux platforms are provided. This chapter contains the following sections:
Note - The Sun Java System servers described in this manual were previously named iPlanet servers. |
This section provides an overview of the security features of the Sun Crypto Accelerator 6000 board as it is administered with Sun Java System applications.
Note - To manage keystores, you must have access to the system administrator account for your system. |
Keystores and users must be created for applications that communicate with the Sun Crypto Accelerator 6000 board through a PKCS#11 interface, such as the Sun Java System Applications.
Note - The Apache Web Server (Chapter 8) does not use the keystore or user account features described in this chapter. |
Within the context of the Sun Crypto Accelerator 6000 board, users are owners of cryptographic keying material. Each key is owned by a single user. Each user may own multiple keys. A user might want to own multiple keys to support different configurations, such as a production key and a development key (to reflect the organizations the user is supporting).
A keystore is a repository for key material. Associated with a keystore are security officers and users. Keystores provide not only storage, but a means for key objects to be owned by user accounts. This enables keys to be hidden from applications that do not authenticate as the owner. Keystores have three components:
A typical installation contains a single keystore with three users. For example, such a configuration could consist of a single keystore keystore-name and three users within that keystore, webserv, dirserv, and mailserv. This would enable the three users to own and maintain access control of their server keys within that single keystore. FIGURE 7-1 illustrates an overview of a typical installation.
FIGURE 7-1 Keystore and Users Overview
An administrative tool, scamgr, is used to manage Sun Crypto Accelerator 6000 keystores and users. See Managing Keystores With scamgr.
As discussed in Chapter 6, there are four kinds of slots presented through the Oracle Solaris Cryptographic Framework’s PKCS#11 interface.
The Sun Crypto Accelerator 6000 Keystore slot can also be used for Sun Java System applications. Through a Keystore slot, asymmetric operations are the only mechanisms accelerated by the Sun Crypto Accelerator 6000 board. When there are more than two boards using the same keystore, Keystore slot provides additional performance and fault-tolerance.
If there are two boards, mca0 and mca1, each is assigned a keystore name (engineering and finance), three slots are presented to the Sun Java System application.
If the server certificate resides in the finance keystore, the possible slots to be used for the Sun Java System application is as follows:
2. finance (the Keystore slot)
This section describes assigning passwords, how to populate a keystore, and how to enable the Sun Java System Web Server.
You are asked for several passwords in the course of enabling a Sun Java System Web Server, all of which are described in TABLE 7-2. These passwords are referred to throughout this chapter.
Before you can enable the board for use with a Sun Java System Web Server, you must first initialize the board and populate the board’s keystore with at least one user. The keystore for the board is created during the initialization process. You can also initialize Sun Crypto Accelerator 6000 boards to use an existing keystore. See Initializing the Board With scamgr.
1. Access the scamgr utility with the scamgr command or enter scamgr -h hostname to connect scamgr to a board on a remote host.
2. Populate the board’s keystore with users.
These user names are known only within the domain of the Sun Crypto Accelerator 6000 board and do not need to be identical to the UNIX user name that the web server process is using. Before attempting to create the user, you must first log in as a scamgr security officer. See Chapter 3.
3. Create a user with the create user command.
scamgr{mca0@hostname, sec-officer}> create user username Initial password: Confirm password: User username created successfully. |
The username and password created here collectively make the username:password (TABLE 7-1). You must use this password when authenticating during a web server startup. This is the keystore password for a single user.
![]() |
Caution - Users must remember this username:password. Without this password, users cannot access their keys. There is no way to retrieve a lost password. |
This section describes how to install and configure Sun Java System Web Server 6.1 to use the board. You must perform these procedures in order. Refer to the Sun Java System Web Server documentation for more information about installing and using Sun Java System Web Servers.
This section includes the following procedures:
1. Install Sun Java System Web Server 6.1
3. Register the Board With the Web Server
4. Generate a Server Certificate
5. Install the Server Certificate
6. Enable the Web Server for SSL
![]() |
Caution - These procedures must be followed in the order given. Failure to do so could result in an incorrect configuration. |
![]() |
Caution - The Sun Java System Web Server Administration Server must be up and running during the configuration process. |
Note - The example in this section uses the Keystore slot. |
|
1. Download the Sun Java System Web Server 6.1 software.
2. Change to the installation directory and extract the web server software.
3. Install the web server with the setup script from the command line.
The default path name for the server is: /opt/SUNWwbsvr/.
This chapter refers to the default paths. If you decide to install the software in a different location, ensure you note where you installed it.
4. Answer the prompts from the installation script.
Except for the following prompts, you can accept the defaults:
a. Agree to accept the license terms by typing yes.
b. Enter a fully qualified domain name.
c. Enter the Sun Java System Web Server 6.1 Administration Server password twice.
d. Press Return when prompted.
The Sun Java System Web Server Administration Server must be up and running during the configuration process.
|
1. Start the Sun Java System Web Server 6.1 Administration Server.
Use the following command (instead of running startconsole as setup requests):
The response provides the URL for connecting to your servers.
2. Start the Administration GUI by opening up a web browser and typing:
In the Authentication window, enter the Sun Java System Web Server 6.1 Administration Server user name and password you selected while running setup.
Note - If you used the default settings during Sun Java System Web Server setup, enter admin for the User ID or the Sun Java System Web Server 6.1 Administration Server user name. |
The Sun Java System Web Server 6.1 Administration Server window is displayed.
4. Create the trust database for the web server instance.
You might want to enable security on more than one web server instance. If so, repeat the following Step a through Step d for each web server instance.
a. Click the Servers tab in the Sun Java System Web Server 6.1 Administration Server window.
b. Select a server and click the Manage button.
c. Click the Security tab near the top of the page and click the Create Database link.
d. Enter a password in the two dialog boxes and click OK.
See TABLE 7-1 for the web server trust database password information.
Choose a password of at least eight characters. This will be the password used to start the internal cryptographic modules when the Sun Java System Web Server runs in secure mode.
|
1. Register the Oracle Solaris PKCS#11 library in the security module database of the Sun Java System Web Server using the modutil utility.
% modutil -dbdir /opt/SUNWwbsvr/alias -nocertdb -add "Solaris Cryptographic Framework" -libfile /usr/lib/libpkcs11.so |
2. To limit the slots presented to those required to start the web server, disable all slots, except for one slot used by the Sun Java System application.
If the application asks for a password for every known PKCS#11 token, do not provide one.
|
1. Restart the Sun Java System Web Server 6.1 Administration Server by typing the following commands:
The response provides the URL for connecting to your servers.
2. Start the Administration GUI by opening up a web browser and typing:
In the Authentication dialog box, enter the Sun Java System Web Server 6.1 Administration Server user name and password you selected while running setup.
Note - If you used the default settings during Sun Java System Web Server setup, enter admin for the user ID or the Sun Java System Web Server 6.1 Administration Server user name. |
The Sun Java System Web Server 6.1 Administration Server window is displayed.
4. To request the server certificate, select the Servers tab near the top of Sun Java System Web Server 6.1 Administration Server window.
5. Select a server from the drop-down menu and click the Manage button.
The Sun Java System Web Server 6.1 Server Manager window is displayed.
6. Select the Security tab near the top of the Sun Java System Web Server 6.1 Server Manager window.
7. Click the Request a Certificate link on the left panel.
FIGURE 7-2 Sun Java System Web Server 6.1 Administration Server Request a Server Certificate Window With keystore-name Selected
8. Fill out the form to generate a certificate request, using the following information:
If you can directly post your certificate request to a web-capable certificate authority or registration authority, select the CA URL link. Otherwise, select CA Email Address and enter an email address where you would like the certificate request to be sent.
b. Select the Cryptographic Module you want to use.
Each slot has its own entry in this pull-down menu. For this example, the keystore-name is chosen.
c. In the Key Pair File Password dialog box, provide the password for the user that will own the key.
This password is the username:password (See TABLE 7-1).
d. Type the appropriate information for the requestor information fields in TABLE 7-2.
Two-letter ISO code for the country (for example, the United States is US) |
e. Click OK to submit the information.
9. Use a certificate authority to generate the certificate.
10. Once the certificate is generated, copy it, along with the headers, to the clipboard.
Note - The certificate is different from the certificate request and is usually presented to you in text form. Keep this data on the clipboard for Step 4 of Install the Server Certificate. |
|
Once your request has been approved by a certificate authority and a certificate has been issued, you must install the certificate in the Sun Java System Web Server.
1. Click the Security tab near the top of the Sun Java System Web Server 6.1 Server Manager window.
2. On the left panel, click the Install Certificate link.
FIGURE 7-3 Sun Java System Web Server 6.1 Administration Server Install a Server Certificate Window
3. Fill out the form to install your certificate:
Each slot has its own entry in this pull-down menu. Ensure that you select the correct slot name. For this example, use keystore-name. |
|
This password is the username:password (TABLE 7-1) |
|
In most cases, you can leave this blank. If you provide a name, it alters the name the web server uses to access the certificate and key when running with SSL support. The default for this field is Server-Cert. |
4. Paste the certificate you copied from the certificate authority (in Step 10 of the Generate a Server Certificate) into the Message text box.
You are shown some basic information about the certificate.
6. If everything looks correct, click the Add Server Certificate button.
On-screen messages tell you to restart the server. This is not necessary because the web server instance has been shut down the entire time.
You are also notified that in order for the web server to use SSL, the web server must be configured to do so. Use the following procedure to configure the web server.
Now that your web server and the Server Certificate are installed, you must enable the web server for SSL.
|
1. Select the Preferences tab near the top of the page.
2. Select the Edit Listen Sockets link on the left panel.
The main panel lists all the listen sockets set for the web server instance.
a. Click the link under Listen Socket ID for the listen socket you wish to configure.
b. Alter the following fields:
c. Click OK to apply these changes.
3. Click the link under Listen Socket ID again for the listen socket you wish to configure.
4. Enter the username:password to authenticate to the keystore on the system.
5. If you want to change the default set of ciphers, select the cipher suites under the Ciphers heading.
A window is displayed for changing the cipher settings. You can select either Cipher Default settings, SSL2, or SSL3/TLS. If you select the Cipher Default, you are not shown the default settings. The other two choices require you to select the algorithms you want to enable in a pop-up window. Refer to your Sun Java System documentation on cipher selection.
6. Select the certificate for the keystore followed by: Server-Cert (or the name you chose).
Only keys that the appropriate keystore user owns appear in the Certificate Name field. This keystore user is the user that is authenticated with the username:password.
7. When you have chosen a certificate and confirmed all the security settings, click OK.
8. Select the Apply link in the far upper right corner to apply these changes before you start your server.
9. Select the Load Configuration Files link to apply the changes.
You are redirected to a page that enables you to start your web server instance.
If you click the Apply Changes button when the server is off, an authentication window prompts you for the username:password. This window is not resizable, and you might have a problem submitting the change.
There are two workarounds for this problem:
10. In the Sun Java System Web Server 6.1 Administration Server window, select the On/Off link on the left side of the window.
11. Enter the passwords for the servers and click Server On.
You are prompted for one or more passwords.
a. At the Module Internal prompt, provide the password for the web server trust database.
b. At the Module keystore-name prompt, enter the username:password.
c. Enter the username:password for other keystores as prompted.
12. Verify the new SSL-enabled web server at the following URL:
https://hostname.domain:server-port/
Note - The default server-port is 443. |
This section describes how to install and configure Sun Java System Web Server 7.0 to use the board. You must perform these procedures in order. Refer to the Sun Java System Web Server documentation for more information about installing and using Sun Java System Web Servers.
This section includes the following procedures:
1. Install Sun Java System Web Server 7.0
2. Register the Board With the Web Server
3. Start the Sun Java System Web Server Administration Server
6. Pre-Set the Password for Tokens
7. Generate a Server Certificate
8. Install the Server Certificate
10. Enable the Web Server for SSL
![]() |
Caution - These procedures must be followed in the order given. Failure to do so could result in an incorrect configuration. |
![]() |
Caution - The Sun Java System Web Server Administration Server must be up and running during the configuration process. |
Note - The example in this section uses the Keystore slot. |
|
1. Download the Sun Java System Web Server 7.0 Update 1 software.
You can find the web server software at:
2. Change to the installation directory and extract the web server software.
3. Install the web server with the setup script from the command line.
The default path name for the server is: /sun/webserver7.
This chapter refers to the default path. If you decide to install the software in a different location, ensure you note where you installed it.
4. Answer the prompts from the installation script.
Except for the following prompts, you can accept the defaults:
a. Agree to accept the license terms by typing yes.
b. Enter the Sun Java System Web Server 7.0 Administration Server password twice.
c. Press Return when prompted.
|
Register the Oracle Solaris PKCS#11 library in the security module database of the Sun Java System Web Server using the modutil utility.
# modutil -dbdir /sun/webserver7/admin-server/config-store/hostname/config -nocertdb -add "Solaris Cryptographic Framework" -libfile /usr/lib/libpkcs11.so |
|
1. Use the following command as requested by the setup:
The response provides the URL for connecting to your servers.
2. Start the Administration GUI by opening a web browser and typing:
In the Authentication window, enter the Sun Java System Web Server 7.0 Administration Server user name and password you selected while running setup.
Note - If you used the default settings during Sun Java System Web Server setup, enter admin for the User ID or the Sun Java System Web Server 7.0 Administration Server user name. |
|
With Sun Java System Web Server 7.0, tokens are managed using the administration server.
Disable all tokens except for the internal token and the token you would like to use.
|
1. On the home page, click the Configurations button.
2. Click on the configuration you would like to modify.
3. Click the Certificates tab.
4. Click the PKCS#11 Tokens tab below the main tabs.
5. Click on the token name that will not be used. A new window pops up.
6. Uncheck the Token State box (that is, disable the token).
You can also pre-set the password for tokens so that the Sun Java System Web Server can start up without user interaction on reboot.
|
1. On the home page, click the Configurations button.
2. Click on the configuration you would like to modify.
3. Click the Certificates tab.
4. Click the PKCS#11 Tokens tab below the main tabs.
5. Click on the token name for which you would like to pre-set the password. This pops up a new window.
6. Click the Edit Token Password box.
7. Enter the password in the Current Password dialog box, and check “Do not prompt for the current password at instance startup.”
|
1. To request the server certificate, select the Common Tasks Tab at the home page, and select Request Server Certificate under Configuration Tasks.
2. Select a server from the scroll-down menu and click the Next button.
3. Select a token you would like to use from the pull-down menu and enter the password for the token. For this example, keystore_name is chosen.
FIGURE 7-4 Screenshot of the Sun Java Web Server 7.0 Request a Server Certificate Wizard
4. Fill out the form to generate a certificate request, and click Next to submit the information. TABLE 7-4 describes the requestor information fields.
5. Choose the key type and click Next. See TABLE 3-7 for the supported key type and key size range.
6. Check CA Signed Certificate and click Next.
7. Review the setting and click Finish.
8. A Certificate Signing Request (CSR) is displayed. Copy the CSR including the headers and send it to the Certificate Signing Authority to get the requested certificate.
The certificate is different from the certificate request and is usually presented in text form. Keep this data on the clipboard for Step 4 of Install the Server Certificate.
|
Once your request has been approved by a certificate authority and a certificate has been issued, you must install the certificate in the Sun Java System Web Server.
1. Click the Common Tasks tab on the home page, and click Install Server Certificate under Configuration Tasks.
2. Select a server from the scroll-down menu and click Next.
3. Select a token you would like to use from the pull-down menu and enter the password for the token.
4. Paste the certificate you copied from the certificate authority (in Step 9 of Generate a Server Certificate) into the Certificate Data text box. Click Next.
5. Type the nickname of the certificate, and click Next. In this example, Server-Cert is used.
FIGURE 7-5 Screenshot of the Sun Java Web Server Install a Server Certificate Wizard
6. The basic information of the certicate is shown. If everything looks correct, click Finish.
8. Once the certificate is installed, the window is at the Server Certificates tab. Set the password for the token:
a. Click Set Passwords in the upper right corner.
b. In the new window, enter the password for the token on which the certificate is installed.
9. The certificate for the token is displayed.
The nickname is in the form, token name:Certificate Nickname.
|
Whenever you make a change to a server instance, the change is temporarily made to the copy of the server instance. For the changes to take an effect, the change must be deployed. The Sun Java System Web Server Administration GUI warns you to deploy when a configuration is modified on the copy.
The warning shows up on the upper right corner: Deployment Pending (highlighted in yellow in FIGURE 7-6).
FIGURE 7-6 Screenshot of the Sun Java Web Server Virtual Servers Window
1. Click the Deployment Pending link.
2. Click on the Deploy button to deploy the new configuration.
3. Ensure that the deployment was successful and close the window.
Now that your web server and the Server Certificate are installed, you must enable the web server for SSL.
|
1. Select the HTTP Listeners tab.
2. Click the name of the listner to configure. A new window pops up.
3. Alter the port number on which you will be running your SSL-enabled web server (usually this is port 443).
5. Click SSL tab at the top of the window.
6. Alter the following fields:
FIGURE 7-7 Screenshot of the Sun Java Web Server Edit HTTP Listener - SSL Settings
7. Click the Apply button, and close the window.
Note - Ensure to deploy the change after the web server is configured for SSL. |
|
1. On the home page, click Start/Stop Instances under Configuration Tasks.
2. Select the instance to start by clicking the check box, and click the Start button.
If you did not pre-set the password for the token as described in Pre-Set the Password for Tokens, a new window prompts for the password.
3. Confirm that the instance has started successfully, and close the window.
4. Verify the new SSL-enabled web server at the following URL:
https://hostname.domain:server-port/
The Sun Java System Web Server is supported with Red Hat Enterprise Linux 4.0. Both RHEL 4.0 and SuSE 9 are supported with the Sun Java Web Server software.
The installation and configuration of Sun Java System Web Server on Linux is similar to that on Oracle Solaris. The only difference is the registration of the board with the web server. Refer to Register the Board With the Web Server in this chapter for details.
On Linux platforms, the PKCS#11 library is /usr/local/lib/libopencryptoki.so. Thus, use the following command to register the board with the Sun Java Web Server:
% modutil -dbdir /opt/SUNWwbsvr/alias -nocertdb -add "openCryptoki" -libfile /usr/local/lib/libopencryptoki.so |
Use the following commands to disable the openCryptoki slots other than the Sun Crypto Accelerator 6000 slot:
% modutil -dbdir /opt/SUNWwbsvr/alias -nocertdb -disable "openCryptoki" % modutil -dbdir /opt/SUNWwbsvr/alias -nocertdb -enable "openCryptoki" -slot "slot-name" |
For example, for SuSE 9 SP1 the "slot-name" is as follows:
Use the following command to check whether the other slots are disabled:
The output of this command should be similar to the following:
Notice the Status: Enabled for Linux 2.6.5-7.139-smp Linux (SCA) slot and Status: DISABLED (user disabled) for Linux 2.6.5-7.139-smp Linux (Soft). If the Linux 2.6.5-7.139-smp Linux (Soft) slot is not disabled (Java System Web Server 6.1 SP4 and SP5 might have this behavior), type the following command to remove the Linux 2.6.5-7.139-smp Linux (Soft) slot:
You can enable the Sun Java System Web Servers to perform an unattended startup at reboot with an encrypted key.
|
1. Navigate to the config subdirectory for your Sun Java System Web Server instance. For example, /opt/SUNWwbsvr/https-webserver-instance-name/config.
2. Create a password.conf file with only the following lines (TABLE 7-1 for password definitions):
3. Set the file ownership of the password file to the UNIX user ID that the web server runs as, and set the file permissions to be readable only by the owner of the file:
Copyright © 2013, Oracle and/or its affiliates. All rights reserved.