Centralized Credential Management Servlet (CCMS) Quick Start Guide

Transcription

1 Centralized Credential Management Servlet (CCMS) Quick Start Guide Facilitating the Deployment of X.509 Credentials with Centralized Key Generation and PKI Management Version November 5, 2014

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. CCMS 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 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. CCMS is protected by U.S. Patent No. 5,699,431. CCMS is a trademark of Information Security Corp. Authenticode is a registered trademark of Microsoft. Other product and company names mentioned in this document may be the trademarks of their respective owners. The cryptographic functionality of CCMS is provided by CDK 7.0, ISC s FIPS Level 1compliant cryptographic module. In addition, CCMS uses the following open source software packages redistributable under the terms of the Apache License Version 2.0: Log4j, Version : Copyright The Apache Software Foundation. All Rights Reserved. Commons IO, Version 2.4 Copyright The Apache Software Foundation. All Rights Reserved. JSON.simple, Version 1.1.1: Copyright The Apache Software Foundation. All Rights Reserved. JSON-RPC, Version 2.0: Copyright by the JSON-RPC Working Group JSTL, Version 1.2: Copyright 2013 Oracle Corporation. All Rights Reserved. JSP-API, Version 2.2.1: Copyright 2013 Oracle Corporation. All Rights Reserved. CCMS Quick Start Guide, Version (November 2014) 2014 Information Security Corp. All rights reserved. Information Security Corporation 1011 Lake Street, Suite 425 Oak Park, IL Phone: Fax: Website: sales@infoseccorp.com 2

3 Table of Contents 1 Installation and Configuration System Requirements Configuring Database Oracle MySQL HyperSQL Installing CCMS Starting/Stopping CCMS Configuring Oracle Instant Client if needed CCMS Web Interface Administrative Web Interface Logging In Entering the System Password Configuring Database Settings Configuring CA Settings Configuring Storefront Settings Configuring Request Generation Settings Adding Authorized Administrators Releasing Keys ( key release permission required) Revoking Keys ( key revoke permission required) Recovering Keys ( key recover permission required) Storefront Submitting Key Retrieval Requests Downloading Credentials Appendix A Red Hat Certificate System Profile Validity Period Subject Alternative Name Certificate Policies Extended Key Usage Subject Directory Attributes

4 1 Installation and Configuration 1.1 System Requirements The following components are required to run CCMS on your 64-bit Linux system: memory: 1 GB RAM (minimum) 64-bit Java Development Kit (JDK) or Java Runtime Environment (JRE) 1.6 or above a suitable Java servlet container such as Apache Tomcat or Oracle WebLogic; see vendor s documentation for additional system requirements a suitable database such as Oracle, MySQL, or HyperSQL, and its JDBC driver CertAgent or above, or Red Hat Certificate System 8.0 or above 1.2 Configuring Database The current release of CCMS uses an auxiliary Oracle, MySQL, or HyperSQL database for the storage of its user and escrow agent credentials, auditor and RA access control lists, and audit trails. Consequently, a compatible JDBC driver or Instant Client must be separately licensed by the customer and installed on the CCMS host; they are not included in the standard CCMS software distribution package Oracle Using the Oracle JDBC Thin Driver If you are planning to use the JDBC thin driver to connect to your Oracle database and do not already have it installed, it may be freely downloaded from the Oracle website: To install: 1. Select the appropriate database version. 2. Choose the appropriate ojdbc6.jar file and save it to a file Using the Oracle JDBC OCI Driver If you are planning to use the JDBC-OCI driver to connect to your Oracle database and do not already have the Instant Client installed, it may be freely downloaded from Oracle: To install: 4

5 3. Select the appropriate 64-bit Instant Client for your CCMS host platform. 4. Download the latest Instant Client Package Basic package. 5. Unzip the package into an appropriate directory (e.g., /usr). A directory named Instantclient_<version> will be created. The JDBC driver ojdbc6.jar is located in this directory Creating Database User Database user is required to have its own database schema to store CCMS tables. Use the following command to create a new user for CCMS. SQL> create user ccmsuser identified by password; SQL> grant dba to ccmsuser; Using JDBC URL To configure the CCMS host to use the thin driver for database access, specify a database URI of the following form: jdbc:oracle:thin:@//<host>:<port>/<service name> If your database supports OCI, a SQL*Net configuration file may be used to define the addresses of database connections. Below is a sample tnsnames.ora file that must be located in the <ORACLE_HOME>/network/admin directory. RACDB = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = cl6cluster-scan)(port = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = racdb.infoseccorp.com) (FAILOVER_MODE =(TYPE=select)(METHOD=basic)) ) ) When configuring the database connection on the CCMS administrative site, specify jdbc:oracle:oci:@racdb in the URL field. Alternatively, include the above configuration in the URL: jdbc:oracle:oci:@(description=(address=(protocol=tcp) (HOST=cl6cluster-scan)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED) (SERVICE_NAME=racdb.infoseccorp.com)(FAILOVER_MODE=(TYPE=select) (METHOD=basic)))) 5

6 1.2.2 MySQL Downloading the JDBC Driver (Connector/J) If you do not already have the MySQL JDBC driver installed, it may be freely downloaded from MySQL: To install: 1. Select Platform Independent from the drop-down list. 2. Download the TAR Archive. 3. Unzip the package into an appropriate directory (e.g., /usr). A directory named mysql-connector-java-_<version> will be created. The JDBC driver mysqlconnector-java-<version>-bin.jar is located in this directory Creating Database User Database user is required to have its own database to store CCMS tables. Use the following command to create a new user and a database for CCMS. mysql> create user 'ccmsuser' identified by 'password'; mysql> create database ccmsdb; mysql> grant all on ccmsdb.* to ccmsuser; HyperSQL Downloading the JDBC Driver If you do not already have the HyperSQL JDBC driver installed, it may be freely downloaded from sourceforge.net: To install: 1. Download the latest version. 2. Unzip the package into an appropriate directory (e.g., /usr). A directory named hsqldb-_<version> will be created. The JDBC driver hsqldb.jar is located in the lib directory. 6

7 Creating Database User Database user is required to have its own database schema to store CCMS tables. Use the following command to create a new user for CCMS. Note: the schema name must be exactly the same as the user name. SA> create user "ccmsuser" password "password" admin; SA> create schema ccmsuser authorization "ccmsuser"; SA> alter user "ccmsuser set initial schema ccmsuser; 7

8 1.3 Installing CCMS In this document <ccms home> always refers to the CCMS root installation directory (/usr/ccms3). To install a fresh installation of CCMS: 1. Unpack ccms lnx.x64.tar.gz into any convenient directory on your system. 2. Go to the ccms-install directory and run install.sh to start the installation of CCMS and (optionally) Apache Tomcat. 3. Follow the on screen instructions to install CCMS into the <ccms home> directory. The installation script will generate all required credentials and configure your CCMS system. Be sure to make a note of the system password (<ccms sys pass>), SSL password (<ccms ssl pass>), admin site access port (<admin port>), and storefront access port (<storefront port>) you enter during installation. 4. Import into your browser s certificate store the newly generated administrator credentials <ccms home>/keystore/ccms-admin.p12 using the password <ccms sys pass> that you supplied to the installation script. 5. Once the installation has completed, the ccms-install directory may be deleted. 1.4 Starting/Stopping CCMS CCMS is installed in Apache Tomcat. Apache Tomcat is installed as a service which starts automatically on system boot. To start or stop CCMS manually, run the following command: /usr/ccms3/tomcat.sh [start stop] 1.5 Configuring Oracle Instant Client if needed To configure CCMS to use Oracle Instant Client: 1. Insert the highlighted text below into <ccms home>/tomcat.sh: 8

9 <...> ORACLE_HOME=/usr/instantclient_11_2; export ORACLE_HOME LD_LIBRARY_PATH=$CCMS_HOME/bin:$ORACLE_HOME:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH <...> 2. Restart the Tomcat service. 9

10 2 CCMS Web Interface 2.1 Administrative Web Interface CCMS s web-based administrative interface may be accessed by authorized administrators. An initial administrator certificate (<ccms home>/keystore/ccms-admin.der) is automatically added to the administrator ACL with admin permission during installation. Administrators with admin permission can: install and configure system settings manage system, key escrow, and signing credentials enter the system password manage ACLs Logging In To log in to the administrative interface: 3. Launch your browser and enter the following URL: port>/ccms/main.jsp 4. Select the certificate CN=CCMS Administrator, O=<organization>, C=US and click OK. 5. You should now be logged in to the administrative site Entering the System Password To enter the system password: 1. Select SystemPassword from the main menu. 2. Enter the system password (<ccms sys pass>) and click Submit Configuring Database Settings CCMS requires an Oracle, MySQL, or HyperSQL database in which to store user credentials, auditor and RA access control lists, audit trails and escrow agent credentials. An appropriate JDBC driver is required but is not included in the CCMS distribution and must be licensed separately. If you do not already have these items installed, see the section Configuring Database for information on how to proceed. 10

11 To specify the database settings: 1. Select Configuration Database from the main navigation bar, then click the icon. 2. Choose the database vendor from Oracle, MySQL, and HSQLDB. 3. Enter the database access settings. Depending on your configuration, use one of the following URL formats: Oracle database connection URL if using Thin driver: Syntax: (Note: On this syntax SERVICE may be an oracle service name or a SID) e.g.: jdbc:oracle:thin:@// :1521/ccmsdb For details, see MySQL database connection URL: Syntax: jdbc:mysql://[host][:port]/[database] e.g.: jdbc:mysql:// :3306/ccmsdb For details, see HSQLDB network server database connection URL: Syntax: jdbc:hsqldb:hsql://host[:port][/<alias>] e.g.: jdbc:hsqldb:hsql://localhost:9001/ccmsdb For details, see 4. Change the connection pool setting if needed. CCMS uses a connection pool for database communications. By default, five connections are created upon pool initialization and a maximum of twenty connections can be cached. A connection timeout value of 20 seconds is set to allow CCMS to wait for an available connection in the pool before terminating a request. A connection in the pool is automatically closed once it has been idle for seven hours. 5. Click Test to test the configuration. 6. Click Update to save your changes and the CCMS tables will be created after updating. 11

12 2.1.4 Configuring CA Settings CCMS uses CertAgent or Red Hat Certificate System to issue and revoke user certificates by POSTing requests to the Management Interface over a TLS-secured connection with client authentication Using Red Hat Certificate System Before configuring TLS connections, you must ensure the following: the client has its own credentials (certificate and private key in a local PKCS #12 or Java keystore file) as well as the trust anchor for path validation of the CA instance s TLS certificate the Java trust keystore of the CA instance contains the trust anchor for path validation of the client certificate the CA instance is properly configured and operational and the client has been added to the Certificate Manager Agents and Subsystem Group groups using pkiconsole To configure CCMS to use Red Hat Certificate System: 1. Select Configuration CA from the main navigation bar. 2. Click the icon in the CA Instance section: a. Select Red Hat Certificate System from the CA Vendor drop-down. b. Specify the Host, Secure EE port for enrollment, Secure Agent Port for revocation, and CA certificate chain in PKCS7 format. NOTE: Secure ports are located in the file /var/lib/<instance name>/conf/server.xml. The CA certificate chain can be obtained using the Red Hat Certificate Manager ( EE port>/ca/ee/ca/), Retrieval tab, Import CA Certificate Chain option. c. Click Update. 3. Click the icon in the Client Keystore section: a. Select PKCS12 or JKS from the Type drop-down. b. Click Browse to select the file containing CA s RA credentials. c. Enter the password. d. Click Update. 4. Click the icon in the Trust Anchor section: a. Click Browse to select the root certificate for path validation of CA s TLS certificate. b. Click Update. 12

13 Using CertAgent Before configuring RAMI TLS connections, you must ensure the following: the client has its own credentials (certificate and private key in a local PKCS #12 or Java keystore file) as well as the trust anchor for path validation of the CertAgent TLS certificate the CertAgent Java trust keystore contains the trust anchor for path validation of the client certificate and the client certificate has been added to the ACL for the appropriate CA account with RAMI permission. the CertAgent system is properly configured and operational. Be sure to follow all sections in the CertAgent Quick Start Guide. In addition, be sure to enable RAMI enrollment for the selected Certificate Authorities (this is done by logging in to the CA account, selecting Enrollment, clicking on the RAMI tab, and checking all appropriate options). To configure CCMS to use CertAgent: 1. Select Configuration CA from the main navigation bar. 2. Click the icon in the CA Instance section: a. Select CertAgent from the CA Vendor drop-down. b. Specify the CertAgent host (<ca host>) and admin access port (<ca admin port>). c. Click Update. 3. Click the icon in the Client Keystore section: a. Select PKCS12 from the Type drop-down. b. Click Browse to select the PKCS#12 file containing the CertAgent RA credentials (e.g., <ca home>/keystore/ca-admin.p12). d. Select PKCS12 from the Type drop-down. e. Enter the password (<ca key pass>). f. Click Update. 4. Click the icon in the Trust Anchor section. a. Click Browse to select the root certificate for path validation of CertAgent s TLS certificate (e.g., <ca home>/keystore/ca-root.der). b. Click Update. 13

14 2.1.5 Configuring Storefront Settings CCMS supports user certificate enrollment and retrieval requests via a storefront site. If a request is approved, CCMS will generate a key pair and certificate request for the user and then submit the request to the specified CA account(s). CCMS will then send notification to the user to download the credentials. To configure storefront settings: 1. Select ConfigurationStorefront from the main menu. 2. Click the icon in the CA Profiles section. a. Specify a CA account or profile name that CCMS will submit certificate requests to. b. Click Update. 3. Click the icon in the section. a. Specify the server configuration. b. Click Update. 4. If needed, change the Download Links, User Authentication, and Customize s options Configuring Request Generation Settings When generating a certificate request, a subject DN must be specified. Optionally, the validity period and other extensions can also be specified. A default set of these values can be defined so they are populated with a user s attributes retrieved from an LDAP repository. To configure the default certificate request generation settings: 1. Select ConfigurationStorefront from the main menu. 2. Click the icon in the LDAP settings section. a. Fill in the LDAP configuration information. b. Select the search filter (either user ID or address) and specify the filter attribute to locate the user s entry from LDAP. c. Specify the attribute and common name attribute. d. Click Update. 3. Click the icon in the Subject DN section. a. Specify the default subject DN. Example: CN=$CN, O=$O, OU=$OU.1, OU=$OU.2, EM=$ , C=US 14

15 b. Click Update. 4. If needed, specify mapping rules for extensions by clicking the associated icon. For details on attribute mapping rules, see below Attribute Mapping Rule DN Syntax: mappedrule := rdnpattern *[, rdnpattern ] rdnpattern := attrname = attrvalue attrname := CN UID DC O OU C L ST attrvalue := $attrname[. number] value Example: If the mapped subject DN rule is: CN=$CN, OU=$OU.1, OU=$OU.2, DC=infoseccorp, DC=com And the User s LDAP Entry is: user1@infoseccorp.com cn: User 1 ou: HR ou: People The mapped DN will be: CN=User 1, OU=HR, OU=People, DC=infoseccorp, DC=com CN=the (first) cn value in the CN attribute OU=the (first) ou value in the OU attribute OU=the (second) ou value in the OU attribute DC=the string infoseccorp DC=the string com Note: If a specified attrvalue does not exist in a user s entry, the $attrname will remain in the subject DN and a warning message will be returned in the key release page Extensions Syntax: extmappedrule := $attrname[. number] value attrname := value Example: Subject Alternative Name: RFC822 Name: $ Subject Directory Attribute: Employee Type (RFC2798): $employeetype 15

16 2.1.7 Adding Authorized Administrators An initial CCMS administrator certificate is added to the ACL with admin permission. Other permissions are defined to allow different administrators to perform different tasks. The following table describes the various administrative permissions and their responsibilities: Permission admin audit key release key revoke key recover via CMP via MIAPI Description manage system configuration, manage system, key escrow, and signing credentials, enter system password, and manage ACLs view and export audit trials approve or reject user certificate requests revoke user certificates recover user credentials submit CMP requests submit credentials management requests via MIAPI To add authorized administrators: 1. Select SystemACL from the main menu. 2. Click Add. 3. Then upload the certificate by clicking Browse, locating the appropriate X.509 or PKCS#7 certificate file, choosing the desired permissions, and clicking Upload. Note: when you manage credentials via storefront by following section , you can search the existing user credentials by searching the user ID, address, or common name. When entering the search string, you can search for an exact match of your search string, place one or two asterisks in your search string to get results that match a fuzzy string searching, or enter an asterisk to display all results Releasing Keys ( key release permission required) To process key requests: 1. Select Key ManagementRelease from the main menu. 16

17 2. Select from dropdown list, searching by user ID, address, or common name, enter your search string, and click Go. 3. Depending on whether you want to reject or release keys for the request continue to section or as appropriate Rejecting Requests 1. Select Reject and optionally enter a comment. 2. Click Submit. The request will be rejected and a notification will be sent to the user Releasing Credentials 1. Select Release Credentials. 2. Select Generate new credentials and/or Include existing credentials. 3. Click Submit. The result message will be displayed. If the credentials were successfully released, a notification will be sent to the user containing a download link Revoking Keys ( key revoke permission required) To revoke keys: 1. Select Key ManagementRevoke from the main menu. 2. Select from dropdown list, searching by user ID, address, or common name, enter your search string, and click Go. 3. Check the desired certificate(s) to be revoked and select a reason code from the drop-down. 4. Click Apply Recovering Keys ( key recover permission required) Key recovery requires two administrators with the key recover permission. First, Administrator A initiates the request. Next, Administrator B approves the request. Finally, Administrator A receives a download link to retrieve the user credentials. To initiate recovery requests (logged in as Administrator A): 17

18 1. Select Key ManagementRecover from the main menu. 2. Select from dropdown list, searching by user ID, address, or common name, enter your search string, and click Go. 3. Check the Initiate box(es) for the credentials to be recovered. 4. Enter your address if it is not present in the certificate used for client authentication. 5. Click Apply. To approve recovery requests (logged in as Administrator B): 1. Select Key ManagementRecover from the main menu. 2. Select from dropdown list, searching by user ID, address, or common name, enter your search string, and click Go. 3. Select one or more Release To options for the credentials to be recovered. 4. Click Apply. The download link will be sent to the administrator who initiated the request. 2.2 Storefront Submitting Key Retrieval Requests To submit a key retrieval request, an end user should: 1. Launch your browser and enter the following URL: port>/ccms/user 2. Enter your address or your user ID and optionally enter a comment. 3. Click Submit. 4. A result message will be displayed. If you do not currently have any keys available for retrieval, you need to contact a CCMS officer to process your request. Otherwise, a download link will be sent via Downloading Credentials After the key release request is approved, the user will receive a notification with a download link. Click the download link to access the download page. The user will be authenticated by either IP address 18

19 or an authentication code. Enter the authentication code if prompted. If authenticated, a list of available credentials and their statuses will be displayed. Click the download icon for the associated credentials to download the credentials as a PKCS#12 file. 19

20 Appendix A Red Hat Certificate System Profile To support customized validity periods and certificate extensions when using Red Hat Certificate System enrollment, the following sessions need to be included in the Profile. The name examplecertset and the numbers are only for example, and should be adjusted to fit into the actual profile being used. Validity Period policyset.examplecertset.10.constraint.class_id=noconstraintimpl policyset.examplecertset.10.constraint.name=no Constraint policyset.examplecertset.10.default.class_id=uservaliditydefaultimpl policyset.examplecertset.10.default.name=user Validity Default If the profile has a default validity period session (class_id=validitydefaultimpl), put the above user validity session after the default validity session. Then the user validity will be applied only if it is provided, otherwise the default validity will be used. Subject Alternative Name policyset.examplecertset.11.constraint.class_id=noconstraintimpl policyset.examplecertset.11.constraint.name=no Constraint policyset.examplecertset.11.default.class_id=userextensiondefaultimpl policyset.examplecertset.11.default.name=user Extension Default SAN policyset.examplecertset.11.default.params.userextoid= Certificate Policies policyset.examplecertset.12.constraint.class_id=noconstraintimpl policyset.examplecertset.12.constraint.name=no Constraint policyset.examplecertset.12.default.class_id=userextensiondefaultimpl policyset.examplecertset.12.default.name=user Extension Default CP policyset.examplecertset.12.default.params.userextoid= Extended Key Usage policyset.examplecertset.13.constraint.class_id=noconstraintimpl policyset.examplecertset.13.constraint.name=no Constraint policyset.examplecertset.13.default.class_id=userextensiondefaultimpl policyset.examplecertset.13.default.name=user Extension Default EKU policyset.examplecertset.13.default.params.userextoid=

21 Subject Directory Attributes policyset.examplecertset.14.constraint.class_id=noconstraintimpl policyset.examplecertset.14.constraint.name=no Constraint policyset.examplecertset.14.default.class_id=userextensiondefaultimpl policyset.examplecertset.14.default.name=user Extension Default SDA policyset.examplecertset.14.default.params.userextoid=