Sun™ ONE Certificate Server 4.7SP1

---

Release Notes

These Release Notes contain important information available at the time of the Version 4.7 Service Pack 1 (SP1) release of Sun™ ONE Certificate Server. Fixes, installation notes, known problems, and other late-breaking issues are addressed here. Read this document before you install this Service Pack 1.

This is a living document and subject to ongoing updates. Check the following URL frequently to ensure you have the latest version of Release Notes:

http://docs.sun.com/source/816-6407-10/index.html

For comprehensive product documentation for Certificate Server 4.7, go to:

http://docs.sun.com/db?p=coll/S1_s1CertificateServer_47

Note

Sun™ ONE Certificate Server was previously iPlanet™ Certificate Management System. The product was renamed shortly before the launch of this 4.7 release. The late renaming of this product has resulted in a situation where the new product name is not fully integrated into the shipping product. In particular, you will see the product referenced as iPlanet Certificate Management System within the product GUI and within the product documentation. For this release, please consider iPlanet Certificate Management System (CMS) and Sun ONE Certificate Server as interchangeable names for the same product.

An electronic version of the complete product documentation set can be found at the Sun ONE documentation website:

http://docs.sun.com/db?p=coll/S1_s1CertificateServer_47

Check the website prior to installing and setting up your software and then periodically thereafter to view the most up-to-date release notes and manuals.

These release notes contain the following sections:

• What's New in This Release

• Software and Hardware Requirements

• Installing Certificate Server 4.7 Service Pack 1

• Upgrading From a Previous Certificate Server or Certificate Management System Installation

• Microsoft Security Patch Q323172

• Updated setpin Tool

• Known Problems and Limitations

• How to Report Problems

• For More Information

---

What's New in This Release

Certificate Server 4.7 Service Pack 1 includes the following fixes for problem areas found in previous versions of the software:

• Using Sun ONE Identity Server 6.0

• Using Microsoft Internet Explorer

• Updated setpin Tool

• FIPS-140 Level 3 Hardware

• Using Sun ONE Console

• Using Certificate Enrollment Protocol (CEP)

• Filtering Automatic Notifications

• Using the revoker Command-Line Tool

• Updated Migration Scripts

Using Sun ONE Identity Server 6.0

• Proper checking of the Identity Server now occurs when you set the system property for handler packages. (4716156)

• The mandatory field com.iplanet.am.notification.url in the SSOBasedAuthentication module checks for null value, and now displays an error message when the value is not filled in. (4714292)

• When an administrator generates certificates for all users, the certificate no longer shows the uid of the administrator. It displays the uid of the corresponding user in each certificate.

Using Microsoft Internet Explorer

• Importing a certificate on Internet Explorer no longer returns the error message "Could not convert cert to pkcs7 format." (4721621)

• These Release Notes include instructions for using CMS with Microsoft Security Patch Q323172F. See "Microsoft Security Patch Q323172."

• When you use Microsoft Internet Explorer on Windows NT or Windows 2000 to request a client certificate, CMS issues two client certificates with different serial numbers (535181).

  This Service Pack includes a fix for this problem. However, after installing the Service Pack, you must manually edit some files.

  If you have customized DirPinUserEnroll.html and DirUserEnroll.html, then follow these steps:

  1. In the file Sub Send_OnClick, remove the string TheForm.Submit.

  2. Look for the following verification statements:

     
     
     

     <script lang="javascript">

     if (navigator.appName == "Netscape" && (navMajorVersion() <= 3)) {

     // short cut for Nav 3.x or earlier, crypto is not defined

     document.write(

     `<form name="ReqForm" method="post" action="/enrollment"

     >');

     } else

     if ((navigator.appName == "Netscape" &&

     typeof(crypto.version) != "undefined")) {

     document.write(

     `<form name="ReqForm" method="post" action="/enrollment"

     >');

     } else

     document.writeln(

     `<form name="ReqForm" method="post" action="/enrollment"

     `+

     `onSubmit="return validate(document.forms[0])">');

     }

     //-->

     </script>

     
     
     

  3. Replace the last else statement:

  
  
  

  } else

  document.writeln(

  `<form name="ReqForm" method="post" action="/enrollment"

  `+

  `onSubmit="return validate(document.forms[0])">');

  }

  //-->

  </script>

  
  
  

  with the following else statement:

  
  
  

  } else

  if (navigator.appName == "Microsoft Internet Explorer") {

  // Fix for escalation 535181. Removed the existing validate and

  // since Send_OnClick is called for IE browsers.

  document.write(

  `<form name="ReqForm" method="post" action="/enrollment">');

  } else

  if ((navigator.appName == "Netscape" &&

  typeof(crypto.version) == "undefined")) {

  // For Netscape Navigator version 4.7x

  document.write(

  `<form name="ReqForm" method="post" action="/enrollment" `+

  `onSubmit="return validate(document.forms[0])">');

  }

  </script>

  
  
  

  If you have not customized DirPinUserEnroll.html and DirUserEnroll.html, then follow these steps:

  1. Copy the file bin/cert/web/ee/DirPinUserEnroll.html to your CMS installation area.

     cp bin/cert/web/ee/DirPinUserEnroll.html
       <cms_server_root>/web/ee/DirPinUserEnroll.html

  2. Copy the file bin/cert/web/ee/DirUserEnroll.html to your CMS installation area.

     cp bin/cert/web/ee/DirUserEnroll.html
       <cms_server_root>/web/ee/DirUserEnroll.html

  3. Copy the file bin/cert/sdk/i18n/ja/DirUserEnroll.html to your CMS installation area.

     cp bin/cert/sdk/i18n/ja/DirUserEnroll.html
      <cms_server_root>/cms_sdk/i18n/ja/cms_sdk_DirUserEnroll.html

     cp sdk/i18n/ja/DirUserEnroll.html
       <cms_server_root>/cms_sdk/i18n/ja/DirUserEnroll.html

  4. Copy the file bin/cert/sdk/i18n/ko/DirUserEnroll.html to your CMS installation area.

     cp bin/cert/sdk/i18n/ko/DirUserEnroll.html
      <cms_server_root>/cms_sdk/i18n/ko/cms_sdk_DirUserEnroll.html

     cp bin/cert/sdk/i18n/ko/DirUserEnroll.html
       <cms_server_root>/cms_sdk/i18n/ko/DirUserEnroll.html

  5. Restart CMS.

Updated setpin Tool

• The setpin tool has been fixed so than now it supports SSL connections over LDAP. (4727358)

FIPS-140 Level 3 Hardware

• You can now use a FIPS-140 Level 3 hardware unit such as Chrysalis LunaCA3 with a DRM to recover keys. The process no longer fails and no longer displays the message, "Recovery failed. No private key."(4738571)

• Chrysalis LunaCA3 hardware was tested on Solaris 8 and Windows 2000 platforms using driver version 7.5. Before the LunaCA3 will work with CMS 4.7 SP1, you must manually modify a driver configuration file. On the computer system where you installed the Chrysalis 7.5 driver, make the following modification:
  • On Solaris 8, in the file /etc/Chrystoki.conf, add the following:

    Misc = {

    NetscapeCustomize=1023;

    AppIdMinor=2;

    AppIdMajor=4;

    }

  • On Windows, in the file c:\WINNT\crystoki.ini, add the following:

    [Misc]

    NetscapeCustomize=1023

    AppIdMajor=2

    AppIdMinor=4

Using Sun ONE Console

• When CMS is running on Solaris, and iPlanet Console is running on Windows, Sun ONE Console now obtains and displays accurate Start/Stop status. In previous versions of CMS, when iPlanet Console could not obtain Start/Stop status, it was difficult to manage or configure Certificate Server. (536653)

Using Certificate Enrollment Protocol (CEP)

• CMS now works with Certificate Enrollment Protocol (CEP) using hardware tokens. (540300)

• A router can now successfully request a certificate from a Registration Manager (RA) using CEP. The CEP connection no longer fails. (538348)

• The script cepconfig.pl for automating Certificte Enrollment Process (CEP) enrollment now works as designed (540168). After installing Service Pack 1, follow the instructions in Chapter 25, "Setting Up CEP Enrollment" in the CMS Installation and Setup Guide.

Filtering Automatic Notifications

Problems with setting up filters for automatic issuance and renewal notifications have been resolved.

Certificate Issuance Notifications

You can now filter certificate issuance notifications (4750621). A new field, Predicate, was added to the Certificate Issued tab. Use this new field to specify a predicate string. For more information, click the Help button in the Certificates Issued tab, illustrated below.

Certificate Renewal Notifications

You can now filter certificate renewal notifications (4749893). A new field, baseDN, was added to the Job Instance Editor window.

In order for this new baseDN field to display, you must delete the old certRenewalNotifier instance, and create a new one. Follow these steps:

1. In the CMS administration window, click the Configuration Tab.

2. In the navigation tree, click Jobs Scheduler > Jobs.

3. Click the Add, and then choose Renewal Notification.

4. Use the Job Instance Editor to create a new notification job instance. For detailed information about the baseDN field, click Help.
   
   

   The following illustration shows a new job instance named NewRenewalNotification, and it is Enabled. The older instance, named certRenewalNotifier, is Disabled.
   
   

5. Highlight the older instance, in this example named certRenewalNotifier, and then click Delete.

Using the revoker Command-Line Tool

The following problems have been resolved:

• The error "Segmentation Fault" no longer occurs when using the revoker command-line tool. (4745117)

• You can now send a request to CMS to remove the Hold status on a certificate by using the -u option (539771). For full usage of the revoker command line, after installing the Service Pack, run the revoker command without any parameters.
  Example:

    cd <server-root>/bin/cert/tools

    setenv LD_LIBRARY_PATH <server_root>/bin/cert/lib

    ./revoker

Updated Migration Scripts

The following issues have been resolved in the migration scripts:

• The migration scripts are now menu-driven. Note that you must perform all steps, and they must be performed in the same numbered sequence as displayed in the program menu.

• On Unix and Windows NT, if you enter Ctrl + C while running the migration script, the program now asks you to confirm that you want to stop the script. The previous version of the script would quit abruptly and would not allow you to resume the program.

• The migration script now gives you the opportunity to review the values you've entered, and provides a means for changing those values before committing them.

• The migration script now automatically adds the Remote Revocation agent group to the Directory Server.

---

Software and Hardware Requirements

Operating Systems Supported

• Windows 2000 and Windows NT 4.0 with Service Pack 6

• Solaris 8

Other Required Software

• Sun ONE Certificate Server 4.7, also known as iPlanet Certificate Management System 4.7, must be installed and running before you can install this Service Pack.

• Administrators and end users use web browsers to perform user management tasks.CMS 4.7 SP1 supports the following web browsers:
  • Netscape Communicator 4.79 on the following platforms:
    Solaris 8; Windows versions NT 4.0 SP6a and 98SE.

  • Microsoft Internet Explorer 5.5 SP2 on the following Windows versions:
    2000 Professional, NT 4.0 SP6a, and 98 SE.

  • Microsoft Internet Explorer 6.0 on the following Windows versions:
    2000 Professional, NT 4.0 SP6a.

Platform and Hard Disk Requirements

These requirements are based on the requirements for installing and running Certificate Server 4.7.

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 Server.

Table 0-1    Platform and Hard Disk Requirements

Solaris Platform Requirements
OS Version	Solaris 8
Machine	Ultra 1 or faster
RAM	128 MB (256 MB recommended)
Hard disk storage space requirements	Total required is approximately 450 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 300 MB Additional space to allow for database growth in pilot deployment: approximately 50 MB Total disk storage space for installation: approximately 350 MB
Windows Platform Requirements
OS Version	Windows 2000, Windows NT 4.0 SP6a
Machine	Pentium II 400 or faster
File system	NTFS or FAT
RAM	128 MB (256 MB 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).

---

Installing Certificate Server 4.7 Service Pack 1

This service pack contains only select java classes and related files that will be copied into the appropriate directories of an existing Certificate Server 4.7 (CMS 4.7) installation. If you have a pre-4.7 version of CMS installed, see the following section "Migration Paths and Related Information."

If you don't have and existing CMS 4.7 installation, follow the instructions in the Certificate Server Installation and Setup Guide for installing the software.

• If you're using the product CD for installation, this book is available in HTML in the /Docs directory.

• If you downloaded the software from the website, be sure to download the pdf version of the book from this site: http://docs.sun.com/db?p=coll/S1_s1CertificateServer_47

Migration Paths and Related Information

Depending upon which version of Certificate Management System or Certificate System you have currently installed, choose one of the following migration paths:

Migrating from CMS 4.2 SP2

If CMS 4.2 SP2 is currently installed, follow these steps:

1. Upgrade to CMS 4.7.

   Follow instructions in the CMS 4.7 Release Notes at the following URL:
   http://docs.sun.com/source/816-5547-10/relnotes.html#70287, of CMS 4.7 Release Notes

2. Migrate to CMS 4.7 SP1.

   Follow instructions in the section "Upgrading From a Previous Certificate Server or Certificate Management System Installation" of these Release Notes.

Migrating from CMS 4.2

If CMS 4.2 is currently installed, follow these steps:

1. Upgrade to CMS 4.2 SP2.

   Follow instructions in Chapter 7, "Installing and Uninstalling CMS Instances" of the CMS 4.2 SP2 Installation and Setup Guide at the following URL:
   http://docs.sun.com/source/816-5541-10/man_inst.htm#32168.

2. Upgrade to CMS 4.7.

   Follow instructions in the CMS 4.7 Release Notes at the following URL:
   http://docs.sun.com/source/816-5547-10/relnotes.html#70287, of CMS 4.7 Release Notes

3. Upgrade to CMS 4.7 SP1.

   Follow instructions in the section "Upgrading From a Previous Certificate Server or Certificate Management System Installation" of these Release Notes.

Migrating from pre-CMS 4.2

1. Upgrade to CMS 4.2.

   Follow the instructions in the section "Upgrade From Certificate Management System 4.1" in the CMS 4.2 Release Notes at the following URL:
   http://docs.sun.com/source/816-5535-10/index.html#Upgrade From
     CMS 41x

2. Upgrade to CMS 4.2 SP2.

   Follow instructions in Chapter 7, "Installing and Uninstalling CMS Instances" of the CMS 4.2 SP2 Installation and Setup Guide at the following URL:
   http://docs.sun.com/source/816-5541-10/man_inst.htm#32168.

3. Upgrade to CMS 4.7.

   Follow instructions in the CMS 4.7 Release Notes at the following URL:
   http://docs.sun.com/source/816-5547-10/relnotes.html#70287, of CMS 4.7 Release Notes

4. Upgrade to CMS 4.7 SP1.

   Follow instructions in the section "Upgrading From a Previous Certificate Server or Certificate Management System Installation" of these Release Notes.

To Install CMS 4.7SP1

Before you begin, you must have an existing installation of CMS 4.7. For more information, see "Installing Certificate Server 4.7 Service Pack 1."

1. Stop all instances of CMS. For detailed instructions, see Chapter 8, "Starting and Stopping CMS Instances" in the CMS Agent's Guide.

2. Stop the Administration Server of Sun ONE Console.

   Unix: cd <server_root>
       ./stop-admin

   Windows: Click Start, choose Run, and then enter the following:
           serverRoot/stop-admin.cmd

3. Go to the directory where Certificate Server 4.7 is installed. This is also known as the Certificate Server root directory.

4. Copy the CMS 4.7SP1 tar or zip file to the Certificate Server root directory.

5. Untar or unzip the Certificate Server 4.7 Service Pack 1:

   Unix: tar -oxvf cms47sp1.tar

   Windows: unzip cms47sp1.zip

6. Restart the Administration Server of Sun ONE Console.

   Unix: cd <server_root>
       ./start-admin

   Windows: Click Start, choose Run, and then enter the following:
           serverRoot/start-admin.cmd

7. Restart all instances of CMS. For detailed instructions, see Chapter 8, "Starting and Stopping CMS Instances" in the CMS Agent's Guide.

All Java classes and related files are automatically copied into the appropriate directories of your existing Certificate Server 4.7 installation.

---

Upgrading From a Previous Certificate Server or Certificate Management System Installation

The only direct migration path to Certificate Server 4.7SP1 is from version 4.7. If you have an existing installation of Certificate Server or Certificate Management System, please see the Certificate Server 4.7 Release Notes at the following URL:

http://docs.sun.com/db?p=coll/S1_s1CertificateServer_47

---

The Certificate Server Migration Tool

Certificate Server 4.7SP1 provides a utility that migrates certificates, keys, CRLs, and related user information contained in the Internal DB directories.

Note

This migration tool is an updated version of the tool that comes with Certificate Server 4.7. Use this tool only if you have not already migrated from Certificate Server version 4.2SP2 to version 4.7. If you already have Certificate Server 4.7 installed and running, it is not necessary to use this migration tool.

The tool migrates only Certificate Server instances, and only on a single host; it does not span multiple machines. If your iPlanet Certificate Management Server implementation spans multiple machines, then each instance must be migrated separately. For example, if you have set up a Certificate Authority on one host and a Registration Authority on a different host, migrating the Certificate Authority does not automatically migrate the Registration Authority. Each instance must be migrated separately.

There are two versions of the migration utility, one for Unix and one for Windows. All steps listed in the migration tool documentation are performed.

Log files containing migration details can be found in the following directories:

Solaris:

/47_binaries_location/migration_MM-DD-YYYY-HH_MM_SS.log for   migration detailss

Windows:

\47_binaries_location\migration-MMDDYYYY.log

Known Issues and Workarounds

If you're upgrading a Windows NT or 2000 installation:

• If you use a third-party tool such as MKS toolkit, then the PATH should have the MKS toolkit as the last entry. Otherwise, the perl script will fail to execute.

• The migration script requires the following files in the system path:
  • smime.dll

  • nssetup32.dll

  • plc4.dll

  • plds4.dll

  If they are missing, you must add them to your system path. (4757146) You can obtain them from the directory where you unpacked the CMS 4.7 binaries. The file smime.dll is contained in the following zip file:

  /dist/admin/admin.z

  The files nssetup.32.dll, plc4.dll, and plds4.dll are contained in the following zip file:

  /dist/svcore/svrcoresys.z

• During the migration and after Certificate Server 4.2SP2 is uninstalled, if this message displays: "There are files marked for deletion upon next Reboot, Do you wish to Reboot now?" you have an option to either enter "No" or "Yes."
  • If you choose "No", then you can continue with the migration process in the mode you've selected (Typical or Custom).

  • If you choose "Yes", and you had selected the Typical mode for migration, then you will not be able to continue using the Typical mode. In this case, to continue with the migration process you must use the Custom mode, and then select the appropriate option.

• After migrating from CMS version 4.2SP2 to version 4.7, you may see an extra instance of Certificate Server in the iPlanet Console navigation tree; the instance is named after the computer system where CMS is installed. (4757146) This only occurs if, when you originally installed CMS 4.2SP2, you specified a Server Identifier other than the default. In the following illustration, for example, during installation of CMS 4.2SP2, the default name was derived from the name of the computer system where CMS is being installed. But the administrator changed the default to guest2000.

  
  
  

  When the administrator migrates the instance cert-guest2000 to CMS version 4.7, the migration script automatically creates a new instance of cert-<hostname> in addition to an upgraded instance of cert-guest2000.

  If you need another instance of Certificate Server, you can configure the new instance cert-<hostname> to suit your needs.

  If you do not need another instance of Certificate Server, you can remove the instance from iPlanet Console by following these steps:

  1. In iPlanet Console, click the Certificate Server instance you want to remove.

  2. Right-click, and then choose Remove Server from the menu.

Before You Begin

You should address the following issues before running the migration tool:

• Migration to Certificate Server 4.7 can be performed only on the same machine where Certificate Server 4.2SP2 is installed.

• Identify the Certificate Server 4.2SP2 instance that you want to migrate and note the corresponding server root and instance ID.

• Process all 4.2SP2 pending certificate requests.

• Back up the your CMS 4.2SP2 installation in case you need to recover your data.

• Gather information about the servers running on the system. For example, you should know the server names, ports, and plug-ins being used, and so on.

• Know the passwords for the Sun ONE Console administrator, the Certificate Server administrator, the LDAP databases, the single sign on for each instance.

• Close the 4.2SP2 Certificate Server window, and close any instances of Sun ONE servers before starting the migration process.

• Close all sessions to Certificate Server 4.2SP2. Do not access Certificate Server until after the migration process is completed.

• On Unix, you should run the migration tool as the same user who installed CMS 4.2SP2.

• Know the location of the unzipped Certificate Server 4.7 binaries.

• If a Certificate Server instance has been deleted from the installation, then delete its corresponding internal database instance.

• The migration tool needs ample space to backup the Certificate Server instances. Be sure that there is sufficient disk space in /var/tmp and the new 4.7 installation directory for Unix/Solaris, or in the default system drive for Windows NT/2000.

• On Windows only:
  • Prior to running the migration tool, you should install PERL on a directory other than the one that contains the PERL that comes with Certificate Server 4.2SP2. If the PATH to PERL is set to the PERL that comes with Certificate Server 4.2SP2, the PATH will be invalid after uninstallation.

  • If possible, take a system image of your machine for recovery purposes.

  • You should run the migration tool as Administrator.

Running the Migration Tool on Unix

The Unix version is a bourne shell script and is supported on Solaris.

There are two methods for using the migration tool on Unix. Choose one of the following methods:

1. Use the migration script that comes with CMS 4.7

2. Use the migration script that comes with CMS 4.7SP1.

1) Using the Migration Script that Comes with CMS 4.7

Note that the CMS 4.7 binaries contain an older version of the migration script. You can still use the script as is, following the instructions in the section "Upgrading from a Previous Certificate Server Installation" of the CMS 4.7 Release Notes. When you use this older script, you'll be prompted to obtain the latest version of the script from the Sun website.

To Run the Migration Script that Comes with CMS 4.7

1. Download and untar the file certificate-4.7-domestic-us.sparc-sun-solaris2.8.tar.gz from http://wwws.sun.com/software/download/download/5264.html. These are the binaries for CMS 4.7.

2. Follow the instructions in the section "Upgrading From a Previous Certificate Server Installation" of the CMS 4.7 Release Notes at http://docs.sun.com/source/816-5547-10/relnotes.html#70287.

3. Continue with the installation as usual, following the onscreen instructions.

   When installation is finished, the migration process will also be completed.

2) Using the Migration Script Obtained from CMS4.7 Service Pack 1

Note that the CMS 4.7 Service Pack 1 contains the latest version of the migration script. You can copy this latest MigrationSolaris file directly into the same directory where you unpack the CMS4.7 binaries.

To Run the Migration Script Obtained from CMS 4.7 Service Pack 1

1. Download and untar the file certificate-4.7-domestic-us.sparc-sun-solaris2.8.tar.gz from http://wwws.sun.com/software/download/download/5264.html. These are the binaries for CMS 4.7.

2. Download the file cms4.7sp1.tar from http://wwws.sun.com/software/download/download/5264.html. These are the files for Service Pack 1. To access the latest migration script, do one of the following:
   • From the file cms4.7sp1.tar, extract just the one file named MigrationSolaris.

     or

   • In a directory other than the CMS 4.2SP2 root directory, untar the file cms4.7sp1.tar.

3. Copy MigrationSolaris to the directory where you unpacked the CMS 4.7 binaries in step 1. This overwrites the existing MigrationSolaris file.

4. In the directory where you unpacked the CMS 4.7 binaries, run the migration script:

   ./MigrationSolaris

5. When prompted, "Please choose the type of Migration to run:"

   Choose Typical if you want to automatically migrate CMS 4.2SP2 to CMS 4.7 using default values and without stopping between each step of the migration. When you choose Typical, the script automatically migrates the 4.2SP2 instance(s) to 4.7 using default values. When the script is finished, skip to Step 7 of this document.

   Choose Custom if you want to be able to pause between each step of the migration. This is useful if you want to view the logs or view directories in the CMS installation to verify the changes being made. When you choose Custom, the following menu is displayed.

   
   
   

   Please choose one of the following options:

   ================================================================

   1. Provide information required for migration.

   2. Make a backup of CMS 4.2 SP2 configuration and internal database files.

   3. Create the silent mode installation file.

   4. Install the new CMS 4.7.

   5. Create individual CMS 4.7 instances.

   6. Copy the configuration files from the backup.

   7. Import data into the new internal databases.

   8. Modify CMS 4.7 configuration files.

   9. Remove the backup files.

   0. Exit.

   
   
   
   
   

   Note

   In order to migrate your data successfully, each of these steps must be performed in this exact sequence. Each time you complete a step, the same menu is displayed so that you can choose the next step in the sequence. Choose Exit when you want to stop the script after the completion of any step in the migration sequence.

   
   
   

6. After completing all of the steps in the migration sequence, verify that the new installation works and that your data has been successfully migrated.

7. Manually uninstall CMS 4.2SP2.

The migration process is complete. You can now install the CMS 4.7 Service Pack 1 following the instructions in the section "Installing Certificate Server 4.7 Service Pack 1" of this document.

Running the Migration Tool on Windows

The migration tool for Windows is PERL script using PERL 5.005 or higher.

There are two methods for using the migration tool on Windows. Choose one of the following methods:

1. Use the migration script that comes with CMS 4.7

2. Use the migration script obtained from CMS 4.7SP1.

1) Using the Migration Script that Comes with CMS 4.7

Note that the CMS 4.7 binaries contain an older version of the script named migration.pl. You can still use the script as is, following the instructions in the section "Upgrading From a Previous Certificate Server Installation" of the CMS 4.7 Release Notes. When you use this older script, you'll be prompted to obtain the latest version of the script from the Sun website.

To Run the Migration Script that Comes with CMS 4.7

1. Download and unzip the file certificate-4.7-domestic-us.win2000.zip from http://wwws.sun.com/software/download/download/5264.html. These are the binaries for CMS 4.7 for Windows 2000.

2. Follow the instructions in the section "Upgrading From a Previous Certificate Server Installation" of the CMS 4.7 Release Notes at http://docs.sun.com/source/816-5547-10/index.html.

3. When you run the migration script migrationNT.pl, when asked "Get the latest version?" enter Yes.

4. Continue with the installation as usual, following the onscreen instructions.

   When installation is finished, the migration process will also be completed.

2) Using the Migration Script Obtained from CMS4.7 Service Pack 1

Note that the CMS 4.7 Service Pack 1 contains the latest version of the migration script. You can copy this latest migrationNT.pl file directly into the same directory where you unpack the CMS4.7 binaries.

To Run the Migration Script Obtained from CMS 4.7 Service Pack 1

1. Download and unzip the file certificate-4.7-domestic-us.win2000.zip from http://wwws.sun.com/software/download/download/5264.html. These are the binaries for CMS 4.7 for Windows 2000.

2. Download the file cms4.7sp1.zip from http://wwws.sun.com/software/download/download/5264.html. These are the files for Service Pack 1. To access the latest migration script, do one of the following:
   • From the file cms4.7sp1.zip, extract just the one file named migrationNT.pl.

     or

   • In a directory other than the CMS 4.2SP2 root directory, unzip the file cms4.7sp1.zip.

3. Copy migrationNT.pl to the directory where you unpacked the CMS 4.7 binaries in step 1. This overwrites the existing migrationNT.pl file.

4. Run the migration scripts:

   <server_root> MigrationNT.pl

5. When prompted, "Please choose the type of Migration to run:"

   Choose Typical if you want to automatically migrate CMS 4.2SP2 to CMS 4.7 using default values and without stopping between each step of the migration. When you choose Typical, the script automatically migrates the 4.2SP2 instance(s) to 4.7 using default values. When the script is finished, skip to Step 7 of this document.

   Choose Custom if you want to be able to pause between each step of the migration. This is useful if you want to view the logs or view directories the CMS installation to verify the changes being made. When you choose Custom, the following menu is displayed.

   
   
   

   1. Make a backup of CMS 4.2 SP2 configuration files.

   2. Make a backup of CMS 4.2 SP2 internal database files.

   3. Create the silent mode installation file.

   4. Uninstall CMS 4.2 SP2.

   5. Install the new CMS 4.7.

   6. Create individual CMS 4.7 instances.

   7. Copy the configuration files from the backup.

   8. Import data into the new internal databases.

   9. Modify CMS 4.7 configuration files.

   10. Remove the backup files.

   11. Exit.

   
   
   

Note that in order to migrate your data successfully, each of these steps must be performed in this exact sequence. Each time you complete a step, the same menu is displayed so that you can choose the next step in the sequence.

Caution

On Windows and Windows 2000 platforms, if you reboot the computer system for any reason after using the script to uninstall version 4.2SP2 (step 4 in the menu), then you will not be able to continue using the Typical mode. To continue with the migration process you will have to use the Custom mode. When the migration menu is displayed, begin with option 5) Install CMS 4.7.

Choose Exit when you want to stop the script after the completion of any step in the migration sequence.

6. After the script has completed, reboot the computer system.

7. Verify that the new installation works and that your data has been successfully migrated.

   The migration tool for Windows automatically uninstalls the CMS 4.2SP2 installation. It is a good practice to check the old installation directory and to delete any remaining files.

The migration process is complete. You can now install the CMS 4.7 Service Pack 1 following the instructions in the section "Installing Certificate Server 4.7 Service Pack 1" of this document.

---

Microsoft Security Patch Q323172

Microsoft's Crypto APIs contain bugs which could allow identity spoofing or the deletion of digital certificates. Microsoft has released patch Q323172 to eliminate these security vulnerabilities. For detailed information about the nature of these bugs and how the Microsoft patch addresses them, go to the following URLs:

http://www.microsoft.com/technet/treeview/default.asp?url=/technet/  security/bulletin/MS02-050.asp

http://www.microsoft.com/technet/treeview/default.asp?url=/technet/security  /bulletin/ms02-048.asp

If you have not installed the Microsoft security patch Q323172, and you attempt to do one of the following:

• access CMS enrollment forms using Microsoft Internet Explorer 5.x or above

• use multiple Certificate Managers, Registration Managers, or clones,

then the following dialog box is displayed (540435):

Click Yes to install it, and the certificate gets generated as expected. To prevent this dialog from being displayed in the future, follow these steps:

1. Copy web/ee/xenroll.dll into the directory <cms_server_root>/web/ee. Example:

   cp web/ee/xenroll.dll /opt/SUNWcertsrv/certsrv47/cert-abc/web/ee

2. Copy web/agent/ca/xenroll.dll into the directory <cms_server_root>/web/agent/ca directory.
   Example:

   cp web/agent/ca/xenroll.dll   /opt/SUNWcertsrv/certsrv47/cert-abc/web/agent/ca

3. Copy web/agent/ra/xenroll.dll into the directory <cms_server_root>web/agent/ra.
   Example:

   cp web/agent/ra/xenroll.dll   /opt/SUNWcertsrv/certsrv47/cert-abc/web/agent/ra

4. If the SUN One Certificate Server enrollment forms (*.html and *.template) have already been customized, you must edit the classid in the appropriate CMS enrollment forms and templates. To edit the classid, In each affected enrollment form or template located in the following directories:

   <cms_server_root>/web/ee

   <cms_server_root>/web/agent/ca

   <cms_server_root>/web/agent/ra

   replace the following:

   
   
   

   classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"

   CODEBASE="/xenroll.dll"

   id=Enroll >

   </OBJECT>

   
   
   

   with the following:

   
   
   

   <OBJECT

   classid="clsid:127698e4-e730-4e5c-a2b1-21490a70c8a1"

   CODEBASE="/xenroll.dll"

   id=Enroll >

   </OBJECT>

   
   
   

5. If the SUN One Certificate Server enrollment forms (*.html and *.template) are not already customized, follow these steps.
   1. Copy web/ee/*.* into the directory <cms_server_root>/web/ee.
      Example:

      cp web/ee/*.*   /opt/SUNWcertsrv/certsrv47/cert-<instance>/web/ee

   2. Copy web/agent/ca/*.* into the directory <cms_server_root>/web/agent/ca.
      Example:

      cp web/agent/ca/*.*   /opt/SUNWcertsrv/certsrv47/cert-<instance>/web/agent/ca

   3. Copy web/agent/ra/*.* into the directory <cms_server_root>/web/agent/ra.
      Example:

      cp web/agent/ra/*.*   /opt/SUNWcertsrv/certsrv47/cert-<instance>/web/agent/ra

---

Updated setpin Tool

The setpin tool has fixed so that it now supports SSL connections over LDAP. An example usage is:

setpin host=localhost port=636 ssl

binddn=cn=pinmanager,dc=red,dc=sun,dc=com

bindpw=<password>

basedn=ou=people,dc=red,dc=sun,dc=com

"filter=(uid=*)"

output=outputfile

write

Included Files

• /bin/cert/tools/setpin
  new setpin executable

• /bin/cert/tools/setpin.conf
  updated configuration file

Notes on the Updated setpin Tools

There are a few things to be aware of when running the setpin tool.

• The setpin tool requires dynamic libraries located in two directories of a CMS 4.7 installation. The inclusion of these dynamic libraries is order specific. Example:

    setenv LD_LIBRARY_PATH
      /<server-root>/bin/cert/lib:/<server-root>/lib

• To run in SSL mode, it is necessary for setpin to have access to a certificate database which contains and trusts the signer of Directory Servers SSL certificate. You can use the CA's certificate database or you can use a new database and install a certificate.

To create a new database:

certutil -d . -N

To install a certificate:

certutil -d . -A -n caSigningCert -t C -a -i inputfile

   where inputfile contains the CA's signing certificate in base-64.

By default, setpin will look in the current working directory to locate a certificate database. Option 'certdb' may be used to specify a path to a directory containing the certificate database.

---

Known Problems and Limitations

The following issues remains unresolved in Certificate Server 4.7SP1 at this time. Check back frequently for more information on this issue.

Generating a PKCS10 Request Using a Cisco Router

There is a problem with Cisco routers that prevents a router, when connecting to a Registration Manger (RA), from successfully generating a PKCS10 request. This problem is being investigated by Cisco at this time. A temporary workaround is available through Sun Technical Support at the following URL:

http://sunsolve.sun.com/pub-cgi/show.pl?target=home

SSOBasedAuthentication

Descriptions of the following attributes should be included in the online Help for an SSOBasedAthentication instance:

com.iplanet.am.notification.url: Type the Certificate Server URL (without 'enrollment') used by Identity Server in the Identity Server Security Service Configuration. It uses the form:

  http://<cms_server_hostname>:<non-ssl end entity port number> or

  https://<cms_server_hostname>:<ssl end entity port number>

com.iplanet.am.notification.servletclass: Type the notification servlet class used by Identity Server. The default value is:   com.iplanet.services.comm.client.PLLNotificationServlet.

This information will be added to online Help in the next release of the product (4766746).

---

For More Information

Useful Sun ONE information can be found at the following Internet locations:

• Sun ONE release notes and other documentation --- http://docs.sun.com/db/prod/sunone

• Sun ONE product status --- http://www.sun.com/products/

• Sun ONE Professional Services information --- http://www.sun.com/service/support/

• Sun ONE developer information --- http://www.sun.com/developers/support/

Last Updated November 07, 2002