Redhat CERTIFICATE SYSTEM User Manual
Red Hat Certificate System 7.2
Command-Line Tools
Guide
7.2
ISBN: N/A
Publication date:
Red Hat Certificate System 7.2
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.
Red Hat Certificate System 7.2: Command-Line Tools Guide
Copyright © 2007, 2008 Red Hat, Inc.
Copyright © 2007, 2008 Red Hat. This material may only be distributed subject to the terms and conditions set forth in
the Open Publication License, V1.0 or later with the restrictions noted below (the latest version of the OPL is presently
available at http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the
copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is
prohibited unless prior permission is obtained from the copyright holder.
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other
countries.
All other trademarks referenced herein are the property of their respective owners.
The GPG fingerprint of the security@redhat.com key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
1801 Varsity Drive
Raleigh, NC 27606-2072
USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park, NC 27709
USA
Red Hat Certificate System 7.2
About This Guide ......................................................................................................vii
1. Required Information ..................................................................................... vii
2. What Is in This Guide .................................................................................... vii
3. Additional Reading .........................................................................................ix
4. Common Tool Information ...............................................................................x
5. Examples and Formatting ................................................................................x
6. Giving Feedback ............................................................................................xi
7. Revision History ............................................................................................ xii
1. Create and Remove Instance Tools ........................................................................ 1
1. pkicreate ....................................................................................................... 1
1.1. Syntax ................................................................................................ 1
1.2. Usage ................................................................................................ 2
2. pkiremove ..................................................................................................... 3
2.1. Syntax ................................................................................................ 3
2.2. Usage ................................................................................................ 3
2. Silent Installation .................................................................................................... 5
1. Syntax ........................................................................................................... 5
2. Usage ........................................................................................................... 9
3. TokenInfo .............................................................................................................11
1. Syntax ..........................................................................................................11
4. SSLGet ................................................................................................................13
1. Syntax ..........................................................................................................13
2. Usage ..........................................................................................................13
5. AuditVerify ............................................................................................................15
1. Setting up the Auditor's Database ..................................................................15
2. Syntax ..........................................................................................................16
3. Return Values ...............................................................................................17
4. Usage ..........................................................................................................17
6. PIN Generator ......................................................................................................19
1. The setpin Command ....................................................................................19
1.1. Editing the setpin.conf Configuration File .............................................19
1.2. Syntax ...............................................................................................20
1.3. Usage ...............................................................................................23
2. How setpin Works .........................................................................................23
2.1. Input File ...........................................................................................25
2.2. Output File .........................................................................................26
2.3. How PINs Are Stored in the Directory ..................................................27
2.4. Exit Codes .........................................................................................27
7. ASCII to Binary .....................................................................................................29
1. Syntax ..........................................................................................................29
2. Usage ..........................................................................................................29
8. Binary to ASCII .....................................................................................................31
1. Syntax ..........................................................................................................31
2. Usage ..........................................................................................................31
9. Pretty Print Certificate ...........................................................................................33
1. Syntax ..........................................................................................................33
v
Red Hat Certificate System 7.2
2. Usage ..........................................................................................................33
10. Pretty Print CRL ..................................................................................................37
1. Syntax ..........................................................................................................37
2. Usage ..........................................................................................................37
11. TKS Tool ............................................................................................................39
1. Syntax ..........................................................................................................39
2. Usage ..........................................................................................................42
12. CMC Request .....................................................................................................47
1. Syntax ..........................................................................................................47
2. Usage ..........................................................................................................51
13. CMC Enrollment ..................................................................................................53
1. Syntax ..........................................................................................................53
2. Usage ..........................................................................................................53
14. CMC Response ..................................................................................................57
1. Syntax ..........................................................................................................57
15. CMC Revocation .................................................................................................59
1. Syntax ..........................................................................................................59
2. Testing CMC Revocation ...............................................................................60
16. CRMF Pop Request ............................................................................................61
1. Syntax ..........................................................................................................61
2. Usage ..........................................................................................................62
17. Extension Joiner .................................................................................................65
1. Syntax ..........................................................................................................65
2. Usage ..........................................................................................................65
18. Key Usage Extension ..........................................................................................69
1. Syntax ..........................................................................................................69
19. Issuer Alternative Name Extension .......................................................................71
1. Syntax ..........................................................................................................71
2. Usage ..........................................................................................................73
20. Subject Alternative Name Extension .....................................................................75
1. Syntax ..........................................................................................................75
2. Usage ..........................................................................................................77
21. HTTP Client ........................................................................................................79
1. Syntax ..........................................................................................................79
22. OCSP Request ...................................................................................................81
1. Syntax ..........................................................................................................81
23. PKCS #10 Client .................................................................................................83
1. Syntax ..........................................................................................................83
24. Bulk Issuance Tool ..............................................................................................85
1. Syntax ..........................................................................................................85
25. Revocation Automation Utility ..............................................................................87
1. Syntax ..........................................................................................................87
26. tpsclient ..............................................................................................................89
1. Syntax ..........................................................................................................91
Index .......................................................................................................................95
vi
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 Information
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
Chapter 2, Silent Installation Describes the tool used for a silent instance
Describes the tools used to create and
remove subsystem instances.
creation.
Chapter 3, TokenInfo Describes the utility which can be used to
identify tokens on a machine, which shows
vii
About This Guide
whether the Certificate System can detect
those tokens to use for a subsystem.
Chapter 4, SSLGet Describes a tool used by the Certificate
System to help configure and use security
domains.
Chapter 5, AuditVerify Describes how to use the tool used to verify
signed audit logs.
Chapter 6, PIN Generator Describes how to use the tool for generating
unique PINs for end users and for populating
their directory entries with PINs.
Chapter 7, ASCII to Binary Describes how to use the tool for converting
ASCII data to its binary equivalent.
Chapter 8, Binary to ASCII Describes how to use the tool for converting
binary data to its ASCII equivalent.
Chapter 9, 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 10, 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 11, TKS Tool Describes how to manipulate symmetric keys,
including keys stored on tokens, the TKS
master key, and related keys and databases.
Chapter 12, CMC Request Describes how to construct a Certificate
Management Messages over Cryptographic
Message Syntax (CMC) request.
Chapter 13, CMC Enrollment Describes how to sign a CMC certificate
enrollment request with an agent's certificate.
Chapter 14, CMC Response Describes how to parse a CMC response.
Chapter 15, CMC Revocation Describes how to sign a CMC revocation
request with an agent's certificate.
Chapter 16, CRMF Pop Request Describes how to generate Certificate
Request Message Format (CRMF) requests
with proof of possession (POP).
Chapter 17, Extension Joiner Describes how to use the tool for joining
MIME-64 encoded formats of certificate
extensions to create a single blob.
Chapter 18, Key Usage Extension Describes how to generate a distinguished
encoding rules (DER)-encoded Extended Key
Usage extension.
viii
Additional Reading
Chapter 19, Issuer Alternative Name
Extension
Chapter 20, Subject Alternative Name
Extension
Chapter 21, HTTP Client Describes how to communicate with any
Chapter 22, OCSP Request Describes how to verify certificate status by
Chapter 23, PKCS #10 Client Describes how to generate a Public-Key
Chapter 24, Bulk Issuance Tool Describes how to send either a KEYGEN or
Describes how to generate an Issuer
Alternative Name extension in base-64
encoding.
Describes how to generate a Subject
Alternative Name extension in base-64
encoding.
HTTP/HTTPS server.
submitting Online Certificate Status Protocol
(OCSP) requests to an instance of an OCSP
subsystem.
Cryptography Standards (PKCS) #10
enrollment request.
CRMF enrollment request to the bulk
issuance interface to create certificates
automatically.
Chapter 25, Revocation Automation Utility Describes how to automate user management
scripts to revoke certificates.
Chapter 26, tpsclient Describes how to test the TPS configuration
and common operations.
Table 1. List of Contents
3. Additional Reading
The documentation for the Certificate System also contains the following guides:
• Certificate System Administrator's Guide explains all administrative functions for the
Certificate System, such as adding users, creating and renewing certificates, managing smart
cards, publishing CRLs, and modifying subsystem settings like port numbers.
• Certificate System Agent's Guide details how to perform agent operations for the CA, DRM,
OCSP, and TPS subsystems through the Certificate System agent services interfaces.
• Certificate System Enterprise Security Client Guide explains how to install, configure, and use
the Enterprise Security Client, the user client application for managing smart cards, user
certificates, and user keys.
• Certificate System Migration Guide provides detailed migration information for migrating all
parts and subsystems of previous versions of Certificate System to Red Hat Certificate
ix
About This Guide
System 7.2.
Additional Certificate System information is provided in the Certificate System SDK, an online
reference to HTTP interfaces, javadocs, samples, and tutorials related to Certificate System; a
downloadable zip file of this material is available for user interaction with the tutorials.
For the latest information about Certificate System, including current release notes, complete
product documentation, technical notes, and deployment information, see the Red Hat
documentation page:
http://www.redhat.com/docs/manuals/cert-system/
4. 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.
5. Examples and Formatting
All of the examples for Red Hat Certificate System commands, file locations, and other usage
are given for Red Hat Enterprise Linux 5 systems. Be certain to use the appropriate commands
and files for your platform. For example:
To start the Red Hat Directory Server:
service dir-server start
Example 1. Example Command
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.
This type of formatting is used for anything entered or returned
Monospace
with a
background
Italicized text Any text which is italicized is a variable, such as
x
in a command prompt.
instance_name or hostname. Occasionally, this is also used to
emphasize a new term or other phrase.
Giving Feedback
Formatting Style Purpose
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.
TIP
A tip is typically an alternative way of performing a task.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a
configuration change that will not persist after a reboot.
CAUTION and WARNING
A caution indicates an act that would violate your support agreement.
A warning indicates potential data loss, as may happen when tuning hardware
for maximum performance.
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.
xi
About This Guide
• Set the component to Doc - cli-tools-guide.
• Set the version number to 7.2.
• 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 mailto:docs@redhat.com.
7. Revision History
Revision History
Revision 7.2.1 Tuesday, August 5, 2008 Ella Deon
Lackey<dlackey@redhat.com>
Updating setpin information per Bugzilla #224748 and Bugzilla #224930.
xii
Chapter 1.
Create and Remove Instance Tools
The Certificate System includes two tools to create and remove subsystem instances,
pkicreate 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 up2date
command. This tool creates new instances after the default subsystems have
been installed.
Likewise, the pkiremove utility does not uninstall the Certificate System
subsystem; it removes a single instance.
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 page, as with configuring the
default instances.
The following sections explain the syntax and usage of the pkicreate tool.
1.1. Syntax
This tool has the following syntax:
pkicreate -pki_instance_root=/directory/path -subsystem_type=type
-pki_instance_name=instance_ID [-secure_port=SSLport]
[-unsecure_port=port] -tomcat_server_port=port
-user=user_name -group=group_name [-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
default subsystem instance (before running the rhpki-install script), this
allows the default instance to be installed in a user-defined location instead of the
default location.
1
Chapter 1. Create and Remove Instance Tools
Parameter Description
pki_instance_root Gives the full path to the new instance
configuration directory.
subsystem_type
Gives the type of subsystem being created.
The possible values are as follows:
• ca, for a Certificate Manager
• 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.The
name must be unique within the security
domain. Even cloned subsystems must have
different instance names for cloning to
succeed.
secure_port Optional. Sets the SSL port number. If this is
not set, the number is randomly generated.
unsecure_port Optional. Sets the regular port number. If this
is not set, the number is randomly generated.
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 instance since it does not use
a Tomcat web server.
user Sets the user as which the Certificate System
instance will run. This option must be set.
group 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.2. Usage
In the following example, the pkicreate is used to create a new DRM instance running on ports
2
pkiremove
10543 and 10180, named rhpki-drm2, in the /var/lib/rhpki-drm2 directory.
pkicreate -pki_instance_root=/var/lib -subsystem_type=kra
-pki_instance_name=rhpki-drm2 -secure_port=10543
-unsecure_port=10180 -tomcat_server_port=1802 -user=pkiuser
-group=pkigroup -verbose
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
2. pkiremove
The pkiremove tool removes subsystem instances. This tool removes the single subsystem
instance specified; it does not uninstall the Certificate System packages.
2.1. Syntax
This tool has the following syntax:
pkiremove -pki_instance_root=/directory/path -pki_instance_name=instance_ID
Parameter Description
pki_instance_root Gives the full path to the instance
configuration directory.
pki_instance_name Gives the name of the instance.
2.2. Usage
The following example removes a DRM instance named rhpki-drm2 which was installed in the
/var/lib/rhpki-drm2 directory.
pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-drm2
3
4
Chapter 2.
Silent Installation
The Certificate System includes a tool, pkisilent, which can completely create and configure
an instance in a single step. Normally, adding instances requires running the pkicreate utility
to create the instance and then accessing the subsystem HTML page to complete the
configuration. The pkisilent utility creates and configures the instance in a single step. The
pkisilent tool must be downloaded independently. It is available through the Red Hat
Certificate System 7.2 Red Hat Network channel.
NOTE
Run this tool 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.
The utility can be downloaded and saved to any location and is then executed locally.
1. Syntax
This tool has the following syntax for a CA:
perl pkisilent ConfigureCA -cs_hostname hostname
-cs_port SSLport
-client_certdb_dir certDBdir
-client_certdb_pwd password
-preop_pin preoppin
-domain_name domain_name
-admin_user adminUID
-admin_email admin@email
-admin_password password
-agent_name agentName
-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 search_base_DN
-db_name dbName
-key_size keySize
-key_type keyType
-token_name HSM_name
5
Chapter 2. Silent Installation
-token_pwd HSM_password
-save_p12 export-p12-file
-backup_pwd password
This tool has the following syntax for the DRM, OCSP, and TKS subsystems:
perl pkisilent ConfiguresubsystemType -cs_hostname hostname
-cs_port SSLport
-ca_hostname hostname
-ca_port port
-ca_ssl_port SSLport
-ca_agent_name agentName
-ca_agent_password password
-client_certdb_dir certDBdir
-client_certdb_pwd password
-preop_pin preoppin
-domain_name domain_name
-admin_user adminUID
-admin_email admin@email
-admin_password password
-agent_name agentName
-ldap_host hostname
-ldap_port port
-bind_dn bindDN
-bind_password password
-base_dn search_base_DN
-db_name dbName
-key_size keySize
-key_type keyType
-agent_key_size keySize
-agent_key_type keyType
-agent_cert_subject cert_subject_name
-backup_pwd password
This tool has the following syntax for the TPS subsystem:
perl pkisilent ConfigureTPS -cs_hostname hostname
-cs_port SSLport
-ca_hostname hostname
-ca_port port
-ca_ssl_port SSLport
-ca_agent_name agentName
-ca_agent_password password
-client_certdb_dir certDBdir
-client_certdb_pwd password
-preop_pin preoppin
-domain_name domain_name
-admin_user adminUID
-admin_email admin@email
-admin_password password
-agent_name agentName
-ldap_host hostname
-ldap_port port
-bind_dn bindDN
6
-bind_password password
-base_dn search_base_DN
-db_name dbName
-key_size keySize
-key_type keyType
-agent_key_size keySize
-agent_key_type keyType
-agent_cert_subject cert_subject_name
-ldap_auth_host ldap_auth_host
-ldap_auth_port ldap_auth_port
-ldap_auth_base_dn ldap_auth_base_dn
Java Class Name Subsystem
ConfigureCA For the CA.
ConfigureDRM For the DRM.
ConfigureOCSP For the OCSP.
ConfigureTKS For the TKS.
Syntax
ConfigureTPS For the TPS.
Table 2.1. Subsystem Java Classes for pkisilent
NOTE
The ConfigureCA script is used to create a security domain or to add the new
CA to an existing domain. The other scripts only add the subsystem to an
existing security domain.
Parameter Description
cs_hostname The hostname for the Certificate System
machine.
cs_port The SSL port number of the Certificate
System.
ca_hostname The hostname for the CA subsystem which
will issue the certificates for the DRM, OCSP,
TKS, or TPS subsystem.
ca_port The non-SSL port number of the CA.
ca_ssl_port The SSL port number of the CA.
ca_agent_name The UID of the CA agent.
ca_agent_password The password of the CA agent.
client_certdb_dir The directory for the subsystem certificate
databases.
7
Chapter 2. Silent Installation
Parameter Description
client_certdb_pwd The password to protect the certificate
database.
preop_pin The preoperation PIN number used for the
initial configuration.
domain_name The name of the security domain to which the
subsystem will be added.
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_name The new agent for the new subsystem.
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.
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.
key_size The size of the key to generate. The
recommended size for an RSA key is 1024
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
8
Usage
Parameter Description
installation.
token_name Gives the name of the HSM token used to
store the subsystem certificates. Only for the
CA subsystem.
token_password Gives the password for the HSM. Only for the
CA subsystem.
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.
Table 2.2. Parameters for pkisilent
2. Usage
The options are slightly different between the subsystems; all subsystems except for the CA
subsystem require extra options specifying the Certificate Manager to which to submit the
certificate requests.
This silent installation script example installs a CA subsystem:
perl pkisilent ConfigureCA -cs_hostname localhost -cs_port 9543
-client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin
sYY8er834FG9793fsef7et5
-domain_name "testca" -admin_user admin -admin_email "admin@example.com"
-admin_password password -agent_name "rhpki-ca2 agent" -agent_key_size 2048
-agent_key_type rsa -agent_cert_subject "ca agent cert" -ldap_host server
-ldap_port 389 -bind_dn "cn=directory manager" -bind_password password
-base_dn "o=rhpki-ca2" -db_name "rhpki-ca2" -key_size 2048
-key_type rsa -save_p12 true -backup_pwd password
This silent installation script example installs a TKS subsystem; this script has extra options to
point to the CA server:
perl pkisilent ConfigureTKS -cs_hostname localhost -cs_port 13543
-ca_hostname server.example.com -ca_port 9080 -ca_ssl_port 9443
-ca_agent_name agent -ca_agent_password password
-client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin
9
Chapter 2. Silent Installation
fS44I6SASGF34FD76WKJHIW4
-domain_name "testca" -admin_user admin -admin_email "admin@example.com"
-admin_password password -agent_name "rhpki-tks2 agent" -ldap_host server
-ldap_port 389 -bind_dn "cn=directory manager" -bind_password password
-base_dn "o=rhpki-tks2" -db_name "rhpki-tks2" -key_size 2048
-key_type rsa -agent_key_size 2048 -agent_key_type rsa
-agent_cert_subject "tks agent cert" -backup_pwd password
This silent installation script example installs a TPS subsystem; this script has extra options to
point to the LDAP authentication database used for storing token information:
perl pkisilent ConfigureTPS -cs_hostname localhost -cs_port 7988
-ca_hostname server.example.com -ca_port 9080 -ca_ssl_port 9443
-ca_agent_name agent -ca_agent_password password
-client_certdb_dir /tmp/ -client_certdb_pwd password -preop_pin
fS44I6SASGF34FD76WKJHIW4
-domain_name "testca" -admin_user admin -admin_email "admin@example.com"
-admin_password password -agent_name "rhpki-tks2 agent" -ldap_host server
-ldap_port 389 -bind_dn "cn=directory manager" -bind_password password
-base_dn "o=rhpki-tks2" -db_name "rhpki-tks2" -key_size 2048
-key_type rsa -agent_key_size 2048 -agent_key_type rsa
-agent_cert_subject "tps agent cert" -ldap_auth_host server
-ldap_auth_port 389 -ldap_auth_base_dn "o=TPS DB,dc=example,dc=com"
10
Chapter 3.
TokenInfo
This tool is used to determine which external hardware tokens are visible to the Certificate
System subsystem. This can be used to diagnose whether problems using tokens are related to
the Certificate System being unable to detect it.
1. Syntax
The TokenInfo tool has the following syntax:
TokenInfo /directory/alias
Option Description
/directory/alias Specifies the path and file to the certificate
and key database directory; for example,
/var/lib/rhpki-ca/alias/.
11
12
Chapter 4.
SSLGet
This tool is similar to the the wget command, which downloads files over HTTP. sslget
supports client authentication using NSS libraries. The configuration wizard uses this utility to
retrieve security domain information from the CA.
1. Syntax
The sslget tool has the following syntax:
sslget [-e profile information] -n rsa_nickname [-p password | -w pwfile]
[-d dbdir] [-v] [-V] -r url hostname[:port]
Option Description
e Optional. Submits information through a
subsystem form by specifying the form name
and the form fields. For example, this can be
used to submit certificate enrollments through
a certificate profile.
n Gives the CA certificate nickname.
p Gives the certificate database password. Not
used if the -w option is used.
w Optional. Gives the password file path and
name. Not used if the -p option is used.
d Optional. Gives the path to the security
databases.
v Optional. Sets the operation in verbose mode.
V Optional. Gives the version of the sslget
tool.
r Gives the URL of the site or server from which
to download the information.
hostname Gives the hostname of the server to which to
send the request.
port Optional. Gives the port number of the server.
2. Usage
It is possible to use sslget to submit information securely to Certificate System subsystems.
For example, to submit a certificate request through a certificate profile enrollment for to a CA,
the command is as follows:
13
Chapter 4. SSLGet
sslget -e
"profileId=caInternalAuthServerCert&cert_request_type=pkcs10
&requestor_name=TPS-server.example.com-7889
&cert_request=MIIBGTCBxAIBADBfMSgwJgYDVQQKEx8yMDA2MTEwNngxMi
BTZmJheSBSZWRoYXQgRG9tYWluMRIwEAYDVQQLEwlyaHBraS10cHMxHzAdBgNVBA
MTFndhdGVyLnNmYmF5LnJlZGhhdC5jb20wXDANBgkqhkiG9w0BAQEFAANLADBIAk
EAsMcYjKD2cDJOeKjhuAiyaC0YVh8hUzfcrf7ZJlVyROQx1pQrHiHmBQbcCdQxNz
YK7rxWiR62BPDR4dHtQzj8RwIDAQABoAAwDQYJKoZIhvcNAQEEBQADQQAKpuTYGP
%2BI1k50tjn6enPV6j%2B2lFFjrYNwlYWBe4qYhm3WoA0tIuplNLpzP0vw6ttIMZ
kpE8rcfAeMG10doUpp
&xmlOutput=true&sessionID=-4771521138734965265
&auth_hostname=server.example.com&auth_port=9443"
-d "/var/lib/rhpki-tps/alias" -p "password123" -v -n "Server-Cert
cert-rhpki-tps"
-r "/ca/ee/ca/profileSubmit" server.example.com:9443
14
Chapter 5.
AuditVerify
The AuditVerify tool is used to verify that signed audit logs were signed with the private
signing key and that the audit logs have not been compromised.
Auditors can verify the authenticity of signed audit logs using the AuditVerify tool. This tool
uses the public key of the signed audit log signing certificate to verify the digital signatures
embedded in a signed audit log file. The tool response indicates either that the signed audit log
was successfully verified or that the signed audit log was not successfully verified. An
unsuccessful verification warns the auditor that the signature failed to verify, indicating the log
file may have been tampered with (compromised).
1. Setting up the Auditor's Database
AuditVerify needs access to a set of security databases containing the signed audit log
signing certificate and its chain of issuing certificates. One of the CA certificates in the issuance
chain must be marked as trusted in the database.
The auditor should import the audit signing certificate into certificate and key databases before
running AuditVerify. The auditor should not use the security databases of the Certificate
System instance that generated the signed audit log files. If there are no readily accessible
certificate and key database, the auditor must create a set of certificate and key databases and
import the signed audit log signing certificate chain.
To create the security databases and import the certificate chain, do the following:
1. Create the security database directory in the filesystem.
mkdir /var/lib/instance_ID/logs/signedAudit/dbdir
2. Use the certutil tool to create an empty set of certificate databases.
certutil -d /var/lib/instance_ID/logs/signedAudit/dbdir -N
3. Import the CA certificate and log signing certificate into the databases, marking the CA
certificate as trusted. The certificates can be obtained from the CA in ASCII format.
If the CA certificate is in a file called cacert.txt and the log signing certificate is in a file
called logsigncert.txt, both in the Certificate System alias/ directory, then the certutil
is used to set the trust for the new audit security database directory pointing to those files, as
follows:
certutil -d /var/lib/instance_ID/logs/signedAudit/dbdir -A -n "CA
Certificate" -t \
"CT,CT,CT" -a -i /var/lib/instance_ID/alias/cacert.txtcertutil -d \
15
Chapter 5. AuditVerify
/var/lib/instance_ID/logs/signedAudit/dbdir -A -n "Log Signing
Certificate" -a -i \
/var/lib/instance_ID/alias/logsigncert.txt
2. Syntax
The AuditVerify tool has the following syntax:
AuditVerify -d dbdir -n signing_certificate_nickname -a logListFile [-P
cert/key_db_prefix] [-v]
Option Description
d Specifies the directory containing the security
databases with the imported audit log signing
certificate.
n Gives the nickname of the certificate used to
sign the log files. The nickname is whatever
was used when the log signing certificate was
imported into that database.
a Specifies the text file containing a comma
separated list (in chronological order) of the
signed audit logs to be verified. The contents
of the logListFile are the full paths to the audit
logs. For example:
/var/lib/rhpki-ca/logs/signedAudit/ca_cert-ca_audit,
\
/var/lib/rhpki-ca/logs/signedAudit/ca_cert-ca_audit.20030227102711,
\
/var/lib/rhpki-ca/logs/signedAudit/ca_cert-ca_audit.20030226094015
P Optional. The prefix to prepend to the
certificate and key database filenames. If
used, a value of empty quotation marks (“”)
should be specified for this argument, since
the auditor is using separate certificate and
key databases from the Certificate System
instance and it is unlikely that the prefix
should be prepended to the new audit security
database files.
v Optional. Specifies verbose output.
16
Usage
3. Return Values
When AuditVerify is used, one of the following codes is returned:
Return Value Description
0 Indicates that the signed audit log has been
successfully verified.
1 Indicates that there was an error while the tool
was running.
2 Indicates that one or more invalid signatures
were found in the specified file, meaning that
at least one of the log files could not be
verified.
4. Usage
After a separate audit database directory has been configured, do the following:
1. Create a text file containing a comma-separated list of the log files to be verified. The name
of this file is referenced in the AuditVerify command.
For example, this file could be logListFile in the /etc/audit directory. The contents are
the comma-separated list of audit logs to be verified, such as "auditlog.1213,
auditlog.1214, auditlog.1215."
2. If the audit databases do not contain prefixes and are located in the user home directory,
such as /usr/home/smith/.redhat, and the signing certificate nickname is
“auditsigningcert”, the AuditVerify command is run as follows:
AuditVerify -d /usr/home/smith/.redhat -n auditsigningcert -a
/etc/audit/logListFile -P "" -v
17
18
Loading...