Provided by: pki-server_10.8.3-1ubuntu1_amd64 
NAME
pkispawn - Sets up a PKI subsystem.
SYNOPSIS
pkispawn -s subsystem -f config_file [-h] [-v]
DESCRIPTION
Sets up a PKI subsystem (CA, KRA, OCSP, TKS, or TPS) in a Tomcat instance.
Note: A 389 Directory Server instance must be configured and running before this script
can be run. PKI server requires an internal directory database. The default
configuration assumes a Directory Server instance running on the same machine on port 389.
For more information on creating a Directory Server instance, see setup-ds.pl(8).
An instance can contain multiple subsystems, although it may contain at most one of each
type of subsystem on a single machine. So, for example, an instance could contain CA and
KRA subsystems, but not two CA subsystems. To create an instance with a CA and a KRA,
simply run pkispawn twice, with values -s CA and -s KRA respectively.
The instances are created based on values for configuration parameters in the default
configuration (i.e. /usr/share/pki/server/etc/default.cfg) and the user-provided
configuration file. The user-provided configuration file is read after the default
configuration file, so any parameters defined in that file will override parameters in the
default configuration file. In general, most users will store only those parameters which
are different from the default configuration in their user-provided configuration file.
This configuration file contains parameters that are grouped into sections. These
sections are stacked, so that parameters defined in earlier sections can be overwritten by
parameters defined in later sections. The sections are read in the following order:
[DEFAULT], [Tomcat], and the subsystem section ([CA], [KRA], [OCSP], [TKS], or [TPS]).
This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT]
or [Tomcat], and system-specific customization.
Note: Any non-password related parameter values in the configuration file that needs to
contain a % character must be properly escaped. For example, a value of foo%bar would be
specified as foo%%bar in the configuration file.
At a minimum, the user-defined configuration file must provide some passwords needed for
the install. An example configuration file is provided in the EXAMPLES section below.
For more information on the default configuration file and the parameters it contains (and
can be customized), see pki_default.cfg(5).
The pkispawn run creates several different installation files that can be referenced
later, if need be:
• For Tomcat-based instances, a Tomcat instance is created at
/var/lib/pki/pki_instance_name, where pki_instance_name is defined in the
configuration file.
• A log file of pkispawn operations is written to
/var/log/pki/pki-subsystem-spawn.timestamp.log.
• A .p12 (PKCS #12) file containing a certificate for a subsystem administrator is
stored in pki_client_dir.
When the utility is done running, the CA can be accessed by pointing a browser to
https://hostname:pki_https_port/. The agent pages can be accessed by importing the CA
certificate and administrator certificate into the browser.
The PKI server instance can also be accessed using the pki command line interface. See
pki(1). For more extensive documentation on how to use PKI features, see the Red Hat
Certificate System Documentation at
⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩.
Instances created using pkispawn can be removed using pkidestroy. See pkidestroy(8).
pkispawn supersedes and combines the functionality of pkicreate and pkisilent, which were
available in earlier releases of Certificate Server. It is now possible to completely
create and configure the Certificate Server subsystem in a single step using pkispawn.
Note: Previously, as an alternative to using pkisilent to perform a non-interactive batch
configuration, a PKI instance could be interactively configured by a GUI-based
configuration wizard via a Firefox browser. GUI-based configuration of a PKI instance is
unavailable in this version of the product.
OPTIONS
-s subsystem
Specifies the subsystem to be installed and configured, where subsystem is CA, KRA,
OCSP, TKS, or TPS.
-f config_file
Specifies the path to the user-defined configuration file.
This file contains differences between the default configuration and the custom
configuration.
--precheck
Execute pre-checks and exit.
--skip-configuration
Run the first step of the installation (i.e. skipping the instance configuration
step).
--skip-installation
Run the second step of the installation (i.e. skipping the instance installation
step).
-h, --help
Prints additional help information.
-v
Displays verbose information about the installation.
This flag can be provided multiple times to increase verbosity.
See pkispawn -h for details.
SEPARATE VERSUS SHARED INSTANCES
Separate PKI instances
As described above, this version of PKI continues to support separate PKI instances for
all subsystems.
Separate PKI instances run as a single Java-based Apache Tomcat instance, contain a single
PKI subsystem (CA, KRA, OCSP, TKS, or TPS), and must utilize unique ports if co-located on
the same machine.
Shared PKI instances
Additionally, this version of PKI introduces the notion of a shared PKI instance.
Shared PKI instances also run as a single Java-based Apache Tomcat instance, but may
contain any combination of up to one of each type of PKI subsystem:
• CA
• TKS
• CA, KRA
• CA, OCSP
• TKS, TPS
• CA, KRA, TKS, TPS
• CA, KRA, OCSP, TKS, TPS
• etc.
Shared PKI instances allow all of their subsystems contained within that instance to share
the same ports, and must utilize unique ports if more than one shared PKI instance is
co-located on the same machine.
Semantically, a shared PKI instance that contains a single PKI subsystem is identical to a
separate PKI instance.
INTERACTIVE MODE
If no options are specified, pkispawn will provide an interactive menu to collect the
parameters needed to install the Certificate Server instance. Note that only the most
basic installation options are provided. This includes root CA, KRA, OCSP, TKS, and TPS
connecting to an existing directory server. More advanced setups such as cloned
subsystems, subordinate or externally signed CA, subsystems that connect to the directory
server using LDAPS, and subsystems that are customized beyond the options described below
require the use of a configuration file with the -f option.
The interactive option is most useful for those users getting familiar with Certificate
Server. The parameters collected are written to the installation file of the subsystem,
which can be found at /etc/dogtag/tomcat/instance_name/subsystem/deployment.cfg.
The following parameters are queried interactively during the installation process.
Subsystem Type
Subsystem (CA/KRA/OCSP/TKS/TPS):
The type of subsystem to be installed.
Prompted when the -s option is not specified.
The default value chosen is CA.
Instance Specific Parameters
Instance name:
The name of the tomcat instance in which the subsystem is to be installed. The default
value is pki-tomcat.
Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can exist within a
given instance.
HTTP port:
The HTTP port of the Tomcat instance. The default value is 8080.
Secure HTTP port:
The HTTPS port of the Tomcat instance. The default value is 8443.
AJP port:
The AJP port of the Tomcat instance. The default value is 8009.
Management port:
The management port of the Tomcat instance. The default value is 8005.
Note: When deploying a new subsystem into an existing instance, pkispawn will attempt to
read the ports from deployment.cfg files stored for previously installed subsystems for
this instance. If successful, the installer will not prompt for these ports.
Administrative User Parameters
Username:
The username of the administrator of this subsystem. The default value is
<ca/kra/ocsp/tks/tps>admin.
Password:
Password for the administrator user.
Import certificate:
An optional parameter that can be used to import an already available CA admin
certificate into this instance.
Export certificate:
Setup the path where the admin certificate of this <subsystem> should be stored.
The default value is $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.
Directory Server Parameters
Hostname:
Hostname of the directory server instance. The default value is the hostname of the
system.
Use a secure LDAPS connection?
Answering yes to this question will cause prompts for Secure LDAPS Port: and Directory
Server CA certificate pem file:.
Answering no to this question will cause a prompt for LDAP Port.
The initial default value for this question is no.
Secure LDAPS Port:
Secure LDAPS port for the directory server instance. The default value is 636.
Directory Server CA certificate PEM file:
The fully-qualified path including the filename of the file which contains an exported
copy of the Directory Server's CA certificate (e.g. $HOME/dscacert.pem).
This file must exist prior to pkispawn being able to utilize it.
For details on creation of this file see the EXAMPLES section below entitled
Installing PKI Subsystem with Secure LDAP Connection.
LDAP Port:
LDAP port for the directory server instance. The default value is 389.
Base DN:
The Base DN to be used for the internal database for this subsystem.
The default value is o=pki-tomcat-<subsystem>.
Bind DN:
The bind DN required to connect for the directory server.
This user must have sufficient permissions to install the required schema and
database.
The default value is cn=Directory Manager.
Password:
Password for the bind DN.
Security Domain Parameters
Name:
The name of the security domain. Required only if installing a root CA.
Default value: <DNS domain name> Security Domain.
Hostname:
The hostname for the security domain CA. Required only for non-CA subsystems.
The default value is the hostname of this system.
Secure HTTP port:
The https port for the security domain. Required only for non-CA subsystems. The
default value is 8443.
Username:
The username of the security domain administrator of the CA.
Required only for non-CA subsystems.
The default value is caadmin.
Password:
Password for the security domain administrator. Required for all subsystems that are
not root CAs.
PRE-CHECK MODE
This option is only available when pkispawn is invoked in a non-interactive mode. When
the --precheck option is provided, a set of basic tests are performed to ensure that the
parameters provided to pkispawn are valid and consistent.
pkispawn will then exit with an exit code of 0 on success, or 1 on failure. This mode can
be used to perform basic tests prior to doing any actual installation of the PKI server
instance.
Flags are available to disable specific tests. For instance, one might want to disable
validation of the credentials for the internal database user if the directory server
instance has not yet been created.
See pki_default.cfg(5) for more details about available flags.
TWO-STEP INSTALLATION MODE
pkispawn provides a number of parameters to customize an instance before it is created.
Usually, most other customization can be done after the server is created. However,
sometimes certain types of customization need to be done before the server is created, but
there are no parameters for that. For example, configuring session timeout, adding CSR
extensions, customizing certificate profiles, configuring TLS ciphers, etc. To support
such customization, pkispawn provides a two-step installation mode.
Generally, instance creation happens in one step (except for the external CA case).
Internally, the process happens in two stages. In the first stage, pkispawn will install
the instance files (e.g. CS.cfg, NSS database, profiles, etc.) in the instance directory
and customize them based on pkispawn parameters. In the second stage, pkispawn will start
the instance and configure the instance based on the instance configuration files (e.g.
initializing database, generating certificates, configuring connectors, etc.). The
two-step process allows the process to be stopped after the first stage, allowing further
customization to be done before running the second stage.
To use two-step installation mode, prepare a normal pkispawn configuration file, then run
pkispawn with the --skip-configuration parameter. For example:
$ pkispawn -s CA -f myconfig.txt --skip-configuration
Then customize the files in the instance directory as needed. Finally, finish the
installation by running pkispawn again with the --skip-installation parameter. For
example:
$ pkispawn -s CA -f myconfig.txt --skip-installation
EXAMPLES
Installing Root CA
To install a root CA in a new instance execute the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
Prior to running this command, a Directory Server instance should be created and running.
This command assumes that the Directory Server instance is using its default
configuration:
• Installed on the local machine
• Listening on port 389
• The user is cn=Directory Manager, with the password specified in pki_ds_password
This invocation of pkispawn creates a Tomcat instance containing a CA running on the local
machine with secure port 8443 and unsecure port 8080. To access this CA, simply point a
browser to https://hostname:8443.
The instance name (defined by pki_instance_name) is pki-tomcat, and it is located at
/var/lib/pki/pki-tomcat. Logs for the instance are located at /var/log/pki/pki-tomcat, and
an installation log is written to /var/log/pki/pki-subsystem-spawn.timestamp.log.
A PKCS #12 file containing the administrator certificate is created in
$HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password designated by
pki_client_pkcs12_password in the configuration file.
To access the agent pages, first import the CA certificate by accessing the CA End Entity
Pages and clicking on the Retrieval Tab. Be sure to trust the CA certificate. Then, import
the administrator certificate in the PKCS #12 file.
Installing Root CA using ECC
To install a root CA in a new instance using ECC execute the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_admin_key_algorithm=SHA256withEC
pki_admin_key_size=nistp256
pki_admin_key_type=ecc
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_sslserver_key_algorithm=SHA256withEC
pki_sslserver_key_size=nistp256
pki_sslserver_key_type=ecc
pki_subsystem_key_algorithm=SHA256withEC
pki_subsystem_key_size=nistp256
pki_subsystem_key_type=ecc
[CA]
pki_ca_signing_key_algorithm=SHA256withEC
pki_ca_signing_key_size=nistp256
pki_ca_signing_key_type=ecc
pki_ca_signing_signing_algorithm=SHA256withEC
pki_ocsp_signing_key_algorithm=SHA256withEC
pki_ocsp_signing_key_size=nistp256
pki_ocsp_signing_key_type=ecc
pki_ocsp_signing_signing_algorithm=SHA256withEC
In order to utilize ECC, the SSL Server and Subsystem key algorithm, key size, and key
type should be changed from SHA256withRSA to SHA256withEC, 2048 to nistp256, and rsa to
ecc, respectively. To use an ECC admin key size and key type, the values should also be
changed from 2048 to nistp256, and rsa to ecc.
Additionally, for a CA subsystem, both the CA and OCSP Signing key algorithm, key size,
key type, and signing algorithm should be changed from SHA256withRSA to SHA256withEC, 2048
to nistp256, rsa to ecc, and SHA256withRSA to SHA256withEC, respectively.
Note: For all PKI subsystems including the CA, ECC is not supported for the corresponding
Audit Signing parameters. Similarly, for KRA subsystems, ECC is not supported for either
of the corresponding Storage or Transport parameters.
Installing KRA, OCSP, TKS, or TPS in Shared Instance
For this example, assume that a new CA instance has been installed by executing the
following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
To install a shared KRA in the same instance used by the CA execute the following command:
$ pkispawn -s KRA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
To install a shared OCSP in the same instance used by the CA execute the following
command:
$ pkispawn -s OCSP -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
To install a shared TKS in the same instance used by the CA execute the following command:
$ pkispawn -s TKS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
To install a shared TPS in the same instance used by the CA execute the following command:
$ pkispawn -s TPS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[TPS]
# Shared TPS instances optionally utilize their shared KRA
# for server-side keygen
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
Note: For this particular example, the computed default values for a PKI instance name
including its ports, URLs, machine names, etc. were utilized as defined in
/usr/share/pki/server/etc/default.cfg. Each subsystem in this example will reside under
the /var/lib/pki/pki-tomcat instance housed within their own ca, kra, ocsp, tks, and tps
subdirectories, utilizing the same default port values of 8080 (http), 8443 (https), 8009
(ajp), 8005 (tomcat), using the same computed hostname and URL information, and sharing a
single common PKI Administrator Certificate.
The pki_security_domain_password is the admin password of the CA installed in the same
instance. This command should be run after a CA is installed. This installs another
subsystem within the same instance using the certificate generated for the CA
administrator for the subsystem's administrator. This allows a user to access both
subsystems on the browser with a single administrator certificate. To access the new
subsystem's functionality, simply point the browser to https://hostname:8443 and click the
relevant top-level links.
To install TPS in a shared instance the following section must be added to myconfig.txt:
[TPS]
pki_authdb_basedn=dc=example,dc=com
TPS requires an authentication database. The pki_authdb_basedn specifies the base DN of
the authentication database.
TPS also requires that a CA and a TKS subsystems are already installed in the same
instance. Since they are in the same instance, a shared secret key will automatically be
generated in TKS and imported into TPS.
Optionally, server-side key generation can be enabled in TPS by adding the following
parameter in [TPS]:
pki_enable_server_side_keygen=True
Enabling server-side key generation requires that a KRA subsystem is already installed in
the same instance.
Installing KRA, OCSP, TKS, or TPS in Separate Instance
For this example, assume that a new CA instance has been installed by executing the
following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated CA instance name and ports
pki_instance_name=pki-ca
pki_http_port=18080
pki_https_port=18443
# This Separated CA instance will be its own security domain
pki_security_domain_https_port=18443
[Tomcat]
# Separated CA Tomcat ports
pki_ajp_port=18009
pki_tomcat_server_port=18005
To install a separate KRA which connects to this remote CA execute the following command:
$ pkispawn -s KRA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated KRA instance name and ports
pki_instance_name=pki-kra
pki_http_port=28080
pki_https_port=28443
# Separated KRA instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated KRA Tomcat ports
pki_ajp_port=28009
pki_tomcat_server_port=28005
[KRA]
# A Separated KRA instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
To install a separate OCSP which connects to this remote CA execute the following command:
$ pkispawn -s OCSP -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated OCSP instance name and ports
pki_instance_name=pki-ocsp
pki_http_port=29080
pki_https_port=29443
# Separated OCSP instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated OCSP Tomcat ports
pki_ajp_port=29009
pki_tomcat_server_port=29005
[OCSP]
# A Separated OCSP instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
To install a separate TKS which connects to this remote CA execute the following command:
$ pkispawn -s TKS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated TKS instance name and ports
pki_instance_name=pki-tks
pki_http_port=30080
pki_https_port=30443
# Separated TKS instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated TKS Tomcat ports
pki_ajp_port=30009
pki_tomcat_server_port=30005
[TKS]
# A Separated TKS instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
To install a separate TPS which connects to this remote CA execute the following command:
$ pkispawn -s TPS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated TPS instance name and ports
pki_instance_name=pki-tps
pki_http_port=31080
pki_https_port=31443
# Separated TPS instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated TPS Tomcat ports
pki_ajp_port=31009
pki_tomcat_server_port=31005
[TPS]
# Separated TPS instances require specifying a remote CA
pki_ca_uri=https://pki.example.com:18443
# Separated TPS instances optionally utilize a remote KRA
# for server-side keygen
pki_kra_uri=https://pki.example.com:28443
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
# Separated TPS instances require specifying a remote TKS
pki_tks_uri=https://pki.example.com:30443
pki_import_shared_secret=True
# A Separated TPS instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
Note: For this particular example, besides passwords, sample values were also utilized for
PKI instance names, ports, URLs, machine names, etc. Under no circumstances should these
demonstrative values be construed to be required literal values.
A remote CA is one where the CA resides in another PKI server instance, either on the
local machine or a remote machine. In this case, myconfig.txt must specify the connection
information for the remote CA and the information about the security domain (the trusted
collection of subsystems within an instance).
The subsystem section is [KRA], [OCSP], [TKS], or [TPS]. This example assumes that the
specified CA hosts the security domain. The CA must be running and accessible.
A new administrator certificate is generated for the new subsystem and stored in a PKCS
#12 file in $HOME/.dogtag/pki_instance_name.
As in a shared instance, to install TPS in a separate instance the authentication database
must be specified in the [TPS] section, and optionally the server-side key generation can
be enabled. If the CA, KRA, or TKS subsystems required by TPS are running on a remote
instance the following parameters must be added into the [TPS] section to specify their
locations:
pki_ca_uri=https://<ca_hostname>:<ca_https_port>
pki_kra_uri=https://<kra_hostname>:<kra_https_port>
pki_tks_uri=https://<tks_hostname>:<tks_https_port>
If TPS and TKS are installed on separate instances the shared secret key should be
imported over the wire between the TKS and TPS automatically.
If the automated procedure fails for any unlikely reason the following manual procedure
will serve as a fallback. The key needs to be created on the TKS side and imported into
the TPS side in this case.
Generate the shared secret key (if needed) in TKS with the following command:
$ tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
Verify the shared secret key in TKS with the following command:
$ tkstool -L -d /var/lib/pki/pki-tomcat/alias
Once TPS is installed, shutdown TPS instance, then import the shared secret key into TPS
with the following command:
$ tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
Verify the shared secret key in TPS with the following command:
$ tkstool -L -d /var/lib/pki/pki-tomcat/alias
The shared secret key nickname should be stored in the following property in the TPS's
CS.cfg:
conn.tks1.tksSharedSymKeyName=sharedSecret
Finally, restart the TPS instance.
Installing CA, KRA, OCSP, TKS, or TPS using HSM
This section provides sample myconfig.txt files when a Hardware Security Module (HSM) is
being utilized in a shared PKI instance.
For this example, assume that a new CA instance has been installed by executing the
following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[CA]
# Provide CA-specific HSM token names
pki_ca_signing_token=<hsm_token_name>
pki_ocsp_signing_token=<hsm_token_name>
To install a shared KRA in the same instance used by the CA execute the following command:
$ pkispawn -s KRA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[KRA]
# Provide KRA-specific HSM token names
pki_storage_token=<hsm_token_name>
pki_transport_token=<hsm_token_name>
To install a shared OCSP in the same instance used by the CA execute the following
command:
$ pkispawn -s OCSP -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[OCSP]
# Provide OCSP-specific HSM token names
pki_ocsp_signing_token=<hsm_token_name>
To install a shared TKS in the same instance used by the CA execute the following command:
$ pkispawn -s TKS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
To install a shared TPS in the same instance used by the CA execute the following command:
$ pkispawn -s TPS -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[TPS]
# Shared TPS instances optionally utilize their shared KRA
# for server-side keygen
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
Important: Since HSM keys are stored in the HSM, they cannot be backed up, moved, or
copied to a PKCS #12 file. For example, if pki_hsm_enable is set to True, pki_backup_keys
should be set to False and pki_backup_password should be left unset (the default values in
/usr/share/pki/server/etc/default.cfg). Similarly, for the case of clones using an HSM,
this means that the HSM keys must be shared between the master and its clones. Therefore,
if pki_hsm_enable is set to True, both pki_clone_pkcs12_path and pki_clone_pkcs12_password
should be left unset (the default values in /usr/share/pki/server/etc/default.cfg).
Failure to comply with these rules will result in pkispawn reporting an appropriate error
and exiting.
Installing CA Clone
To install a CA clone execute the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
pki_security_domain_post_login_sleep_seconds=5
[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=Secret.123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
A cloned CA is a CA which uses the same signing, OCSP signing, and audit signing
certificates as the master CA, but issues certificates within a different serial number
range. It has its own internal database -- separate from the master CA database -- but
using the same base DN, that keeps in sync with the master CA through replication
agreements between the databases. This is very useful for load sharing and disaster
recovery. To create a clone, the myconfig.txt uses pkiclone* parameters in its [Tomcat]
section which identify the original CA to use as a master template. Additionally, it
connects to the master CA as a remote CA and uses its security domain.
Before the clone can be generated, the Directory Server must be created that is separate
from the master CA's Directory Server. The example assumes that the master CA and cloned
CA are on different machines, and that their Directory Servers are on port 389.
In addition, since this example does not utilize an HSM, the master's system certs and
keys have been stored in a PKCS #12 file that is copied over to the clone subsystem in the
location specified in <path_to_pkcs12_file>. This file needs to be readable by the user
the Certificate Server runs as (by default, pkiuser) and be given the SELinux context
pki_tomcat_cert_t.
The master's system certificates can be exported to a PKCS#12 file when the master is
installed if the parameter pki_backup_keys is set to True and the pki_backup_password is
set. The PKCS#12 file is then found under /var/lib/pki/<instance_name>/alias.
Alternatively, the PKCS#12 file can be generated at any time post-installation using
PKCS12Export.
The pki_security_domain_post_login_sleep_seconds config specifies sleep duration after
logging into a security domain, to allow the security domain session data to be replicated
to subsystems on other hosts. It is optional and defaults to 5 seconds.
An example invocation showing the export of the system certificates and keys, copying the
keys to the replica subsystem, and setting the relevant SELinux and file permissions is
shown below. pwfile is a text file containing the password for the masters NSS DB (found
in /etc/pki/instance_name/password.conf). pkcs12_password_file is a text file containing
the password selected for the generated PKCS12 file.
master# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \
-w pkcs12_password_file -o backup_keys.p12
master# scp backup_keys.p12 clone:/backup_keys.p12
clone# chown pkiuser: /backup_keys.p12
clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
Note: From Dogtag 10.3, a slightly different mechanism has been provided to create and
specify the required PKCS#12 file to the clone subsystem. This new method is provided in
addition to the method above, but will become the preferred method in future releases.
This method can be used if both master and clone are 10.3 or above.
To export the required keys from the master, use the pki-server command line tool.
master# pki-server ca-clone-prepare -i pki-tomcat \
--pkcs12-file backup_keys.p12 \
--pkcs12-password Secret123
master# scp backup_keys.p12 clone:/backup_keys.p12
master# scp /etc/pki/pki-tomcat/external_certs.conf \
clone:/external_certs.conf
The external_certs.conf file contains information about third party certificates that were
added to the master's certificate database using the pki-server command. The certificates
themselves are stored in the backup_keys.p12 file. If there are no third-party certifcates
that have been added, then the external_certs.conf file may not exist and should be
ignored.
The two files (backup_keys.p12 and external_certs.conf) are specified to pkispawn as
below.
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[Tomcat]
pki_server_pkcs12_path=<path to pkcs12 file>
pki_server_pkcs12_password=Secret.123
pki_server_external_certs_path=<path to external_certs.conf file>
pki_clone=True
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
Note that the previous p12 parameters (pki_clonepkcs12*) are no longer needed, and will be
ignored.
Note: One current cloning anomaly to mention is the following scenario:
1. Create a clone of a CA or of any other subsystem.
2. Remove that just created clone.
3. Immediately attempt the exact same clone again, in place of the recently
destroyed instance. Before recreating this clone, make sure the
pki_ds_remove_data=True is used in the clone's deployment config file. This
will remove the old data from the previous clone.
Here the Director Server instance may have worked itself in into a state where it no
longer accepts connections, aborting the clone configuration quickly.
The fix to this is to simply restart the Directory Server instance before creating the
clone for the second time. After restarting the Directory Server it should be possible to
create the mentioned clone instance.
Installing KRA or TKS Clone
To install a KRA or TKS (OCSP and TPS unsupported as of now) execute the following
command:
$ pkispawn -s <subsystem> -f myconfig.txt
where subsystem is KRA or TKS and myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=Secret.123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
As with a CA clone, a KRA or TKS clone uses the same certificates and basic configuration
as the original subsystem. The configuration points to the original subsystem to copy its
configuration. This example also assumes that the CA is on a remote machine and specifies
the CA and security domain information.
The parameter pki_clone_uri should be modified to point to the required master (KRA or
TKS).
As of 10.3, a slightly different mechanism has been introduced to generate and specify the
PKCS#12 file and any third-party certificates. See the Installing CA Clone section for
details.
Installing CA Clone on the Same Host
For testing purposes, it is useful to configure cloned CAs which exist (with their
internal databases) on the same host as the master CA. To configure the cloned CA execute
the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_ds_ldap_port=<unique port different from master>
pki_ds_ldaps_port=<unique port different from master>
pki_http_port=<unique port different from master>
pki_https_port=<unique port different from master>
pki_instance_name=<unique name different from master>
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_password=Secret123
[Tomcat]
pki_ajp_port=<unique port different from master>
pki_clone=True
pki_clone_pkcs12_password=Secret123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
pki_tomcat_server_port=<unique port different from master>
[CA]
pki_ds_base_dn=<identical value as master>
pki_ds_database=<identical value as master>
In this case, because both CA Tomcat instances are on the same host, they must have
distinct ports. Similarly, each CA must use a distinct directory server instance for its
internal database. Like the Tomcat instances, these are distinguished by distinct ports.
The suffix being replicated (pki_ds_base), however, must be the same for both master and
clone.
Installing Subordinate CA in Existing Security Domain
To install a subordinate CA in an existing security domain execute the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<security_domain_ca_hostname>
pki_security_domain_https_port=<security_domain_ca_https_port>
pki_security_domain_user=caadmin
[CA]
pki_subordinate=True
pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
A sub-CA derives its certificate configuration -- such as allowed extensions and validity
periods -- from a superior or root CA. Otherwise, the configuration of the CA is
independent of the root CA, so it is its own instance rather than a clone. A sub-CA is
configured using the pki_subordinate parameter and a pointer to the CA which issues the
sub-CA's certificates.
Note: The value of pki_ca_signing_subject_dn of a subordinate CA should be different from
the root CA's signing subject DN.
Installing Subordinate CA in New Security Domain
To install a subordinate CA in a new security domain execute the following command:
$ pkispawn -s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master CA security domain hostname>
pki_security_domain_https_port=<master CA security domain https port>
pki_security_domain_user=caadmin
[CA]
pki_subordinate=True
pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
pki_subordinate_create_new_security_domain=True
pki_subordinate_security_domain_name=Subordinate CA Security Domain
In this section, the subordinate CA logs onto and registers with the security domain CA
(using parameters pki_security_domain_hostname, pki_security_domain_user and
pki_security_domain_password) as in the previous section, but also creates and hosts a new
security domain. To do this, pki_subordinate_create_new_security_domain must be set to
True. The subordinate CA security domain name can also be specified by specifying a value
for pki_subordinate_security_domain_name.
Note: The value of pki_ca_signing_subject_dn of a subordinate CA should be different from
the root CA's signing subject DN.
Installing Externally-Signed CA
To install an externally signed CA execute the following command:
$ pkispawn -s CA -f myconfig.txt
This is a two-step process.
In the first step, a certificate signing request (CSR) is generated for the signing
certificate and myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[CA]
pki_external=True
pki_ca_signing_csr_path=/tmp/ca_signing.csr
pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
The CSR is written to pki_ca_signing_csr_path. The pki_ca_signing_subject_dn should be
different from the subject DN of the external CA that is signing the request. The
pki_ca_signing_subject_dn parameter can be used to specify the signing certificate's
subject DN.
The CSR is then submitted to the external CA, and the resulting certificate and
certificate chain are saved to files on the system.
In the second step, the configuration file has been modified to install the issued
certificates. In place of the original CSR, the configuration file now points to the
issued CA certificate and certificate chain. There is also a flag to indicate that this
completes the installation process (pki_external_step_two).
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[CA]
pki_external=True
pki_external_step_two=True
pki_cert_chain_path=/tmp/ca_cert_chain.cert
pki_ca_signing_cert_path=/tmp/ca_signing.cert
pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
Then, the pkispawn command is run again:
$ pkispawn -s CA -f myconfig.txt
Installing PKI Subsystem with Secure LDAP Connection
There are three scenarios in which a PKI subsystem (e.g. a CA) needs to communicate
securely via LDAPS with a directory server:
Scenario 1: A directory server exists which is already running LDAPS using a CA
certificate that has been issued by some other CA. For this scenario, the CA certificate
must be made available via a PEM file (e.g. $HOME/dscacert.pem) prior to running pkispawn
such that the new CA may be installed and configured to communicate with this directory
server using LDAPS.
Scenario 2: A directory server exists which is currently running LDAP. Once a CA has been
created, there is a desire to use its CA certificate to issue an SSL certificate for this
directory server so that this CA and this directory server can communicate via LDAPS. For
this scenario, since there is no need to communicate securely during the pkispawn
installation/configuration, simply use pkispawn to install and configure the CA using the
LDAP port of the directory server, issue an SSL certificate from this CA for the directory
server, and then reconfigure the CA and directory server to communicate with each other
via LDAPS.
Scenario 3: Similar to the previous scenario, a directory server exists which is currently
running LDAP, and the desire is to create a CA and use it to establish LDAPS
communications between this CA and this directory server. However, for this scenario,
there is a need for the CA and the directory server to communicate securely during
pkispawn installation and configuration. For this to succeed, the directory server must
generate a temporary self-signed certificate which then must be made available via a PEM
file (e.g. $HOME/dscacert.pem) prior to running pkispawn. Once the CA has been created,
swap things out to reconfigure the CA and directory server to utilize LDAPS through the
desired certificates.
The following example demonstrates the steps to generate a temporary self-signed
certificate in the Directory Server which requires an Admin Server. Directory Server and
Admin Server instances can be created with the following command:
$ setup-ds.pl
Enable LDAPS in the Directory Server with the following command:
$ /usr/sbin/setupssl2.sh /etc/dirsrv/slapd-pki 389 636 Secret.123
Note: The setupssl2.sh script may be downloaded from
⟨https://raw.githubusercontent.com/richm/scripts/master/setupssl2.sh⟩.
Restart the Directory Server with the following command:
$ systemctl restart dirsrv.target
Verify that a client can connect securely over LDAPS with the following command:
$ /usr/lib64/mozldap/ldapsearch -Z -h pki.example.com -p 636 \
-D "cn=Directory Manager" -w Secret.123 -b "dc=example, dc=com" "objectclass=*"
Note: The mozldap ldapsearch utility is available from the mozldap-tools package.
Export the self-signed CA certificate with the following command:
$ certutil -L -d /etc/dirsrv/slapd-pki -n "CA certificate" -a > $HOME/dscacert.pem
Once the self-signed CA certificate is obtained, add the following parameters into the
[DEFAULT] section in myconfig.txt:
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
Then execute pkispawn to create the CA subsystem.
Managing PKI instance
To start all 389 instances (local PKI databases):
$ systemctl start dirsrv.target
To stop all 389 instances (local PKI databases):
$ systemctl stop dirsrv.target
To restart all 389 instances (local PKI databases):
$ systemctl restart dirsrv.target
To obtain the status of all 389 instances (local PKI databases):
$ systemctl status dirsrv.target
To start a PKI instance named <pki_instance_name>:
$ systemctl start pki-tomcatd@<pki_instance_name>.service
To stop a PKI instance named <pki_instance_name>:
$ systemctl stop pki-tomcatd@<pki_instance_name>.service
To restart a PKI instance named <pki_instance_name>:
$ systemctl restart pki-tomcatd@<pki_instance_name>.service
To obtain the status of a PKI instance named <pki_instance_name>:
$ systemctl status pki-tomcatd@<pki_instance_name>.service
To obtain a detailed status of a Tomcat PKI instance named <pki_instance_name>:
$ pkidaemon status tomcat <pki_instance_name>
To obtain a detailed status of all Tomcat PKI instances:
$ pkidaemon status tomcat
SEE ALSO
pkidestroy(8)
pki_default.cfg(5)
pki(1)
setup-ds.pl(8)
AUTHORS
Ade Lee ⟨alee@redhat.com⟩.
COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General Public License,
version 2 (GPLv2). A copy of this license is available at
⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.