Provided by: pki-server_10.2.6+git20160317-1_amd64 
NAME
pkispawn - Sets up an instance of Certificate Server.
SYNOPSIS
pkispawn -s <subsystem> -f <config_file> [-h] [-v] [-p <prefix>]
DESCRIPTION
Sets up a Certificate Server 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.
Certificate 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
(/etc/pki/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 Certificate Server instance can also be accessed using the pki command line interface. See pki(1).
For more extensive documentation on how to use Certificate Server 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.
-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.
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 a CA connecting securely to a Directory Server via LDAPS.
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.
EXAMPLES
Installing a 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=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
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 a 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=Secret123
pki_admin_keysize=nistp256
pki_admin_key_type=ecc
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_ssl_server_key_algorithm=SHA256withEC
pki_ssl_server_key_size=nistp256
pki_ssl_server_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 --> SHA256withEC, 2048 --> nistp256, and rsa --> ecc, respectively. To use an
ECC admin key size and key type, the values should also be changed from 2048 --> nistp256, and rsa -->
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 --> SHA256withEC, 2048 --> nistp256, rsa --> ecc,
and SHA256withRSA --> 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 a KRA, OCSP, TKS, or TPS in a shared instance
To install a KRA, OCSP, TKS, or TPS in the same instance used by the CA execute
the following command:
pkispawn -s <subsystem> -f myconfig.txt
where subsystem is KRA, OCSP, TKS, or TPS, and 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_security_domain_password=Secret123
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 a KRA, OCSP, TKS, or TPS in a separate instance
To install a KRA, OCSP, TKS, or TPS with a remote a CA execute the following command:
pkispawn -s <subsystem> -f myconfig.txt
where subsystem is KRA, OCSP, TKS, or TPS, and 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_security_domain_password=Secret123
pki_security_domain_hostname=<ca_hostname>
pki_security_domain_https_port=<ca_https_port>
pki_security_domain_user=caadmin
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
[KRA/OCSP/TKS/TPS]
pki_import_admin_cert=False
A remote CA is one where the CA resides in another Certificate 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-tomcat.
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 needs to be generated manually
in TKS, then manually imported into TPS.
Generate the shared secret key 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 a 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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
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=Secret123
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 pki_clone-* 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.
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 master 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: 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 a 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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
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=Secret123
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).
Installing a 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 a 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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
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 a 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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
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 an 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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
[CA]
pki_external=True
pki_external_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_external_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=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_security_domain_password=Secret123
[CA]
pki_external=True
pki_external_ca_cert_chain_path=/tmp/ca_cert_chain.cert
pki_external_ca_cert_path=/tmp/ca_signing.cert
pki_external_step_two=True
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 a PKI subsystem with a 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:
* 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.
* 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.
* 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-admin.pl
Enable LDAPS in the Directory Server with the following command:
/usr/sbin/setupssl2.sh /etc/dirsrv/slapd-pki 389 636 Secret123
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 Secret123
-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
BUGS
Report bugs to http://bugzilla.redhat.com.
AUTHORS
Ade Lee <alee@redhat.com>. pkispawn was written by the Certificate Server project.
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.
SEE ALSO
pkidestroy(8), pki_default.cfg(5), pki(1), setup-ds.pl(8)
version 1.0 December 13, 2012 pkispawn(8)