Red Hat CERTIFICATE SYSTEM 8 - DEPLOYMENT User manual

Red Hat Certificate
System 8
Command-Line Tools Guide
Ella Deon Lackey
Publication date: July 22, 2009, updated on March 25, 2010

Command-Line Tools Guide
Red Hat Certificate System 8 Command-Line Tools Guide
Author Ella Deon Lackey
Copyright © 2009 Red Hat, Inc.
Copyright © 2009 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity
Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
All other trademarks are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park, NC 27709 USA
This book covers important, Certificate System-specific, command-line tools that you can use to
create, remove, and manage subsystem instances and to create and manage keys and certificates.

iii
About This Guide vii
1. Required Concepts ........................................................................................................ vii
2. What Is in This Guide .................................................................................................... vii
3. Common Tool Information ............................................................................................... ix
4. Examples and Formatting ............................................................................................... ix
4.1. Formatting for Examples and Commands .............................................................. ix
4.2. Tool Locations ..................................................................................................... ix
4.3. Guide Formatting ................................................................................................. ix
5. Additional Reading .......................................................................................................... x
6. Giving Feedback ............................................................................................................ xi
7. Document History .......................................................................................................... xii
1. Create and Remove Instance Tools 1
1.1. pkicreate ...................................................................................................................... 1
1.1.1. Syntax .............................................................................................................. 1
1.1.2. Usage ............................................................................................................... 2
1.2. pkisilent ....................................................................................................................... 3
1.2.1. Syntax .............................................................................................................. 4
1.2.2. Usage ............................................................................................................... 7
1.3. pkiremove .................................................................................................................. 10
1.3.1. Syntax ............................................................................................................. 10
1.3.2. Usage ............................................................................................................. 10
2. TokenInfo 11
2.1. Syntax ....................................................................................................................... 11
3. SSLGet 13
3.1. Syntax ....................................................................................................................... 13
3.2. Usage ........................................................................................................................ 13
4. AuditVerify 15
4.1. About the AuditVerify Tool ........................................................................................... 15
4.2. Setting up the Auditor's Database ............................................................................... 15
4.3. Syntax ....................................................................................................................... 15
4.4. Return Values ............................................................................................................ 16
4.5. Usage ........................................................................................................................ 16
5. PIN Generator 17
5.1. The setpin Command ................................................................................................. 17
5.1.1. Editing the setpin.conf Configuration File ........................................................... 17
5.1.2. Syntax ............................................................................................................. 18
5.1.3. Usage ............................................................................................................. 19
5.2. How setpin Works ...................................................................................................... 19
5.2.1. Input File ......................................................................................................... 21
5.2.2. Output File ...................................................................................................... 22
5.2.3. How PINs Are Stored in the Directory ............................................................... 22
5.2.4. Exit Codes ...................................................................................................... 23
6. ASCII to Binary 25
6.1. Syntax ....................................................................................................................... 25
6.2. Usage ........................................................................................................................ 25
7. Binary to ASCII 27
7.1. Syntax ....................................................................................................................... 27
7.2. Usage ........................................................................................................................ 27

Command-Line Tools Guide
iv
8. Pretty Print Certificate 29
8.1. Syntax ....................................................................................................................... 29
8.2. Usage ........................................................................................................................ 29
9. Pretty Print CRL 31
9.1. Syntax ....................................................................................................................... 31
9.2. Usage ........................................................................................................................ 31
10. TKS Tool 33
10.1. Syntax ..................................................................................................................... 33
10.2. Usage ...................................................................................................................... 35
11. CMC Request 39
11.1. Syntax ...................................................................................................................... 39
11.2. Usage ...................................................................................................................... 41
12. CMC Enrollment 43
12.1. Syntax ..................................................................................................................... 43
12.2. Usage ...................................................................................................................... 43
13. CMC Response 45
13.1. Syntax ..................................................................................................................... 45
14. CMC Revocation 47
14.1. Syntax ..................................................................................................................... 47
14.2. Testing CMC Revocation ........................................................................................... 47
15. CRMF Pop Request 49
15.1. Syntax ..................................................................................................................... 49
15.2. Usage ...................................................................................................................... 50
16. Extension Joiner 51
16.1. Syntax ..................................................................................................................... 51
16.2. Usage ...................................................................................................................... 51
17. Key Usage Extension 53
17.1. Syntax ..................................................................................................................... 53
18. Issuer Alternative Name Extension 55
18.1. Syntax ..................................................................................................................... 55
18.2. Usage ...................................................................................................................... 56
19. Subject Alternative Name Extension 57
19.1. Syntax ..................................................................................................................... 57
19.2. Usage ...................................................................................................................... 58
20. HTTP Client 59
20.1. Syntax ..................................................................................................................... 59
21. OCSP Client Tool 61
21.1. Syntax ..................................................................................................................... 61
22. PKCS #10 Client 63
22.1. Syntax ..................................................................................................................... 63
23. Bulk Issuance Tool 65
23.1. Syntax ..................................................................................................................... 65
24. Revocation Automation Utility 67
24.1. Syntax ..................................................................................................................... 67

v
25. tpsclient 69
25.1. Syntax ..................................................................................................................... 71
Index 73

vi

vii
About This Guide
The Certificate System Command-Line Tools Guide describes the command-line tools and utilities
bundled with Red Hat Certificate System and provides information such as command syntax and
usage examples to help use these tools.
This guide is intended for experienced system administrators who are planning to deploy the
Certificate System. Certificate System agents should use the Certificate System Agent's Guide
for information on how to perform agent tasks, such as handling certificate requests and revoking
certificates.
1. Required Concepts
This guide assumes familiarity with the following concepts:
• Public-key cryptography and the Secure Sockets Layer (SSL) protocol
• SSL cipher suites
• The purpose of and major steps in the SSL handshake
• Intranet, extranet, Internet security, and the role of digital certificates in a secure enterprise,
including the following topics:
• Encryption and decryption
• Public keys, private keys, and symmetric keys
• Significance of key lengths
• Digital signatures
• Digital certificates
• The role of digital certificates in a public-key infrastructure (PKI)
• Certificate hierarchies
2. What Is in This Guide
This guide contains the following topics:
Chapter 1, Create and Remove Instance Tools Describes the tools used to create and remove
subsystem instances.
Section 1.2, “pkisilent” Describes the tool used for a silent instance
creation.
Chapter 2, TokenInfo Describes the utility which can be used to identify
tokens on a machine, which shows whether the
Certificate System can detect those tokens to
use for a subsystem.
Chapter 3, SSLGet Describes a tool used by the Certificate System
to help configure and use security domains.
Chapter 4, AuditVerify Describes how to use the tool used to verify
signed audit logs.

About This Guide
viii
Chapter 5, PIN Generator Describes how to use the tool for generating
unique PINs for end users and for populating
their directory entries with PINs.
Chapter 6, ASCII to Binary Describes how to use the tool for converting
ASCII data to its binary equivalent.
Chapter 7, Binary to ASCII Describes how to use the tool for converting
binary data to its ASCII equivalent.
Chapter 8, Pretty Print Certificate Describes how to use the tool for printing or
viewing the contents of a certificate stored
as ASCII base-64 encoded data in a human-
readable form.
Chapter 9, Pretty Print CRL Describes how to use the tool for printing or
viewing the contents of a CRL stored as ASCII
base-64 encoded data in a human-readable
form.
Chapter 10, TKS Tool Describes how to manipulate symmetric keys,
including keys stored on tokens, the TKS master
key, and related keys and databases.
Chapter 11, CMC Request Describes how to construct a Certificate
Management Messages over Cryptographic
Message Syntax (CMC) request.
Chapter 12, CMC Enrollment Describes how to sign a CMC certificate
enrollment request with an agent's certificate.
Chapter 13, CMC Response Describes how to parse a CMC response.
Chapter 14, CMC Revocation Describes how to sign a CMC revocation request
with an agent's certificate.
Chapter 15, CRMF Pop Request Describes how to generate Certificate Request
Message Format (CRMF) requests with proof of
possession (POP).
Chapter 16, Extension Joiner Describes how to use the tool for joining
MIME-64 encoded formats of certificate
extensions to create a single blob.
Chapter 17, Key Usage Extension Describes how to generate a distinguished
encoding rules (DER)-encoded Extended Key
Usage extension.
Chapter 18, Issuer Alternative Name Extension Describes how to generate an Issuer Alternative
Name extension in base-64 encoding.
Chapter 19, Subject Alternative Name Extension Describes how to generate a Subject Alternative
Name extension in base-64 encoding.
Chapter 20, HTTP Client Describes how to communicate with any HTTP/
HTTPS server.
Chapter 21, OCSP Client Tool Describes how to verify certificate status by
submitting Online Certificate Status Protocol
(OCSP) requests to an instance of an OCSP
subsystem.

Common Tool Information
ix
Chapter 22, PKCS #10 Client Describes how to generate a Public-Key
Cryptography Standards (PKCS) #10 enrollment
request.
Chapter 23, Bulk Issuance Tool Describes how to send either a KEYGEN or
CRMF enrollment request to the bulk issuance
interface to create certificates automatically.
Chapter 24, Revocation Automation Utility Describes how to automate user management
scripts to revoke certificates.
Chapter 25, tpsclient Describes how to test the TPS configuration and
common operations.
Table 1. List of Contents
3. Common Tool Information
All of the tools in this guide are located in the /usr/bin directory, except for the Silent Install tool,
which is downloaded separately and installed to any directory. These tools can be run from any
location without specifying the tool location.
4. Examples and Formatting
4.1. Formatting for Examples and Commands
All of the examples for Red Hat Certificate System commands, file locations, and other usage are
given for Red Hat Enterprise Linux 5 (32 bit) systems. Be certain to use the appropriate commands
and files for your platform.
To start the Red Hat Certificate System:
service pki-ca start
Example 1. Example Command
4.2. Tool Locations
All of the tools for Red Hat Certificate System are located in the /usr/bin directory. These tools can
be run from any location without specifying the tool location.
4.3. Guide Formatting
Certain words are represented in different fonts, styles, and weights. Different character formatting is
used to indicate the function or purpose of the phrase being highlighted.
Formatting Style Purpose
Monospace font Monospace is used for commands, package names, files and
directory paths, and any text displayed in a prompt.
Monospace
with a
background
This type of formatting is used for anything entered or returned
in a command prompt.

About This Guide
x
Formatting Style Purpose
Italicized text Any text which is italicized is a variable, such as
instance_name or hostname. Occasionally, this is also used to
emphasize a new term or other phrase.
Bolded text Most phrases which are in bold are application names, such as
Cygwin, or are fields or options in a user interface, such as a
User Name Here: field or Save button.
Other formatting styles draw attention to important text.
NOTE
A note provides additional information that can help illustrate the behavior of the system or
provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration
change that will not persist after a reboot.
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for
maximum performance.
5. Additional Reading
The documentation for Certificate System includes the following guides:
•Certificate System Deployment Guide1 describes basic PKI concepts and gives an overview of the
planning process for setting up Certificate System.
This manual is intended for Certificate System administrators.
•Certificate System Installation Guide2 covers the installation process for all Certificate System
subsystems.
This manual is intended for Certificate System administrators.
•Certificate System Administrator's Guide3 explains all administrative functions for the Certificate
System. Administrators maintain the subsystems themselves, so this manual details backend
configuration for certificate profiles, publishing, and issuing certificates and CRLs. It also covers
managing subsystem settings like port numbers, users, and subsystem certificates.
This manual is intended for Certificate System administrators.
•Certificate System Agent's Guide4 describes how agents — users responsible for processing
certificate requests and managing other aspects of certificate management — can use the
Certificate System subsystems web services pages to process certificate requests, key recovery,
OCSP requests and CRLs, and other functions.

Giving Feedback
xi
This manual is intended for Certificate System agents.
•Managing Smart Cards with the Enterprise Security Client5 explains how to install, configure,
and use the Enterprise Security Client, the user client application for managing smart cards, user
certificates, and user keys.
This manual is intended for Certificate System administrators, agents, privileged users (such as
security officers), and regular end users.
•Using End User Services6 is a quick overview of the end-user services in Certificate System, a
simple way for users to learn how to access Certificate System services.
This manual is intended for regular end users.
•Certificate System Command-Line Tools Guide7 covers the command-line scripts supplied with Red
Hat Certificate System.
This manual is intended for Certificate System administrators.
•Certificate System Migration Guide8 covers version-specific procedures for migrating from older
versions of Certificate System to Red Hat Certificate System 8.0.
This manual is intended for Certificate System administrators.
•Release Notes9 contains important information on new features, fixed bugs, known issues and
workarounds, and other important deployment information for Red Hat Certificate System 8.0.
All of the latest information about Red Hat Certificate System and both current and archived
documentation is available at http://www.redhat.com/docs/manuals/cert-system/.
6. Giving Feedback
If there is any error in this Command-Line Tools Guide or there is any way to improve the
documentation, please let us know. Bugs can be filed against the documentation for Red Hat
Certificate System through Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as
specific as possible, so we can be more effective in correcting any issues:
• Select the Red Hat Certificate System product.
• Set the component to Doc - cli-tools-guide.
• Set the version number to 8.0.
• For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct
description of the problem, such as incorrect procedure or typo.
For enhancements, put in what information needs to be added and why.
• Give a clear title for the bug. For example, "Incorrect command example for setup
script options" is better than "Bad example".
We appreciate receiving any feedback — requests for new sections, corrections, improvements,
enhancements, even new ways of delivering the documentation or new styles of docs. You are
welcome to contact Red Hat Content Services directly at [email protected].

About This Guide
xii
7. Document History
Revision 8.0.5 March 25, 2010 Ella Deon Lackey [email protected]
Adding information on new end-entities client authentication port for the CA, related to the MitM
resolution in Errata RHBA-2010:0170.
Revision 8.0.4 February 18, 2009 Ella Deon Lackey [email protected]
Reverting AuditVerify setup, per Bugzilla 533526.
Correcting the cs_port definition, per Bugzilla 533303.
Revision 8.0.3 August 28, 2009 Ella Deon Lackey
Removing draft mark, since the tech reviews are complete.
Tech edits to the setup procedure for the auditor's database as part of the tech reviews, per Bugzilla
#510590.
Revision 8.0.2 August 1, 2009 Ella Deon Lackey
Tech edits to chapters 17 through 26 (extension joiner through tpslcient), per Bugzilla #510593.
Revision 8.0.1 July 26, 2009 Ella Deon Lackey
Edits to the pkicreate, pkiremove, and pkisilent sections for technical reviews, related to Bugzilla
#510588 and Bugzilla #512746.
Revision 8.0.0 July 22, 2009 Ella Deon Lackey
Initial draft for Certificate System 8.0 Command-Line Tools Guide.

Chapter 1.
1
Create and Remove Instance Tools
The Certificate System includes three tools to create, configure, and remove subsystem instances:
pkicreate, pkisilent, and pkiremove.
NOTE
The pkicreate tool does not install the Certificate System system; this is done through
installing the packages or running the Red Hat Enterprise Linux yum command. This tool
creates new instances after the default subsystems have been installed.
Likewise, the pkiremove utility does not uninstall the Certificate System subsystem
packages; it removes a single subsystem instance.
1.1. pkicreate
The pkicreate tool creates instances of Certificate System subsystems and does a minimal
configuration of the new instance, such as setting the configuration directory and port numbers.
Further configuration is done through the HTML configuration pages.
1.1.1. Syntax
The pkicreate command has slightly different syntax depending on the type of subsystem being
created because of port differences between the subsystem types. For a CA, OCSP, DRM, or TKS, the
tool has the following syntax:
pkicreate -pki_instance_root=/directory/path -subsystem_type=type -pki-
instance_name=instance_ID [[ -secure_port=SSLport ] | [ -agent_secure_port=SSLport
-ee_secure_port=SSLport -ee_secure_client_auth_port=SSLport_CA_only -
admin_secure_port=SSLport ]] -unsecure_port=port -tomcat_server_port=port [ -
user=user_name ] [ -group=group_name ] [ -redirect_conf=conf_directory ] [ -
redirect_logs=log_directory ] [ -verbose ] [ -help ]
For an RA or TPS, the tool has the following syntax:
pkicreate -pki_instance_root=/directory/path -subsystem_type=type -pki-
instance_name=instance_ID -secure_port=SSLport -non_clientauth_secure_port=SSLport
-unsecure_port=port [ -user=user_name ] [ -group=group_name ] [ -
redirect_conf=conf_directory ] [ -redirect_logs=log_directory ] [ -verbose ] [ -help ]
NOTE
The pkicreate tool also accepts an environment variable, DONT_RUN_PKICREATE;
if this is set, the pkicreate utility is prevented from doing anything. When the
DONT_RUN_PKICREATE variable is set before installing the subsystem packages, to allow
the first instance to be installed in a user-defined location instead of the default location.
Parameter Description
pki_instance_root Gives the full path to the new instance configuration directory.

Chapter 1. Create and Remove Instance Tools
2
Parameter Description
subsystem_type Gives the type of subsystem being created. The possible values are as follows:
•ca, for a Certificate Authority
•ra, for a Registration Authority
•kra, for a DRM
•ocsp, for an OCSP
•tks, for a TKS
•tps, for a TPS
pki_instance_name Gives the name of the new instance. Instance names must be unique on a single machine, but do not have to be unique within the
security domain (since instances are identified by hostname and port, not instance name).
secure_port Sets a single SSL port number for the subsystem. This parameter is required if port separation is not configured, meaning that
separate ports are not assigned for the administrator, agent, and end-entities services.
agent_secure_port Sets the SSL port for the agent web services. If this is specified, then both ee_secure_port and admin_secure_port must be
specified. For CAs only, an end-entities client authentication port is also required with the ee_secure_client_auth_port option.
ee_secure_port Sets the SSL port for the end-entities web services. If this is specified, then both agent_secure_port and admin_secure_port
must be specified. For CAs only, an end-entities client authentication port is also required with the ee_secure_client_auth_port
option.
ee_secure_client_auth_port For CAs only. Sets the SSL port for the end-entity client authentication. If this is specified, then ee_secure_port,
agent_secure_port, and admin_secure_port must be specified.
admin_secure_port Sets the SSL port number for the administrator services, usually the pkiconsole. If this is specified, then both
agent_secure_port and ee_secure_port must be specified. For CAs only, an end-entities client authentication port is also
required with the ee_secure_client_auth_port option.
non_clientauth_secure_port Sets the end entities SSL port for RA and TPS subsystems.
unsecure_port Sets the regular port number. If this is not set, the number is randomly generated. Still, it is recommended that administrators set this
value to make sure there are no conflicts with SELinux labels for other services.
tomcat_server_port Sets the port number for the Tomcat web server. This option must be set for CA, OCSP, TKS, and DRM instances.
tomcat_server_port is not used when creating a TPS or RA instance since those subsystems do not use a Tomcat web server.
redirect_conf Optional. Sets the location for the configuration files for the new instance.
redirect_logs Optional. Sets the location for the log files for the new instance.
user Optional. Sets the user as which the Certificate System instance will run. This option must be set.
group Optional. Sets the group as which the Certificate System instance will run. This option must be set.
verbose Optional. Runs the new instance creation in verbose mode.
help Shows the help information.
1.1.2. Usage
In Example 1.1, “pkicreate Usage with a Single SSL Port”, the pkicreate is used to create a new CA
instance running on ports 9080 and 9543, named pki-ca2, in the /var/lib/subsystem_name/
pki-ca2 directory.

pkisilent
3
pkicreate -pki_instance_root=/var/lib -subsystem_type=ca -pki_instance_name=pki-ca2
-secure_port=9543 -unsecure_port=9080 -tomcat_server_port=1802 -user=pkiuser -
group=pkiuser -verbose
Example 1.1. pkicreate Usage with a Single SSL Port
Alternatively, the CA services can run on different ports. Example 1.2, “pkicreate with Port Separation”
creates a CA instance with port separation. The agent port is 9544, the end-entity port is 9543, and
the administrator port is 9545.
pkicreate -pki_instance_root=/var/lib -subsystem_type=ca -pki_instance_name=pki-ca2
-agent_secure_port=9544 -ee_secure_port=9543 -ee_secure_client_auth_port=9546 -
admin_secure_port=9545 -unsecure_port=9080 -tomcat_server_port=1702 -user=pkiuser -
group=pkiuser -verbose
Example 1.2. pkicreate with Port Separation
To keep the pkicreate script from creating a new instance when it is run, set the
DONT_RUN_PKICREATE environment variable to 1.
export DONT_RUN_PKICREATE=1
While not required, it is a good idea to set the directories for the log and configuration files to keep the
proper file structure.
pkicreate -pki_instance_root=/var/lib -subsystem_type=ca -pki_instance_name=pki-ca2
-agent_secure_port=9544 -ee_secure_port=9543 -ee_secure_client_auth_port=9546 -
admin_secure_port=9545 -unsecure_port=9080 -tomcat_server_port=1702 -redirect_conf /var/
lib -redirect_log /var/log -user=pkiuser -group=pkiuser -verbose
Example 1.3. pkicreate with Specified Directory Locations
1.2. pkisilent
The Certificate System includes a tool, pkisilent, which configures an instance through the
command line, without having to access the HTML services pages.
NOTE
While pkicreate and pkiremove are installed with the other Red Hat Certificate
System packages, the pkisilent tool must be downloaded independently. To install it,
run yum install pki-silent.
Run pkisilent on a system which already has a subsystem installed, since this tool depends on
having libraries, JRE, and core jar files already installed.
Two files are installed for the pkisilent tool:
•pkisilent, the Perl wrapper script.
•pkisilent.jar, the jar files containing the Java classes to perform a silent installation.

Chapter 1. Create and Remove Instance Tools
4
The utility can be downloaded and saved to any location and is then executed locally.
1.2.1. Syntax
The pkisilent script can be used to configure a new subsystem instance. This tool has the following
syntax:
pkisilent Configuretype -cs_hostname hostname -cs_port admin_ssl_port -subsystem_name
name -client_certdb_dir certDBdir -client_certdb_pwd password -preop_pin preoppin [ -
domain_name new_domain_name | -sd_hostname domain_CA_hostname -sd_admin_port
admin_port -sd_agent_port agent_port -sd_ssl_port ee_ssl_port -sd_admin_name
username -sd_admin_password password ] -admin_user adminUID -admin_email admin@email
-admin_password password -agent_key_size keySize -agent_key_type keyType -
agent_cert_subject cert_subject_name -ldap_host hostname -ldap_port port -bind_dn
bindDN -bind_password password -base_dn install_base_DN -db_name dbName -key_size
keySize -key_type keyType -token_name HSM_name -token_pwd HSM_password -save_p12
true -backup_pwd password -backup_fname file [[ -ca_subsystem_cert_subject_name
cert_name -ca_ocsp_cert_subject_name cert_name -ca_server_cert_subject_name
cert_name -ca_sign_cert_subject_name cert_name -ca_audit_signing_cert_subject_name
cert_name ] | [ -ra_subsystem_cert_subject_name cert_name -ra_server_cert_subject_name
cert_name -ra_subsystem_cert_nickname nickname -ra_server_cert_nickname nickname ] | [ -
ocsp_subsystem_cert_subject_name cert_name -ocsp_sign_cert_subject_name cert_name -
ocsp_server_cert_subject_name cert_name -ocsp_audit_signing_cert_subject_name cert_name ]
| [ -drm_subsystem_cert_subject_name cert_name -drm_storage_cert_subject_name cert_name
-drm_transport_cert_subject_name cert_name -drm_server_cert_subject_name cert_name
-drm_audit_signing_cert_subject_name cert_name ] | [ -tks_subsystem_cert_subject_name
cert_name -tks_server_cert_subject_name cert_name -tks_audit_signing_cert_subject_name
cert_name ] | [ -tps_subsystem_cert_subject_name cert_name -tps_server_cert_subject_name
cert_name -tps_audit_signing_cert_subject_name cert_name -tps_subsystem_cert_nickname
nickname -tps_server_cert_nickname nickname ]] [[ -external false ] | [ -external
true -ext_csr_file output_cert_request_file -ext_cert_file input_cert_file -
ext_ca_cert_chain_file input_ca_cert_chain ]] [[ -ca_hostname hostname -ca_port
port -ca_ssl_port client_secure_port ] | [ -drm_hostname hostname -drm_ssl_port
secure_port ] | [ -tks_hostname hostname -tks_ssl_port secure_port ]] [ -ldap_auth_host
authentication_directory_hostname -ldap_auth_port authentication_directory_port
-ldap_auth_base_dn search_base ]
It is also possible to configure a clone CA instance using pkisilent. This requires additional
parameters to retrieve the master subsystem's keys.
NOTE
Only a clone CA can be configured using pkisilent. Clone DRMs, OCSPs, or TKSs
must be configured using the HTML-based configuration wizard.
pkisilent ... -clone true -clone_p12_file p12-file -clone_p12_password password
TIP
There are two template files that are shell scripts for silent configuration: /usr/
share/pki/silent/pki_silent.template and /usr/share/pki/silent/

Syntax
5
subca_silent.template. Both of these templates have detailed information on
parameters and usage options for pkisilent.
To check the specific options for any Configuretype option, just run the pkisilent
command with the Configuretype option and the -help flag. For example, to get the
help for configuring a subordinate CA:
pkisilent ConfigureSubCA -help
The Configuretype option sets what kind of subsystem is being configured. This can be any of the
following:
• ConfigureCA (for a root CA) or ConfigureSubCA (for a subordinate CA)
• ConfigureRA
• ConfigureDRM
• ConfigureOCSP
• ConfigureTKS
• ConfigureTPS
Parameter Description
Basic Instance Configuration
cs_hostname The hostname for the Certificate System machine.
cs_port The administrative SSL port number of the Certificate System instance.
subsystem_name Sets the name of the new subsystem instance.
client_certdb_dir The directory for the subsystem certificate databases.
client_certdb_pwd The password to protect the certificate database.
preop_pin The preoperation PIN number used for the initial configuration.
token_name Gives the name of the HSM token used to store the subsystem certificates. This is only required for hardware tokens; if this
parameter is not given, then the script automatically uses the local software token.
token_pwd Gives the password for the HSM.
Agent and Admin User Configuration
admin_user The new admin user for the new subsystem.
admin_email The email address of the admin user.
admin_password The password for the admin user.
agent_key_size The key size to use for generating the agent certificate and key pair.
agent_key_type The key type to use for generating the agent certificate and key pair.
agent_cert_subject The subject name for the agent certificate.
Security Domain Configuration
domain_name The name of the security domain to which the subsystem will be added.
sd_hostname The hostname of the CA which hosts security domain.

Chapter 1. Create and Remove Instance Tools
6
Parameter Description
sd_admin_port The admin SSL port of the CA which hosts security domain.
sd_agent_port The agent SSL port of the CA which hosts security domain.
sd_ssl_port The end-entities SSL port of the CA which hosts security domain.
sd_admin_name The username of the administrative user for the CA hosting the security domain.
sd_admin_password The password of the administrative user for the CA hosting the security domain.
Internal Database Configuration
ldap_host The hostname of the Directory Server machine.
ldap_port The non-SSL port of the Directory Server.
bind_dn The bind DN which will access the Directory Server; this is normally the Directory Manager ID.
bind_password The bind DN password.
base_dn The entry DN under which to create all of the subsystem entries.
db_name The database name.
Subsystem Certificates and Keys Configuration
key_size The size of the key to generate. The recommended size for an RSA key is 1048 bits for regular operations and 2048 bits for sensitive
operations.
key_type The type of key to generate; the only option is RSA.
save_p12 Sets whether to export the keys and certificate information to a backup PKCS #12 file. true backs up the information; false does
not back up the information. Only for the CA subsystem.
backup_pwd The password to protect the PKCS #12 backup file containing the subsystem keys and certificates. Not for use with TPS installation.
backup_fname The file to which to export the the PKCS #12 backup file.
ca_subsystem_cert_subject_name
ca_ocsp_cert_subject_name
ca_server_cert_subject_name
ca_sign_cert_subject_name
ca_audit_signing_cert_subject_name
The subject names for the CA subsystem certificates.
ra_subsystem_cert_subject_name
ra_server_cert_subject_name
ra_subsystem_cert_nickname
ra_server_cert_nickname
The subject names for the RA subsystem certificates.
ocsp_ocsp_cert_subject_name
ocsp_server_cert_subject_name
ocsp_subsystem_cert_subject_name
ocsp_audit_signing_cert_subject_name
The subject names for the OCSP subsystem certificates.
drm_storage_cert_subject_name
drm_transport_cert_subject_name
drm_server_cert_subject_name
drm_subsystem_cert_subject_name
drm_audit_signing_cert_subject_name
The subject names for the DRM subsystem certificates.
tks_subsystem_cert_subject_name
tks_server_cert_subject_name
tks_audit_signing_cert_subject_name
The subject names for the TKS subsystem certificates.
tps_subsystem_cert_subject_nameThe subject names for the TPS subsystem certificates.

Usage
7
Parameter Description
tps_server_cert_subject_name
tps_subsystem_cert_nickname
tps_server_cert_nickname
Required Subsystem Configuration
ca_hostname The hostname for the CA subsystem which will issue the certificates for a subordinate CA, RA, DRM, OCSP, TKS, or TPS
subsystem.
ca_port The non-SSL port number of the CA.
ca_ssl_port The SSL end entities port number of the CA.
drm_hostname The hostname for the DRM subsystem to use to archive keys. For the TPS only.
drm_ssl_port The SSL agent port number of the DRM. For the TPS only.
tks_hostname The hostname for the TKS subsystem to use to derive keys. For the TPS only.
tks_ssl_port The SSL agent port number of the TKS. For the TPS only.
Authentication Database Configuration (TPS only)
ldap_auth_host Gives the hostname of the LDAP directory database to use for the TPS subsystem token database. Only for the TPS subsystem.
ldap_auth_port Gives the port number of the LDAP directory database to use for the TPS subsystem token database. Only for the TPS subsystem.
ldap_auth_base_dn Gives the base DN in the LDAP directory tree of the TPS token database under which to create token entries. Only for the TPS
subsystem.
External CA for Issuing Certificates
external Sets whether to submit the subsystem certificates to the configured CA or to an external CA. The options are true or false.
ext_csr_file The output file to which to write the generated certificate requests for the subsystem certificates. Step one of the silent configuration
process.
ext_cert_file The input file for the certificates issued by the external CA. Step two of the silent configuration process.
ext_ca_cert_chain_file The input file for the CA certificate chain for the external CA issuing the certificate. Step two of the silent configuration process.
Cloning Configuration
clone Sets whether the new instance is a clone. Its possible values are true or false.
clone_p12_file The path and file name of the PKCS#12 file for the backed-up keys for the original instance.
clone_p12_password The password to access the PKCS#12 file.
Table 1.1. Parameters for pkisilent
1.2.2. Usage
1.2.2.1. Installing a CA
The options are slightly different between the subsystems; the simplest to configure is a CA with a new
security domain.
This configured a CA, creates a new security domain, backs up its keys, and self-signs its certificates.
Any spaces in the arguments must be escaped.
pkisilent ConfigureCA -cs_hostname localhost -cs_port 9445 -subsystem_name "pki-ca2" -
client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin sYY8er834FG9793fsef7et5 -
domain_name "testca" -admin_user admin -admin_email "[email protected]" -admin_password secret
-agent_key_size 2048 -agent_key_type rsa -agent_cert_subject "cn=ca\ agent\ cert" -ldap_host
server -ldap_port 389 -bind_dn "cn=directory\ manager" -bind_password secret -base_dn

Chapter 1. Create and Remove Instance Tools
8
"o=pki-ca2" -db_name "server.example.com-pki-ca2" -key_size 2048 -key_type rsa -save_p12
true -backup_pwd password -backup_fname /export/backup.p12 -ca_subsystem_cert_subject_name
"cn=ca\ subsystem\ cert,o=testca\ domain" -ca_ocsp_cert_subject_name "cn=ocsp\ signing
\ cert,o=testca\ domain" -ca_server_cert_subject_name "cn=ca\ client\ cert,o=testca
\ domain" -ca_sign_cert_subject_name "cn=ca\ signing\ cert,o=testca\ domain" -
ca_audit_signing_cert_subject_name "cn=audit\ signing\ cert,o=testca\ domain"
A subordinate CA — along with the DRM, OCSP, and TKS — is configured to join an existing security
domain and to have its certificates signed by an existing Certificate System CA (by default; it is also
possible to use an external CA, as in Section 1.2.2.4, “Submitting Requests to an External CA”).
pkisilent ConfigureSubCA -cs_hostname localhost -cs_port 9445 -subsystem_name "pki-ca2" -
client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin sYY8er834FG9793fsef7et5 -
sd_hostname "domain.example.com" -sd_admin_port 9445 -sd_agent_port 9443 -sd_ssl_port
9444 -sd_admin_name admin -sd_admin_password secret -admin_user admin -admin_email
"[email protected]" -admin_password secret -agent_key_size 2048 -agent_key_type
rsa -agent_cert_subject "cn=ca\ agent\ cert" -ldap_host server -ldap_port 389 -
bind_dn "cn=directory\ manager" -bind_password secret -base_dn "o=pki-ca2" -db_name
"server.example.com-pki-ca2" -key_size 2048 -key_type rsa -save_p12 true -backup_pwd
password -backup_fname /export/backup.p12 -ca_hostname server.example.com ca_port
9180 -ca_ssl_port 9443 -ca_subsystem_cert_subject_name "cn=ca\ subsystem\ cert,o=testca
\ domain" -ca_ocsp_cert_subject_name "cn=ocsp\ signing\ cert,o=testca\ domain" -
ca_server_cert_subject_name "cn=ca\ client\ cert,o=testca\ domain" -ca_sign_cert_subject_name
"cn=ca\ signing\ cert,o=testca\ domain" -ca_audit_signing_cert_subject_name "cn=audit\
signing\ cert,o=testca\ domain"
Example 1.4. Configuring a Subordinate CA
1.2.2.2. Installing a TPS
A TPS requires the most parameters, since it depends on having a CA, DRM, and TKS configured and
uses two LDAP databases, along with joining an existing security domain.
pkisilent ConfigureTPS -cs_hostname localhost -cs_port 9445 -subsystem_name "pki-tps2"
-client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin sYY8er834FG9793fsef7et5
-sd_hostname "domain.example.com" -sd_admin_port 9445 -sd_agent_port 9443 -sd_ssl_port
9444 -sd_admin_name admin -sd_admin_password password -admin_user admin -admin_email
"[email protected]" -admin_password password -agent_key_size 2048 -agent_key_type
rsa -agent_cert_subject "cn=tps\ agent\ cert" -ldap_host server -ldap_port 389 -
bind_dn "cn=directory\ manager" -bind_password password -base_dn "o=pki-tps2" -db_name
"server.example.com-pki-tps2" -key_size 2048 -key_type rsa -tps_subsystem_cert_subject_name
"cn=tps\ subsystem\ cert,o=testca\ domain" -tps_server_cert_subject_name "cn=tps\ client\
cert,o=testca\ domain" -tps_audit_signing_cert_subject_name "cn=audit\ signing\ cert,o=testca
\ domain" -ldap_auth_host auth.example.com -ldap_auth_port 389 -ldap_auth_base_dn
"ou=tps,ou=People,dc=example,dc=com"
1.2.2.3. Cloning a CA
pkisilent can be used to configure a clone for a CA. A clone mirrors and uses much of the same
configuration as its master, and the clone options either reflect the same configuration settings as the
master or actually draw on the master's configuration:
• The keys for the master's certificates, stored in its PKCS #12 backup files (-clone_p12_file and -
clone_p12_password)
• The same issuing CA for certificates
• The same security domain, set in the -sd_* parameters