Appendix D Using SSL with Enterprise Server 3.x

This appendix explains how to get client certificate authentication working with Netscape Enterprise Server 3.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 Netscape Administration Server using your administrator's ID and password.

A General Administration window appears. In this figure, there is already one server running called mog, on the default port 80.



2. Click Create New Netscape Enterprise Server. In the screen that appears, most of the fields have default values.
3. Verify and tweak any settings as necessary. Sample server settings are:
• Server Name: myhost.mydomain.com


• Bind address: (specify only if necessary)


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


• Server Identifier: myhost-ssl


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 More about this server."

See Enabling SSL on the Server.

• Generating a Key Pair


• Submitting a Certificate Signing Request


• Importing the Certificate

Use the Unix command-line tool sec-key to create an encryption key pair for the server. You will use this key pair to create the certificate request.

1. Open a Unix command shell on the computer on which the server runs.
2. Log in as root.
3. Execute the command-line tool {suitespot-dir}/bin/admin/admin/bin/sec-key.
4. When you are prompted, enter an alias name for the key pair.

You can use the name of the machine, for example, or the name of the application that will use the certificate.

The system prompts you once more.

5. In response to the prompt, type random characters until the system prompts you to stop.

These characters are used to generate a random seed used in the certificate.

error: Could not generate key (returned -1), try again!

If you do, run sec-key again until you succeed. Sometimes it can take a few tries to get it to work (most notably under Solaris 2.6).

1. When you are prompted, assign a password with which to encrypt your new key pair.

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

Once you have generated a key pair, you must create a PKCS #10 certificate request and submit it to Certificate Management System to obtain your server SSL certificate.

1. Go to the General Administration page for the Enterprise Server instance.
2. Click Keys & Certificates.
3. Click Request Certificate.
4. Click New Certificate.
5. Click "CA Email Address."
6. Enter your own email address or the address of your CMS administrator.
7. Select the certificate and key database alias and enter the password that you specified when you generated the key pair.
8. Enter your contact and server information:
• The common name should be the host name of the server.

• The email address is of the server administrator (you can use a group alias).


• The organization should be the exact string that you use to identify your organization in certificates.


• Check with your system administrator for any other format requirements at your site.


9. Click OK.

A confirmation dialog box appears.

10. Double-check your entries in the confirmation dialog box, and click OK.

The PKCS #10 certificate enrollment request is generated and emailed to the address you have specified. It also appears in your browser window.

11. Copy the encoded certificate request to the clipboard, using the Copy command on the browser's Edit menu.

1. In your browser, go to the URL for the Certificate Management System end-user pages. For example:

	https://mycertserver.mydomain.com:17005

2. Click the Enrollment tab.
3. Under Server Enrollment in the left pane, click Manual or Directory-Based.

Depending on how your Certificate Management System is configured, only one of these choices may be offered. If both choices are offered and you don't know which one to use, check with your CMS administrator.

4. Paste the encoded certificate request from the clipboard into the text box labeled PKCS #10 Request.
5. Fill out the rest of the form, and click Submit.

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, go to the page containing the certificate.
• If you use directory-based enrollment, the certificate is issued automatically and appears in the browser.
• If you use manual enrollment, you must wait until an agent approves the request. When it is issued, the URL containing the certificate is mailed to you. Go to that URL.

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.
4. Go back to your Enterprise Server's General Administration page.
5. Click Keys & Certificates.
6. In the left frame under Keys and Certificates, select Install Certificate.

This page appears.



7. Verify that the certificate is for "This Server."
8. Select "Message text (with headers)."
9. Paste the encoded certificate information into the text box.
10. In the Alias list, choose the alias that is associated with this certificate.

It should be the same alias you created when you generated the key pair above.

11. Click OK.

You should see a confirmation page like this one:



12. Click Add Certificate.

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

13. Restart Administration Server.

• Trusting the Root CA Certificate


• Enabling Encryption on the Server


• Modifying the Configuration File


• Modifying the Access Control Lists


• Specifying the Authentication Directory


• Removing Untrusted CA Roots

For the server to accept 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.mydomain.com:17006

2. Select the Retrieval tab.
3. Click Certificate Chain Importation.
4. In the importation form, select "Display the certificate chain for importing into the 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. Go to the General Administration page for the Administration Server.
8. In the General Administration page, select Keys & Certificates.
9. In the left frame under Keys and Certificates, select Install Certificate.
10. Select "Trusted Certificate Authority."
11. Select "Message text (with headers)," and paste the encoded certificate chain into the text box.
12. Submit the form.
13. In the confirmation page, confirm that you want to trust this CA root.

To enable the general use of SSL for server communications, follow these steps.

1. Go back to the General Administration page, and select your web server.
2. Under Server Preferences in the left frame, click Encryption On/Off.

You see this page:



3. Select On.
4. In the Port Number box, enter the port number you want to use for the SSL service.

(The default for HTTPS is 443.)

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

Enterprise 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 Enterprise 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 netscape CN=rootca.netscape.com, OU=Information Systems, 
O=Netscape Communications Corporation, C=US 

netscape:DNComps o, c 

netscape:FilterComps UID 

netscape:verifycert 

• certmap

The certmap line establishes a nickname for client certificates that exactly match all of the given DN components. The remaining lines use that nickname. The certificate that the user presents must match exactly.

• 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. For example, if a user's certificate has attributes "C=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 slot 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. (Certificate Management System must be configured to publish certificate information to a directory.)

You can configure the access control lists (ACLs) on Enterprise 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. Go to the General Administration page for the Administration Server.
2. Select the Enterprise Server instance to be SSL-enabled.
3. Click Server Preferences.
4. Under Server Preferences in the left panel, click Restrict Access.
5. In the right panel, select Entire Server, or a subdirectory to which you want to restrict access.
6. Click Edit Access Control.

This page appears.



7. In the top pane under Users/Groups, select All.
8. 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

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

Specifying the Authentication Directory

You must specify a particular LDAP directory for Enterprise 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 General Administration tool of the server, and select Global Settings.
2. Select Configure Directory Service.

This screen appears.



3. Under "Obtain Directory Services From," select LDAP Directory Server
4. Supply the host name, port number, and base DN for the LDAP directory to be used for authentication.
5. If you want, click Yes to specify an SSL connection for authentication communications between Enterprise Server and Directory Server. (You must also enable the SSL connection in Directory Server.)
6. When you have finished filling out the form, save the changes to the Enterprise Server configuration.

When you have set up your Enterprise Server to talk to the LDAP server as shown, you also get access to the following environmental 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.

Avoid having untrusted root CA certificates in your database. They are not useful, and can sometimes cause problems. In particular, there is a known problem in Enterprise Server 3.x (in versions earlier that 3.6) that causes it to send down to the client all of the CA root certificates that are in its database as if they were trusted. This can cause problems when the client is configured to use "Select automatically" to determine what certificate to present to the server, and when the user has more than one client certificate.

1. Using the General Administration tool of the server, select Keys & Certificates.
2. Click Manage Certificates.
3. Choose your server alias, and click OK.

You see a list of the server certificates that are installed in your server's certificate database.

4. Delete all of the entries except the following:
• The certificate named "Server-Cert" having the type "Own"
• The CA certificate for your root CA
• Any certificates that are part of the root CA certificate chain

5. Click the links for each of the deleted certificates.

For each, this dialog box appears:



6. Click Delete Certificate for each of the certificates to be deleted.

1. Start the server, either from Administration Server or from the command line.
• To start the server from Administration Server, go to the General Administration page and click On. A dialog box requests the password for the certificate database. Note that if you have not enabled SSL on Administration Server (as you just did for Enterprise 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-mog-ssl 

	> ls 

	agents-db  conf_bk    db         restart    start 

	catalog    config     logs       rotate     stop 

	> ./start 

	Key File Password: {passphrase for key entered here} 

	Netscape-Enterprise/3.5.1 B98.027.1521 

	startup: listening to https://mog.mcom.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.