Kousec Server Certificate Manager - readme

Install Instructions and Release Notes

Version: 1.0.0b, date 5/4/2010

What's New in 1.0.0b

• The installer file is now digitally signed. Please note that other program files in the product are not digitally signed yet.
• A few minor bug fixes.

About Kousec Server Certificate Manager

Shorthand Notations

System Requirements

Server Side

• Windows XP SP2 or SP3, Windows 7
• Windows Server 2003 SP1 or later, Windows Server 2008 (all 32-bits)
• Windows Server 2008 R2 (64-bit)
• 1GB or more of RAM

Optional Server Side Components

• Java Runtime Environment Version 5 or higher.
  If you want to import the certificate from a Java keystore, you need to have JRE accessible from CertMgr.
• Windows Management Framework Core (PowerShell 2.0, WinRM 2.0)
  Required only if you want to automate certificate install for IIS 7/7.5.

Supported Web Browsers

• IE 7.0
• Firefox 3.0, 3.6
• IE 6.0 (Limitation: Some icons have gray background colors)

Software Requirements for Automated Certificate Install

For automated installation of certificate to IIS servers, there are not only software requirements but also network requiements. Please see "Requirements for Automated Certificate Install" down below for details.

In an environment where you cannot use automated certificate install, you can still use one-click certificate installers for IIS.

Installing Kousec Server Certificate Manager

BETA/RC Users: you must uninstall any previous version of Server Certificate Manager and also remove the install directory completely. (e.g., C:\KousecCertMgr)

Initial Install

1. Execute the Kousec CertMgr Installer program. It must be executed by a user with Administrator privilege.
2. Select the install folder. The folder's name or name of the parent folder must not include any space characters.
3. During install, a Windows service named "KousecCertMgr" will be created and started.

KousecCertMgr service is set to start automatically when the OS starts. You can also use shortcuts in Kousec Server Certificate Manager menu to start/stop/restart the service.

Upgrade Install

Notes

• You cannot migrate any user data from any Beta or RC versions.
• Backing up the install directory before starting upgrade install is strongly recommended.

Upgrade Procedure

1. Uninstall the Kousec Server Certificte Manager software. This will leave all user data intact in the install directory.
2. Execute the new version of Kousec CertMgr Installer program. You must select the same install directory to migrate the data.
3. When the previous version is uninstalled, the KousecCertMgr service information is also deleted. If you had changed the service account for running the KousecCertMgr service, you must set the same service account again. (Required if you use IIS7 or Windows CA for lifecycle management).
4. See any upgrade notes in this readme file or other documentation for any additional work that must be done by the administrator.

Accessing Kousec Server Certificate Manager for the first time

About Access Control

• Restriction by Client IP addresses
  Access to Kousec CertMgr web server is allowed to clients with any IPv4 addresses. See Users Guide for how to change the IP address access control. Also please be sure to protect the computer with the Windows firewall.
• To access Kousec CertMgr and the Document Folders application in Kousec CertMgr, you must log in with a username and password..

For more details, see the User's Guide.

Limitations and Known Issues

• None.

Supported Server Software Products

(*) SUSE11 : SUSE Linux Enterprise Server 11

Requirements for Automated Certificate Installs

Install to IIS6

• If CertMgr is installed on Windows XP:
  You need to install IIS 6.0 Manager for Windows XP. You may also have to install common components of IIS 5.1 (XP) if you encouter the error as described in the second artitle.
  • Internet Information Services (IIS) 6.0 Manager for Windows XP
  • You receive an error message when you try to use IIS 6.0 Manager for Windows XP to connect to an instance of IIS 6.0 that is running on a remote server
• If CertMgr is installed on Windows Server 2003:
  You need to install IIS Manager that comes with Windows Server 2003.
• Network:
  There must be no firewall between the CertMgr computer and target IIS server. (We use DCOM protocol).

Install to IIS 7 or 7.5

• CertMgr computer: Windows XP or Windows Server 2003:
  You need to install Windows Management Framework Core (PowerShell 2.0, WinRM 2.0) and configure Powershell Remoting feature.
  • Windows Management Framework Core (PowerShell 2.0, WinRM 2.0)
• Managed server: Windows Server 2008 or Windows Server 2008 R2
  If the managed server is runnig Windows Server 2008, you need to install Windows Management Framework Core (PowerShell 2.0, WinRM 2.0), as stated above.
  If running Windows Server 2008 R2, PowerShell 2.0 and WinRM 2.0 are already installed as part of the OS.
  Powershell Remoting feature must be configured.
• KousecCertMgr Service Account
  After installing Kousec Server Certificae Manager, change the OS account that runs "KousecCertMgr" service. The user-specified account must be an Administrator on the local machine.
• Network:
  Managed servers need to open WinRM TCP ports for the CertMgr computer.

   Default ports: 5985(HTTP), 5986(HTTPS)

• Enabling PowerShell Remoting
  The following are the most basic steps to enable PowerShell Remoting. For the production deployment, please see a separate document for more secure configuration.
  • CertMgr computer
    

    PS> Set-ExecutionPolicy RemoteSigned
    PS> set-item WSMan:\localhost\Client\TrustedHosts -value "*"

    Note for 64-bit Windows: You must start 32-bit version of PowerShell to execute the above.
    CMD> C:\WINDOWS\syswow64\windowspowershell\v1.0\powershell.exe
    
    
  • Managed servers
    

    PS> Enable-PSRemoting

Exchange 2007 Support

One-click installer for Exchange 2007

Since Exchage 2007 Server is a large and complex product that supports various deployment toplogies with specfic requirements, CertMgr provides a certificate install package that first installs any intermediate CA certificates required and then auto-starts a powershell script that will import and enable the server certificate. The script actually shows the comand (import and enable) and asks you if you want to execute that command. It also leaves the powershell command window open after the script ends so you can manually execute those commands and/or check to see if the certificate is valid and enabled for desired services.

For server certificate usage in Exchange 2007, see the following articles:

• Certificate Use in Exchange Server 2007

Using Server Certificate from the Built-in Private CA

It is recommended by Microsoft to obtain server certificate(s) from a commercial CA for an Exchange 2007 site. In an Exchange 2007 initial install, the required SSL server certificates are generated as self-signed certificates. Therefore there is no point in getting a server certificate for Exchange 2007 from the built-in Private CA, except for testing purposes.

The following are additional steps you must take when using a certificate from the private CA.

• Publish the CRL (Certificate Revocation List) and the certificate of the private CA on the web server of Kousec Certmgr.
  The CRL file is publically available on the CertMgr web server as "/privca_pub/1.crl". The CA certificate is publically available on the web server as "/privca_pub/ca-cert.cer".
• Direct the private CA to put these URLs as certificate extensions in all certificates that the CA issues.
  Create a file called "ca_ext.conf" in the "myca" directory (i.e., "myca\ca_ext.conf"), and enter the following text in that file. Note that this change must be made before the target server certificate is generated.
  
  

  [default]
  
  crlDistributionPoints=URI:<external-url>/privca_pub/1.crl
  authorityInfoAccess=caIssuers;URI:<external-url>/privca_pub/ca-cert.cer
  

  For example,

  [default]
  
  crlDistributionPoints=URI:http://any-hostname-needed/privca_pub/1.crl
  authorityInfoAccess=caIssuers;URI:http://any-hostname-needed/privca_pub/ca-cert.cer
  
  
  Type "gencert -info" to make sure that the file is recognized.

  Then, ensure that these URLs is accessible without any access control from the target server (the Exchanage 2007 server computer(s) to which you have installed the certificate). You can run "certutil -verify -urlfetch cert.pem" to see if access from the Windows OS succeeds or not. (cert.pem is an exported server cert file.)

Support for "IIS (generic)"

You can choose "IIS (generic)" as the server software type when you want to use the certificate for the following Windows services

• WinRM (PowerShell Remoting) over HTTPS
• Windows Remote Desktop Services or Terminal Services

A one-click installer that is created for IIS (generic) imports the server certificate and its private key to the local computer's Personal Certificates store and also imports any associated CA certificate(s) to the CA certificate store or Trusted Root certificate store as appropriately. It will NOT set up the application (WinRM or Win RDS) to use the server certificate just imported. The server administrator must carry out that task.

• WinRM: See the separate document for details.
• Windows Remote Desktop Services or Terminal Services:
  You can set up the certificate using Terminal Services Configuration tool. See the Windows help file and the documentation.

JKS (generic) Support

CertMgr can create a certificate installer package with Java Keystore importer program. This feature supports many Java-based application servers that use a keystore of JKS (Java KeyStore) format for storing its own private key. The JKS importer program first backs up the existing JKS file if one exists and then imports the new private key and server and intermediate CA certificates under the alias name specified by CertMgr administrator. A Java-based server may also use another keystore as a TrustStore that contains trusted CA certificates. The CertMgr importer program does not touch the TrustStore in any way.

Creating a certificate installer package

As CertMgr administrator you can specify the location of the keystore in the JKS File Path text box in the Server Software Options tab. You should enter a full path to the keystore file to be updated. If no value is specified, ".keystore" in the home directory of the user who is executing the installer package is assumed. Enter the alias name and keystore password, in the Alias in Keystore text box and the Keystore Password text box respectively.

In the Server Instance text box, enter a descriptive text that identifies the server software instance on the target server. This information is for the server administrator.

Example

Server Instance: Tomcat-prod2
JKS File Path: C:\Document and Settings\Administrator\keystore.jks
Alias in Keystore: tomcat2
Keystore Password: mypass

Running the certificate installer package

As the server administrator, when you receive the installer package, unzip it with the distribution password printed on the Install Request email. On Windows, you can then double click "jks_inst.bat". On Unix/Linux servers, you can execute "bash jks_inst.sh" or "java -cp JksUtil.jar JksUtil". If the JKS file already exists, it will be backed up. Otherwise a new JKS keystore will be created. The java installer imports the new private key and certificates under the alias as configured by the CertMgr administrator.

If the required alias or keypassword is different from what the CertMgr administrator already set up, you can change them after the import. The import program shows how to change the alias and password using the keytool command included in your Java Runtime Environment.

Alternatively, you can use another tool that may be bundled with your server software product, such as ImportPrivateKey in WebLogic Server.

Java Compatibility

Target servers need to have JRE 1.4 or higher installed.

Tested Java-based Products

Apache Tomcat : Tomcat 4.1, Tomcat 5.5, Tomcat 6.0
Oracle WebLogic Server : WebLogic Server 9.2, WebLogic Server 8.1

Apache on Linux Support (One-click Installer)

CertMgr will create a certificate installer package with an install script. You can use the installer script for the Apache server that is installed in the OS standard location. The install script detects the OS version and certificate locations, and if there are any unexpected configuration, the script stops, undoing any changes done so far.
If you have a second instance, you will need to use manual installation method using certificate and key files included in the certificate installer package.

Requirements for the Target Server

• The Apache server must have been configured for SSL using any server certificate and its private key.
• CentOS/RHEL 4.x and 5.x : There is no additional software or configurations needed.
• SUSE 11 : There is no additional software or configurations needed.
• Ubuntu 9 and 8: PHP CLI version and "unzip" program must be installed. Execute the following commands to install the programs:
  "sudo apt-get install php5-cli" and "sudo apt-get install unzip"
• Linux distribution versions not listed in the support matrix:
  the installer checks for individual requirements and if all are met it will try to install the certificate. The PHP version must be 4.3.x or higher. Enter the location of the SSL config file (explained later) in the SSL Conf Path text box.
  

Creating a certificate installer package

The certificate installer looks for an Apache configuration file (refered to as SSL Config File here) that contains SSL certificate settings (SSLCertificateFile and SSLCertificateKeyFile). You can specify the location of an SSL Config File in the SSL Conf Path text box of the Server Software Options tab. If you have SSL certificate settings in the standard (default) SSL config file, which depends on your Linux distribution version, you can leave the SSL Conf Path text box empty. The following table shows default SSL config file locations for each Linux distribution supported.

Running the certificate installer package

As the server administrator, when you receive the installer package, upload it onto /tmp directory on the target server and unzip it with the distribution password printed on the Install Request email. Then follow the instructions in the email.
All files including cert and key files and Apache configuration files will be backed up before modifying them. The install script will create an undo script that you can run to back out any changes.

Apache on Linux Support (Automated Installer)

CertMgr will send the certificate installer package and necessary install scripts to the target server and execute the installer script to install the certificate. You can use the installer script for the Apache server that is installed in the OS standard location. The install script detects the OS version and certificate locations, and if there are any unexpected configuration, the script stops, undoing any changes done so far.
If you have a second instance, you will need to use manual installation method using certificate and key files included in the certificate installer package.

System Requirements

There are requirements for the automated installation on top of the requirements for the one-click installer version:

• The CertMgr computer must be able to log in to the target server using SSH v2 protocol with password authentication.
  • SUSE 11: you must set PasswordAuthentication to 'yes' in the SSHD configuration.
• The username and the password of the superuser (root) of the target server must be registered in the Certificate Deployment process. The username or the password will not be written in the certificate install package.
• If the target server doesn't allow the "root" user to log in and instead requires use of "sudo" command, enter the username who is authorized to call "sudo" to execute any commands.
  • This is the case in Ubuntu OS.

Creating a certificate installer package

As with one-click installer, enter the location of your SSL Config File in the SSL Conf Path text box as necessary. For Username for Auto-install and Password for Auto-install, enter the user name and the password for CertMgr to access the target server. Specify either "root" or another user who has an appropriate "sudo" privilege to carry out tasks as the OS superuer. Also make sure that the CertMgr computer can access the target server via the server name specified in Server Name for Certificate.

Executing Auto-Install

After you have created a certificate install package with additional Auto-install information, click the Install certificate now button. CertMgr will try to install the certificate and show a result. Click See log to show the auto-install execution log if the install failed.

Support for OpenSSL based Server Software (One-click Installer/Automated Install)

We support many server software programs that use OpenSSL as their SSL library. The table below shows currently supported server software types. Please note that support for Apache HTTP Server (which is also OpenSSL-based) is provided in the server software type of "Apache/Linux", not as this type of "Openssl". For other OpenSSL-based software not listed here, you can select this type and manually install the certificate.

Requirements for the Target Server

• The server software must have been configured for SSL using any server certificate and its private key.
• GNU bash (shell) and perl must be available on the target server.
• Currently supported OS is Linux.

Creating a certificate installer package

Select Openssl (generic) in the Server Software Type selection box. Then in the Server Software Options tab, select appropriate server software type. See the online help for other options.

Running the certificate installer package (One-click installer)

As the server administrator, when you receive the installer package, upload it onto /tmp directory on the target server and unzip it with the distribution password printed on the Install Request email. Then follow the instructions in the email.
All files including cert and key files will be backed up before modifying them. The install script will create an undo script that you can run to back out any changes.

Running installer remotely (Automated install)

If you select vsftpd/Dovecot/Postfix as the software type, you can also execute the automated install. Be sure to specify an OS user and its password in Auto-Install Options. The user needs to be the super-user (root) or one of sudo-enabled users.

Support for VMware ESXi

Automated Certificate Install

System Requirements and Notes

• No additional software is required on CertMgr computer.
• TCP port 443 (HTTPS) on the ESXi machine must be open to the CertMgr computer.
• The VMware administrator must manually invoke the Restart Management Agents after the certificate is installed on the ESXi server.
• You need a purchased license for the ESXi . The free-license ESXi does not allow the certificate to be updated remotely. Use One-Click Installer in that case.

Basic Procedure for Installing Certificate Initially

1. In the VMware ESXi direct console, configure management network as necessary. Use the Restart Management Network operation to have the settings to take effect.
2. On VI Client or vSphere Client, change the hostname (hostname.domainname) of VMware ESXi server to your choice. Follow its instruction to have the settings to take effect.
3. On CertMgr, prepare a certificate for the ESXi server. The certificate needs to have the same hostname (hostname.domainname) in its Common Name. You can also put multiple hostnames into Domain Name List on CertMgr to create a multi-domain certificate. For example, you can put "hostname", "hostname.domainname", "192.168.1.188" so that the ESXi server can be accessed via any of the three names.
4. In the CertMgr deploy process, enter username and password for the ESXi server in Auto-Install options. Click the Install Certificate button to install the certificate.
5. In the VMware ESXi direct console, use the Restart Management Agents for the new certificate to be effective.

One Click Installer

System Requirements and Notes

• To execute this one-click installer, you must log in to the ESXi hypervisor kernel. This operation is not supported by VMware. You should only use this method if you are using the free version of ESXi.

Basic Procedure for Installing Certificate

1. On CertMgr, prepare a certificate for the ESXi server.
2. Download its certificate install package to your PC.
3. Unzip the package on your PC, entering the package password. Note that this package contains an unencrypted form of private key. So be sure to securely handle it.
4. Transfer all three files in the expanded package to the /tmp directory on the ESXi server. You can use unsupported SSH or the Datastore Browser to do this.
5. Run the command "sh /tmp/inst_esxi.sh" on the ESXi server.
6. The installer script automatically restart ESXi management services.
7. Be sure to delete the unencrypted private key that could be left behind when being transfered to the ESXi server.

Support for VMware ESX

Automated Certificate Install

System Requirements and Notes

• No additional software is required on CertMgr computer.
• TCP port 22 (SSH) on the ESX service console OS must be open to the CertMgr computer.
• The super user (root) log in via SSH must be enabled. SSH-logging-in as a regular user and sudo-ing is not supported.

Basic Procedure for Installing Certificate Initially

1. In the VMware ESX service console, configure SSHD to allow the user root to log in. Change the parameter PermitRootLogin to yes in /etc/ssh/sshd_config file and restart the sshd service.
2. On CertMgr, prepare a certificate for the ESX server. The certificate needs to have the same hostname (hostname.domainname) in its Common Name. You can also put multiple hostnames into Domain Name List on CertMgr to create a multi-domain certificate. For example, you can put "hostname", "hostname.domainname", "192.168.1.188" so that the ESX server can be accessed via any of the three names.
3. In the CertMgr deploy process, enter username (i.e., root) and password for the ESX server in Auto-Install options. Click the Install Certificate button to install the certificate.
4. After installing the certificate, several management services will be restarted on the ESX server. It will take more than a few minutes before the HTTPS service becomes available with the new certificate. A deploy check immediately after the certificate install will fail because of that. In that case repeat the deploy check five or ten minutes later.

Support for VMware vCenter Server

You can create an one-click certificate installer for replacing the default self-signed SSL certificates in vCenter Server.

One-click Certificate Installer

System Requirements and Notes

• No additional software is required on CertMgr computer.
• The one-click installer asks for user confirmation on many of the installation steps to ensure the the server administrator is well aware of vCenter Server shutdown and startup timings.

Basic Procedure

1. On CertMgr, prepare a certificate for the vCenter Server computer. The certificate needs to have the same hostname (hostname.domainname) in its Common Name. You can also put multiple hostnames into Domain Name List on CertMgr to create a multi-domain certificate. For example, you can put "hostname", "hostname.domainname", "192.168.1.188" so that the vCenter Server computer can be accessed via any of the three names.
2. In the CertMgr deploy process, proceed to create a certificate package for the vCenter Server computer. Send the certificate package and its package password to the adminisrator of the vCenter Server computer.
3. When the vCenter administrator receives the the certificate package, upload it on to the vCenter Server computer and execute it by entering the package password. It will prompt for user confirmation.

A separate document discussing how to deploy Kousec Server Certificate Manager to a VMware vSphere environment will be posted on the Kousec Software website.

Integration with Windows Certificate Services

You can automate requesting a server certificate and retrieving it from a Windows certificate services. Kousec CertMgr supports two modes of operations. One is to directly contact a Windows CA. The other is to go through Windows Certificate Enrollment Web Services (CES) to reach the behind Windows CA.

Supported Configurations

Windows Certification Authority (Windows CA)

• Computer that runs Windows Certification Authority:
  Windows Server 2003 Enterprise Edition with Enterprise CA
  Windows Server 2008 Enterprise Edition with Enterprise CA
  Windows Server 2008 R2 Enterprise Edition or Standard Edition with Enterprise CA
• Computer that runs Kousec CertMgr : any Windows OS that is supported by Kousec CertMgr.
  
• The Kousec CertMgr computer and the computer that is running the Windows CA must be members of the same Active Directory domain.
  (This requirement can be somewhite relaxed as described below)

Windows Certificate Enrollment Web Service (Windows CES)

• Computer that runs Windows Certification Authority:
  Windows Server 2008 R2 Enterprise Edition with Enterprise CA
• Computer that runs Windows Certificate Enrollment Web Service:
  Windows Server 2008 R2 Enterprise Edition.
  • Authentication Type for CES must be Username and password
    
• Computer that runs Kousec CertMgr :
  Windows Server 2008 R2 Standard Edition or Enterprise Edition (64-bit)
  Windows 7 (only for evaluation purposes only)
• The Kousec CertMgr computer and the computer that is running the Windows CES can be in totally unrelated Active Directory domains.

Necessary Setup (for Windows CA)
After installing Kousec Server Certificae Manager, change the OS user account that runs "Kousec CertMgr" service to any domain user with the following access privilege

• Has READ and ENROLL permissions on the desired Certificate Template on the Windows CA. Typically, Domain Admins and Enterprise Admins groups are granted these permissions on all certificate templates on the CA.
• If you need to run Kousec CertMgr on a standalone computer (as opposed to domain member), you can create a local user having the same name and password as those of the domain user and use that local user to run the Kousec CertMgr service.

Once you log in to CertMgr web console, open "CA Contracts" screen and follow the instructions there.

Necessary Setup (for Windows CES)

When editing information for a CA Contract, enter username and password of an ActiveDirectory user account who has READ and ENROLL permissions on the desired certificate template. A username must be prefixed with the domain name:

• Example: DOMAIN\MyUser

For the Server String, enter the URI for the Windows CES that you have set up. You can view the URI in the Application Settings of the CES virtual directory on IIS Manager. The URI should look like the following.

• https://myca.example.com/example-MYCA-CA_CES_UsernamePassword/service.svc/CES

This HTTPS access will authenticate the server's IIS certificate. Be sure to install the issuing CA's certificate in the Trusted Root store of the local computer if the CA is a private CA.