CertAgent. Installation, Configuration, and Management Guide

Transcription

1 CertAgent Installation, Configuration, and Management Guide Version April 2, 2013

2 Information in this document is subject to change without notice and does not represent a commitment on the part of Information Security Corporation. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser s personal use without the prior written permission of Information Security Corp. CertAgent is commercial computer software and, together with any related documentation, is subject to the restrictions on U.S. Government use as set forth below. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS Contractor/manufacturer is Information Security Corporation, 1011 W. Lake Street, Suite 425, Oak Park, IL The U.S. International Traffic in Arms Regulations (ITARs) (22 CFR ) prohibits the dissemination of certain types of technical data to foreign nationals. Protected by U.S. Patents No. 5,274,707, 5,373,560, and 5,699,431. CertAgent is a trademark of Information Security Corp. Other product and company names mentioned in this document may be the trademarks of their respective owners. The cryptographic functionality of CertAgent is provided by CDK 7.0, ISC s FIPS validated cryptographic module, via a Java JNI and/or an RMI interface. In addition, CertAgent uses code extracted or derived from the following open source software packages redistributable under the terms of the GPL or Apache License Version 2.0: Hypersonic SQL, Version 2.1.0: Copyright The Hypersonic SQL Group. All rights reserved. Copyright The HSQL Development Group. All rights reserved. JavaLDAP, Version 0.20: Copyright 2000 Clayton Donley. All rights reserved. Log4j, Version : Copyright The Apache Software Foundation. All rights reserved. Version (April 2013) Copyright Information Security Corporation. All rights reserved. Information Security Corporation 1011 W. Lake Street, Suite 425 Oak Park, IL Phone: Fax: Website: sales@infoseccorp.com 2

3 Table of Contents 1 Introduction About this Guide CertAgent Architecture CertAgent Administration Technical Support Conventions Used in this Guide Print Conventions Command Terminology Mouse Conventions Installation and Configuration System Requirements HSM Support Installation Checklist Unpacking the Software Distribution UNIX Windows Updating an Existing CertAgent Installation Updating from CertAgent 4.x or 5.x Using the Key Management Utility Managing PBE-Protected System Credentials Managing HSM-Protected System Credentials Managing the Java Keystore Configuring CertAgent on Apache Tomcat Installing Apache Tomcat Configuring TLS Creating the Web Application Manager Account Starting Tomcat Server Deploying the CertAgent Web Applications Configuring CertAgent on Oracle WebLogic Server 11g (10.3) References to WebLogic Documentation Deployment Checklist Creating a New WebLogic Domain Starting the WebLogic Server Configuring TLS for the Administrative Server Deploying the Administrative Web Application Creating and Configuring the Public Server Starting the Public Server Deploying the Public Web Application Configuring the CertAgent Audit Trail Firewall Configuration and Security Managing the CertAgent Server

4 3.1 Using the certagent Script Starting the Server Stopping the Server Entering the System Password after CertAgent Startup Viewing the Server Log Viewing the System Version Number Using the Windows Service Using the CertAgent Web Interface Before Using the Administrative Site Entering the Administrative Site Using a CA Account Using the Public Site Additional Management Tools The CertAgent Command Line Tool Command Line Syntax Creating a CA Account Creating a Profile Generating Credentials for a CA Account Generating a Certificate Request for a CA Account Installing a CA Certificate Generating Credentials for a SCEP RA Generating a Certificate Request for Cross Certification Listing Account Configuration Settings Listing Profile Configuration Settings Updating Account Configuration Settings Listing Accounts and Profiles Listing Supported Key Generation Options Listing Available Hash Functions for a Specific Key Type and Size Listing the Slots and Labels on an HSM Adding to an Account s Access Control List Removing a Certificate from an Account s Access Control List Viewing an Account s Access Control List Deleting an Account Importing Issued Certificates Importing a CRL Deleting Expired Certificates Deleting Processed or Rejected Certificate Requests Deleting CRLs The Certificate Report Generator Command Line Syntax Sample commands The CertAgent RA Management Interface Establishing a TLS Session with Client Authentication Submitting a Certificate Request Parameters Responses and Their Parameters Revoking a Certificate

5 5.3.1 Parameters Responses and Their Parameters Reinstating a Certificate Parameters Responses and Their Parameters Issuing a CRL Parameters Responses and Their Parameters The Database Access Service Managing the Database Access Service Preparing the dbaccess Script Command Line Syntax Starting and Stopping the DBAccess Service Listing the DBAccess Settings of All CA Accounts Enabling and Disabling the DBAccess Service for a CA Account Managing DBAccess ACLs Configuring the DBAccess Audit Trail Using the DBAccess API Developing a Java Client Using the DBAccess API Supported SQL Syntax CertAgent Database Schema Sample SQL statements

6 1 Introduction CertAgent is an easily managed, web-based certificate authority (CA) intended to be used as the core component of an enterprise public key infrastructure (PKI). Designed to meet the needs of a wide variety of organizations, the current release offers enhanced enrollment services, remote administration, integrated certificate and CRL databases for each CA, as well as a publically accessible LDAP repository. It supports an unlimited number of root and intermediate CAs, providing support for as complex a certificate hierarchy as the size of your enterprise warrants. 1.1 About this Guide This guide explains how to install CertAgent on an existing webserver and configure it for use. The introduction provides an overview of the organization of the CertAgent system, provides contact information for technical support, and explains the stylistic conventions used in this manual. The following chapter, Installation and Configuration, describes how to install CertAgent on different webservers and explains how to use the Key Management Utility (KMU) to generate the credentials required to properly configure the server s various authentication services. Managing the CertAgent Server describes how to manage a CertAgent system using a command line script, the Windows control panel, and via its administrative web interface. The final chapter, Additional Management Tools, describes the bundled management utilities and enrollment API. 1.2 CertAgent Architecture CertAgent consists of two separate web applications that must both be deployed into a Servlet/JSP container running on a webserver: an admin site - the web application providing the system administration and CA account interfaces (including the registration authority management interface), and a public site - a web application providing end-user enrollment and certificate management interfaces The following diagram illustrates the basic layout of the CertAgent system. 6

7 HSM (optional) External LDAP Repository (optional) CertAgent ISC CDK (FIPS 140-2) JNI CertAgent Server Audit Trail (log4j-based) Certificate/CRL Database Keystores RMI DBAccess TLS w/ auth. (ACL) Report Generator Key Management Utility CACLI Admin Interface TLS w/ auth. (ACL) Java Servlet/JSP Container Administration Module Certificate Authority Interface RA Management Interface TLS w/ client auth. (ACL) Public Module (enrollment, certificate retrieval, etc.) TLS w/o client auth. LDAP v3 SQL query (via secure RMI) Administrator CAs RAs End-users Public access (optional) The CertAgent 6.0 System Architecture Of course, to support TLS encryption and authentication, the host webserver must be provisioned with a TLS certificate and private key and be configured with two TLS ports: one with enforced client authentication (for the admin site) and one without client authentication (for the public site). In addition, CertAgent requires a system certificate to encrypt the private keys for all CA accounts. The corresponding system private key can be provided in either of the following two formats: a.prv file containing a PKCS#8 PDU (PBE-encrypted with a system password that must be entered after server startup), or a.p7m CMS PDU containing a raw PKCS#8 private key (with a NULL password), encrypted with an HSM certificate (the PIN for which must be entered after server startup). Note that all administrators and CAs must be provided with certificates so that they may authenticate themselves to the webserver during login. If the required TLS and system credentials do not already exist, the Key Management Utility (KMU) integrated into CertAgent may be used to generate and install them. Otherwise, your existing certificates and private keys can be simply copied onto the host system. See the section entitled Using the Key Management Utility for details. 7

8 1.3 CertAgent Administration The CertAgent administrator is responsible for: installing CertAgent (optional) generating certificate and private keys (using the Key Management Utility) installing the TLS and system credentials starting the server and entering the system password (or HSM PIN) managing CA accounts 1.4 Technical Support Information Security Corporation provides technical support for CertAgent during the following business hours: 8:30 a.m. to 5:00 p.m. Central Time Please contact us in one of the following ways: Voice: (708) Fax: (708) Web: 8

9 1.5 Conventions Used in this Guide This Installation Guide consistently employs certain text formatting and language conventions to assist you in learning how to use CertAgent Print Conventions The following typographical conventions are used throughout this guide for screen displays, command entries, and keyboard characters: Actions in procedures are printed in bold type. Window titles, menu names, and dialog names are printed exactly as they appear in the application. Actions requiring key combinations are joined with a plus sign, e.g., <Ctrl + P>. To execute this type of action, press and hold the first key, then press the second key and release both keys Command Terminology The following terminology is used consistently in describing individual or multi-step actions. Select refers to making a choice from a menu or list of options in a dialog box. For example, select On Hold option means that you must select this option by clicking on it with the mouse Mouse Conventions The assumption throughout this User s Guide is that your left mouse button is configured as the Windows primary mouse button and that the right button is the secondary button. (You may, of course, choose to reverse the roles of these buttons using Windows Mouse control panel.) The following terminology regarding mouse usage is employed throughout this manual: Click means to position the cursor over an object and then to press and immediately release the primary mouse button without moving the mouse. Double-click means to position the cursor and then to press and immediately release the primary mouse button twice in quick succession. Drag means to position the cursor over an object (the source of the drag operation) and then to press and hold the primary mouse button while moving the cursor to a new location. Once the cursor has reached its destination, release the mouse button to drop the object onto the target. 9

10 2 Installation and Configuration 2.1 System Requirements The following components are required to run CertAgent: memory: 512 MB RAM (minimum) available disk space: 50MB 32-bit Java Development Kit (JDK) or Java Runtime Environment (JRE) 1.5 or above If you do not already have the JDK/JRE installed on your Solaris, Linux or Microsoft Windows host, it may be freely downloaded from the following Oracle webpage: a suitable Java Servlet container; see vendor s documentation for additional system requirements. 2.2 HSM Support CertAgent fully supports hardware security modules (HSMs) in the sense that each CA s keys can be stored on an HSM and the system private key can be encrypted under an HSM-based key pair. While any HSM with a PKCS#11-compliant interface should work with CertAgent, the following HSMs have been successfully tested by ISC and found to be fully compatible: ncipher nshield 800 F3 PCI Safenet Luna CA3 Safenet ProtectServer Orange HSM External Safenet ikey

11 2.3 Installation Checklist The list below provides an overview of the installation and configuration tasks required to get a typical CertAgent system up and running. Unpack the software distribution Generate a system key pair using the Key Management Utility (KMU) Generate an administrator key pair using the KMU (or optionally, install an existing key pair) Import the administrator key pair into a Java trust keystore using the KMU Install the administrator s credentials into a web browser on the administrator s system (e.g., into Internet Explorer s CAPI store) Generate the webserver s TLS key pair and install it into a Java keystore using the KMU (or optionally, install an existing TLS key pair into a Java keystore) Configure the host TLS settings: one TLS port with client authentication for the administrative site and one TLS port without client authentication for the public site Deploy the administrative and public web applications Configure firewall Start the CertAgent server and enter the system password or PIN 11

12 2.4 Unpacking the Software Distribution UNIX The CertAgent package for UNIX platforms consists of a zip archive that may be unzipped (with directory structure preserved) into any convenient directory on your webserver s hard drive, though we recommend that you use /usr/local/certagent. (If you choose a different installation directory, make sure that the entire path to that directory does not contain any spaces.) Throughout this document <ca home> will be used to refer to the CertAgent root installation directory. The contents of the current distribution are as follows: Directory Files Description <ca home> <ca home>/lib certagent.sh (UNIX) certagent.bat (Windows) calicense.txt *.jar *.txt log4j.properties CertAgent server script CertAgent license agreement Java program libraries, licenses, and log4j configuration file for additional audit trail output <ca home>/isc.certagent * CertAgent data directory <ca home>/bin *.kyp *.so.* *.dll (UNIX) (Windows) CertAgent program libraries <ca home>/tomcat * (Windows) Apache Tomcat 7 <ca home>/tools *.sh (UNIX) *.bat (Windows) *.java *.txt Scripts used to run the Key Management Utility (KMU) and to update CertAgent from previous versions; sample program illustrating the use of the registration authority management interface; sample configuration file for command line tools. <ca home>/tools/dbaccess/server <ca home>/tools/dbaccess/client *.sh (UNIX) *.bat (Windows) dbaccess.log4j certagentdbaccess.jar DBAccessSample.java doc/* command line scripts and audit trail configuration file for the database access service the database access library, a sample program illustrating its use, and a doc folder containing API documentation <ca home>/webapp *.war Web application archives 12

13 Preparing Credentials Using Key Management Utility The supplied Key Management Utility (KMU), <ca home>/tools/keyman.sh, allows you to quickly bootstrap the configuration of a new CertAgent system by creating the required Java trust keystore and generating new (possibly temporary) system, TLS server, and administrator credentials. Before using this utility, open the file <ca home>/tools/keyman.sh in your favorite text editor and modify the environment variable settings as indicated in the embedded comments. Then simply execute the script to launch the KMU. Use Quick Start option to quickly generate X.509 credentials for the system, TLS server, and administrator; create the TLS server s Java keystore; import the administrator s certificate into the Java trust keystore and administrator ACL; and configure CertAgent with its default operational settings. 1. Select Quick Start on the KMU s main page, and then click Next. 13

14 2. Complete the form: enter the domain name or IP address of your server enter the name of your organization The subject DNs of the system and TLS server certificates, and of the administrator certificate that will be generated will be of the form: CN= CertAgent System Key, O=<organization>, C=US, CN=<domain name>, O=<organization>, C=US and CN= CertAgent Administrator, O=<organization>, C=US respectively. enter a common password for the private keys and server s TLS keystore specify a location and password for the Java trust keystore (Sun s default values for these items are <java home>/jre/lib/security/cacerts and changeit ) specify an output directory for the new credentials (optional) check the box labeled protect system private key with HSM if you would like to encrypt the system private key with credentials stored on an HSM Then click Next. 3. If protect system private key with HSM is selected, complete the following form and click Next. 14

15 4. The result page that appears should be checked to confirm that all operations completed successfully: new system credentials were created webserver TLS credentials were created and imported into a new Java keystore administrator credentials were created the administrator certificate was imported into the Java trust keystore and CertAgent administrator s ACL system configuration file was updated the results of these operations were written to the active audit trail log file Before closing this window, please make a note of the location of the server s TLS keystore and key alias. You will be required to reenter this information to properly configure the server s TLS services. You should also make a note of the complete path to the administrator s PKCS#12 file and import it into the Microsoft CAPI personal store or browser certificate store on your own computer. (These credentials are required for administrative access to the webserver via TLS with client authentication.) 5. Click Finish to exit. Please note that the certificates produced by the Quick Start option are software-based and self-signed. They are intended to be used only to boot-strap the system configuration process. After Quick Start completes and you have created at least one CA account, you should use the KMU to replace the temporary system, TLS server, and administrator credentials with real (i.e., CA-issued, possibly HSMbased) credentials with corrected key sizes, RDNs, and certificate extensions. 15

16 Use the Manage System Key option on the KMU Main page to update the system credentials (which are used to protect all CA private keys and HSM PINs on the system), or to upgrade the system private key protection mechanism from PBE to HSM-based. For details, see the section Managing PBE-Protected System Credentials. You can also use the Manage Java Keystore option to add any required trust anchors (i.e., root CA certificates) to the system s Java trust keystore. For details, see the section Managing the Java Keystore. To continue CertAgent installation, skip to the section Configuring CertAgent on Apache Tomcat 7 or Configuring CertAgent on Oracle WebLogic Server 11g (10.3) to install and configure CertAgent to run inside your existing servlet container. 16

17 2.4.2 Windows CertAgent for Windows is packaged as a zip archive. The following instructions step you through the installation process of installing CertAgent and (optionally) Apache Tomcat. If Java Runtime Environment (JRE) 6 or above is not found on your server, the CertAgent installation wizard will attempt to install it. It is recommended that you accept all default installation options; the default installation directory is C:\CertAgent. (If you choose a different installation directory, make sure that the entire path to that directory does not contain any spaces.) Throughout this document <ca home> will be used to refer to the CertAgent root installation directory. 1. Extract all files from CertAgent600win.zip into a temporary directory. 2. Double click on ca600.exe to begin the installation process. 3. If the User Account Control dialog appears, click Yes to allow CertAgent to make changes to your computer. 4. When the CertAgent Setup Wizard appears, click Next to install CertAgent. 5. Review the license agreement and click I Agree. 6. Select the features you would like to install and click Next to continue. Unless Tomcat, WebLogic or another Java servlet container is already installed on your system and you wish to use it, choose the option to install Apache Tomcat Click Browse to change the destination folder if needed and click Next. 8. Complete the form: enter the server IP address or domain name enter the admin and public TLS/SSL ports enter the name of your organization enter a common password for the system and administrator private keys enter a password for the SSL server private key Then click Install. Installation will begin. After generating administrator credentials, the installer will launch the Certificate Import Wizard three times: first to import the administrator PKCS#12 credentials into the Personal store, second to import the administrator certificate into the Trusted Root Certificate Authorities store, and third to import the SSL server certificate into the Trusted Root store. The subject DNs of the system and TLS server certificates, and of the administrator certificate that will be generated will be of the form: CN= CertAgent System Key, O=<organization>, C=US, CN=<server IP>, O=<organization>, C=US and CN= CertAgent Administrator, O=<organization>, C=US respectively. 17

18 9. When the Finish page appears, click Finish to close the Wizard. By default, the wizard will open the Administration page and README file. Please note that the certificates produced by the installer are software-based and self-signed. They are intended to be used only to boot-strap the system configuration process. After installation completes and you have created at least one CA account, you should use the KMU to replace the temporary system, TLS server, and administrator credentials with real (i.e., CA-issued, possibly HSM-based) credentials with corrected key sizes, RDNs, and certificate extensions. Use the Manage System Key option on the KMU Main page to update the system credentials (which are used to protect all CA private keys and HSM PINs on the system), or to upgrade the system private key protection mechanism from PBE to HSM-based. For details, see the section Managing PBE-Protected System Credentials. You can also use the Manage Java Keystore option to add any required trust anchors (i.e., root CA certificates) to the system s Java trust keystore. For details, see the section Managing the Java Keystore. If Apache Tomcat was included in the list of packages to be installed, the CertAgent web applications are deployed within it and Tomcat is started automatically. You can then skip to the section entitled Using the Windows Service for details. Otherwise, skip to the section Configuring CertAgent on Apache Tomcat 7 or Configuring CertAgent on Oracle WebLogic Server 11g (10.3) to install and configure CertAgent to run inside your existing servlet container. 18

19 2.5 Updating an Existing CertAgent Installation Updating from CertAgent 4.x or 5.x If you have CertAgent installed on a UNIX system and are updating to the current release, unzip the software distribution archive into a new directory on your server s hard drive do not use the original CertAgent installation directory. Once the new distribution is unpacked, run the following script:./update/update.sh This will update your existing CA account databases and program files. If you have CertAgent installed on a Windows system and are updating to the current release, unzip the software distribution archive into a new directory on your server s hard drive do not use the original CertAgent installation directory. Once the new distribution is unpacked, run the following script:.\update\update.bat This will update your existing CA databases and program files. If you are running CertAgent on a Windows system with Apache Tomcat, the updated CertAgent administrative and public web application will be deployed automatically. Otherwise, you must manually deploy these web applications (./webapp/*.war) to your existing servlet container. 19

20 2.6 Using the Key Management Utility The supplied Key Management Utility (KMU), <ca home>/tools/keyman.sh, allows you to quickly bootstrap the configuration of a new CertAgent system by creating the required Java trust keystore and generating new (possibly temporary) system, TLS server, and administrator credentials. If your system is already up and running, you can use the KMU to update system credentials and manage the Java keystore. Before using this utility for the first time on a UNIX system, open the file <ca home>/tools/keyman.sh in your favorite text editor and modify the environment variable settings as indicated in the embedded comments. Then simply execute the script to launch the KMU. To launch the KMU on a Windows system, select Start All Programs CertAgent Key Management Utility Managing PBE-Protected System Credentials 1. Select Manage System Key on the main page and click Next. 2. Current system key information is displayed. Enter the private key password for the current key pair, and then click Next. 3. Follow the instructions below to replace the system keys or convert the system private key into an HSM-protected private key Replacing the System Key When CertAgent system credentials are about to expire, you may either renew them or generate ones. In the latter case, all private keys (and any HSM PINs) that were encrypted under the old certificate must be re-wrapped under the new system certificate. The KMU facilitates this process. To replace the existing system key: 1. Select Replace system key option on the Manage System Key page and click Next. 2. If the new system key pair is in a PKCS#12 file, select that file and enter its password. Otherwise, select a PKCS#7 or X.509 certificate file, specify the associated private key file, and enter the private key password. Then, click Next. The Results window below confirms that the new key pair has been successfully imported, all CA private keys have been rewrapped with the new system certificate, and the system configuration file has been updated. 3. Click Finish to exit. 20

21 Be sure to notify all system administrators of any change in the system password. The private key password used above in step 2 must be entered into the administrative page each time the CertAgent system is restarted Converting a PBE-Protected Private Key into an HSM-Protected One You can use the KMU to convert an existing PBE-protected system private key into an HSM-protected private key. Note that once this is done, the system administrator must enter the correct HSM PIN upon system startup rather a private key password. To upgrade the protection mechanism on the system private key from PBE to HSM-based: 1. Select Convert a PBE-protected private key into an HSM-protected private key on the Manage System Key page and click Next. 2. Provide the requested HSM access information. Note: You can specify a library file and then click Pick Slot/Label to select from a list of available slots on the HSM device. 3. Click the HSM Certificate Browse button to display a list of all available HSM certificates. 4. Select the certificate you wish to use to protect the system private key, and then click OK. 5. Click Next. The message window shown below confirms that the system private key has been successfully encrypted with the specified HSM certificate and that the configuration file has been updated. 6. Click Finish to exit. If necessary, be sure to notify all system administrators of this change in the system private key protection mechanism. They should be aware that an appropriate HSM PIN (rather than a private key password) must be entered into the administrative page upon system startup Managing HSM-Protected System Credentials 1. Select Manage System Key on the main page of the KMU and click Next. 2. The current system key information is displayed. Enter the HSM PIN, and then click Next. 21

22 3. Follow the instructions below to replace the system key, to update the HSM certificate used to wrap the system private key, or to downgrade the private key protection mechanism from HSM-based to PBE Replacing the System Key When CertAgent system credentials are about to expire, you may either renew them or generate ones. In the latter case, all private keys (and any HSM PINs) that were encrypted under the old certificate must be re-wrapped under the new one. The KMU facilitates this process. To replace the existing system key: 1. Select Replace system key on the Manage System Key page and click Next. 2. If the new system key pair is in a PKCS#12 file, select that file and enter its password. Otherwise, select a PKCS#7 or X.509 certificate file, specify the associated private key file, and enter the private key password. Then click Next. 3. Update the HSM access information and certificate if needed, and then click Next. The Results window below confirms that the new key pair has been successfully imported, all CA private keys have been rewrapped with the new system certificate, and the system configuration file has been updated. 4. Click Finish to exit. Be sure to notify all system administrators of any change in the HSM PIN. They should be aware that the new PIN must be entered into the administrative page upon system startup Updating the HSM Certificate 1. Select Update HSM certificate on the Manage System Key page and click Next. 2. Update the current HSM access information and certificate. Then, click Next. The Results window below confirms that the current system private has been successfully encrypted with the specified HSM certificate and that the system configuration file has been updated. 3. Click Finish to exit. If the HSM PIN has changed, be sure to notify all system administrators of that fact. 22

23 Converting an HSM-Protected Private Key into a PBE-Protected One 1. Select Converting an HSM-protected private key into a PBE-protected private key on the Manage System Key page and click Next. 2. Enter a password for the system private key, confirm it, and then click Next. The Results window below confirms that the current system private key has been decrypted and re-encrypted with the new password, and that the system configuration file has been updated. 3. Click Finish to exit. If necessary, be sure to notify all system administrators of the change in the system private key protection mechanism. They should be aware that the private key password (rather than an HSM PIN) must be entered into the administrative page upon system startup Managing the Java Keystore The KMU can also be used for common Java keystore management tasks: creating a new keystore, inspecting the contents of an existing keystore, adding or removing certificates or key pairs, inspecting certificates, and changing a keystore password. For CertAgent purposes, this utility can be used to manage the server s TLS and Java trust keystores Preparing the Server s TLS Keystore The webserver hosting your CertAgent system must be configured to provide TLS encryption and authentication. If you don t already have an appropriate TLS credentials, the Quick Start option in the Key Management Utility (KMU) described above can be used to generate a new TLS key pair and selfsigned certificate and install them into a suitable Java keystore. This section, therefore, explains how to use the KMU to import existing TLS credentials that you already have in PKCS#12 format. 1. Select Manage Java Keystore on the main page. Then, click Next. 2. Click New to create a new keystore. 3. Click Import and select the PKCS#12 file that contains your TLS credentials. 4. Enter the PKCS#12 password for this file and click OK. 5. Enter a new password for protection of the key in the keystore: 23

24 6. When prompted for a server key alias, enter tomcat if you are using Tomcat as your webserver; otherwise, specify any alias you wish to use (e.g., the server s IP address or domain name). Then click OK. 7. Once your credentials have been successfully imported, they will appear in the keystore. Click Save to store the new keystore in a specified location. 8. You will be prompted to enter a keystore password. Since some servers require the keystore password to be the same as that of its keys, it is safest to reenter the password you used in step 5 if you are unsure about the requirements of your particular server. 9. Click OK, and then click Close to close the keystore. Click Finish to exit. Be sure to remember the alias and passwords you entered here as this information will later be required to configure the host s TLS services Managing the Java Trust Keystore Since all administrative access to the CertAgent system is via TLS with client authentication, administrator and CA certificates must be installed into the Java trust keystore which acts as the server s TLS access control list. The KMU can be used to install these certificates. 1. Select Manage Java Keystore on the main page, and then click Next. 2. To manage the Java default trust keystore: a. Click Open, select the Java default trust keystore (typically <java home>/jre/lib/security/cacerts), then enter the password for this keystore (the default password is changeit ) and click OK. b. The aliases of all trusted CA certificates will be listed. 3. To create a new trust keystore: a. Click New. 4. Click Import and select the file containing the certificate you wish to add to this keystore. 5. The alias for the new keystore entry defaults to the common name of the selected certificate. Change it if desired, then click OK: 6. Once the specified certificate has been added to the alias list, click Save to save the modified keystore contents. 24

25 7. If a new keystore was selected: a. Specify a new keystore location and click Save. b. Set the keystore password and click OK. 8. Then click Close to close the keystore and click Finish to exit the KMU Changing the Keystore Password 1. Select Manage Java Keystore on the main page, and then click Next. 2. Click Open and select a Java default keystore. 3. Enter the keystore password and then click Change Password. 4. Enter a new password for the keystore, confirm it, and then click OK. 5. The dialog below confirms that the keystore password has been changed 6. Click OK to close the dialog and click Close to close the keystore, then click Finish to exit. 2.7 Configuring CertAgent on Apache Tomcat 7 This section explains how to configure the host TLS settings and deploy the CertAgent administrative and public web application modules on a Tomcat server. For additional information on the relevant Tomcat operations, please consult the Tomcat documentation indicated below. Topic general information server configuration starting/stopping the server deployment of applications configuring TLS Reference URL <tomcat home>\running.txt

26 2.7.1 Installing Apache Tomcat 7 If you do not already have the Tomcat package installed on your system, the software distribution may be freely obtained from the following Apache.org webpage: Administrators of 32-bit Windows servers should download the 32-bit/64-bit Windows Service Installer package in the core section. Run the installer (.exe) and follow the on-screen instructions to install Tomcat. For 64-bit Windows hosts, download the 32-bit Windows zip file. Unzip the package into any convenient directory (e.g., C:\) on your system. Tomcat files will be extracted to a \apachetomcat-7.x.xx directory tree under the target directory. (Note: CertAgent depends on 32-bit Java, so 32-bit Apache Tomcat must be installed even on 64-bit systems.) For UNIX-based platforms, download the tar.gz package in the core section. Unzip the Tomcat package into any convenient directory (e.g., /usr) on your system. Tomcat files will be extracted to a /apachetomcat-7.x.xx directory tree under the target directory. Throughout this document <tomcat home> will be used to refer to the Tomcat root installation directory (e.g., /usr/apache-tomcat-7.x.xx or C:\apache-tomcat-7.X.XX) Configuring TLS The CertAgent administrative and public web interfaces must be run on SSL ports with and without client authentication respectively. If Tomcat has not been configured to support these two SSL ports, follow these steps: 1. Open the Tomcat configuration file in an editor: <tomcat home>/conf/server.xml <tomcat home>\conf\server.xml (UNIX) (Windows) 2. Disable the APR library loader and insert the lines highlighted below into the appropriate XML file for your system at the indicated location: 26

27 <...> <!--APR library loader. Documentation at /docs/apr.html --> <!-- <Listener classname="org.apache.catalina.core.aprlifecyclelistener" SSLEngine="on" /> --> <...> <Service name="catalina"> <...> <!-- one-way TLS HTTP connector for public site --> <Connector port="443" protocol="http/1.1" SSLEnabled="true" maxthreads="150" scheme="https" secure="true" clientauth="false" sslprotocol="tls" keystorefile="c:\certagent\keystore\ssl.ks" keystorepass="password" /> <!-- two-way TLS HTTP connector for admin site --> <Connector port="8443" protocol="http/1.1" SSLEnabled="true" maxthreads="150" scheme="https" secure="true" clientauth="true" sslprotocol="tls" keystorefile="c:\certagent\keystore\ssl.ks" keystorepass="password" /> Modify the keystorefile, keystorepass and port values as appropriate for your installation. port keystorefile keystorepass keystoretype Parameter Value TLS/SSL ports for administrative and public sites file path of a Java keystore containing the SSL server credentials password of the Java keystore and the SSL server private key password (optional) set to PKCS12 if keystorefile is in PKCS#12 format instead of Java key store If you have used Quick Start in the Key Management Utility to generate all the credentials, keystorefile should set to <output directory>\ssl.ks and keystorepass is the password entered in the Quick Start form. 3. Save the server.xml file and close your editor Creating the Web Application Manager Account If Tomcat was installed as part of the CertAgent package on a Windows system, the CertAgent web applications will be deployed automatically. In this situation, you do not need to create an application manager account and may skip this section. If, however, you are running Tomcat on a UNIX system or Tomcat was not installed as part of the CertAgent package on Windows, please perform the following tasks: 1. If a Web application manager account has not yet been created, open the Tomcat users configuration file in an editor: <tomcat home>/conf/tomcat-users.xml 2. Insert the line highlighted below into this xml file at the indicated location: 27

28 <?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="tomcat"/> <role rolename="role1"/> <role rolename="standard"/> <role rolename="manager"/> <user username="tomcat" password="tomcat" roles="tomcat"/> <user username="role1" password="tomcat" roles="role1"/> <user username="both" password="tomcat" roles="tomcat,role1"/> <user username="manager" password="password" roles="manager"/> </tomcat-users> 3. Modify the manager username and password fields as appropriate for your installation. 4. Save the tomcat-users.xml file and close your editor Starting Tomcat Server If Tomcat is installed along with CertAgent on a Window system, the Tomcat service is registered and starts/stops automatically upon system startup/shutdown. On a UNIX system, or on a Windows system on which Tomcat has been installed separately from CertAgent, you must follow the instructions below to start the Tomcat server (using the Windows service or UNIX startup script) Using the Windows Service If the Tomcat service has not been installed: 1. If the Tomcat service has not been installed, open a command as an administrator and run the following command to register the service: C:\apache-tomcat \bin>service.bat install Installing the service 'Tomcat7'... Using CATALINA_HOME: "C:\apache-tomcat " Using CATALINA_BASE: "C:\apache-tomcat " Using JAVA_HOME: "" Using JVM: "auto" The service 'Tomcat7' has been installed. 2. Run <ca home>\bin\tomcat7w.exe as administrator to open the Apache Tomcat 7 Properties dialog. 3. In the General tab, change the Startup type to Automatic if desired, then click Apply to save the change. 4. Click Start to start the Tomcat service. 28

29 5. Click OK to close the dialog. For details on managing the Tomcat service, see: Using the Startup Script On a UNIX system, or on a Windows system on which Tomcat has been installed separately, follow these steps to create a startup script. 1. Create a new tomcat startup script: <ca home>/starttomcat.sh <ca home>\starttomcat.bat (UNIX) (Windows) 2. Insert the lines below into the appropriate file for your system. # Sample Tomcat Startup File for UNIX JRE_HOME=/usr/java/jre1.6.0; export JRE_HOME CATALINA_HOME=/usr/apache-tomcat ; export CATALINA_HOME nohup Sample Tomcat Startup File for Windows set JRE_HOME=C:\Program Files\Java\jre6 set CATALINA_HOME=C:\apache-tomcat call %CATALINA_HOME%\bin\startup.bat If a customized Java trust keystore is used, set the following options to the CATALINA_OPTS variable: -Djavax.net.ssl.trustStore=<trust keystore path> -Djavax.net.ssl.trustStorePassword=<trust keystore password> The default session time-out value for administrative and CA logins is 30 minutes. To change this value, append the following option to the CATALINA_OPTS variable: -Disc.ca.web.session.timeout=<time-out value in minutes> 3. Save the file and close your editor. 4. Run the Tomcat startup script: 29

30 <ca home>/starttomcat.sh <ca home>/starttomcat.bat (UNIX) (Windows) Deploying the CertAgent Web Applications If Tomcat is installed as part of the CertAgent package on a Windows system, the CertAgent web applications are deployed automatically, so you may skip this section. Otherwise: 1. Launch the Tomcat Web Application Manager by opening the following link in your web browser: 2. In the Enter Network Password dialog, enter the user name and password you specified for the manager account in the tomcat-users.xml configuration file, then click OK. 3. On the Tomcat Web Application Manger page, click Browse on the WAR file to deploy section to select the Administrative web application archive: /certagent/webapp/certagentadmin.war Then, click Deploy. Deployment status will be displayed on the Application section. 4. Repeat the previous step to deploy the public site by selecting the archive: /certagent/webapp/certagent.war 2.8 Configuring CertAgent on Oracle WebLogic Server 11g (10.3) This section explains how to configure the host TLS settings and deploy the CertAgent administrative and public web application modules on a WebLogic server. These instructions assume WebLogic has been previously installed References to WebLogic Documentation For additional information on the relevant WebLogic operations, please consult the Oracle documentation indicated below: 30

31 2.8.2 Deployment Checklist The checklist in this section provides a high-level overview of the process of configuring CertAgent on an Oracle WebLogic 10.3 server. Installation steps are presented in the recommend chronological order. To plan your deployment, start by recording in the third column of the following tables the various configuration settings that will be required. (This information should be collected here so that you can conveniently refer to it in later steps.) 1. If you don t already have appropriate key pairs and certificates, you may use the Quick Start feature of the Key Management Utility (KMU) to generate TLS credentials for the webserver as well as for the system and administrator accounts. Use values entered into the following table with section Preparing Credentials Using Key Management Utility. Field Default Value Value 1. Server Key Alias tomcat 2. Server P12 and Keystore Password <password> 3.Server Certificate File <ca home>/keystore/ssl.cer 4. Server P12 File <ca home>/keystore/ssl.p12 5. Server Java Keystore <ca home>/keystore/ssl.ks 6. Admin Common Name CertAgent Administrator 7. Admin Password <password> 8. Admin.p12 File <ca home>/keystore/admin.p12 9. Default JavaTrust Keystore JAVA_HOME/jre/lib/security/cacerts 2. Configure your Oracle WebLogic server by following the instructions starting in section using the values entered into the following table. Field Example Value Value 10. Admin Server Name CAAdmin 11. Listen Port

32 12. TLS Listen Port Admin User Name weblogic 14. Admin User Password Password 3. Modify your WebLogic startup script as described in section Error! Reference source not found.. 4. Configure the TLS service on your server; see section Deploy the CertAgent Admin Web Application; see section Deploy the CertAgent Public Web Application, using values in the following table with the instructions in section Field Example Value Value 15. CA Public Server Name CAPublic 16. Listen Port TLS Listen Port Finally, import the administrator credentials (admin.p12) into your browser so that you can successfully authenticate to the administrative web pages on the server. Once the server is running and you can log in to the administrator account, refer to the CertAgent Administrator s Guide for further instructions on configuring the server and establishing CA accounts Creating a New WebLogic Domain 1. Start the Oracle WebLogic Configuration Wizard by running the following script: <weblogic home>/wlserver_10.3/common/bin/config.sh (UNIX) Start -> All Programs -> Oracle WebLogic -> WebLogic Server 11gR1 -> Tools -> Configuration Wizard (Windows) 2. On the Welcome page, select Create a new WebLogic domain and click Next. 32

33 3. On the Select Domain Source page, select Generate a domain configured automatically to support the following products and click Next. 4. On the Specify Domain Name and Location page, fill in the domain name (e.g., CertAgent) and keep the default domain location. Then, click Next. 5. On the Configure Administrative User Name and Password page, enter <Admin User Name (e.g., weblogic)> and <Admin User Password> onto the form. Then, click Next. Enter Values into Checklist #13 and On the Configure Server Start Mode and JDK page, select Production Mode and JRockit SDK. Then, click Next. 7. On the Select Optional Configuration page, check Administration Server box and click Next. 8. On the Configure the Administration Server page, enter <Admin Server Name (e.g., CAAdmin)> into the Name field, select All Local Addresses as the Listen address, and enter <Listen Port (e.g., 7001)> as the Listen port. Check SSL enabled and enter <TLS Listen Port (e.g., 8443)> as the SSL listen port. Then, click Next. Enter values into Checklist # On the Configuration Summary page, click Create. 10. On the Creating Domain page, click Done to close the wizard Starting the WebLogic Server 1. Start the WebLogic Server by running the following script: /user_projects/domains/<domain>/startweblogic.sh (UNIX) \user_projects\domains\<domain>\startweblogic.cmd (Windows) Note: on Windows 7, you must open a command prompt as an administrator and then run this batch file. 2. When prompted, enter the username <Admin User Name> and <Admin User Password> to start the server. Note: <Admin User Name> and <Admin User Password> are the values entered in step 5 under Creating. (Enter the values of checklist items #13 and #14.) 3. Continue to the next section. 33