Appendix D Using SSL with iPlanet Web Server, Enterprise Edition 4.x

This appendix explains how to get client certificate authentication working with iPlanet Web Server, Enterprise Edition 4.x. When you have finished following these steps, you will have a web server that requires a user to present a valid client SSL certificate (issued by Certificate Management System) in order to access the restricted areas on the server. The certificate that the user presents must match the certificate that was published to the LDAP directory when it was issued.

• Creating a New Server


• Obtaining a Server Certificate


• Enabling SSL on the Server


• Testing Client Authentication

1. Log into iPlanet Web Server Administration Server using your administrator's ID and password.

A Manage Servers window appears. In this figure, there is already one server running called example, on port 8000.



2. Click Add Server. In the screen that appears, most of the fields have default values.
3. Verify and update any settings as necessary. Sample server settings are:
• Server Name: myhost.example.com


• Server Port: (typically 443, but can be any unused port)


• Server Identifier: myhost-ssl


• Server User: nobody



For details about these fields, click Help to see the iPlanet Web Server documentation.

4. Submit the form.

A notification for a new server is created.

5. When you are ready to configure the new server to enable SSL, click "Configure your new server."

See Enabling SSL on the Server.

• Creating a Trust Database


• Submitting a Certificate Signing Request


• Importing the Certificate

To support SSL, you first create a Trust Database that will contain all of the keys and certificates used by the server (including many pre-installed root certificates from public Certificate Authorities).

1. Open the Server Manager page for the server you want to configure.
2. Click the Security tab.

The default page on the Security Tab is the Create a Trust Database page; an example is shown in the following figure.




3. Type in a password to protect the Trust Database in the password fields.

This password will protect the certificates the server uses, including its SSL server certificate. The password must contain at least 8 characters and have at least one non-alphabetic character.

Whenever you start an SSL-enabled HTTP server, you will be asked for this password to access the certificate database.

4. Click OK to submit the form.

Once you have a Trust Database, you can create a PKCS #10 certificate request and submit it to Certificate Management System to obtain your server SSL certificate.

1. Open the Server Manager page for the server you want to configure.
2. Click the Security tab.
3. Click Request a Certificate in the Security tab menu.

This figure shows an example of the Request a Server Certificate page that appears.




4. Select the New certificate checkbox.
5. In the "Submit to Certificate Authority via" area, select the CA URL checkbox.
6. In the CA URL text field, enter the URL for the end-entity enrollment interface of a CMS Certificate or Registration Manager.

Simply append /enrollment to the URL for the end-entity gateway. For example, https://myca.example.com:443/enrollment.

7. Type the Trust Database password in the Key Pair File Password field.
8. The remaining fields request identifying information about the server. Use the fully qualified domain name of the server for Common Name.
9. Click OK to submit the form.

A confirmation window appears, showing the information you entered and the PKCS#10 request. Back up the PKCS#10 data by copying it with the browser's copy command and pasting it into a file using a text editor.

10. Double check the information about the server, then click OK to submit the form.

A message from the CMS server appears to tell you that the request is pending. Note the request ID number; it can be used to retrieve the certifcate from the CMS end-entity gateway when the certificate is issued.

A CMS agent will process your certificate request. When the certificate is issued, you will receive an email containing the certificate or a URL where the certificate can be retrieved. Once you have been issued a server certificate, you must import it into your server. (This is different from importing a personal certificate into your browser.)

1. In your browser or mail reader, go to the page or message containing the certificate.
2. Scroll down to the part of the page that contains the base-64 encoded certificate. It looks like this:

-----BEGIN CERTIFICATE-----
MIICeTCCAeKgAwIBAgICHfQwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1 UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25z IENvcnBvcYXBlIENvbW11bmljYXRpb25zIENvcnAuMSAwHgYDVQQDF Bdtb2cuKG5ldHNjYXBlfG1jb20pLmNvbTCBnTANBgkqhkiG9w0B N0nZmUaB3adv7D1TPA==
-----END CERTIFICATE-----

3. Select and copy the base-64 encoded certificate, using Copy from the Edit menu in the browser or mail reader.
4. Go back to your iPlanet Web Server's Administration page, and open the Server Manager page for the server where you are installing this certificate.
5. Click the Security tab.
6. Click Install Certificate in the Security tab menu.

This page appears.



7. Verify that the certificate is for "This Server."
8. Type the Trust Database password in the Key Pair File Password field.
9. Select "Message text (with headers)."
10. Paste the encoded certificate information into the text box.
11. Click OK.

A confirmation page appears, showing the contents of the certificate to be added.

12. Click Add Server Certificate.

A dialog box tells you to restart the iPlanet Web Server for the changes to take effect.

13. Complete the instructions in Enabling SSL on the Server before you restart the server.

• Specifying the Authentication Directory


• Modifying the Configuration File


• Modifying the Access Control Lists

This procedure explains how to turn SSL on for the server.

1. Open the Server Manager page for the server that you want to use SSL
2. Click the Preferences tab if it is not showing.
3. In the left frame, click Encryption On/Off.

The Encryption On/Off page appears.

4. For the Encryption checkbox, select On.
5. In the Port Number box, enter the port number you want to use for the SSL service.

(The default for HTTPS is 443.)

6. Verify that the correct alias is selected.
7. Click OK.
8. Follow the directions to Save and Apply the changes.

You can Save to save the changes to the configuration file, or Save and Apply to save the changes and restart the server. If you plan to continue configuring SSL, you can just Save now and restart the server later.

For the server to accept SSL client certificates issued by your root CA, you must import the certificate chain from your root CA into the server and establish it as a trusted CA.

1. Go to the URL for the secure end-entity port of the Certificate Manager that is to act as your root CA, using HTTPS. For example:

	https://myCA.example.com:443/

2. Select the Retrieval tab.
3. Click Import CA Certificate Chain.
4. In the Import CA Certificate Chain form, select "Display the CA certificate chain in PKCS#7 for importing into a server."
5. Click Submit.

The certificate chain appears in your browser window in an encoded format.

6. Copy the encoded certificate chain, using Copy from the browser's Edit menu.
7. Open the iPlanet Web Server Server Manager page for the server where you want to import the CA certificate chain.
8. Click the Security tab.
9. Select Install Certificate from the Security tab menu on the left.
10. Select "Trusted Certificate Authority."
11. Type the Trust Database password into the Key Pair File Password field.
12. Select "Message text (with headers)," and paste the encoded certificate chain into the text box.
13. Submit the form.
14. In the confirmation page, click Add Server Certificate.

To require SSL client authentication for all requests on a server:

1. Open the Server Manager page for the server that uses SSL
2. Click the Preferences tab if it is not showing.
3. In the left frame, click Encryption Preferences.
4. For the "Require client certificate (regardless of access control)" checkbox, select Yes.
5. Click OK to submit the form.
6. Choose Save if you want to configure more about the server or Save and Apply to save changes and restart the server.

You must specify a particular LDAP directory for iPlanet Web Server to use for authentication. This must be the same directory to which CMS publishes certificate information.

To specify an authentication directory, follow these steps:

1. Open the Web Server Administration Server page, and select the Global Settings tab.
2. Select Configure Directory Service.

This screen appears.




3. Supply the host name, port number, and base DN for the LDAP directory to be used for authentication.
4. If you want, click Yes to specify an SSL connection for authentication communications between iPlanet Web Server and Directory Server. (You must also enable the SSL connection in Directory Server.)
5. Specify the Base DN to use for searching for user entries.
6. Specify the distinguished name (DN) to use to bind to the directory for searching.

The Bind DN can be the DN of a directory administrator or any DN that has permission to search the directory.

7. Specify the password used with the Bind DN to bind to the directory.
8. When you have finished filling out the form, save the changes to the iPlanet Web Server configuration.

When you have set up your iPlanet Web Server to use the LDAP server as shown, you also get access to the following environment variables from within CGI scripts:

• REMOTE_USER is set to the UID of the user, such as jsmith. This is the most useful variable. For example, you can use it to check the LDAP directory for the user's manager, phone number, and so on, or you can customize the information presented to different users.
• CLIENT_CERT contains an encoded copy of the user's certificate.
• AUTH_TYPE is set to ssl when appropriate.
• HTTPS is set to on when appropriate.
• HTTPS_KEYSIZE is the number of bits in the encryption key, for example, 128.
• HTTPS_SECRETKEYSIZE is the number of bits in the secret key, usually 40 for export and 128 for the US.

The iPlanet Web Server does not automatically check each certificate against the certificate revocation list (CRL), and so cannot detect a revoked certificate. However, if Certificate Management System is configured to remove revoked certificates from the LDAP directory, you can tell iPlanet Web Server to verify each client certificate against the LDAP directory, thus protecting against the presentation of revoked certificates.

In this example of a certmap.conf file, we have issued certificates that have a UID field and then specified that field as the key field for the LDAP search.

certmap example CN=Certificate Manager, OU=Information Systems, 
O=Example, C=US 

example:DNComps O, C

example:FilterComps UID 

example:verifycert on

• certmap <token> <issuerDN>

The certmap line establishes a token to identify rules corresponding to certificates whose issuer DN matches the DN provided. Subsequent lines in the certmap.conf file that begin with the token specify rules to map the SSL client certificate to an entry in the LDAP directory.

• DNComps

The DNComps line tells the server to glean the given attributes from the user's certificate to figure out where to start looking for the user in the LDAP tree. The example uses O and C: if a user's certificate has attributes "O=Netscape Communications Corp." and "C=US," the web server uses that DN when it looks for the user in LDAP. You can include the entry but leave the value blank; in this case, the server searches the entire LDAP tree for entries matching the filter.

• FilterComps

The FilterComps line tells the server to search based on the UID field in the certificate. If you configure all certificates issued by your root CA to have a UID field, this kind of search will always succeed.

• verifycert

The fourth line tells the server to verify that the certificate which the user has presented is in fact the certificate currently in the usercertificate attribute on the LDAP server. If you do not include this line, the server will check that the user is a legal user (that is, has access privileges to some particular part of the document root), but it will not check whether the user is using the right certificate.

You can configure the access control lists (ACLs) on iPlanet Web Server to allow only those who hold a valid certificate issued by your root CA to access the parts of the site that you designate as private.

1. Open the Server Manager page for the server that you want to use SSL
2. Click the Preferences tab if it is not showing.
3. In the left frame, click Restrict Access.
4. In the right panel, select Entire Server, or a subdirectory to which you want to restrict access.
5. Click Edit Access Control.

This page appears.



6. In the top pane under Users/Groups, select All.
7. In the bottom pane, select the following:
• Authenticated people only
• Select either "All in the authentication database" or "Only the following people." If you restrict access, select authorized users from the lists of specific users and groups
• Under Authentication Method, select SSL
• Under Authentication Database, select Default LDAP

8. Click Update.
9. In the top pane, click Submit.

1. Start the server, either from the iPlanet Web Server Administration Server or from the command line.
• To start the server from the iPlanet Web Server Administration Server, go to the server's Server Administration page, select the Preferences tab, enter the Trust Database password, and click On. Note that if you have not enabled SSL on Administration Server (as you just did for iPlanet Web Server), your password will go across the network unencrypted.
• To start the server from the command line, open a command shell window, go to the installation directory, and run the start script for the new server instance. You must supply the key database password to unlock the certificate and start up the new SSL server. Note that if you do not have a secure connection, your password will go across the network unencrypted. The script interaction looks like the following:

	> pwd 

	/opt/netscape/suitespot/https-example-ssl 

	> ls 

	agents-db  conf_bk    db         restart    start 

	catalog    config     logs       rotate     stop 

	> ./start 

	Please enter password for Internal (software) token: <password>

	iPlanet-WebServer-Enterprise/4.1 BB1 

	startup: listening to https://www.example.com, port 443 as nobody 

2. Use your browser to access a page on the server that is part of a subdirectory to which you have restricted access. (See Modifying the Access Control Lists.)
3. If you are on the list of restricted users and if SSL has been successfully enabled, you will be asked to present your client SSL certificate from your root CA.