pki_default.cfg(5) PKI Default Instance Configuration pki_default.cfg(5)NAMEpki_default.cfg - Certificate Server instance default config file.
LOCATION
/etc/pki/default.cfg
DESCRIPTION
This file contains the default settings for a Certificate Server
instance created using pkispawn. This file should not be edited, as it
can be modified when the Certificate Server packages are updated.
Rather, when setting up a Certificate Server instance, a user-provided
configuration file can provide overrides to the defaults in
/etc/pki/default.cfg. See pkispawn(8) for details.
SECTIONS
default.cfg is divided into subsystem-based sections ([DEFAULT] for
general configuration and subsystem-type sections such as [CA] and
[KRA]). These sections are stacked, so that parameters read in earlier
sections can be overwritten by parameters in later sections. For the
Java subsystems (CA, KRA, OCSP, and TKS), the sections read are
[DEFAULT], [Tomcat] and the subsystem type section -- [CA], [KRA],
[OCSP], and [TKS] -- in that order. This allows the ability to specify
parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and
subsystem-specific upgrades in the other sections.
There are a small number of bootstrap parameters which are passed in
the configuration file by pkispawn. Other parameter's values can be
interpolated tokens rather than explicit values. For example:
pki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA
This substitutes the value of pki_instance_name into the parameter
value. It is possible to interpolate any parameter within a section or
in [DEFAULT]. Any parameter used in interpolation can ONLY be overrid‐
den within the same section. So, for example, pki_instance_name should
only be overridden in [DEFAULT]; otherwise, interpolations can fail.
GENERAL INSTANCE PARAMETERS
The parameters described below, as well as the parameters located in
the following sections, can be customized as part of a deployment.
This list is not exhaustive.
pki_instance_name
Name of the instance. The instance is located at
/var/lib/pki/<instance_name>. For Java subsystems, the default
is specified as pki-tomcat.
pki_https_port, pki_http_port
Secure and unsecure ports. Defaults to standard Tomcat ports
8443 and 8080, respectively, for Java subsystems, and 443 and 80
for Apache subsystems.
pki_ajp_port, pki_tomcat_server_port
Ports for Tomcat subsystems. Defaults to standard Tomcat ports
of 8009 and 8005, respectively.
pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy
Ports for an Apache proxy server. Certificate Server instances
can be run behind an Apache proxy server, which will communicate
with the Tomcat instance through the AJP port. See the Red Hat
Certificate System documentation at https://access.red‐
hat.com/knowledge/docs/Red_Hat_Certificate_System/ for details.
pki_user, pki_group, pki_audit_group
Specifies the default administrative user, group, and auditor
group identities for PKI instances. The default user and group
are both specified as pkiuser, and the default audit group is
specified as pkiaudit.
pki_token_name, pki_token_password
The token and password where this instance's system certificate
and keys are stored. Defaults to the NSS internal software
token.
SYSTEM CERTIFICATE PARAMETERS
pkispawn sets up a number of system certificates for each subsystem.
The system certificates which are required differ between subsystems.
Each system certificate is denoted by a tag, as noted below. The dif‐
ferent system certificates are:
* signing certificate ("signing"). Used to sign other certifi‐
cates. Required for CA.
* OCSP signing certificate ("ocsp_signing" in CA, "signing" in
OCSP). Used to sign CRLs. Required for OCSP and CA.
* storage certificate ("storage"). Used to encrypt keys for
storage in KRA. Required for KRA only.
* transport certificate ("transport"). Used to encrypt keys in
transport to the KRA. Required for KRA only.
* subsystem certificate ("subsystem"). Used to communicate
between subsystems within the security domain. Issued by the
security domain CA. Required for all subsystems.
* server certificate ("sslserver"). Used for communication with
the server. One server certificate is required for each Cer‐
tificate Server instance.
* audit signing certificate ("audit_signing"). Used to sign
audit logs. Required for all subsystems except the RA.
Each system certificate can be customized using the parameters below:
pki_<tag>_key_type, pki_<type>_keysize, pki_<tag>_key_algorithm
Characteristics of the private key. See the Red Hat Certificate
System documentation at https://access.redhat.com/knowl‐
edge/docs/Red_Hat_Certificate_System/ for possible options. The
defaults are RSA for the type, 2048 bits for the key size, and
SHA256withRSA for the algorithm.
pki_<tag>_signing_algorithm
For signing certificates, the algorithm used for signing.
Defaults to SHA256withRSA.
pki_<tag>_token
Location where the certificate and private key are stored.
Defaults to the internal software NSS token database.
pki_<tag>_nickname
Nickname for the certificate in the token database.
pki_<tag>_subject_dn
Subject DN for the certificate. The subject DN for the SSL
Server certificate must include CN=<hostname>.
ADMIN USER PARAMETERS
pkispawn creates a bootstrap administrative user that is a member of
all the necessary groups to administer the installed subsystem. On a
security domain CA, the CA administrative user is also a member of the
groups required to register a new subsystem on the security domain.
The certificate and keys for this administrative user are stored in a
PKCS #12 file in pki_client_dir, and can be imported into a browser to
administer the system.
pki_admin_name, pki_admin_uid
Name and UID of this administrative user. Defaults to caadmin
for CA, kraadmin for KRA, etc.
pki_admin_password
Password for the admin user. This password is used to log into
the pki-console (unless client authentication is enabled), as
well as log into the security domain CA.
pki_admin_email
Email address for the admin user.
pki_admin_dualkey, pki_admin_keysize, pki_admin_keytype
Settings for the administrator certificate and keys.
pki_admin_subject_dn
Subject DN for the administrator certificate. Defaults to
cn=PKI Administrator, e=%(pki_admin_email)s, o=%(pki_secu‐
rity_domain_name)s.
pki_admin_nickname
Nickname for the administrator certificate.
pki_import_admin_cert
Set to True to import an existing admin certificate for the
admin user, rather than generating a new one. A subsystem-spe‐
cific administrator will still be created within the subsystem's
LDAP tree. This is useful to allow multiple subsystems within
the same instance to be more easily administered from the same
browser by using a single certificate.
By default, this is set to False for CA subsystems and true for
KRA, OCSP, and TKS subsystems. In this case, the admin certifi‐
cate is read from the file ca_admin.cert in pki_client_dir.
Note that cloned subsystems do not create a new administrative
user. The administrative user of the master subsystem is used
instead, and the details of this master user are replicated dur‐
ing the install.
pki_client_admin_cert_p12
Location for the PKCS #12 file containing the administrative
user's certificate and keys. For a CA, this defaults to
ca_admin_cert.p12 in the pki_client_dir directory.
BACKUP PARAMETERS
pki_backup_keys, pki_backup_password
Set to True to back up the subsystem certificates and keys to a
PKCS #12 file. This file will be located in
/var/lib/pki/<instance_name>/alias. pki_backup_password is the
password of the PKCS#12 file.
CLIENT DIRECTORY PARAMETERS
pki_client_dir
This is the location where all client data used during the
installation is stored. At the end of the invocation of
pkispawn, the administrative user's certificate and keys are
stored in a PKCS #12 file in this location.
pki_client_database_dir, pki_client_database_password
Location where an NSS token database is created in order to gen‐
erate a key for the administrative user. Usually, the data in
this location is removed at the end of the installation, as the
keys and certificates are stored in a PKCS #12 file in
pki_client_dir.
pki_client_database_purge
Set to True to remove pki_client_database_dir at the end of the
installation. Defaults to True.
INTERNAL DATABASE PARAMETERS
pki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port
Hostname and ports for the internal database. Defaults to
localhost, 389, and 636, respectively.
pki_ds_bind_dn, pki_ds_password
Credentials to connect to the database during installation.
Directory Manager-level access is required during installation
to set up the relevant schema and database. During the instal‐
lation, a more restricted Certificate Server user is set up to
client authentication connections to the database. Some addi‐
tional configuration is required, including setting up the
directory server to use SSL. See the documentation for details.
pki_ds_secure_connection
Sets whether to require connections to the Directory Server
using LDAPS. This requires SSL to be set up on the Directory
Server first. Defaults to false.
pki_ds_remove_data
Sets whether to remove any data from the base DN before starting
the installation. Defaults to True.
pki_ds_base_dn
The base DN for the internal database. It is advised that the
Certificate Server have its own base DN for its internal data‐
base. If the base DN does not exist, it will be created during
the running of pkispawn. For a cloned subsystem, the base DN
for the clone subsystem MUST be the same as for the master sub‐
system.
pki_ds_database
Name of the back-end database. It is advised that the Certifi‐
cate Server have its own base DN for its internal database. If
the back-end does not exist, it will be created during the run‐
ning of pkispawn.
ISSUING CA PARAMETERS
pki_issuing_ca_hostname, pki_issuing_ca_https_port, pki_issuing_ca_uri
Hostname and port, or URI of the issuing CA. Required for
installations of subordinate CA and non-CA subsystems. This
should point to the CA that will issue the relevant system cer‐
tificates for the subsystem. In a default install, this
defaults to the CA subsystem within the same instance. The URI
has the format https://<ca_hostname>:<ca_https_port>.
MISCELLANEOUS PARAMETERS
pki_restart_configured_instance
Sets whether to restart the instance after configuration is com‐
plete. Defaults to True.
pki_skip_configuration
Sets whether to execute the configuration steps when running
pkispawn. If this is true, then the process is analogous to
running pkicreate, when the configuration was performed sepa‐
rately from the instance creation. A configuration URL will be
provided. This URL can be used as a starting point for the
browser-based configuration panels. Defaults to False.
pki_skip_installation
Sets whether to skip the installation steps. With pki_skip_con‐
figuration set to False, this is analogous to running pkisilent.
Defaults to False.
pki_enable_java_debugger
Sets whether to attach a Java debugger such as Eclipse to the
instance for troubleshooting. Defaults to False.
pki_security_manager
Enables the Java security manager policies provided by the JDK
to be used with the instance. Defaults to True.
SECURITY DOMAIN PARAMETERS
The security domain is a component that facilitates communication
between subsystems. The first CA installed hosts this component and is
used to register subsequent subsystems with the security domain. These
subsystems can communicate with each other using their subsystem cer‐
tificate, which is issued by the security domain CA. For more informa‐
tion about the security domain component, see the Red Hat Certificate
System documentation at https://access.redhat.com/knowl‐
edge/docs/Red_Hat_Certificate_System/.
pki_security_domain_hostname, pki_security_domain_https_port
Location of the security domain. Required for KRA, OCSP, and
TKS subsystems and for CA subsystems joining a security domain.
Defaults to the location of the CA subsystem within the same
instance.
pki_security_domain_user, pki_security_domain_password
Administrative user of the security domain. Required for KRA,
OCSP, and TKS subsystems, and for CA subsystems joining a secu‐
rity domain. Defaults to the administrative user for the CA
subsystem within the same instance (caadmin).
pki_security_domain_name
The name of the security domain. This is required for the secu‐
rity domain CA.
CLONE PARAMETERS
pki_clone
Installs a clone, rather than original, subsystem.
pki_clone_pkcs12_password, pki_clone_pkcs12_path
Location and password of the PKCS #12 file containing the system
certificates for the master subsystem being cloned. This file
should be readable by the user that the Certificate Server is
running as (default of pkiuser), and have the correct selinux
context (pki_tomcat_cert_t). This can be achieved by placing
the file in /var/lib/pki/<instance_name>/alias.
pki_clone_replication_master_port, pki_clone_replication_clone_port
Ports on which replication occurs. These are the ports on the
master and clone databases respectively. Defaults to the inter‐
nal database port.
pki_clone_repicate_schema
Replicate schema when the replication agreement is set up and
the new instance (consumer) is initialized. Otherwise, the
schema must be installed in the clone as a separate step before‐
hand. This does not usually have to be changed. Defaults to
True.
pki_clone_replication_security
The type of security used for the replication data. This can be
set to SSL (using LDAPS), TLS, or None. Defaults to None. For
SSL and TLS, SSL must be set up for the database instances
beforehand.
pki_clone_uri
A pointer to the subsystem being cloned. The format is
https://<master_hostname>:<master_https_port>.
EXTERNAL CA CERTIFICATE PARAMETERS
pki_external
Sets whether the new CA will have a signing certificate that
will be issued by an external CA. This is a two step process.
In the first step, a CSR to be presented to the external CA is
generated. In the second step, the issued signing certificate
and certificate chain are provided to the pkispawn utility to
complete the installation. Defaults to False.
pki_external_csr_path
Required in the first step of the external CA signing process.
The CSR will be printed to the screen and stored in this loca‐
tion.
pki_external_step_two
Specifies that this is the second step of the external CA
process. Defaults to False.
pki_external_cert_path, pki_external_cert_chain_path
Required for the second step of the external CA signing process.
This is the location of the CA signing cert (as issued by the
external CA) and the external CA's certificate chain.
SUBORDINATE CA CERTIFICATE PARAMETERS
pki_subordinate
Specifies whether the new CA which will be a subordinate of
another CA. The master CA is specified by pki_issuing_ca.
Defaults to False.
AUTHORS
Ade Lee <alee@redhat.com>. pkispawn was written by the Dogtag 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 ALSOpkispawn(8)version 1.0 December 13, 2012 pki_default.cfg(5)
