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.
A Manage Servers window appears. In this figure, there is already one server running called example, on port 8000.
Verify and update any settings as necessary. Sample server settings are:
For details about these fields, click Help to see the iPlanet Web Server documentation.
A notification for a new server is created.
See Enabling SSL on the Server.
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).
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.
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.
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.
Click Request a Certificate in the Security tab menu.
This figure shows an example of the Request a Server Certificate page that appears.
In the "Submit to Certificate Authority via" area, select the CA URL checkbox.
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.
The remaining fields request identifying information about the server. Use the fully qualified domain name of the server for Common Name.
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.
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.)
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----- Select and copy the base-64 encoded certificate, using Copy from the Edit menu in the browser or mail reader.
-----BEGIN CERTIFICATE----- MIICeTCCAeKgAwIBAgICHfQwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1 UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25z IENvcnBvcYXBlIENvbW11bmljYXRpb25zIENvcnAuMSAwHgYDVQQDF Bdtb2cuKG5ldHNjYXBlfG1jb20pLmNvbTCBnTANBgkqhkiG9w0B N0nZmUaB3adv7D1TPA== -----END CERTIFICATE-----
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.
Click Install Certificate in the Security tab menu.
This page appears. Verify that the certificate is for "This Server."
This page appears.
Type the Trust Database password in the Key Pair File Password field.
Select "Message text (with headers)."
Paste the encoded certificate information into the text box.
Click OK.
A confirmation page appears, showing the contents of the certificate to be added. Click Add Server Certificate.
A confirmation page appears, showing the contents of the certificate to be added.
A dialog box tells you to restart the iPlanet Web Server for the changes to take effect. Complete the instructions in Enabling SSL on the Server before you restart the server.
A dialog box tells you to restart the iPlanet Web Server for the changes to take effect.
This procedure explains how to turn SSL on for the server.
Click the Preferences tab if it is not showing.
In the left frame, click Encryption On/Off.
The Encryption On/Off page appears.
In the Port Number box, enter the port number you want to use for the SSL service.
(The default for HTTPS is 443.)
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.
https://myCA.example.com:443/
Select the Retrieval tab.
Click Import CA Certificate Chain.
In the Import CA Certificate Chain form, select "Display the CA certificate chain in PKCS#7 for importing into a server."
Click Submit.
The certificate chain appears in your browser window in an encoded format. Copy the encoded certificate chain, using Copy from the browser's Edit menu.
The certificate chain appears in your browser window in an encoded format.
Open the iPlanet Web Server Server Manager page for the server where you want to import the CA certificate chain.
Select Install Certificate from the Security tab menu on the left.
Select "Trusted Certificate Authority."
Type the Trust Database password into the Key Pair File Password field.
Select "Message text (with headers)," and paste the encoded certificate chain into the text box.
Submit the form.
In the confirmation page, click Add Server Certificate.
To require SSL client authentication for all requests on a server:
In the left frame, click Encryption Preferences.
For the "Require client certificate (regardless of access control)" checkbox, select Yes.
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:
Select Configure Directory Service.
This screen appears.
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.)
Specify the Base DN to use for searching for user entries.
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.
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:
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
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.
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.
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.
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.
In the left frame, click Restrict Access.
In the right panel, select Entire Server, or a subdirectory to which you want to restrict access.
Click Edit Access Control.
This page appears. In the top pane under Users/Groups, select All.
In the bottom pane, select the following:
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
In the top pane, click Submit.
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
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.