These release notes contain important information about Netscape Certificate Management System, version 4.2. Please read these notes before using the product. Use of this product is subject to the terms detailed in the license agreement accompanying it.

Note: The name of the product has been changed to iPlanet Certificate Management System and the product-download site (http://www.iplanet.com/downloads/download/) identifies the product as iPlanet Certificate Management System 4.2. The name change is not reflected in the documentation or in the software.

---

Contents

---

What's New in This Release

• Supported Operating Systems
• Other Packages
• Features

Supported Operating Systems

Other Packages

Features

CMS Documentation

After you run the setup script as described under Installation Procedure, see the file below for a complete list of the documentation installed with the product: <server_root>/manual/index.html

If you are working with files you have downloaded from the web site (http://www.iplanet.com/downloads/download/index.html), as opposed to the files on the CD, the Docs directory mentioned above will not be present. Instead, you must first run the setup script, then check this file for the documentation: <server_root>/manual/index.html

For the latest information about Certificate Management System, including current release notes, technical notes, and deployment information, check this URL: http://docs.iplanet.com/docs/manuals/cms.html

Software/Hardware Requirements

Operating Systems Supported

Windows NT 4.0 with Service Pack 4, 5, or 6

Solaris 2.6, 2.7, or 8

Compaq Tru64 v4.0D

AIX 4.3

HP-UX B.11.00

Other Required Software

• Netscape Administration Server 4.2 (included)
• Netscape Directory Server 4.12 (included)

Check the Directory Server 4.12 release notes at http://docs.iplanet.com/docs/manuals/directory.html for the latest information about installing this server.
• Browser software that supports SSL

Note: We strongly recommend that users who will interact with Certificate Management System as agents or end entities using Netscape Communicator should use Communicator version 4.7x. Earlier versions, such as 4.5x, may not work properly. Netscape 6 has not yet been fully tested with Certificate Management System 4.2.

 Platform and Hard Disk Requirements

In addition to the requirements listed below, make sure you have ample swap space or virtual memory allocated for the system on which you intend to install Certificate Management System.
 

Solaris Platform Requirements
OS Version	Solaris 2.6, 2.7, or 8
Machine	Ultra 1 or faster
RAM	128 MB (required)
Hard disk storage space requirements	Total required is approximately 400 MB, as follows: Total transient space required during installation: 100 MB Hard disk storage space required for installation: Space required for setup, configuration, and running the server: approximately 250 MB Additional space to allow for database growth in pilot deployment: approximately 50 MB Total disk storage space for installation: approximately 300 MB
Windows NT Platform Requirements
OS Version	Windows NT 4.0 with Service Pack 4, 5, or 6
Machine	Pentium 166 or faster
File system	NTFS or FAT
RAM	128 MB of RAM (recommended)
Hard disk storage space requirements	Total required is approximately 350 MB, as follows: Total transient space required during installation: 100 MB Hard disk storage space required for installation: Space required for setup, configuration, and running the server: approximately 200 MB Additional space to allow for database growth in pilot deployment: approximately 50 MB Total disk storage space for installation: approximately 250 MB
Other Requirements
On Unix systems, you must install as root in order to use well-known port numbers (such as 443) that are less than 1024. If you do not plan to use port numbers less than 1024, you do not need to install as root. If you plan to run as root, you should also install as root and specify nobody as the default run-as user and group. On a Windows NT system, you must install as Administrator or a user with Administrator privileges (that is, the user must be in the Administrators group).

---

Installation Procedure

• Before installing the product, be sure to read the installation instructions in Netscape Certificate Management System Installation and Deployment Guide.

• If you're using the product CD for installation, this book is available as a PDF file at Docs/cms42_install.pdf.
• If you downloaded the software from the web site, be sure to download the pdf version of the book from this site: http://docs.iplanet.com/docs/manuals/cms.html

• If you don't have any previous installation of Certificate Management System, follow the instructions for installing the software. It involves the following stages:
• Stage 1: Run the installation script (setup on Unix, setup.exe on Windows NT) to install administration and directory servers as necessary, and perform the initial phase of CMS installation.
• Stage 2: Run the Installation Wizard to set up the initial configuration of the CMS instance. This is where you specify which subsystems are to be part of this instance.
• Stage 3: Use Netscape Console to further configure the new CMS instance as needed. For example, you must provide it with information about the LDAP publishing and authentication directories.
• Stage 4: If you wish, use Netscape Console to create additional instances of the Certificate Management System in the same server root directory, and use the Installation Wizard to configure them.

• If you want to upgrade from Certificate Management System, version 4.1, follow the instructions in Upgrade From Certificate Management System 4.1x.

• If you wish to install a separate, stand-alone version of Netscape Console 4.2 for any reason, you can download it from this site: http://www.iplanet.com/downloads/patches/

---

Upgrade From Certificate Management System 4.1x

When you run the installation program for upgrading a CMS 4.1x instance, you will be presented with the following panels (the example below lists the panels on UNIX):

- Welcome
- License
- Product Selection
- Location
- Server Products Components

- Core Components
- Directory Suite Components
- Administration Service Components
- Certificate Server Components

- Fully qualified domain name of machine
- User and Group

- System User
- System Group

- Configuration Directory Server Administration Identifier

- Administrator ID
- Password

- Administration Server Port for Console (You must enter the same port
    number that was used for your 4.1 Console)
- Administration Server User
- Certificate Server Identifier (The CMS instance name that you enter in
    this panel must exist.)

• Prior to attempting any upgrade from CMS 4.1 to CMS 4.2, always remember to shutdown all instances of the Console, as these clients are never shutdown by the upgrade process, and therefore, may not be correctly updated. [# 399545]
• Only the CMS instance you specify in the upgrade panel is updated, although all of the global files are restored upon updating each and every instance. Therefore, you must perform the upgrade process for each and every CMS instance individually.
• All CMS instances are shutdown each time so that any global CMS information may be updated.
• Backup copies of the following list of original files and directories are saved with an underscore and timestamp appended (for example, classes/ becomes classes_20000506035603Z/) before the new file or directory replaces them:

- Instance Specific:
- classes/           (directory)
- emails/            (directory)
- restart-cert[.bat] (file)
- start-cert[.bat]   (file)
- stop-cert[.bat]    (file)
- web/               (directory)


- Globally Specific:  (backed up for each instance)

- bin/cert/classes/  (directory)

• Since the start and restart scripts are always replaced on a per instance basis, any changes you have made will be backed up, and you must manually edit these scripts to put back your customizations.
• All CMS instances are restarted. During restart, you are prompted for the single sign-on password, if automatic restart has not already been configured/reconfigured ahead of time.
• There should be no reason to configure an updated instance, as there is on a first-time installation.
• You may upgrade an instance numerous times to restore any corrupted global binaries. However, backup copies of the files and directories detailed above will be created upon each update.
• Occasionally, upgrade does not allow you to specify the port number for the console to be reused. It is okay to use a different port number for the console, however, you must remember to use this new port number the next time that you login to Netscape Console.
• Since upgrades must be done on a per instance basis, if you have two instances, and if you upgrade the first and then launch the console, you may notice that the instance that has not been upgraded will be displayed "out of alignment" within the GUI. You can consider this as a visual clue that you need to upgrade this instance as well. After upgrading this, the instance will appear aligned correctly within the GUI. [# 394988]

Step 1. Stop Certificate Management System.
Step 2. Update the basic indexes.
     To do this, make sure the following indexes are specified in the
     <server_root>/slapd-<instance_id>-db/config/slapd.ldbm.conf file:

index description eq,pres
index serialno eq,pres
index subjectname eq,pres,sub
index certstatus eq,pres
index extension eq,pres,sub
index revinfo eq,pres,sub
index revokedby eq
index issuedby eq
index requestid eq,pres
index requesttype eq,pres
index requeststate eq,pres
index notbefore eq,pres
index notafter eq,pres
index ownername eq,pres
index publickeydata eq,pres
index duration eq,pres
index dateOfCreate eq,pres
index revokedOn eq,pres
index publickeydata eq,pres
index archivedby eq,pres

1. Go to this directory: <server_root>/slapd-<instance_id>-db
2. Perform the following command for each installed subsystem (that is, the Certificate Manager, Registration Manager, and Data Recovery Manager):

../shared/bin/ldapmodify -h <HOSTNAME> -p <PORT_OF_SLAPD_INSTANCE> -D <DN_OF_DIRECTORY_MANAGER> -w <PASSWORD> -c -a -f <INDEX_FILE>
where <INDEX_FILE> is as follows:

<server_root>/bin/cert/install/42-ca-vlv.ldif for the Certificate Manager
<server_root>/bin/cert/install/42-ra-vlv.ldif for the  Registration Manager
<server_root>/bin/cert/install/42-kra-vlv.ldif for the Data Recovery Manager

For example, if you have a CMS instance with Certificate Manager and Data Recovery Manager, your command would look similar to this:

../shared/bin/ldapmodify -h certificate.siroe.com -p 38900 -D "cn=directory manager" -w "pwd1234" -c -a -f d:\netscape\server4\bin\cert\install\42-ca-vlv.ldif

../shared/bin/ldapmodify -h certificate.siroe.com -p 38900 -D "cn=directory manager" -w "pwd1234" -c -a -f d:\netscape\server4\bin\cert\install\42-kra-vlv.ldif

(You might see some warning messages because some of the indexes were
created in CMS 4.1 installation.)

      ./db2ldif

This command will create a file in ldif sub-directory, and the timestamp is used as the filename.

./ldif2db -noconfig -i <server_root>/slapd-<instance_id>-db/ldif/<timestamp>.ldif

Step 8. Start Certificate Management System.

Important Notes and Known Bugs

• Administration Server
• Authentication
• Backup and Restore
• Browser
• CA Cloning
• CEP Support
• CGI Support
• CRLs
• Custom Plug-in Modules
• Directory Server
• DSA
• Enrollment
• Enterprise Server
• Extensions
• Hardware Tokens
• Installation
• Internationalization
• Job Scheduling/Notification
• JSS
• Logging
• Migration Tool
• Miscellaneous
• Performance
• Personal Security Manager
• Policies
• Publishing
• Remote Registration Manager
• Renewal of CMS Certificates
• Request Queue Processing
• Revocation
• Samples and SDKs
• Scalability/Sizing
• Searching for Certificates
• Starting/Stopping the Server
• Third-Party Products
• UI (Netscape Console/CMS Window)

Administration Server

• To change the IP address of Administration Server, use the perl script provided in
<server_root>/shared/bin/admin_ip.pl
The syntax is admin_ip.pl <Dir Manager's DN> <Dir Manager's password> <old IP> <new IP> [port]
where
• <Dir Manager's DN> is the DN of the manager of the Administration Server configuration directory (for example, "cn=Directory Manager");
• <Dir Manager's password> is the password used to bind to the Administration Server configuration directory;
• <old IP> is the current IP address;
• <new IP> is the new IP address you want to use;
• [port] (optional) is the port Administration Server should use on the new address.

• After you create a new CMS instance using Netscape Console, the Console window does not display the instance in the navigation panel. To display the new CMS instance in the panel, click the Console's View menu and select Refresh.

• When you're trying to create a new CMS instance and if Administration Server starts up before the configuration Directory Server, you will get the following message and the instance will not be created:

Please restart the console and admin server before creating a new instance

Once you  restart Administration Server, you will be able to create CMS instances without receiving the above message. Note that the above message will not always occur for all CMS  instance creations--it appears mostly due to the randomness of the start order between Administration and Directory Servers on Window NT; typically, Directory Server starts first, but there are cases where Administration Server starts first. Certificate Management System requires Directory Server started prior to Administration Server. [# 394059]

• Netscape Administration Server does not support EXCEED X server software for running Unix X-Windows applications on Windows NT. Therefore, EXCEED will not run reliably with Certificate Management System.

• Netscape Administration Server might crash when you create or remove a CMS instance. If this happens, go to the command line and start Administration Server. [# 352824 and # 352372]

• By default, Administration Server administrator's password (also known as the SIE password) is stored in clear text in the adm.conf file.

This does not usually pose a security threat because most administrators use their Operating System's security features to ensure that the file is protected from other users. However, as an added security measure, you may choose to remove the clear text password.

If you remove the password from the adm.conf file, every time you start Netscape Console, you'll be prompted for the Administration Server administrator's password.



Once you've provided the password, if the server you're trying to connect to uses SSL, you'll be asked for the SSL token password you specified when you installed the server certificate.



To remove the clear text Administration Server password:

1. Stop the Administration Server.
2. Go to this directory: <server_root>/admin-serv/config
3. Open the adm.conf file in a text editor.
4. Delete this entry: siepid: <password>
5. Save the text file.
6. To restart the Administration Server, at the command line, run start-admin.

Known problem: As long as the SIE password is not included in the adm.conf file, you won't be able to use Netscape Console to restart Administration Server; you'll have to start the server by running startconsole at the command line. [ # 357862]

• See also the ones listed in Installation and UI (Netscape Console/CMS Window) sections.

Authentication

• When naming an authentication instance (or rule), be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type Pin_Dir_auth or PinDirAuth as the instance name, but not Pin Dir Auth.

• Agents and administrators must be users in the Certificate Management System user and group database. This will be replaced by ACLs in future releases.

Backup and Restore

• You cannot restore backed-up data to a CMS instance until it has been configured. So, if you had to re-install the Certificate Management System, you must configure the server (using the configuration wizard in Netscape Console) before you can restore the data. Appendix B of the Administrator's Guide documents how to back up and restore data. The following text should be included as part of the "Before You Restore Data" section in that appendix:

You cannot restore data to a CMS instance that has not been configured. If you re-installed Certificate Management System prior to attempting to restore data, you must configure the new CMS instance. When you configure the new installation, keep the following points in mind:
• All services (CMS, directory servers) should be running on the same network ports as they were when the backup archive was created. For example, the administration console port is a random number by default, so be sure to change the default offered during installation to the same port that the backed-up server installation used.
• During configuration, you still need to create new keys and certificates for any servers that use the internal software token. You only need to create these keys to complete the configuration process. Your signing, SSL, and DRM transport certificates and keys will be restored when you run the restore script (replacing whatever is created during the new configuration). [# 388080]

Browser

• Certificate Management System supports RSA key sizes that are up to 4096 bits in length. If you plan on issuing certificates with key sizes larger than 2048 bits, make sure to use Netscape Communicator versions 4.72 or later because only these versions support key sizes larger than 2048 bits. If you're using Netscape Communicator with Personal Security Manager, you can use version 4.7x. For example, if you've generated the CA signing certificate of a Certificate Manager with 4096-bit key and if you attempt to connect to the agent port or the end-entity secure (HTTPS) port using Communicator versions earlier than 4.72, the browser will crash. Similarly, if you connect to sites that use 4096-bit keys (for their SSL server certificates), the browser will crash. Also, you won't be able to read an email whose signature was made with a 4096-bit key. [# 386815, # 386883]

• IE 5.X, 128-bit strength can access an SSL certificate that has an RSA key of length 4096 bits. IE 4.X and IE 5.X, 56-bit strength cannot access an SSL certificate that has an RSA key of length 4096 bits; IE 5.X with 56-bit strength produces a different error message than IE 4.X. [# 394936]

• IE 4.X and 5.X cache secure pages, but don't provide a means to flush the cache. This is especially frustrating when you authenticate to the agent interface with the wrong certificate, and then try to reload the page and reauthenticate with the correct certificate. You must reboot the system to get IE to stop caching the page. Communicator has similar problems with caching pages, but restarting Communicator causes it to flush cached secure pages. [# 394936]

• Microsoft Internet Explorer 3.x and Netscape Navigator 3.x are not fully supported by the default HTML interfaces for Agent Services (of the Registration Manager, Certificate Manager, and Data Recovery Manager). For best results, use Communicator 4.x or Internet Explorer 4.x.

• Client time drift detection on IE is disabled -- the HTML forms provided for end-user enrollment and renewal include JavaScript code (function named checkClientTime) that detects the time drift between the client and server clocks and prompts users to adjust their clocks (to be in sync with that of the server). This feature works only with Communicator. [# 341838]

• If you view a CRL as an agent using IE or Communicator, then revoke a certificate, and then view the CRL again, you will not see the certificate you just revoked listed in the CRL. To work around, exit the browser, relaunch it, and then view the CRL again. [# 347146]

• When you import a CRL from Certificate Management System into Communicator 4.x, a "View-Edit CRL's" button is added to the SIGNERS section of the Security Info window. If you click the "Reload" button for that particular CRL, it won't reload properly because of the incorrect URL. To make it work, you have to manually change the URL from https://<CMSEndEntityURL>/getCRL  to https://<CMSEndEntityURL>/getCRL?certSerialNumber=&op=importCRL&issuepoint=MasterCRL&submit=Submit.

• Communicator will crash when asked to do SSL client authentication if the DN for an SSL server certificate or a CA certificate does not have the O= attribute. However, there is a warning message displayed in the Installation Wizard if O= is left out of the DN when creating the certificates. This problem is fixed in Communicator 4.6.

• Communicator shows an error dialog when connecting with SSL to Netscape Enterprise Server, if the SSL certificate was generated with the Key Usage Extension policy turned on. To work around, turn off or disable the Key Usage Extension policy module. [# 344996]

• IE fails to present a dialog asking the agent user to specify the certificate to be used for SSL client authentication to the second server, when two SSL servers are configured on the same machine. This problem occurs when you connect to two different servers running on two different ports of the same machine. When you do SSL client authentication to the first server, IE  presents a dialog box  from which you can choose the certificate you want to use to authenticate. When you connect to the other server on the same machine, IE assumes that you want to use the same certificate and doesn't provide you with an opportunity to change your selection. The result is that you fail to authenticate to the second server, because IE automatically presents the certificate you chose previously. The workaround is to restart IE (after authenticating to the first server) and then attempt to authenticate to the second server; when you restart, you can connect to the other server and you will again be presented with a dialog box for choosing an SSL client certificate. [# 350416]

• If you are using the Solaris version of IE to get a certificate using directory-based user enrollment, Certificate Management System successfully imports the certificate, but IE crashes. [# 347824]

• If IE 4.x is configured to prompt the user for a confirmation when a form is being submitted, the request will be submitted correctly. However, a second browser window may appear. [# 355696]

• IE 4.x (or higher) has problem importing a renewed certificate if the KEYGEN for the certificate didn't happen in that IE. For example, if you attempt to import a renewed certificate to IE and if the original certificate was issued to Communicator or IE (installed on another machine), you'll get the following error message: Error in acceptPKCS7. Error Number 80092004 occured.

Note that the renewed certificate can be retrieved with Communicator and imported into IE without any problem, but any attempt to retrieve it using IE produces the above error. [# 397451]

• See also the ones listed in DSA, Installation, Internationalization, and Personal Security Manager sections.

CA Cloning

• Assume that you have a CA, named CA, and have created its clone, named CAClone1, using the procedures documented in CMS Installation and Deployment Guide for cloning CAs; see topic "Cloned Certificate Manager Configuration" in Chapter 5 "Installation and Configuration". The following procedure explains how to use the same agent certificate that you've already created for CA, for the cloned CA, CAClone1 (instead of creating a new agent certificate for CAClone1). [# 394959]

1. Configure the CAClone1 instance by running the Certificate Setup Wizard.
2. Locate the configuration file, CMS.cfg, for the CAClone1 instance and open it in a text editor.
3. Locate this line: agentgateway.enableAdminEnroll=true
4. Edit the line so it looks like this: agentgateway.enableAdminEnroll=false

This will change CAClone1 in to a mode where it expects a certificate (that was already issued and chains properly) to be presented when you access its agent interface.
5. Restart the CAClone1 instance.
6. Use Netscape Console and open the CMS Window for the CAClone1 instance.
7. Go to the "Users and Groups" section, create a new agent user, and associate the agent certificate of CA with the new agent. To add the correct certificate, check the serial number of the CA's agent certificate (this certificate should already exist in one of the browsers that you use to access CA's agent interface) and search for it in the CA's certificate repository. Once you locate the certificate, paste the certificate (in its base-64 encoded form) in as the agent certificate in CAClone1.
8. After creating the agent entry for CAClone1, go to https://<CAClone1 hostname>:<agent port> to verify that you can access its agent interface successfully.

• You can create a clone of a Certificate Manager on the same machine; that is, you cannot create a clone of a Certificate Manager on another machine. When you clone a Certificate Manager installed on one machine to another machine, you get the following error message: Property null.ca_keyType missing value.

For example, assume you installed and configured a Certificate Manager named CA1 on Host1. Then you tried to clone CA1 on another host, Host2. For the cloned CA, you can use the same CA signing certificate from CA1. However, since you're cloning the CA on different machine, you need to create a new SSL server certificate for the cloned CA. When you attempt to do that, you'll get the above mentioned error message:  [# 503641]

To fix the problem, use the updated Java class named CreateCertificateProcessor.class. This class is bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2-SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.

CEP Support

• See # 341389 in the Remote Registration Manager section.

• If you are setting up publishing for use with Cisco Routers^TM, it is recommended that you set the appendDN parameter in the CEP script. This will append the given DN onto all the subject names of issued CEP certificates. The reason for this is that the subject names as requested by Cisco Routers are of this form:

UNSTRUCTUREDNAME=xxx+UNSTRUCTUREDADDRESS=yyy

Appending a DN such as O=company gives the certificate a root in which it is to be published. [# 386926]

• You can download a DSA CA certificate using IRE VPN client 3.0.1b3. However, because there is no way a DSA CA certificate can be used for encryption, such an action should give you some sort of meaningful message, instead of  the message that's currently being generated:  Getting cbEncodedBlob length failed

(This message is generated after a user selects the DSA certificate for enrollment, which leads to Keygen failure with the message.) [# 394928]

• Certificate Management System comes with an automated script, cepconfig.pl, for configuring a Certificate Manager for CEP enrollments. To invoke the script, in a command-line window, cd to the server root and then enter the following:

% install/perl bin/cert/tools/cepconfig.pl on UNIX
% install\perl bin\cert\tools\cepconfig.pl on Windows NT

Notice the use of forward slash (/) on UNIX and backward slash (\) on Windows NT. The CMS Administrator's Guide (in Chapter 27 "Issuing and Managing End-Entity Certificates") doesn't tell you this; it simply asks you to enter
% install/perl/bin/cert/tools/cepconfig.pl. to invoke the script. [# 394940]

• There're four known problems with CEP enrollment:
• Configuring authentication is optional for CEP enrollments. That is, if you do not configure the server to use automated authentication for CEP-enrollment requests, requests are supposed to get deferred to the manual processing queue for approval by agents. Currently, this is broken. [# 511839]

If users try to enroll with CEP, their requests, instead of getting queued up for agent approval, get rejected with the following message in the 'system' log: User failed to  authenticate

• If the client did not set the challenge password attribute in the request, the request processing fails, but the response sent to client indicates that the request is pending. [# 517187]

• The deferOnFailure preference is not working; it always treats the value as if false and requests get rejected. (The requests are not deferred to the queue if authentication failed.) [# 517191]

• If the CEP response does not include an issued certificate (for example, if the request is still pending), Certificate Management System encodes part of the response incorrectly. The ContentInfo inside the SignedData erroneously includes an ObjectIdentifier. (The fix suggested below replaces the ObjectIdentifier with an empty octet string.) [# 517057]

To fix these problems, use the updated Java classes named CRSEnrollment.class, FlatFileAuth.class, and CRSPKIMessage.class. These classes are bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2 SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.

CGI Support

To configure the server to run a CGI script:

1. Stop Certificate Management System.
2. Go to this directory: <server_root>/cert-<instance_id>/web/ee
3. Create a directory for putting your CGI script, for example, cgi-bin.
4. Copy your CGI script to the cgi-bin directory.
5. Change to this directory: <server_root>/cert-<instance_id>/config
6. Open the configuration file, CMS.cfg, in a text editor.
7. Add the following lines:

eeGateway.servletName.CGI=com.netscape.certsrv.http.CgiServlet
eeGateway.servletAlias./cgi-bin=CGI
In this example, any file under the cgi-bin directory, or any path starting with /cgi-bin/ in the eeGateway will be executed as a CGI.
8. Save your changes.
9. Close the file.
10. Restart Certificate Management System.

CRLs

• If you are using the ValiCert plug-in with Enterprise Server, it is highly recommended that you force publish an empty CRL during the installation/configuration of your CMS system. This is so that if there are no revoked certificates, the ValiCert plug-in would not interpret it as an error and wrongly deny valid user accesses. The steps you should follow (you need to do this after all the configuration, before CMS is deployed and used) to force a CRL update is:

1. Open a web browser window.
2. Point your browser to the agent page URL, which is in this form: https://<host_name>:<agent_port>
3. Select the Update Revocation List menu.
4. Click the Update button.

• The file-based publisher doesn't create a new DER-encoded file (with timestamp) every time it publishes the CRL as stated in the documentation. Instead, it creates a single file, named crl.der, overwriting the previously published CRL with the new CRL. [# 388072]

• See also the ones listed in Browser and Publishing sections.

Custom Plug-in Modules

• When developing custom modules (for example, authentication and policy) for Certificate Management System, it is recommended that you use JDK version 1.1.8.

• See also the one in the Starting/Stopping the Server section.

Directory Server

• In the first stage of CMS installation, you run the setup program during which you specify details relevant to the configuration Directory Server, Administration Server, and Netscape Console. In one of the screens, you're asked to specify the following information about the configuration directory (whether it is an existing one or a new one to be created by the Installation Wizard):
• Directory Server identifier -- A unique identifier for the Directory Server instance (and is required for each instance). For example, configdir.
• Directory Server network port -- The port number at which the Directory Server instance will listen to (or is listening for) requests. The default is 389.
• Suffix -- The domain name of the host. If you are creating a new directory, this should be the domain name of the current host. For example, O=mydomain.comoro=siroe.com.

In the Suffix field, you should enter a valid domain name. Otherwise, the suffix/base DN of the configuration directory will not appear correctly in the configuration Directory Server UI, accessible from within Netscape Console. For example, assume you used O=Siroe Corporation as the suffix/base DN for your configuration directory. When you open the configuration Directory Server console, the highlighted top level "Siroe Corporation" displays as follows:

User Directory Subtree: O=Siroe

The "<space>Corporation" gets left off; that is, the words trailing the space get truncated in the UI. [# 395046]

• For all external directories such as the ones used for LDAP publishing and directory based authentication, if the directory is not up when Certificate Management System is started, it will still start; only an error will be logged. When the external Directory Server comes back up connections will automatically be remade. However, you can stop Certificate Management System from starting when any of the configured external directories are down with the help of the errorIfDown parameter in the configuration file, CMS.cfg. For example, if you set auths.instance.UserDirEnrollment.ldap.errorIfDown=true, Certificate Management System will fail to start up if the external authentication directory is down.

Certificate Management system will not start if the internal directory (internal database) is down.

Note that this configuration variable can only be modified in the CMS.cfg; it is not available through the CMS window. [# 345776]

• Each instance of Certificate Management System uses a Netscape Directory Server instance as its data store, referred to as the internal database. Because the internal database contains information for CMS activities, for example, activities of your CA, it's important to insulate the internal database from being visible outside its host system (and thus prevent users from outside to have access to the internal database). To make the internal database accessible only from the local machine, you must bind the Directory Server instance functioning as the internal database to a localhost (that is, IP address 127.0.0.1) with the help of listenhost parameter in the slapd.conf file; a server on localhost can only be accessed from the local machine.

However, if you bind the internal database to a localhost, Netscape Console fails to connect to the internal database. That is, if you attempt to open the console interface for the internal database from within Netscape Console, the console returns err=91, cannot connect because the LDAP server is either down or unreachable. [# 395001, # 395003]

The steps below explain how to configure Certificate Management System and the internal database to run on a localhost successfully:
1. Install Certificate Management System as you normally would.
2. Stop Certificate Management System and the Directory Server instance functioning as the internal database.
3. Add listenhost 127.0.0.1 to the slapd.conf file of the internal database. To do this:
1. Open a command-line window.
2. Go to this directory: <server_root>/slapd-<internal_database_id>-db/config
3. Open the slapd.conf file in a text editor.
4. Add this line to the beginning of the file: listenhost 127.0.0.1
5. Save your changes and close the file.
4. Change the value of the serverhostname parameter of the internal database to 127.0.0.1; if you do not do this, you cannot open the internal database from the Netscape Console topology tree. You can make this change from the configuration Directory Server Console or by using ldapmodify. To do this from the configuration Directory Server Console:
1. Log in to Netscape Console.
2. Open the console interface for the configuration directory.
3. Select the Directory tab and navigate to the server instance entry (SIE) for the internal database. The screen shot below shows how to navigate to the SIE entry of an internal database, slapd-thomask-db. (o=NetscapeRoot -> o=red.iplanet.com -> thomask.red.iplanet.com -> Server Group -> Netscape Directory Server -> slapd-thomask-db)


 
4. Right click the SIE node (for example, the slapd-thomask-db node) and select Properties. The Edit Entry dialog box appears.


 
5. Click the Advanced button at the bottom of the dialog box. The Property Editor dialog box opens.
6. Change the value of the serverhostname attribute to 127.0.0.1.


 
7. Click OK.
5. Restart Certificate Management System and the internal database.
6. Start Netscape Console by running startconsole from the command line.
7. Try to open the console interface for the internal database from within Netscape Console.

• Due to a bug in the Netscape Directory Server Gateway component of the Directory Server that comes with Certificate Management System, it is advisable to disable access to Directory Server Gateway until a fix is provided.

To disable access to Directory Server Gateway:
1. Log in to Netscape Console.
2. Open the Administration Server window (by double-clicking on its server instance ID).
3. Select the Configuration tab.
4. Select the Access tab.
5. Uncheck both "Enable end user access" and "Enable Directory Server Gateway" checkboxes.
6. Click Save.
7. Restart the Administration Server for the changes to take effect.

• See also the ones listed in Installation and Internationalization sections.

DSA

• When a DSA signing key pair is generated for a Certificate Manager, the Configuration Wizard first generates a new set of PQG parameters. This process is computationally intensive and will result in delays of several minutes, depending on the speed of the hardware.

• Communicator 4.x is the only browser that can successfully obtain and use DSA client certificates for SSL client authentication and that can recognize the signature on SSL certificates signed by a DSA CA. IE 5.x, which does support DSA, does not recognize SSL certificates signed by a DSA CA. Navigator 3.x and IE 3.x  do not support DSA at all.

• In order for Communicator to generate a DSA key pair, you must modify the KEYGEN tag in the default certificate enrollment forms; the modifications will indicate that the DSA algorithm is to be used, and will also supply the PQG parameters. For details on the KEYGEN tag, see "Netscape Extensions for User Key Generation" at this site: http://home.netscape.com/eng/security/comm4-keygen.html

Note that depending on your use of DSA, you may need to edit two KEYGEN tags in the adminEnroll.html form located here: <server_root>/cert-<instance_id>/web/agent/ca

Additionally, you may need to modify the KEYGEN tags in the following certificate enrollment forms:

• DirPinUserEnroll.html
• DirUserEnroll.html
• ManObjSignEnroll.html
• ManUserEnroll.html
• NISUserEnroll.html
• PortalEnrollment.html

These files are located here: <server_root>/cert-<instance_id>/web/ee

The procedure below explains how to modify an enrollment form:

1. Open the Certificate Manager's configuration file (CMS.cfg) in a text editor.
2. Open the enrollment form in a text editor.
3. In the configuration file, find the DSSParms entry; this entry represents the PQG attribute and its value contains the PQG parameters that the CA has generated during configuration.
4. Copy the value of the DSSParms entry.
5. Go to the text editor that has the enrollment form open.
6. Search for the KEYGEN tag.
7. Insert the cursor, a space after the word KEYGEN and type the following:

keytype="DSA" PQG=

8. Paste the value of the 'DSSParms' entry following the equal to (=) sign and enclose the value you pasted in double quotes (" ").

An example of a modified KEYGEN tag is shown below (the modifications are shown in bold):

<KEYGEN keytype="DSA" PQG="MIIBHgKBgQCsQeVqw5ID/xhSe7s4vLaOuKskCFJN23OBgWCEquYIZbMZdHN7015p6n
N7XsDpTWBccLdrSdpMxmJd8rF2agb3tbk9hjZ6//MfLCTAwvegdgAzzRwB7akOgYD/SpPFb7rYu
vPfkiRjiDDrrp9r+csWqnue9uABvJtWGnW8WVYP6wIVAMCRu0u3q+PORrJxO9QcswzrLpnfAoGA
M3ZBjxLTPbXOgWIXHZnIFSpGAW1JzK5ywEtnabJWfiIRrWi3hyWLj98PcIc2cxbpOh60rwqeElU
Mv74V72Q2+HwIQwsPvTFyQUcBtOG40zlXoFwEqlaqDoXv3iA0Zp2XQy/JQFbx23J+0HKz7iB7co
04LCa0wDU7Z0x+oTwmsd0=" name="subjectKeyGenInfo">

9. Repeat steps 6 through 8 to modify any additional KEYGEN tags.
10. Save your changes.
11. Following the procedure below, configure the server to accept DSA key based certificate enrollment requests; by default, the server only accepts RSA key-based requests. [# 352662 and # 356015]

a. Open Netscape Console.
b. Open the CMS window for the Certificate Manager.
c. Click the Configuration tab.
d. In the navigation tree, select Certificate Manager.
e. Click Policies.
f. In the Policy Rules Management tab, select the KeyAlgRule entry.
g. Click the Edit/View button.
h. Change the value of the algorithms parameter from RSA to RSA,DSA.
i. Click OK.

• Once you have generated a single DSA private key with Communicator, the browser will reuse the same private key for any subsequent KEYGEN operations, rather than generating a new one. This bug can lead to the issuance of multiple certificates with identical DSA key pairs. To work around this bug, exit Communicator after generating a DSA private key, then relaunch it again. After relaunching, Communicator will generate a new DSA private key instead of reusing an existing one. You must exit Communicator after generating each DSA private key to ensure that no certificates with duplicate private keys are issued.

• For more information about using DSA for the Personal Security Manager installation, see the accompanying CMCJavascriptAPI.html document.

• See also the ones listed in the UI (Netscape Console/CMS Window) section.

Enrollment

• In the Manual user enrollment form, special characters, such as commas, in a subject name are made valid by enclosing the value in double quotes. For example, CN =jdoe, OU=Marketing, O="Siroe Corp. , Ltd", C=US. However, when an agent approves the request, the default Subject text box displays the subject name without the double quotes enclosing the values; for example, it  shows the above subject name as CN =jdoe, OU=Marketing, O=Siroe Corp. , Ltd, C=US. If an agent approves the request, it will fail for lack of double quotes.

To fix the problem, the agent has to modify the subject value in the text box manually, before approving the request; for the given example, the agent has to add the double quotes for the O component so that the subject name is CN =jdoe, OU=Marketing, O="Siroe Corp. , Ltd", C=US. [# 400618]

• On a Windows NT system, if your display configuration is set to use a background color other than white, you may notice that some of the end-entity enrollment forms don't set the background color to white, when displayed by IE 4.0. For example, if you view the manual user enrollment form (ManUserEnroll.html) or the manual object signing enrollment form (ManObjSignEnroll.html) on IE 4.0, you'll notice that the enrollment page doesn't set the background color to white. [# 385573]

• If the Data Recovery Manager's transport certificate copied into the certificate enrollment form of a Registration Manager (or Certificate Manager) is incorrect, during enrollment you will get the following error message:

Problem Processing Your Request

The Registration Manager encountered a problem while processing your request. The following is a detailed message of the error that occurred.

     Invalid Private Key

Please consult your local administrator for further assistance. The Certificate Management System logs may provide further information.

To correct this problem, modify the corresponding enrollment form to include the correct transport certificate; for details, see the section entitled "Step 3. Customize the Certificate Enrollment Form" in Chapter 28, "Recovering Encrypted Data" of Netscape Certificate Management System Administrator's Guide. [# 355937]

• To enroll for certificates using AT&T's Secret Agent product, use the server manual enrollment page. AT&T Secret Agent will generate a PKCS #10 request that can be pasted into the Server manual enrollment page. None of the default User enrollment pages accepts PKCS #10 data. You can, of course, use the server manual enrollment default page as an example for creating a new page dedicated to enrolling AT&T Secret Agent users.

Enterprise Server

• When using Netscape Enterprise Server version 3.62 and JRun, you can use the following Java servlet code to obtain a user's certificate:

        String clientCert = "-----BEGIN CERTIFICATE-----\n" +
                servReq.getHeader("auth-cert") +
         "\n-----END CERTIFICATE-----\n";  // Newlines are critical!!!

Note that the servReq.getHeader("auth-cert") only works on Netscape servers. Sun's Java server uses req.getAttribute("javaex.net.ssl.peer_certificates").
The above code eliminates the need for you to do LDAP queries to obtain the certificate from the LDAP directory. [# 393043]

• Netscape Enterprise Server version 3.62 relies on the trust status of the issuer's certificate in its certificate database when validating client certificates presented during SSL client authentication -- When validating a client certificate, Enterprise Server verifies whether the CA that has signed the client certificate is trusted in its trust database. If the CA certificate is untrusted, the server rejects the client certificate. This information should be of interest to you if you have set up your Certificate Manager to function as a chained or linked CA -- that is, your Certificate Manager's CA signing certificate has been issued by a public or third-party CA.

Assume a deployment scenario in which your
• Certificate Manager is chained to a public root CA
• Certificate Manager has issued client certificates and all clients include the CA chain in their certificate databases
• Enterprise Server's certificate database includes both the public root CA certificate (trusted) and Certificate Manager's CA signing certificate (untrusted)

In this scenario, you would expect the Enterprise Server to successfully validate client certificates, but the server fails to do so because the Certificate Manager's CA signing certificate is untrusted in its database (untrusted issuer); the server doesn't check the root CA certificate for validation. [# 355999]

• See the ones listed in Browser and CRLs sections.

Extensions

• authorityKeyIdentifier. The documentation (Appendix B of the Installation and Deployment Guide) mentions the use of the authorityCertSerialNumber field. Certificate Management System 4.2 does not use or support this field in the authorityKeyIdentifier extension.
• subjectKeyIdentifier. The documentation wrongly states that this extension should be calculated as a hash of the certificate subjectPublicKeyInfo. In fact, it should be a hash of the subjectPublicKey. The appendix also says this extension is "used with the form of the authorityKeyIdentifier extension in which the issuer's public key is specified by a hash. In this case the verifier does not need to compute the hash, since it's only necessary to compare the issuer's Subject Key Identifier with the subject's Authority Key Identifier." Actually the subjectKeyIdentifier extension is only used in conjunction with the authorityKeyIdentifier for CA certificates. If the CA certificate has a subjectKeyIdentifier extension the key identifier in the authorityKeyIdentifier extension (of the certificate being verified) should match the key identifier of the CA's subjectKeyIdentifier extension. It is not necessary for the verifier to recompute the key identifier in this case. [# 384298]

Hardware Tokens

• When using a hardware token, you must use the token vendor's tools or utilities for initializing the token and for setting up the security officer password; the Certificate Setup Wizard may not initialize the hardware token successfully. [# 383999]

• The command-line tool keyutil (or the Key Database Tool) doesn't list keys residing in an nCipher token; for example, the command shown below won't display the list of keys residing in the token.

keyutil -L -h "tokenname" -d . -l

This will be fixed in the future version of the tool. [# 394912]

• If you have problem (Lynkstest.exe not showing expected results) using the SPYRUS^TM card with Certificate Management System running on a Windows NT system, try the following:
1. Click Start and select Control Panel.
2. In the Control Panel, double-click Devices.
3. In the Devices window, select Scsiscan and click Startup.
4. Select Disabled and click OK.


5. Remove the SPYRUS card.
6. Reboot the system.
7. After the system restarts, try running Lynkstest.exe again. If you get an error or forgot to remove the SPYRUS card when you rebooted, take the card out and put it back in, and then run Lynkstest.exe again. [# 389904]

• Hardware tokens that use a physical token (such as a key) or biometric check to unlock the key store typically do not require a password to be created during token initialization. If you're using such a hardware token with Certificate Management System, when initializing the token, the CMS installation wizard will still ask you to provide a password (even though that password is not used). To workaround this, just enter some password at the prompt and it will be ignored. Make sure that you authenticate to the hardware token (for example, by inserting the key or by using your fingerprint) before Certificate Management System attempts to generate the key. [# 381307]

• If you plan on using nCipher hardware tokens for generating keys and certificates used by CMS subsystems (for example, a Certificate Manager's CA signing certificate), be sure to use the latest version of the driver and software for the token. Certificate Management System has been tested to successfully generate DSA keys on a newer release of nCipher token. The details of this release are shown below. [# 390525]

This installer contains the following releases

sslyp devel    - SSLeay source code patch file              1.51.2
nfjava devel   - nFast Java Generic stub                    0.2.11
ldb185 user    -                                            1.0.4
nfast devel    - nFast developer software                   1.52.5
nfast user     - nFast software                             1.52.5
nftcl user     - Command line key management                1.59.2
nsapi user     - Netscape Enterprise Server 3.x plug-in     1.60.6
opensl user    - nftcl certificate generation utility       0.3.6
tclsrc devel   - Tcl run time - Headers and Libraries       1.8.7
tclsrc user    - Tcl run time                               1.8.7

• For the Solaris platform, when installing an nCipher hardware token using driver packages Cryptographic 3.06 and PKCS#11 2.02, the directory /opt/nfast/kmdata will be created. The account designated to run the CMS server processes will need access to the kmdata directory and one of its sub directories. This may be accomplished by editing /etc/group and adding the account designated to run CMS to group nfast.

For older nCipher drivers, the kmdata directory will not be created automatically.  It is recommended that the directory be created and be set to owner root and group nfast. Permissions for the directory should be set to drwxrwsr-x.  Access to the directory is then granted as described above for the newer nCipher drivers. [# 365280]

• When using Administration Server/Netscape Console to add a PKCS#11 Module, the "Add PKCS #11 Module" dialog box offers file-type choices of DLL and JAR. Pick DLL to add a UNIX shared/dynamic library, which on a Solaris machine is identified with the .so extension. [# 394396]

• When using the same hardware token for storing key pairs of multiple Certificate Manager instances, be sure to specify unique issuer DNs for the CA signing certificates. If you specify the same issuer DN for the CA signing certificates (you're asked to specify this when generating the certificate), the CMS installation wizard will fail to generate the certificate, and thus complete the installation process. [# 354993].

For example, assume you installed a CMS instance with a Certificate Manager and specified CN=myCA, O=Siroe, C=US as the issuer DN for the CA signing certificate. Next, you created another CMS instance with a Certificate Manager and attempted to generate a CA signing certificate with CN=myCA, O=Siroe, C=US as the issuer DN. The installation wizard will fail to generate the certificate; instead, it will display the following error message:
Token Error: import CA cert failure com.
netscape.jss.CryptoManager
$UserCertConflictException

• Certificates that are stored on nCipher hardware tokens do not show up in certutil listings; however, the certificates are, in fact, stored on the token. In addition, CMS server instances that require these certificates (for example, the server's SSL server certificate) will not be able to start unless the configuration file is modified. Before you can start a CMS server instance that uses a certificate stored on an nCipher hardware token, you need to prepend "smartcard0:" to the certificate's nickname in CMS.cfg. For example, the line to change will have the form:

    radm.https.nickName=Server-Cert cert-<instance_id>

Change the nick name to include smartcard0: as follows:

    radm.https.nickName=smartcard0:Server-Cert cert-<instance_id>

After this change, the server will be able to start successfully.

• If you are using Chrysalis Luna^TM hardware token for storing CMS keys and certificates, after a period of time Certificate Management System may stop working. To resolve the problem, check if you ran the following command as a part of installing the hardware token:

../../shared/bin/modutil -nocertdb -dbdir . -default chrysalis -mechanisms rc2:rc4:rc5:des:dh:sha1:md5:md2:random

The above command appears in the installation instructions provided by the token vendor. [# 524072]
If you did, you can resolve the problem by rerunning the above command (only) with the undefault option, and then restarting Certificate Management System:

../../shared/bin/modutil -nocertdb -dbdir . -undefault chrysalis -mechanisms rc2:rc4:rc5:des:dh:sha1:md5:md2:random

Installation

• Certain new features, such as revocation checking using the OCSP protocol, supported in this release requires you to use Netscape Communicator versions 4.7 or later. If you're using earlier versions of Communicator, you must install the new version before you install Certificate Management System on a Windows NT system. Installing the client after Certificate Management System results in an error (jre.exe application error), preventing you from completing the CMS installation. [# 355480]

• During the installation of Certificate Management System, port numbers are suggested to the user. While the Installation Wizard tries to suggest only unused ports, sometimes it is impossible to test whether the port is in use, so the wizard may erroneously suggest a port that's in use. Please make sure that the ports you pick are unused before installing the product. [# 522361]

• When installing Certificate Management System, if an existing configuration Directory Server is to be used and if the existing configuration Directory Server is under a different domain, then it may be necessary to run the CMS installation in Custom mode. [# 395070]

• When installing Certificate Management System on a host which contains more than one static IP address (for example, two or more ethernet cards or a cluster), then it may be necessary to run the CMS installation in Custom mode. [# 394785]

• When naming a CMS instance, be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type Netscape_root-CA as the instance name, but not Netscape root CA. [# 397665]

• When you run the setup program on Unix, if you interrupt the installation process at any point, the setup program asks you if you want to continue with a default answer of [n]. Accepting the default actually continues the installation. You need to explicitly answer N to cancel out. [# 397563]

• When running the setup program, be sure to note the port number you assign to the Administration Server and use it later in the Netscape Console login screen to launch Netscape Console. The Netscape Console login screen that shows up after running the setup program does not show the correct URL (the value in the Administration URL field). The port number in the URL isn't the one you specify during setup. In order to launch Netscape Console and complete CMS installation, you need to remember the port number you assign to the Administration Server and then edit the port number in the URL. [# 382662]

• When you log on to Netscape Console to configure a new instance of a CMS server, you must log on using the Console's directory server administrator ID and not the Directory Manager DN (both of these values are specified when you run the setup program to install Netscape Console and/or CMS). If you log on using the Directory Manager DN instead of the administrator ID, the CMS configuration wizard will fail to configure the server. [# 393829]

• If the configuration wizard terminates abnormally, attempts to restart it will generate a dialog box that says: operation error: unable to start the daemon. To workaround the problem, remove the lock file, <server_root>/cert-<instance_id>/logs/daemon.lck. [# 347678]

• When installing a CMS subsystem (for example, the Certificate Manager), if you specify identical subject names for the subsystem's certificates (for example, if you specify CN=myServer, OU=myDept, O=myOrg, C=myCountry as the subject name for both CA signing certificate and SSL server certificate), you will get an error. Make sure to assign appropriate values for the subject names; for example, the CN component of an SSL server certificate must be the fully-qualified host name of the machine on which the Certificate Manager will run. [# 390915]

• If you point Certificate Management System to a configuration directory running on a host which has different domain, you'll get an error message. In other words, if the domain for Administration Server is different than that of Certificate Management System, it would fail to bind to Administration Server; the reason for this is that you cannot set the domain for Administration Server. [# 389862]

• During installation, depending on the subsystems you've chosen to install, you generate various certificates, such as Certificate Manager's CA signing certificate, Registration Manager's signing certificate, and SSL server certificates. As a part of generating these certificates, you're required to specify subject names for the certificates. Subject names are formulated using DN components, such as Common Name (CN), Organizational Unit (OU), Organization (O), Locality (L), State (ST), and Country (C). Be sure to enter an appropriate value, such as the name of your company, for the Organization (O) component. The Organization is required because its absence causes Netscape Communicator version 4.6 (or below) to crash when it encounters the certificate.

Note that the CMS Installation and Deployment Guide doesn't tell you the version of Communicator that has problem dealing with certificates without the O component in the subject name; the document merely states that "The Organization is required because its absence causes Netscape Communicator 4.x to crash." [# 362451]

• When installing a Registration Manager, the installation wizard does not present you with an appropriate screen for specifying whether you want to connect it to a Certificate Manager or to another Registration Manager. The wording on the screen suggests that the Registration Manager can only be connected to a Certificate Manager.

For example, assume that you are installing a Registration Manager (RA2) and want to chain it to another Registration Manager (RA1) that has already been installed and connected to a Certificate Manager (CA). When you run the installation wizard for RA2, you should have the opportunity to specify the host name and port number of RA1 so as to chain RA2 to RA1. However, the screen presented by the installation wizard suggests that you can connect RA2 to CA only. Note that the error is limited to the wordings on the screen only. You may use the input fields to enter values that correspond to a Certificate Manager or Registration Manager. In other words, you should ignore the on-screen wordings and enter the host name and port number of the subsystem -- either a Certificate Manager or another Registration Manager -- to which you want to connect the Registration Manager being installed. [# 351672]

• When running the Installation Wizard for installing a Data Recovery Manager, in the screen where you enter key recovery agents' user IDs and passwords, pressing the Tab key does not advance focus to the next field; this requires you to double-click a field to give it focus. [# 389864]

• At the end of the CMS installation wizard you're asked to enroll for an agent certificate. If you go ahead and request the agent certificate, the Certificate Manager issues you a certificate with a validity period of one year, irrespective of the validity period of your CA certificate. The reason for this is, as any other certificate request your very first agent certificate request gets subjected to the currently configured policy rules of the Certificate Manager. It is important to know that during CMS installation a few policy rules are automatically enabled with default settings. To find out more about these rules:
1. Log in to Netscape Console.
2. Double-click the CMS instance of your interest.
3. In the navigation tree, click Certificate Manager.
4. Click Policies. The right pane lists the currently configured policy rules. To view current settings of a rule, select it and click Edit.

The default policy rule named DefaultValidityRule (which is an instance of ValidityConstraints plug-in) determines the validity period of all certificates issued by the Certificate Manager. By default, this rule is configured to issue certificates that are valid for a year (365 days), starting from the day they are issued.

If you want your agent certificate's validity period to be the same as that of your CA certificate, be sure to edit the DefaultValidityRule policy rule first so that the server can approve the validity period you want to request, and then enter the required validity period in the enrollment form for the first agent certificate. [# 399178]

• If you're installing Certificate Management System on a Japanese version of Windows NT, the default validity dates displayed by the Installation Wizard may not be correct. Be sure to adjust the dates before you click the Next button. [# 401375]

• When installing Certificate Management System as a subordinate CA, in one of the steps, the Installation Wizard asks you to paste the complete root CA certificate chain. Be sure to paste the complete chain for the root CA. If you fail to paste the correct root CA chain, for example, if you paste in the CA certificate instead of the chain, the Installation Wizard does not complain. Later, if you view the certificate chain in the Retrieval tab of End-Entity Services interface, the chain will only display the lower-level CA certificate; it will not show the root CA certificate. [# 384940]

• See the ones listed in Internationalization and Scalability/Sizing sections.

Internationalization

• You cannot add users to the directory if the user entries have attribute data in a non-English (ISO-8859-1) character set and the operating system uses the English (en or C) locale. Netscape Console will not accept multibyte language input, so ldapmodify must be used to add multibyte data to Directory Server. However, there is a bug in ldapmodify that prevents multibyte data from being added successfully if the operating system locale is English. To add multibyte data, install Directory Server on a system whose operating system supports the correct language and run ldapmodify on that system.

• When requesting a certificate using the Manual enrollment form for Netscape Communicator with Personal Security Manager, if you enter double-byte characters, such as Japanese or Korean characters, in Full Name, Common Name, First Name, Last Name, Organizational Name, Organizational Unit Name fields, you get an error. [# 384405]

• When using Netscape Communicator with Personal Security Manager, if you attempt to import a certificate with BMPString encoding, import works. Later, when you view the certificate in the Personal Security Manager interface, the nickname isn't displayed correctly. Also, if you click the View button and check certificate details, the subject name of the certificate doesn't appear correctly. [# 384406]

• If you request a certificate using the Manual enrollment form for the English version of Netscape Communicator 4.7 running on a non-english version of Window NT 4.0 (for example, Korean), Certificate Management System issues the certificate. However, when you attempt to import the certificate into Communicator, the certificate doesn't get imported. There's no error message to indicate that the import operation was unsuccessful. [# 384407]

• Netscape Communicator crashes if you attempt to import a certificate with BMPString encoding. [# 384408]

Job Scheduling/Notification

• When naming a job (instance), be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type My_Job or MyJob as the name, but not My Job.

• The token named $SerialNumber  provided for use in automated-email-notification templates, such as the ones used for constructing certificate issuance notifications to end users, displays the serial number of the certificate as a hexadecimal value in the resulting message. [# 393851]

• If there are no expired certificates in the internal database and if the unpublishExpiredCerts job is enabled, you will see an error similar to this in the log:

6831.unpublishExpiredCerts - [30/Jun/2002:22:50:01 PDT] [20] [0]
unpublishExpiredCerts: buildContentParams: null value for name= SummaryItemList

In addition, in the summary notification sent for unpublished certificates, the words "VALUE UNKNOWN" will show up before the table-title row. All it means is that there are no expired certificates. [# 400973]

• When editing any of the job instances from the console, be sure to follow the documented convention for the cron specification. [# 401621]

If you modify the cron attribute and if there is no space between minute and hour, (for example, 15**** ) and if you save the configuration, you will get the following error: A network error occurred! Server is down or unreachable.

In addition, the following error messages will also be logged:
13229.https:conn-26 - [13/Jul/2000:14:39:11 PDT] [20] [3] jobs/CronItem: invalid item in cron: **
13229.https:conn-26 - [13/Jul/2000:14:39:11 PDT] [20] [3] jobs/JobCron: invalidJobCron: minute

• The UnpublishExpiredJob plug-in that can automatically remove expired certificates from an LDAP directory doesn't work because of the faulty filter; the manual method of unpublishing expired certificates through the Agent interface works just fine. [# 512368]

To fix the problem, use the updated Java class named UnpublishExpiredJob.class. This class is bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2 SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.

• The product documentation erroneously states the following [# 464982]:
  "Using the Jobs Scheduler, you can configure a Certificate Manager or Registration Manager to automatically send email-based renewal notices to users whose certificates are about to expire or have expired."
  
  In fact, you cannot configure a Registration Manager to automatically send such email-based renewal notices. This section of the documentation will be fixed in the next version of the product.

JSS

• Certificate Management System integrates JSS_1_14, which allows you to find VERSIONing information that may be useful when reporting bugs or choosing a patch. Here's how you can find out the version:

• On all UNIX systems (except HP), do the following from the command line:

% strings jss.jar | grep "VERSION ="
          DBM_VERSION = DBM_1_54
          !JDK_VERSION = JDK 1.1.6 & JDK 1.2
          JSS_VERSION = JSS_1_14
          NSPR_VERSION = v3.5.1
          NSS_VERSION = NSS_2_8_3_RTM
          SVRCORE_VERSION = SVRCORE_2_5_1

          % strings libjss.so | grep "VERSION ="
          JSS_VERSION = JSS_1_14
          JDK_VERSION = JDK 1.1.6 & JDK 1.2
          SVRCORE_VERSION = SVRCORE_2_5_1
          NSS_VERSION = NSS_2_8_3_RTM
          DBM_VERSION = DBM_1_54
          NSPR_VERSION = v3.5.1

On HP systems, you can perform the exact same command on jss.jar file, but you will need to specify libjss.sl on the command line instead of libjss.so.

• On Windows Systems that do not have a version of "strings" and/or "grep" via MKS Toolkit, and do not have a compiler installed, the :notepad.exe program can be used. Simply open  the jss.jar file in notepad.exe, and use the Search menu item. Then select Find from the submenu, type in VERSION = in the Find what: field, and check the Match case checkbox. Click the Find Next button to traverse the contents of the file. Likewise, you can open the jss.dll file in notepad and follow the same steps.

Logging

• No known problem.

Migration Tool

• On AIX, the directory containing Informix must be located in /usr/informix (the default), or the migration tool will not function properly. A simple workaround on this platform would be for the administrator to make a symbolic link to the Informix installation, if it has not been installed at this location.

On Windows NT, the location of the Informix DLLs must be specified in the PATH environment variable. For example, if the Informix installation was c:\informix, then c:\informix\bin must be part of the path statement, or the migration tool will complain that it cannot find ISQLT07C.DLL and will not run.

Miscellaneous

• Initial connection to Netscape Console with a 2048-bit RSA SSL server certificate is a bit longer than the one made with a 512 bit RSA SSL server certificate.

• The configuration file, CMS.cfg, only supports Unix-style file separator, the forward slash (/). If MS file separator is required, you should use two backward slashes (\\) instead of one (\). [# 326875 and # 331495]

• Limitation in ECXpert 2.x when using certificates issued by Certificate Management System 4.1 -- when you paste in a certificate issued by Certificate Management System into ECXpert 2.x, be sure to cut and paste the base-64 encoded certificate excluding the marker lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----; including the marker lines will result in an error. [# 356027]

• You may encounter problems with Certificate Management System when using SSL server certificates that are issued by a public CA, if these certificates have Basic Constraints extension set in them. [# 356424]

• When creating a CMS instance, if you receive the following error message, it could be due to the server needing to achieve access over a slow network:

Operation Error: Unable to perform the instance creation task

Note that despite the error message, the instance will be created properly and you will be able to configure it. [# 395304]

• Several components installed by Certificate Management System for Windows NT 4.0 allow an attacker to read/download any file outside the document root directory provided that access to any of the following web servers is given:
• The Agent Services server on TCP/IP port 8100 (This server is accessible by a user with a valid client certificate as it requires SSL client authentication.)
• The End Entity Services server on TCP/IP port 443 (This server is normally accessable by any user over SSL.)

By using a specially formed URI, an attacker can get out of the server's document root directory and open any file. [# 515951]

To fix the problem, use the updated Java class named CMSFileServlet.class. This class is bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2 SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.
• If you're using an earlier version of Certificate Management System (for example, CMS 4.1), it's important that you to upgrade to CMS 4.2 and apply the patch.

 

• The product documentation erroneously states the following [# 4727931]:

"Public storage key: used to encrypt an end entity's private encryption key for long-term storage.


"Private storage key: used to decrypt an end entity's stored private encryption key after m of n recovery agents have authorized the recovery operation."

In fact, the opposite is true. The documentation should read:

"Public storage key: used to decrypt an end entity's stored private encryption key after m of n recovery agents have authorized the recovery operation.used to encrypt an end entity's private encryption key for long-term storage.
"Private storage key: used to encrypt an end entity's private encryption key for long-term storage."

This section of the documentation will be fixed in the next version of the product.

Performance

• To improve performance under high load on Solaris we recommend that you do the following:

1. Install Solaris patches 103582 and 103630; these patches include various TCP/IP performance/stability related fixes.
2. Increase the number of threads available listening on the end-entity port by adding the following to the configuration file (CMS.cfg):
eeGateway.http.backlog=30
eeGateway.http.maxThreads=40
eeGateway.https.backlog=30
eeGateway.https.maxThreads=40
3. If you increase the number of threads available listening on the end-entity port, you must also increase the number of per-process file descriptors. By default, this limit is 64. Check your system by typing: sysdef. Note that the value reported is in hex. To increase the number of file descriptors (each thread may use at least one, maybe two file descriptors; also remember that about 30 are used by Certificate Management System for other purposes), edit the /etc/system file, inserting the following lines:
set rlim_fd_max=1024
set rlim_fd_cur=256
4. Reboot the system. [# 345598]

Personal Security Manager

• If you want to add the NameConstraints extension to certificates and if your client is Netscape Communicator 4.7x with Personal Security Manager, make sure to set the permittedSubtrees.min and excludedSubtrees.min parameters to 0 in the NameConstraintsExt policy rule for client certificates. [# 386825]

• By default, CMS enrollment pages for Personal Security Manager specify the key size as 512 bits. However, you can specify to use the largest key size available using the parameter named crypto.algorithms.rsa.signing.keySizes[0], which is described in the document entitled JavaScript API for Client Certificate Management. To locate this document, check the <server_root>/psm11 directory or check the http://docs.iplanet.com/docs/manuals/psm.html site. Note that the document currently does not say that the 0th element will always be the largest key size supported. [# 395019]

• When you view a CMS-issued certificate in Personal Security Manager, it does not display information such as the algorithm and key size of the key associated with the certificate. However, IE displays this sort of information. [# 395453]

• Also see the ones listed in the Browser section.

Policies

• When naming a policy instance (or rule), be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type My_Policy_Rule or MyPolicyRule as the instance name, but not My Policy Rule.

• The Netscape Comment Policy Extension works only with Netscape Navigator; it does not work with Microsoft Internet Explorer.

• The policy plug-ins provided for Certificate Management System includes a plug-in named RemoveBasicConstrainstExt, which isn't documented in the CMS Administrator's Guide. This policy, if enabled, can detect the presence of Basic Constraints extension in a certificate request and remove it. The policy can be useful in certain enrollment scenarios. For example, enrollment requests from customized clients that can generate CRMF requests can include extensions, including the Basic Constraints extension, and the policy can detect the presence of the Basic Constraints extension and remove it. [# 384929]

• The policy rule named DefaultValidityRule, which is an instance of the ValidityConstraints plug-in, determines the validity period of certificates issued by Certificate Management System; the server automatically creates this rule during installation. By default, the minimum validity period allowed for certificates is set to 1 day (minValidity=1). The documentation says that the minimum validity period allowed for certificates is 30 days (minValidity=30). [# 399178]

• If you make some changes to extensions through policy, for example, add a Subject Directory Attributes Extension policy, and if you clone an old request, you'll see the request with its old set of extensions. However, when you approve the cloned request, the resulting certificate will have the new extension. [# 401670]

• See also the ones listed in the Browser section.

• The policy plug-in named PinPresentConstraints is not included in this release. Instead, a plug-in named AttributePresentConstraints is provided; the source code for the plug-in is included in the samples directory. [# 399016]

The AttributePresentConstraints plug-in enables you to configure the Certificate Manager and Registration Manager to reject a request if an LDAP attribute (for example, pin) is not present in the enrolling user's directory entry or if the attribute does not have a specified value. Many of the parameters defined in the plug-in (see the table below) are specified in the same way as the plug-ins provided for authenticating users during directory-based enrollment.

If you enable the policy and configure it correctly, it first searches for the user under the base specified in the ldap.ldapconn.basedn parameter with the filter (uid=HTTP_PARAMS.UID) for the user's entry.
• If the value parameter is empty, the policy checks the attribute parameter:
• If the attribute named in the attribute parameter is present in the request, the policy accepts the request.
• If the attribute named in the attribute parameter is not present in the request, the policy rejects the request.
• If the value parameter is not empty, the policy checks its value with the value of the attribute specified in the attribute parameter.
• If the attribute named in the attribute parameter has the specified value, the policy accepts the request.
• If the attribute named in the attribute parameter does not have the specified value, the policy rejects the request.
In the case of multi-valued attributes, the request will be accepted if any of the values matches the specified value; comparisons are case sensitive.

Parameter	Description
attribute	Specifies the LDAP attribute, the presence of which is to be checked in the certificate-enrollment request. Permissible values:  Valid directory attributes, separated by commas; the default value is pin. Example: pin
value	If this parameter is non-empty, the attribute value must match this value for the request to proceed to the next stage.
ldap.ldapconn.basedn	Specifies the base DN for searching the LDAP directory--the plug-in uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.  Permissible values: Any valid DN string of up to 255 characters. (If your user's DN is uid=jdoe, o=company, you  might want to use o=company here.) Example: O=siroe.com
ldap.ldapconn.host	Specifies the host name of the LDAP directory to connect to. Permissible values: The name must be fully-qualified host name in the <machine_name>.<your_domain>.<domain> form. Example: corpDirectory.siroe.com
ldap.ldapconn.port	Specifies the TCP/IP port at which the LDAP directory listens to requests from Certificate Management System. Permissible values: Any valid port number. The default is 389; use 636 if the directory is configured for SSL-enabled communication. Example: 389
ldap.ldapconn.secureConn	Specifies the type--SSL or non-SSL--of the port at which the LDAP directory listens to requests from Certificate Management System. Check the box if the port is an SSL (HTTPS) port. If your directory is configured for SSL-enabled communication (with or without SSL client authentication), choose this option. Leave the box unchecked if the port is a non-SSL (HTTP) port.  If your directory is configured for basic authentication, choose this option (default).
ldap.ldapconn.version	Specifies the LDAP protocol version. Permissible values: 2 or 3. 2 specifies LDAP version 2. If your directory is based on Netscape Directory Server 1.x, choose 2. 3 specifies LDAP version 3. For Directory Server versions 3.x and later, choose 3 (default). Example: 3
ldap.ldapauth.bindDN	Specifies the user entry to bind as for checking the attribute in the LDAP directory.  Permissible values: A valid bind DN. Example: CN=pinmanager
password	Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter.
ldap.ldapauth.authtype	Specifies how to bind to the directory or the authentication type--basic authentication or SSL client authentication--required in order to check attributes in the LDAP directory. Permissible values: BasicAuth or SslClientAuth. BasicAuth specifies basic authentication (default). If you choose this option, be sure to enter the correct values for  ldap.ldapauth.bindDN and password parameters; the plug-in uses the DN from the ldap.ldapauth.bindDN attribute to bind to the directory. SslClientAuth specifies SSL client authentication. If you choose this option, be sure to select the ldap.ldapconn.secureConn parameter and set the value of the ldap.ldapauth.clientCertNickname parameter to the nickname of the certificate to be used for SSL client authentication. Example: BasicAuth
ldap.ldapauth.clientCertNickname	Specifies the nickname or the friendly name of the certificate to be used for SSL client authentication to the LDAP directory in order to check attributes. Make sure that the certificate is valid and has been signed by a CA that is trusted in the directory's certificate database, and that the directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory. (This is needed for PIN removal only.) Permissible values: Enter the name of a currently valid CMS certificate, for example, its SSL server certificate. Example: Server-Cert
ldap.ldapconn.minConns	Specifies the minimum number of connections permitted (or to keep open) to the LDAP directory. Permissible values: 1 to 3; the default value is1. Example: 3
ldap.ldapconn.maxConns	Specifies the maximum number of connections permitted to the LDAP directory; when needed, connection pool can grow to this many (multiplexed) connections. Permissible values: 3 to 10; the default value is 5. Example: 9

• If you create an instance of the BasicConstraintsExt policy plug-in with the isCA parameter disabled and the predicate parameter set to non-CA certificates (for example, client), the corresponding non-CA certificates will still contain the Basic Constraints extension as a critical extension; irrespective of the status of the isCA  and critical parameters, the plug-in always considers the values of these two parameters to be set to true [# 516412].

To fix the problem, use the updated Java class named BasicConstraintsExt.class. This class is bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2 SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.

• If you enable an instance of CertificatePoliciesExt plug-in with just Policy ID in the extension, you'll get an error when you view the issued certificate (containing the extension) in its base-64 encoded form using dumpasn1. [# 514915]

To fix the problem, use the updated Java class named CertificatePoliciesExt.class. This class is bundled in a CMS patch named cms42-sp1.zip, which you can access by clicking the iPlanet Certificate Management System 4.2 SP1 link at http://www.iplanet.com/downloads/patches.
• To extract files from cms42-sp1.zip, you may use InfoZip's UnZip utility; see the information available at http://www.info-zip.org/pub/infozip/UnZip.html.
• To install the patch, follow the instructions outlined in the Readme file (README_CMS_42_SP1.TXT), which is included inside the cms42-sp1.zip file.

Publishing

• If your CA certificate does not have the CN component in its subject name, be sure to adjust the CA certificate mapping DN pattern to reflect the DN of the entry in the directory where the CA certificate is to be published. For example, if your CA certificate subject DN is O=Siroe Corporation and the CA's entry in the directory is cn=Certificate Authority, o=Siroe Corporation, the pattern should look like this:

cn=Certificate Authority, o=$subj.o

This also applies to other mappers. [# 395043]

• When configuring publishing, if you enter incorrect data (in the Publishing panel of CMS window) and attempt to save it, Certificate Management System will ask you to either save or abort your changes. If you choose to save, you must later make sure to configure the server correctly, and then restart the server for your changes to take effect. [# 388097]

• If you already have one CA entry created in the publishing directory and if you change the value assigned to the dnPattern parameter of the caSimpleMapper mapper to something different, but with the same UID and O attributes, the mapper will fail to create the second CA entry. For example, if the directory already has a CA entry with UID=CA,OU=Marketing,O=Siroe.com and if you configure the mapper to create another CA entry with UID=CA,OU=Engineering,O=Siroe.com, the operation will fail. [# 399162]

The reason for the failure may be because you are using a directory (for example, the configuration directory) that has the uid uniqueness plug-in set to a specific base DN in the slapd.ldbm.conf file. This setting prevents the directory from having two entries with the same UID under that base DN. For example, it prevents the directory from having two entries under O=Siroe.com with the same UID, CA.

If the mapper fails to create a second CA entry, be sure to check the base DN that the uid uniqueness plug-in is set to (in the slapd.ldbm.conf file) and also check if an entry with the same UID already exists in the directory. If it's true, adjust the mapper setting, remove the old CA entry, comment out the plug-in, or create the entry manually using Netscape Console.

• See also the ones listed in CRLs and UI (Netscape Console/CMS Window) sections.

Remote Registration Manager

• In one of the steps of a Registration Manager installation, the Installation Wizard asks you to paste the CA certificate in its PKCS#7 format. In the PKCS#7 chain that you paste, if either the root CA certificate or subordinate CA certificate doesn't have an O= component in its subject name, the Installation Wizard fails to import the PKCS#7 chain, resulting in the following error message:
java.security.cert
CertificateEncodingException:
CERT_ImportCAChain returned an error

To workaround the problem you should install the required CA certificates (for example, the root CA certificate or subordinate CA certificate, or both) using the certutil tool.  Note that the above suggested workaround prevents you from managing the Registration Manager's certificate database using the UI -- you will not be able to use the 'Manage Certificates' window in the CMS console. [# 512054]
The workaround suggested below is for a Registration Manager connected to a subordinate CA (RA-->subCA-->rootCA).
1. Run the Installation Wizard until you get the above mentioned error.
2. Quit the Installation Wizard.
3. Open a web browser window.
4. Go to the subordinate CA's end-entity interface.
5. Select the Retrieval tab.
6. Click Import CA certificate.
7. Select the "Display certificates in the CA certificate chain for importing individually into a server" option and click Submit.

You should see the certificates in base-64 encoded formats. Don't close this window.
8. Open a command-line window.
9. Go to Registration Manager's configuration directory:

cd <server_root>cert-<ra_instance_id>/config
10. Create two text files named subca and rootca.
11. Copy the base-64 encoding of the subordinate CA certificate into the subca file and of the root CA certificate into the rootca file. Be sure to include the -----BEGIN CERTIFICATE---- and -----END CERTIFICATE----- wrappers.
12. Save and close the files.
13. Add the two certificates to the Registration Manager's certificate database by running the following certutil commands:

certutil -d . -A -n "subca" -a -t TC,TC,TC -i subca
certutil -d . -A -n "rootca" -a -t TC,TC,TC -i rootca
Now you have imported the certificates.
14. Restart the Installation Wizard and run it as usual.
15. When the wizard asks you for the PKCS#7 chain, paste the chain as before. (You must still provide the chain, but the wizard won't try to reimport those certificates because they already exist in the Registration Manager's certificate database.)
16. Complete the installation process.

• If the remote Registration Manager is not set up correctly to work with the Certificate Manager, an unclear HTTP message results. Check to make sure that the configuration for the remote Registration Manager is set up correctly.

• The Registration Manager does not yet support the CRS/CEP enrollment; all router enrollment requests must be made through the Certificate Manager. [# 341389]

• Registration Managers cannot display the full PKCS #7 certificate chain for certificates. If you need the full PKCS #7 chain for a CA's certificate, you must use the Get CA Chain interface on a Certificate Manager instance (see Chapter 24 of the Administrator's Guide for information about the Get CA Chain interface). If you need the full PKCS #7 chain for a particular certificate (such as a subordinate CA) you must go to the Certificate Manager and display the certificate.

• In a chained-CA setup, for example, a setup in which you have two CAs and a Registration Manager (Root CA --> Subordinate CA --> Registration Manager), if you list requests on the Registration Manager as a Registration Manager agent and if you notice that all requests are in the svc_pending state, it's likely that the trust setting among the three entities has not been set up correctly; that is, a certificate (CA or SSL) is not trusted and needs to be trusted. For example, in the above mentioned setup, if the SSL server certificates of the Registration Manager and the subordinate CA are signed by different CAs, transfer of requests from the subordinate CA to the Registration Manager would fail. To troubleshoot the problem, check CMS logs. [# 395614]

Renewal of CMS Certificates

• When renewing the CA signing certificate of a Certificate Manager, if you change the key algorithm, the corresponding parameters don't get changed in the configuration file (CMS.cfg). This causes the server to fail from starting up. To workaround this problem, you must modify the value assigned to the algorithm parameter of the policy rule named SigningAlgRule in the CMS.cfg file. For details about values you can assign to the algorithm parameter, check the section entitled "Signing Algorithm Constraints Policy" of the Administrator's Guide. [# 386772]

• During CMS installation you generate a single SSL server certificate. However, when renewing CMS certificates, the Certificate Setup Wizard (on the certificate selection window) offers choices for renewing two SSL server certificates, SSL Server and SSL Server for Remote Admin.
• SSL Server -- This option is for renewing the certificate that you generated during installation. The certificate is used by the server for SSL server authentication to the HTTP interfaces (the end-entity interface and agent interface).
• SSL Server for Remote Admin  -- This option is for the SSL server certificate that the installation program generates transparently. This certificate is self-signed and is used by the server for SSL server authentication to the remote administration interface, Netscape Console. The certificate is generated with RSA key type and a key size of 512 bits. The validity period of the certificate is set to the same validity period that you choose for the SSL server certificate used by the server for SSL server authentication to the HTTP interfaces. Note that the certificate is not listed in the internal database; You'll see the certificate if you use the command-line tool certutil to list certificates in the certificate database (the cert7.db file) of the server; the CN component in both the subject name and issuer name of the certificate will be set to CN=SSLserver cert-<instance_id>.
Like other CMS certificates, it's important that you renew this certificate before it expires. [# 392535]

Note that the SSL Server for Remote Admin  option in the Certificate Setup Wizard allows you to renew the certificate by submitting the request to a CA only; it doesn't allow you to renew the certificate as a self-signed one (as done during installation). If you want to self sign the certificate, you must use certutil and keyutil tools to extract the key ID from the key database first and then generate a certificate for the key. [# 401863]

The steps below outline how to use these tools to renew the certificate. Be sure to check the documentation on certutil and keyutil tools (Appendix D and E in the online version of CMS Administrator's Guide) to customize your commands to suit your requirements.
1. Note the name (also called nickname) of the remote administration SSL server certificate; the default name is Remote Admin Server-Cert cert-<instance_id>.
2. Stop Certificate Management System.
3. Open a command window.
4. Go to this directory: <server_root>/cert-<instance_id>/config
5. Enter the command below, replacing <certname> with the name of the remote administration SSL server certificate. You may use the -h <tokenname> argument to specify whether the certificate database is on a particular hardware or software token.

certutil -L -n "<certname>"
For example, your command might look like this: certutil -L -n "Remote Admin Server-Cert cert-firefly"
You should see detailed information about the remote administration SSL server certificate.
6. Locate the "Subject Public Key Info:" section and then the "Modulus" section. For example:

      RSA Public Key:
        Modulus:
           00:f6:9e:71:37:62:af:7c:46:af:cb:bf:1e:d8:1a:
           64:0b:5e:71:e2:d8:ec:88:18:6d:eb:32:65:6f:f2:
           18:4b:ef:b3:70:ae:61:de:6f:21:d5:4e:0e:7b:9b:
           b7:42:98:94:1c:d7:46:42:53:39:db:10:07:6c:b8:
           75:7e:94:18:b5
7. Note the second and third byte (f69e in the above example) in the modulus; this is the short key ID for the certificate.
8. Delete the certificate you want to renew.
9. Run the certutil command again to regenerate the certificate for the correct key and to add the resulting certificate to the database. Be sure to use the same name for the certificate and to add the required certificate extensions, such as the Key Usage extension. A sample command syntax is below:

certutil -S -k <shortkeyID> -y rsa|dsa -n "<certname>" -s "<subject>" -t "<trustargs>"  -x -m <serial-number> -v <valid-months> -d <certdir> -1)
For example, your command might look like this: certutil -S -k f69e -y rsa -n "Remote Admin Server-Cert cert-firefly" -s "cn=SSLserver cert-firefly" -t "u,u,u" -x -m 3 -v 12 -d . -1
10. Restart Certificate Management System.

Request Queue Processing

• This release allows agents to list requests based on their type, enrollment, renewal, revocation requests.

• This release does not support the cancel request operation.

Revocation

• When changing the status of a revoked certificate to valid in the internal database (Directory Server), it's not sufficient to change the value of the certStatus field from REVOKED to VALID. To properly switch the status of the certificate from revoked to valid, you need to remove revinfo, empty two fields, revokedon and revokedby, and change the value of the certStatus field from REVOKED to VALID.  [# 393454]

• See also the ones listed in the CRLs section.

Samples and SDKs

• To locate the CMS SDK and sample code, see SDK and Samples.

Scalability/Sizing

• Certificate Management System uses Netscape Directory Server 4.12 as its internal database for storing certificates and related information. We noticed that when you issue approximately 500,000 certificates, the file size of the internal database exceeds 2G -- in other words, to support 500,000 or more certificates, you'll need a directory database that is more than 2G in size.

If you plan on issuing 500,000 or more certificates per CA, make sure to install the Certificate Manager on a system that supports files greater than 2G in size:

• Windows NT supports file systems that contain files greater than 2G in size.
• Solaris versions 2.6 and later support file systems that contain files greater than 2G in size; these versions support a 64-bit file system (the earlier versions support a 32-bit file system).

Searching for Certificates

• Searching for certificates is slow if the search criteria include a validity period and if there are many tens of thousands of certificates in the internal database.

Starting/Stopping the Server

• The 'Stop' operation stops the server without checking the password that is passed from the Console.

• The 'Start' operation fails when passed an incorrect password at startup -- when you attempt to start the server with a wrong password, the server does not prompt that the password you've entered is incorrect.

• You can stop a CMS instance from Netscape Administration Express, an HTML-based interface that can be launched by entering http://<admin_server_host>:<admin_server_port>  in the browser's URL field. However, you cannot start a CMS instance from this interface. [# 389901]

• Certificate Management System doesn't prompt you to supply the single sign-on password when you make an attempt to stop the server from the Windows NT service panel.

• If Certificate Management System is running on a Windows NT machine, it is not advisible to install JDK 1.1.8 on the same machine. After installing JDK 1.1.8, Certificate Management System will not start due to an entry in the registry forcing the CMS jre to use the classpatch provided by the JDK 1.1.8 installation. The solution is to remove the offending registry entry; you can use regedit to search for the jdk1.1.8 directory. [# 395048]

• By default, there is no way to start Certificate Management System non-interactively; the start script requires you to enter a password. However, you can store the single sign-on password in a file and edit the start script to use this file to start without any prompts. This can be useful on UNIX machines to have the server automatically started if the machine reboots for any reason, and it can be useful on Windows NT to be able to start the server without having to be at the system console. Note that there is no way to make the edited start script a service that is automatically started by Windows NT at startup, so if the machine reboots due to a power failure, the CMS servers will not start automatically. To make the start script non-interactive:
1. Create a file named pwfile in the <server_root>/cert-<instance_id>/config/ directory with the single sign-on password in it.
2. In UNIX, edit the <server_root>/cert-<instance_id>/start-cert script. To the end of the line that begins

        $NETSITE_ROOT/bin/cert/admin/bin/cert

add

        -f $NETSITE_ROOT/cert-<instance_id>/config/pwfile

3. In Windows NT, edit the <server_root>/cert-<instance_id>/start-cert script. To the end of the line that begins

        net start cert-<instance_id>

add

        /fC:%NETSITE_ROOT%\cert-<instance_id>\config\pwfile

• In Certificate Management System 4.2, when you view any certificate that has been issued, it also shows you the PKCS#7 chain. The PKCS #7 chain can be used to install the certificate in a third-party CA that requires the certificate to be in the PKCS #7 format (instead of the based-64 encoded format). Note that Certificate Management System 4.1 displays the certificate in its based-64 encoded format only.

RSA Security Server^TM

• RSA Security Server does not accept a certificate that has a DSA signing key. [# 395018]

ValiCert Certificate VA^TM

• Certificate Management System (CMS) 4.2 and Communicator 4.7x with Personal Security Manager (PSM) include support for Online Certificate Status Protocol (OCSP). ValiCert's Certificate VA (CVA) provides OCSP-based certificate validation by receiving CRLs from Certificate Authorities (CAs) and then serving validation requests from clients such as Communicator. For a step-by-step procedure to see how to conduct an end-to-end test of OCSP, CMS, and PSM together, check this file [# 392823]:

<server_root>/cms_sdk/sdkdocs/Valicert_setup.html

For important information on ValiCert Certificate VA^TM (CVA) bundled with Certificate Management System, check the CVA release notes at this location: <server_root>/cva301

• The cva301readme.txt file contains incorrect terms-of-use for Certificate VA bundled with Certificate Management System. [# 395630]

This copy of ValiCert Certificate VA Suite should only be used for evaluation purposes, unless you have also obtained a license from Valicert that entitles you to use it in a production environment, or for commercial purposes with non-zero number of digital certificates or certificate authorities.

The corrected/proper terms-of-use for Certificate VA bundled with Certificate Management System is as follows:

ValiCert grants Licensee a non-exclusive, non-transferrable license, without the right to sublicense, to use the object code version of the Software and Documentation solely for Licensee's internal business purposes and in accordance with the Documentation; provided, however, Licensee shall not, without the prior written consent of ValiCert, use the Software to validate digital certificates other than those produced by the certificate authority that is bundled with the Software.

• You cannot enable SSL for the CVA administration server. The CVA administration server is an Apache server, which does support SSL, but the version that ships with the CVA doesn't support enabling it with SSL. [# 394943]

• CVA doesn't support any hardware signing modules via PKCS#11. Valicert EVA 3.2 does support hardware signing/acceleration modules via PKCS#11. [# 394945]

• CVA can't load a CRL published by Certificate Management System with an RSA key of length 4096 bits. [# 394932]

SHYM PKEnable^TM

• Currently, the OCSP responder root that the SHYM software uses is hardcoded as the ValiCert service root. If the OCSP responder certificate of the CVA is signed by a CA unknown to the SHYM software, then the SHYM software is unable to verify the certificate chain on the signed OCSP response. This will be fixed in v.2.1 version of the SHYM software (in June 00).

• If PeopleSoft or SAP servers are protected by certificates with different CA roots than the one used by SHYM clients, and a new CA certificate is introduced into the SHYM system, the SHYM clients are automatically updated, but the servers are not. This requires the SHYM administrator to restart the PeopleSoft/SAP servers to cause the SHYM's to be reloaded to clear their caches of trusted roots (to refresh their root list).

• In order to introduce a new CA root into the SHYM software, the SHYM's PKEnable™ V2 management console, the following procedure needs to be run by the SHYM administrator:
1. Go to CA's end-entity page (either HTTP or HTTPS).
2. Select the Retrieval tab.
3. Click Import CA Certificate Chain.
4. Click "Download the CA certificate chain in binary form ".
5. Save the X509v3 certificate with a .cer extension.
6. Follow the SHYM software instructions to load the root into the SHYM software.
Note: One can use ValiCert's CVA or EVA software along with the SHYM software; SHYM software supports OCSP, CRLs, and CRTs.

Check Point VPN-1^TM

• You can configure Certificate Management System to work with Check Point VPN-1, version 4.1. Integration of the two products is discussed in a document that you can find in your CMS installation at:

<server_root>/cms_sdk/sdkdocs/CheckPoint_integration.html

Note that the above document incorrectly identifies the product as Check Point FireWall-1, version 4.0 (instead of Check Point VPN-1 4.1). Also, VPN-1 requires that the certificate DN listed on the certificate be identical to the DN listed in the LDAP directory for a given certificate. This means, for use with VPN-1, the subject name of the certificate must be identical to the DN listed in the LDAP directory for a given certificate. If you're using the manual enrollment method, in the enrollment form, enter values so that the subject name of the certificate matches the DN of the corresponding user entry in the LDAP directory. If you're using any of the automated enrollment methods, when configuring the authentication module, set the value of the dnpattern parameter so that the subject names of certificates match the DNs of the corresponding user entries in the LDAP directory. (The dnpattern parameter defined in the authentication plug-in modules enable you to issue certificates with customized subject names.)

UI (Netscape Console/CMS Window)

• Netscape Console, version 4.2 doesn't support the DSA key algorithm. This prevents you from using the auto-submit feature of the Installation Wizard and Certificate Setup Wizard to automatically submit the request to the CMS's HTTPS port for end-entity enrollments, if that CMS instance is using a DSA key.

For example, when installing a Registration Manager, if you attempt to auto submit the Registration Manager's signing certificate request to the end-entity HTTPS port of a Certificate Manager whose SSL server certificate corresponds to a DSA key (or the certificate has been signed by a CA with DSA key), the wizard will fail to submit the request.
The workaround for this is to use the manual method of request submission -- that is, copy the base-64 encoded certificate request, go to the CMS's end-entity enrollment page (HTTPS), open the appropriate form, paste the certificate request, and submit the completed request.
Alternatively, if you must use the auto-submit feature, you can change the CMS's configuration to accept certificate-enrollment requests on the end-entity HTTP (non-secure) port and then auto submit the request. [# 385973]

• When installing a certificate using the Installation Wizard or the Certificate Setup Wizard, if the certificate is contained in a file, you should leave the file until the certificate is successfully installed. If you remove the file before the wizard completes installing the certificate, for example, if you remove the file after the wizard displays the detailed version of the certificate, the wizard will display an error indicating that it cannot find the file. [# 387267]

• When installing a certificate in the Console using X windows, you cannot simply highlight and drop the base-64 encoded certificate into the text box or field. Instead, you must explicitly cut the base-64 encoded certificate from one application (such as a text editor or web browser) and paste into the text box of the console. [# 327841]

• If you install Certificate Management System on HP-UX platform and if the CA's signing certificate is of DSA key type, you'll not be able to use Netscape Console to manage Certificate Management System; Netscape Console will crash if you attempt to connect to Certificate Management System. To workaround the problem, install Netscape Console on a different platform, such as Windows NT or Sun Solaris, and use it to manage Certificate Management System. [# 413268]

• The Certificate Setup Wizard does not properly handle "+" and "," characters in Distinguished Name components. If you need to use one of these characters as part of a DN component, enclose the entire text in double quotes (") or escape the character with a backslash (\). For example, to use Siroe, Inc. as the organization (O) attribute, enter

    "Siroe, Inc."

in the text field for the O component. [# 391583]

• The Certificate Setup Wizard can automatically post a certificate signing request (CSR) to a Certificate Manager's or Registration Manager's enrollment interface. However, the Certificate Setup Wizard assumes that the port is 80 (even if the protocol in the URL is https). When you enter the URL for submitting the request, always include the port number if it is not 80. An example enrollment URL including port 443 is https://ca.siroe.com:443/enrollment. [# 390032]

To use https://, it is also important to have loaded the trusted root for the CA into the Administration Server's trust database prior to doing the enrollment. Otherwise, Administration Server will not be able to verify the SSL certificate that the CA is using -- assuming the SSL certificate is issued by a self-signed CA. If the CA chains under a public CA, this is a non-issue. Assuming the CA's SSL certificate is signed by a CA that Administration Server isn't aware of, you must do the following prior to enrollment for the Administration Server's SSL certificate:
1. Login to Netscape Console.
2. Double-click the Administration Server instance to open the Administration Server console.
3. Start the Certificate Setup Wizard (by clicking the Certificate Setup Wizard button available in the Tasks tab).
4. Click Next.
5. Be sure to select "Yes" as the certificate has already been generated, and click Next.
6. Setup password on the trust database if not already setup.
7. Click on "trusted certificate authority", and click Next.
8. Paste in the trusted root for the unknown CA, and then complete the rest of the wizard steps.

After this point, the SSL certificate that needs to be verified during the Administration Server enrollment (via the https:// URL) will chain
up to the trusted root. Note that if the trusted root (or any part of the chain) contains a DSA certificate, then the Console 4.2 UI will have problems initiating an https:// connection between the Console 4.2 (client) and Administration Server 4.2 (server). This is due to the limitation that Console client does not understand the DSA algorithm. [# 394929]

• If you enable an outbound LDAP connection from Certificate Management System, (for example, for publishing or authentication), make sure you specify the correct port. If you turn on SSL, but specify the regular, non-SSL LDAP port, the console may hang when the LDAP settings are changed. [# 399543]

• In the Console page for setting up LDAP publishing, there are input fields for entering values for the DNComps, filterComps, and baseDN parameters. Although value for either DNComps or baseDN is required, the UI gives the impression that values must be entered in both the fields. [# 331081]

• If a DN (either issuer DN or subject DN) contains special characters defined in RFC-1779, the characters will be automatically prefixed with a backward slash (\) upon displaying. This slash may give you the wrong impression that a slash character is included in the DN, and it is not consistent with the behaviour of Communicator that shows no slash character in such case. [# 351774]

• The Certificate Setup Wizard, when used to request a Registration Manager signing certificate, incorrectly states that you should "paste the request to the CA's server enrollment form". Instead, it should state that "paste the request to the Registration Manager enrollment form provided in the CA's end-entity interface". [# 356680]

• If clicking the Help button on the Console interface does not bring up the help text, Exit Communicator and click the Help button again. If the problem persists, reinstall Communicator. [# 399146]

• If you experience hard to read fonts when redirecting a console on Unix to another X Server, you could try to rename the file <server_root>/bin/base/jre/lib/font.properties to font.properties.old, and restart the console.

• See also the ones listed under Administration Server and Starting/Stopping the Server sections.

---

Contact Information

http://docs.iplanet.com/docs/manuals/cms.html

http://www.iplanet.com/support/index.html

snews://secnews.netscape.com/netscape.dev.certificate

snews://secnews.netscape.com/netscape.dev.ssl
snews://secnews.netscape.com/netscape.dev.security

• The Certificate Management System release number.
• The machine type and operating system version.
• Specific description of the problem.

Change History