|
| Sun ONE Server Console 5.2 Server Management Guide |
Chapter 10 Using SSL and TLS with Sun ONE Servers
This chapter describes how to set up support for the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols in Sun ONE servers. Before reading this chapter, you should be familiar with the concepts described in Appendix A "Introduction to Public-Key Cryptography."
This chapter contains the following sections:
- The SSL and TLS Protocols
- Preparing to Use SSL and TLS Encryption
- Obtaining and Installing a Server Certificate
- Activating SSL
- Managing Server Certificates
- Using Client Authentication
The SSL and TLS Protocols
The Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols are sets of rules governing server authentication, client authentication, and encrypted communication between servers and clients. SSL and TLS are widely used on the Internet, especially for interactions involving the exchange of confidential information such as credit card numbers.
At a minimum, SSL and TLS require a server certificate. As part of the initial "handshake" process, the server authenticates its identity by presenting this server certificate to the client. Using public-key encryption and digital signatures, the client confirms that the server is, in fact, the server it claims to be. If desired, the server can also request that the client authenticate its identity by presenting a client certificate.
If authentication is successful, the client and server use techniques of symmetric-key encryption to encode all the information they exchange for the remainder of the session. Symmetric-key encryption also allows the client and server to detect if any tampering has occurred during the transmission of data.
SSL and TLS Ciphers
The SSL and TLS protocols support a variety of different cryptographic algorithms for use in operations such as authenticating the server and client to each other, transmitting certificates, and establishing session keys. These algorithms are called ciphers and are often implemented in sets called cipher suites. Clients and servers may support different cipher suites depending on factors such as the version of SSL or TLS they use, and company policies regarding acceptable encryption strength. Among their other functions, the SSL and TLS protocols determine how servers and clients negotiate which cipher suites they use to communicate.
Each new version of SSL and TLS maintains backward compatibility with earlier versions. As a result, the SSL 2.0, SSL 3.0, and TLS protocols have several cipher suites in common. This allows a newer client or server to communicate securely with an older client or server. To control the level of encryption used during communication, administrators can enable or disable cipher suites on both clients and servers. When a particular client and server exchange information during the SSL or TLS handshake, they identify the strongest enabled cipher suites they have in common and use those for the session.
Choosing SSL and TLS Ciphers
Decisions about which cipher suites an organization enables are often based on both the sensitivity of the data involved and the speed of the cipher. A 40-bit cipher is relatively easy to break, but very fast. A 128-bit cipher is difficult to break, but slower than other ciphers.
Some organizations may want to disable less secure ciphers to prevent insufficiently encrypted SSL connections. To serve the greatest number of users, it is a good idea for administrators to enable as broad a range of SSL cipher suites as possible. That way, when clients or servers are dealing with each other, they can negotiate the use of the strongest ciphers available.
Since 40-bit ciphers can be broken relatively quickly, administrators whose user communities can use stronger ciphers should disable all 40-bit ciphers if they are concerned about access to data by eavesdroppers.
For detailed information on determining which cipher suites to use when setting up SSL, see Appendix B "Introduction to SSL
Preparing to Use SSL and TLS Encryption
All Sun ONE servers support PKCS #11 and the SSL protocol. Many Sun ONE servers also support TLS. Before you request certificates and begin to exchange information securely, you'll need to set up SSL and TLS. If you're using an external security device, you also need to install a PKCS #11 module.
Using External Security Devices
External security devices are Public Key Cryptography Standard (PKCS) #11 modules. PKCS defines the interface used for communication between SSL and PKCS #11 modules.
A PKCS #11 module is a device, implemented in hardware or software, that provides cryptographic services such as encryption, decryption and, in some cases, storage of keys and certificates. All Sun ONE servers include a built-in software PKCS #11 module.
Sun ONE servers can use a variety of external PKCS #11 modules provided by different manufacturers including for example Sun Crypto Accelerator Boards. Before using an external module, you must install the manufacturer's drivers on the machine running your Sun ONE server.
Slots and Security Devices
A PKCS #11 module always has one or more slots. Slots can be implemented physically in a piece of hardware or conceptually in software. Each slot in a PKCS #11 module can contain a security device, the hardware or software that actually provides cryptographic services and stores certificates and keys. For example, a smart card reader contains one or more slots, each of which can contain a security device called a smart card.
An internal security device is made up of a key-pair and a certificate database stored in a software file on a host computer. By default, Sun ONE Administration Server provides a means to create an internal security device with its PKCS #11 module. If you do not have an external device connected to your server or client, you can use only the Sun ONE internal security device for SSL authentication.
An external security device is a key-pair and certificate database stored in an external device such as a Smart Card. If you have an external device connected to your server, you can use internal and external security devices for SSL authentication.
To Install an External Security Device
- Connect your Smart Card reader or other device and install its drivers on your host machine.
Initially, the device is available to all servers on the host. Depending on the device's capabilities, you may be able to share it across multiple servers on the host. For more information, see the documentation that came with your hardware.
- In the Sun ONE Server Console navigation tree, select the server instance that you want to use the PKCS #11 module with, and then click Open.
- From the server's Console menu, choose Security > Configure Security Modules, and then click Install.
- In the Install Security Module dialog box, enter the following information:
Enter the PKCS #11 module driver filename. Enter the full path to the driver file that came with your device. This file has the extension DLL, JAR, so, or sl.
Enter an identifying name for this module. Enter a descriptive name that helps you identify this device.
- Click OK, and then click Close.
To Remove an External PKCS #11 Module
- In the Sun ONE Server Console navigation tree, select the server instance that is using the external PKCS #11 device, and then click Open.
- From the server's Console menu, choose Security > Configure Security Modules.
- Select your device from the list and then click Remove.
- Click OK to confirm that you want to remove the device, and then click Close.
Obtaining and Installing a Server Certificate
When requesting and installing certificates, you use two wizards. You use the Certificate Request Wizard to request a new server certificate or to renew a certificate that you're already using. You use the Certificate Installation Wizard to install a certificate that you've received from a Certificate Authority (CA). The first time you use the Certificate Request Wizard, it also creates and installs a key and certificate database for you.
This section takes you through the steps of requesting and installing a certificate.
SSL Certificates
Sun ONE Server Console can install three types of certificates: server certificates, server certificate chains, and trusted CA certificates.
A server certificate is a single certificate associated only with your server. It identifies your server to clients. You must request this type of certificate from a CA. To obtain and install a Server Certificate, generate a request and send it to the CA. Then install the certificate.
For information on installing a server certificate, see "Generating a Server Certificate Request"and "Installing the Certificate".
A server certificate chain is a collection of certificates automatically generated for you by your company's internal certificate server or a known CA. The certificates in a chain trace back to the original CA, providing proof of identity. This proof is required each time you obtain or install a new server certificate.
A trusted CA certificate is a single certificate automatically generated for you by your company's internal certificate server or a known CA. A trusted CA certificate is used to authenticate clients.
To obtain a trusted CA certificate, first go to the internal certificate server or CA's web site. Copy the necessary certificate information and save it to a file. Then use the Certificate Installation Wizard to install the certificate. For more information, see "Installing the Certificate"
You can install any number of SSL certificates on a server. When setting up SSL for an instance of Directory Server, you need to install at least a server certificate and a trusted CA certificate.
Preparing to Set Up SSL and TLS
You need to set up SSL and TLS differently depending on whether you are using an internal security device, an external hardware device, or both. This section tells you how to do this.
Setting up SSL or TLS With an Internal Security Device
To set up SSL or TLS with an internal security device, you must request and install a certificate. To request a certificate, run the Certificate Request Wizard. To install the certificate, run the Certificate Installation Wizard. When prompted, specify that you want to install the certificate on the internal security device.
Setting up SSL or TLS With an External Security Device
To set up SSL with an external security device first install the PKCS #11 module provided by the external device manufacturer. Then run the Certificate Request Wizard, specifying the external security device when prompted. For more information, see "To Install an External Security Device".
Setting Up SSL With Internal and External Security Devices
Some servers and clients in your enterprise may use only internal security devices, while others may use both internal and external security devices. If your server needs to communicate with products running both internal and external security devices, run the Certificate Request Wizard two times. During the first use, when prompted, specify the internal security device. During the second use, when prompted, specify the external security device.
Generating a Server Certificate Request
You can use Sun ONE Server Console to generate a certificate request which you can then submit to a CA.
At this time, you must provide a password for the security device. After installing the server certificate, this password must be provided at server startup.
To Generate a Certificate Request
- In the Sun ONE Server Console navigation tree, select the server instance with which you want to use SSL encryption.
- Double click the server instance or click Open to open the management window for the server instance.
- From the Console menu, choose Security > Manage Certificates.
Alternatively, you can click the Manage Certificates task.
- Enter the password for the security device that holds this certificate.
If you are installing the certificate on the internal (software) security device, enter the password for the key and certificate database. If you are installing a certificate on an external (hardware) security device, enter the password for the device.
- Click the Server Certs tab.
- Click Request to open the Certificate Request Wizard.
- Choose "Request Certificate Manually," and then click Next.
- Enter the requested information:
Server Name. (Optional) Enter the fully qualified host name of the machine for which you're requesting a certificate.
Organization. (Optional) Enter your organization's name.
Organizational Unit. (Optional) Enter your division, department, or other organizational unit.
City/locality. (Optional) Enter the city or locality in which your organizational unit is located.
State/province. (Optional) Enter the state or province in which your organizational unit is located.
Country/region. (Optional) Select the state or province in which your organizational unit is located, from the drop down menu.
You can toggle between two views of the request form using the following buttons:
Show DN. Click to show the requestor information in distinguished name (DN) format. The Show DN button is visible only when you are entering information in fields.
Show Fields. Click to show the requestor information in fields. The Show Fields button is visible only when you are entering information in DN format.
- Click Next.
- Enter the password for the security device that stores this certificate.
If you are requesting the certificate for an internal (software) security device, this is the password for the key and certificate database. If you are requesting the certificate for an external (hardware) module, this is the password for your SmartCard or other security device.
Note You must generate a different request for each device.
- Click Next.
- Select one of the following:
Copy to Clipboard. Click to copy your certificate request to the clipboard.
Save to File. Click to save your request as a text file. You are prompted to choose a name and location for the file.
The certificate request you have copied to the clipboard or saved as a text file is required to mail to a Certificate Authority issuing the new certificate. See "To Send a Server Certificate Request as Email".
- Click Done to close the Certificate Request Wizard.
Sending a Server Certificate Request
Once you have generated a server certificate request, you send it to a CA for processing. Many CAs allow you to submit certificate requests through their web sites. Others may require you to send them an email message containing your request.
To Send a Server Certificate Request as Email
- Use your email program to create a new email message.
- Paste your certificate request into the message.
If you copied the certificate request to the clipboard, paste it into the body of the message.
If you saved your certificate request to a file, open it in a text editor. Copy and paste the request into the body of the message.
- Enter a subject and recipient for your request. The type of subject and recipient varies depending on which CA you are using. For more information, see your CA's web site.
- Send the email message to the CA.
Once you've submitted your request, you must wait for the CA to respond with your certificate. Turnaround time is highly variable and depends on the CA. If your company has an internal CA, it may take only a day or two to receive your certificate. If you are using an external CA, it could take as long as several weeks for that CA to respond to your request.
Installing the Certificate
Depending on the CA, you may receive your certificate in an email message or you may have to retrieve it from the CA's web site. Once you have the certificate, you can back it up and install it.
To Back Up a Certificate
- Save, in a text file, the certificate data you received from the CA.
If you ever lose the certificate data, you can reinstall the certificate using this backup file.
To Install a Server Certificate
When you install the first server certificate, you are prompted for a password for the certificate database.
- In the Sun ONE Server Console navigation tree, select the server instance on which you want to install the certificate.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Click the Server Certs tab.
- Specify where to store this certificate.
- If you want to store this certificate on the internal security device, select internal (software) from the Security Device drop-down list.
- If you want to store this certificate on an external hardware device, select the device from the Security Device drop-down list.
- Click Install.
- Enter the certificate's location or enter its text.
In this local file. If your certificate is stored in a text file on your system, enter the full path to the file.
In the following encoded text block. If you copied your certificate to the clipboard, paste the certificate's text into the text field by clicking the Paste from Clipboard button.
- Click Next.
If the certificate information you entered above is valid, you see a page containing the details of your certificate.
- Verify that the certificate information is correct, and then click Next.
- Enter a name for the certificate, and then click Next.
- Enter the password for the security device that holds this certificate.
If you are installing the certificate on the internal (software) security device, enter the password for the key and certificate database. If you are installing a certificate on an external (hardware) security device, enter the password for the device.
- Click Done.
To Install a CA Certificate or Server Certificate Chain
- Obtain the CA certificate or Server Certificate Chain from your CA.
- In the Sun ONE Server Console navigation tree, select the server instance on which you want to install the CA certificate.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Select the CA Certs tab, and then click Install.
- Enter the certificate's location or enter its text:
In this local file. If the certificate is stored in a text file on your system, enter the full path to the file.
In the following encoded text block. If you copied the certificate to the clipboard, paste the certificate's text into the text field by clicking the Paste from Clipboard button.
- Click Next.
If the certificate information you entered in step 6 is valid, you see a page containing the details of the certificate.
- Verify that the certificate information is correct, and then click Next.
- Enter a name for the certificate, and then click Next.
- Select the trust options for this certificate:
Accepting Connections from Clients. Check this box if you want to trust client certificates issued by this CA.
Making Connections to Other Servers. Check this box if you want to trust server certificates issued by this CA.
- Click Done.
Backing Up and Restoring Your Certificate Database
Whenever you install a certificate, you should back up your certificate database. If your database ever becomes corrupted, you can restore your certificate information from this backup.
To Back Up Your Certificate Database
- Open your server root folder.
- Copy all files in the alias folder to another location (preferably on a different disk).
This folder includes your certificates as well as the private key for your trust database.
To Restore Your Certificate Database From a Backup
- Copy your backup files to the alias subfolder of your server root folder.
Activating SSL
Once you've obtained and installed a server certificate, use Sun ONE Server Console to activate SSL on your Sun ONE server. The following procedure uses Sun ONE Administration Server as its example. Activating SSL on other Sun ONE servers is done the same way, although in some cases the interface is slightly different. For more information on how to activate SSL on another server product, see that server's documentation.
To Activate SSL on a Sun ONE Server
- In the Sun ONE Server Console navigation tree, select the server instance with which you want to use SSL encryption.
- Click Open to open the management window for the server instance.
- Click the Configuration tab.
- Click the Encryption tab.
- Enter information as appropriate:
Enable SSL for this server. Select this option if you want to secure this server with Secure Sockets Layer (SSL) encryption. All other SSL encryption options listed here become available to you only when you enable SSL by checking this box.
Use this cipher family. When you enable SSL encryption, the cipher families available to you are listed here. Sun ONE Server Console currently supports RSA cipher families. Select the cipher families you want to use.
Security Device. Choose internal (software) if the key is stored in the local key database. All other choices on this list are available only if you are using an external module.
Certificate. Choose a server certificate to use with this server.
Settings. Click this button to modify cipher (encryption algorithm) settings for the certificate you selected above.
Disable Client Authentication. Select this option if you do not want this server instance to perform client authentication.
Require Client Authentication. Select this option if you want this server instance to require client authentication during the SSL handshake. For background information, refer to "Using Client Authentication".
If you select this option, each Sun ONE Server Console administrator is prompted for a certificate when logging in. This ensures system security because all administrators must present acceptable certificates before they can perform management tasks. Even if an intruder obtains a user name and password, the intruder must present a valid certificate (one issued by a trusted CA) to gain access to your enterprise.
For more information on setting trust options for CA certificates, see "To Change the CA Trust Options".
Note Specific servers include additional options here.
- Click the Network tab.
- Set the port number for the Secure Port.
- Click Save.
- Exit Sun ONE Server Console and restart the server you have SSL-enabled from the command line.
You can now start Sun ONE Server Console again and log in to work with the server through Sun ONE Server Console.
Managing Server Certificates
Periodically, you may need to update information for your installed SSL certificates. From Sun ONE Server Console, you can renew a server certificate as well as view and edit settings for all certificates installed on a server.
Renewing a Certificate
Like credit cards or any other form of identification, all certificates have validity periods. You can check any certificate's expiration date from within Sun ONE Server Console. When a server certificate is nearing its expiration date, you can use Sun ONE Server Console to generate a renewal request.
To Check a Certificate Expiration Date
- In the Sun ONE Server Console navigation tree, select the server instance that is using the certificate whose expiration date you want to check.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Depending on which type of certificate you are checking, click the Server Certs or CA Certs tab.
- Locate the certificate you are checking.
The certificate's validity period ends on the date shown in the Expiration Date column.
To Generate a Certificate Renewal Request
- In the Sun ONE Server Console navigation tree, select the server instance that is using the certificate you want to renew.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Click the Server Certs tab.
- From the list of available certificates, select the one you want to renew, and then click the Renew button.
- Select "Request Certificate Manually," and then click Next.
- Enter the requested information:
Server Name. (Optional) Enter the fully qualified host name of the machine for which you're requesting a certificate.
Organization. (Optional) Enter your organization's name.
Organizational Unit. (Optional) Enter your division, department, or other organizational unit.
City/locality. (Optional) Enter the city or locality in which your organizational unit is located.
State/province. (Optional) Enter the state or province in which your organizational unit is located.
Country/region. (Optional) Enter the state or province in which your organizational unit is located.
You can toggle between two views of the request form using the following buttons:
Show DN. Click to show the requestor information in distinguished name (DN) format. This button is visible only when you are entering information in fields.
Show Fields. Click to show the requestor information in fields. This button is visible only when you are entering information in DN format.
- Click Next.
- Enter the password for the security device that stores this certificate.
If you are using the internal (software) security device, this is the password for the key and certificate database. If you are using an external (hardware) module, this is the password for your SmartCard or other security device.
- Click Next.
- Copy or save the request in one of the following ways:
Copy to Clipboard. Click to copy your certificate request to the clipboard.
Save to File. Click to save your request as a text file. You are prompted to choose a name and location for the file.
The certificate request you have copied to the clipboard or saved as a text file is required to email to a Certificate Authority issuing the new certificate. See "To Send a Server Certificate Request as Email" .
- Click Done to close the Certificate Request Wizard.
You can now send your certificate renewal request to your CA. For more information, see "To Send a Server Certificate Request as Email"
Changing the CA Trust Options
At times, you may need to reject a generally trusted CA. For example, if you are notified that a CA is experiencing technical difficulties that prevent certificate authentication, you can temporarily reject the CA's certificate. When you are informed that the problem has been resolved, you can begin trusting the certificate again.
To Change the CA Trust Options
- In the Sun ONE Server Console navigation tree, select the server instance on which you want to change a CA trust option.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Click the CA Certs tab and then, from the list of available CA certificates, select the CA certificate for which you want to change the trust options.
- Click the Edit Trust button.
- Set the following CA trust options:
Accepting connections from clients (Client Authentication). Uncheck this box if you want to reject client certificates issued by this CA.
Making connections to other servers (Server Authentication). Uncheck this box if you want to reject server certificates issued by this CA.
- Click OK.
Changing Security Device Passwords
You should periodically change the passwords for your security devices.
To Change a Security Device Password
- In the Sun ONE Server Console navigation tree, select the server instance that is using the security device for which you want to change the password.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Choose a security device from the drop-down list.
- Click Password.
- In the Change Security Device Password dialog box, enter password information:
Old password. Enter the password currently used with this device.
New Password. Enter a new password.
New Password (again). Enter the password again to confirm it.
- Click OK.
Managing Revoke Certificate Lists
Certificate revocation lists (CRLs) and compromised key lists (CKLs) allow CAs to specify certificates and keys that client or server users should no longer trust.
If data in a certificate changes, a CA can revoke the certificate and list it in a CRL—for example, when a user changes offices or leaves an organization before his or her certificate expires. If a key is tampered with or otherwise compromised, a CA can list it in a CKL.
CRLs and CKLs are produced and periodically updated by a CA.
To Obtain a CRL or CKL From a CA
- Use a browser to go to the CA's web site. Contact your CA administrator for the exact URL.
- Follow the CA's instructions for downloading the CRL or CKL to a local directory.
Once you've saved the CRL or CKL file to a local directory, you can add its contents to the database of lists of revoked certificates and compromised keys. Once you do this, your server no longer trusts the certificates or keys that are specified in the CRL or CKL file.
To View, Add, or Delete a CRL or CKL
- In the Sun ONE Server Console navigation tree, select the server instance that you want to work with.
- Click Open to open the management window for the server instance.
- On the Tasks tab, click the Manage Certificates task button.
Alternatively, you can open the Console menu, and then choose Security > Manage Certificates.
- Choose a security device.
If the server instance is using only the internal (software) security device, it is automatically chosen for you. If you are using an external (hardware) module, choose it from the drop-down list.
- Select the Revoked Certs tab.
Every CRL and CKL for the chosen device is listed along with the date it was generated and the date for the next update.
- View, add, or delete a CRL or CKL.
- To view the contents of a CRL or CKL, select its name, and click Detail.
- To add a CRL or CKL for the selected device, click Add, and then enter the following information:
Enter full path to CRL/CKL file. Provide the full path to the file containing the CRL or CKL.
File contains a Certificate Revocation List (CRL). Select this option if you're adding a CRL.
File contains a Compromised Key List (CKL). Select this option if you're adding a CKL.
- To delete a CRL or CKL from the selected device's trust database, select it, and then click Delete.
- Click OK.
Using Client Authentication
You can configure some Sun ONE servers to require that clients present certificates when logging in. This allows a server to verify a client's authenticity and to determine if a user has access to the server. The process of presenting and verifying a client certificate is called client authentication.
This section tells you how to set up and use client authentication on your Sun ONE server. Before reading this section, check your server's documentation to verify that the server supports client authentication.
How Client Authentication Works
When a server receives a request from a client, it can ask for the client's certificate before proceeding. A client is programmed to respond by sending a client certificate to the server.
After checking that a client certificate chain ends with a trusted CA, an Sun ONE server can optionally determine which user is identified by the client certificate and then look up that user's entry in the directory. The server authenticates the user by comparing the information in the certificate with the data in the user's directory entry.
In order to locate user entries in the directory, a server must know how to interpret certificates from different CAs. You provide the server with interpretation information by editing a file called certmap.conf. This file provides three kinds of information for each listed CA:
- It maps the distinguished name (DN) in the certificate to a branch point in the LDAP directory.
- It specifies which DN values from the certificate (user name, email address, and so on) the server should use for the purpose of searching the directory.
- It specifies whether the server should go through an additional verification process. This process involves comparing the certificate presented by the client for authentication with the certificate stored in the user's directory entry. By comparing the certificate, the server determines whether to allow access or whether to revoke a certificate by removing it from the user's directory entry.
If more than one directory entry contains the information in the user's certificate, the server can examine all matching entries in order to determine which user is trying to authenticate. When examining a directory entry, the server compares the presented certificate with the certificate stored in the entry. If the presented certificate doesn't match any directory entries or if matching entries don't contain matching certificates, client authentication fails.
After the server finds a matching entry and certificate in the directory, it can determine the appropriate kind of authorization for the client. For example, some servers use information from a user's entry to determine group membership, which in turn can be used during evaluation of ACIs to determine what resources the user is authorized to access.
You can also configure client authentication between an instance of Administration Server and another Sun ONE server. For more information see "Using Client Authentication Between Servers"."
Preparing to Use Client Authentication
In order to accept certificates for client authentication, you must fulfill the following requirements:
- The server must have SSL turned on. For more information, see "Activating SSL".
- The instance of Administration Server must trust the CA who issued the certificate to the client. For more information, see "Changing the CA Trust Options".
- If you are going to search the directory for information contained in certificates, you must map specific CAs to branches of the user directory. To do this, you must edit a file called certmap.conf. The rest of this section describes this file and tells you how to edit it.
The certmap.conf File
When a server performs client authentication, it interprets a certificate, extracts user information, and then searches the directory for that information. In order to process certificates from different CAs, the server uses a file called certmap.conf. This file contains instructions on how to interpret different certificates and how to search the directory for the information that those certificates contain.
The certmap.conf file is stored in the ServerRoot/shared/config folder. The file contains a default mapping as well as mappings for specific CAs.
The default mapping specifies what the server should do if a client certificate was issued by a CA that isn't listed in certmap.conf. The mappings for specific CAs specify what the server should do for client certificates issued by those CAs. All mappings define the following:
- Where in the directory the server should begin its search
- What certificate attributes the server should use as search criteria
- Whether the server should verify the certificate with a certificate that is stored in the directory
Mappings have the following syntax:
certmap name issuerDN
name:property [value]
name:property [value]
...
The first line of a mapping specifies the mapping's name as well as the DN for the issuer of the client certificate. You can name a mapping whatever you want, but the issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuerDN lines differ only in the number of spaces they contain, but the server would treat these two entries as different:
certmap name ou=Sun ONE CA,o=Sun ONE,c=US
certmap name ou=Sun ONE CA, o=Sun ONE, c=US
The second and subsequent lines of a mapping identify the rules that the server should use when searching the directory for information extracted from a certificate. These rules are specified through the use of one or more of the following properties: DNComps, FilterComps, VerifyCert, CmapLdapAttr, Library, and InitFn. These properties are explained next.
DNComps
DNComps is a comma-separated list of relative distinguished name (RDN) keywords used to determine where in the user directory the server should start searching for entries that match the information for the owner of the client certificate. The server gathers values for these keywords from the client certificate and uses the values to form a DN, which determines where the server starts its search in the directory.
For example, if you set DNComps to use the o and c RDN keywords, the server starts the search from the o=org, c=country entry in the directory, where org and country are replaced with values from the DN in the certificate.
- If there isn't a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate to determine where to start searching.
- If the DNComps entry is present but has no value, the server searches the entire directory tree for entries matching the filter specified by FilterComps.
The following RDN keywords are supported for DNComps: cn, ou, o, c, l, st, e, and mail. You can list the keywords in lower case or upper case. You can use e or mail, but not both.
FilterComps
FilterComps is a comma-separated list of RDN keywords used to create a filter by gathering information from the user's DN in the client certificate. The server uses the values for these keywords to form the search criteria for matching entries in the LDAP directory. If the server finds one or more entries in the directory that match the user's information gathered from the certificate, the search is successful and the server performs a verification (if verifycert is set to on).
For example, if FilterComps is set to use the e and uid attribute keywords (FilterComps=e,uid), the server searches the directory for an entry whose values for e and uid match the user's information gathered from the client certificate. Email addresses and user IDs are good filters because they are usually unique entries in the directory.
The filter needs to be specific enough to match one and only one entry in the directory. The following RDN keywords are supported for FilterComps: cn, ou, o, c, l, st, e, and mail. You can list the keywords in lowercase or uppercase letters. You can use e or mail, but not both.
VerifyCert
VerifyCert tells the server whether it should compare the client's certificate with the certificate found in the user's directory entry. It takes one of two values: on or off. Setting the value to on ensures that the server does not authenticate the client unless the certificate presented exactly matches the certificate stored in the directory. Setting the value to off disables the verification process.
CmapLdapAttr
CmapLdapAttr is the name of the attribute in the directory that contains subject DNs from all certificates belonging to the user. Because this attribute isn't a standard LDAP attribute, you have to extend the LDAP schema to include it.
If the CmapLdapAttr property exists in a certmap.conf mapping, the server searches the entire directory for an entry that contains the subject's full DN. The search criteria are the attribute named by CmapLdapAttr and the subject's full DN as listed in the certificate. If the search doesn't yield any entries, the server retries the search using the DNComps and FilterComps mappings. The search takes place more quickly if the attribute specified by CmapLdapAttr is indexed.
Using CmapLdapAttr to match a certificate to a directory entry is useful when it's difficult to match entries using DNComps and FilterComps.
Library
Library is the pathname to a shared library or DLL. You need to use this property only if you want to extend or replace the standard functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless you have very specialized mapping requirements.
InitFn
InitFn is the name of an init function from a custom library. You need to use this property only if you want to extend or replace the functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless you have very specialized mapping requirements.
Editing the certmap.conf File
This section tells you how to edit the certmap.conf file.
To Edit the certmap.conf File
- In a text editor, open ServerRoot/shared/config/certmap.conf.
- If necessary, make changes to the default mapping.
For example, you may want to change the value for DNComps or FilterComps. If you want to comment out a line, insert a # before it.
- If desired, create a mapping for a specific CA.
The mapping should take this form: certmap mappingName issuerDN.
For example, to create a mapping named "Example CA" which has the issuer DN ou=Example CA, o=Example, c=US, you would enter the following:
certmap Example CA ou=Example CA, o=Example, c=US
- Add property settings for a specific CA's mapping.
If you are using the library and InitFn properties, you must specify them before adding any additional properties.
When adding a property, use this form:
mappingName:propertyName value
For example, you could add a DNComps value of o, c for Example CA by entering the following line:
Example CA:DNComps o, c
If you are using the Library and InitFn properties, a complete mapping might look like this:
certmap Example CA ou=Example CA, o=Example, c=US
Example CA:Library /usr/ds/v5.2/servers/userdb/plugin.so
Example CA:InitFn plugin_init_dn
Example CA:DNComps o, c
Example CA:FilterComps e, uid
Example CA:VerifyCert on
Example CA:CmapLdapAttr certSubjectDN
- Save the certmap.conf file.
Example certmap.conf Mappings
The following examples illustrate three different ways you can use the certmap.conf file.
Example of a Default Mapping
Here are the contents of a simple certmap.conf file that contains only the default mapping:
certmap default default
default:DNComps ou, o, c
default:FilterComps e, uid
default:verifycert onUsing this example, the server starts its search at the directory branch point containing the entry ou=organizationalUnit, o=organization, c=country, where the italics represent values from the subject's DN in the client certificate.
The server then uses the values for e (email address) and uid (user ID) from the certificate to search for a match in the directory before authenticating the user. When it finds a matching entry, the server verifies the certificate by comparing the certificate the client sent to the certificate stored in the directory.
Example of an Additional Mapping
Here are the contents of a sample certmap.conf file that defines a default mapping as well as a mapping for MyCA:
certmap default default
default:DNComps
default:FilterComps e, uid
certmap MyCA ou=MySpecialTrust,o=MyOrg,c=US
MyCA:DNComps ou,o,c
MyCA:FilterComps e
MyCA:verifycert onWhen the server gets a certificate from a CA other than MyCA, the server uses the default mapping, which starts at the top of the directory tree and searches for an entry matching the client's email address (e) and user ID (uid). If the certificate is from MyCA, the server starts its search at the directory branch containing the organizational unit specified in the subject DN and searches for email addresses (e) that match the one specified in the certificate. If the certificate is from MyCA, the server verifies the certificate. If the certificate is from another CA, the server does not verify it.
Example of a Mapping With an Attribute Search
This example uses the CmapLdapAttr property to search the directory for an attribute called certSubjectDN whose value exactly matches the entire subject DN in the client certificate:
certmap MyCo ou=My Company Inc, o=MyCo, c=US
MyCo:CmapLdapAttr certSubjectDN
MyCo:DNComps o, c
MyCo:FilterComps mail, uid
MyCo:verifycert onIf the subject DN in the client certificate is uid=Henry Jones Junior, o=Example Inc, c=US, then the server searches for entries that have certSubjectDN=uid=Henry Jones Junior, o=Example Inc, c=US.
If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server uses DNComps and FilterComps to search for matching entries. For the client certificate described above, the server would search for uid=Henry Jones Junior in all entries under o=Example Inc, c=US.
Using Client Authentication Between Servers
If both servers support client authentication, you can use client authentication when establishing a connection from one Sun ONE server to another. Typically, you use client authentication to authenticate an instance of Administration Server to another Sun ONE server instance. In these cases, the instance of Administration Server acts as the client.
The following procedure tells you how to set up client authentication between an Sun ONE server and an instance of Administration Server.
To Set Up Client Authentication Between Servers
- Install certificates on an instance of Administration Server and the Sun ONE server instance that performs the authentication.
For more information, see "To Install a Server Certificate".
- If necessary, install CA certificates and specify that they should be trusted.
The instance of Administration Server needs to trust the CA that issued the certificate in use by the Sun ONE server instance. The Sun ONE server instance needs to trust the CA that issued the certificate in use by the instance of Administration Server.
For more information, see "To Install a CA Certificate or Server Certificate Chain".
- On the Sun ONE server instance that performs the authentication, enable SSL and Client Authentication, and then restart the server.
Typically, you enable SSL and Client Authentication by changing the encryption settings on the server's Configuration tab. For more information, see your server's documentation.
- In a text editor, open ServerRoot/admin-serv/config/adm.conf.
- Change the value for ldapPort to the secure port in use by the Sun ONE server instance.
- Restart the instance of Administration Server.
For more information, see "Restarting Administration Server".
The Sun ONE server instance now uses client authentication when communicating with the instance of Administration Server.
Client Authentication for Users
You can use client authentication to verify the identity and access permission of a user, typically an administrator, to an Administration Server instance. Before enabling client authentication for users, the server must have a CA certificate chain and server certificate installed and have SSL enabled.
Instructions for obtaining and installing server certificates and CA certificate chains are found in this chapter in the section entitled "Obtaining and Installing a Server Certificate". Instructions for enabling SSL are also found in this chapter in the section entitled "Activating SSL".
To Set Up Client Authentication for Users
- Install certificates on both the instance of Administration Server and the client that participates in authentication.
For more information, see "To Install a Server Certificate".
- If necessary, install CA certificates and specify that they should be trusted.
The instance of Administration Server needs to trust the CA that issued the certificate in use by the client. The client needs to trust the CA that issued the certificate in use by the Administration Server.
For more information, see "To Install a CA Certificate or Server Certificate Chain".
- On the Administration Server instance that performs the authentication, enable SSL and Client Authentication, and then restart the server.
Typically, this is done by changing the encryption settings on the server's Configuration tab. For more information, see your server's documentation.
- Save client certificates in the Netscape Communicator certificate database.
New or existing certificates saved in the Netscape Communicator certificate database adopt the appropriate database format.
- Copy the Netscape Communicator certificate database files, cert7.db and key3.db, that contain your certificates to your .mcc directory.
In Windows, the cert7.db and key3.db files are located in C:\ProgramFiles\netscape\Users\username
On UNIX systems, the cert7.db and key3.db files are located in your home directory, /$HOME/.netscape. $HOME is your root directory if you are running Administration Server as root. $HOME is your user home directory if you are running Administration Server as a user, for example, /home/username or /export/home/username.
In Windows the .mcc directory is located in C:\WINNT\Profiles\username
On UNIX systems the .mcc directory is located in your home directory. For example, if the Administration Server is running as root, then .mcc directory is located in the root directory, /.mcc. If Administration Server is running as a user, then .mcc is in your user directory, /home/username/.mcc or /export/home/username/.mcc.
The next time you start Console, the Select Certificate window appears. Select a certificate from the pull down menu to continue with an encrypted session in Console.