Chapter 11. Silently Configuring Instances

11.1. About pkisilent
11.2. Silently Configuring Subsystems
11.3. Using Different Key Settings
11.4. Cloning a Subsystem Silently
11.5. Performing Silent Configuration Using an External CA

The Certificate System includes a tool, pkisilent, which configures an instance in a single step. Normally, instances are configured by accessing the subsystem HTML page and going through the setup wizard. pkisilent can be used to pass all of the configuration parameters to a new instance simply from the command line.

NOTE

The pkisilent script is downloaded and installed in its own package.

11.1. About pkisilent

Silent configuration sets up a new subsystem instance in a single pass, by sending all of the configuration parameters through the command line. For Certificate System subsystems, this is done using the pkisilent command.

The pkisilent command can configure the subsystem instance the same as if it were configured using the HTML-based configuration wizard, so it can create a new security domain or use an existing one, back up keys, create a clone, or use certificates issued by an external CA.

From a high level, the pkisilent command has groups of parameters that define major areas of the subsystem's default settings and users.

There are two template files that are shell scripts for silent configuration: /usr/share/pki/silent/pki_silent.template and /usr/share/pki/silent/subca_silent.template. Both of these templates have detailed information on parameters and usage options for pkisilent.

Example 11.1. pkisilent Command

pkisilent Configuretype -parameters to configure the subsystem URL ... -parameters to configure the admin user ... -parameters to configure the domain ... -parameters to configure the agent ... -parameters to configure the internal database ... -parameters to configure the subsystem keys, certificates, and key store

The options available to use with the pkisilent command are listed in Table 11.1, “Parameters for pkisilent”.

TIP

To check the specific options for any Configuretype option, just run the pkisilent command with the Configuretype option and the -help flag. For example, to get the help for configuring a subordinate CA:

pkisilent ConfigureSubCA -help

The Configuretype option sets what kind of subsystem is being configured. This can be any of the following:

ConfigureCA (for a root CA) or ConfigureSubCA (for a subordinate CA)
ConfigureRA
ConfigureDRM
ConfigureOCSP
ConfigureTKS
ConfigureTPS

Table 11.1. Parameters for pkisilent

Parameter Description

Basic Instance Configuration

cs_hostname The hostname for the Certificate System machine.

cs_port The administrative SSL port number of the Certificate System instance.

subsystem_name Sets the name of the new subsystem instance.

client_certdb_dir The directory for the subsystem certificate databases.

client_certdb_pwd The password to protect the certificate database.

preop_pin The preoperation PIN number used for the initial configuration. This PIN is part of the output of pkicreate, at the end of the configuration URL. It can also be found in the URL in the installation file for the instance (/var/log/pki-name/logs-install.log).

token_name Gives the name of the HSM token used to store the subsystem certificates. This is only required for hardware tokens; if this parameter is not given, then the script automatically uses the local software token.

token_pwd Gives the password for the HSM.

Agent and Admin User Configuration

admin_user The new admin user for the new subsystem.

admin_email The email address of the admin user.

admin_password The password for the admin user.

agent_key_size The key size to use for generating the agent certificate and key pair.

agent_key_type The key type to use for generating the agent certificate and key pair.

agent_cert_subject The subject name for the agent certificate.

Security Domain Configuration

domain_name The name of the security domain to which the subsystem will be added.

sd_hostname The hostname of the CA which hosts security domain.

sd_admin_port The administrative SSL port of the CA which hosts security domain.

sd_agent_port The agent SSL port of the CA which hosts security domain.

sd_ssl_port The end-entities SSL port of the CA which hosts security domain.

sd_admin_name The username of the administrative user for the CA hosting the security domain.

sd_admin_password The password of the administrative user for the CA hosting the security domain.

Internal Database Configuration

ldap_host The hostname of the Directory Server machine.

ldap_port The non-SSL port of the Directory Server.

bind_dn The bind DN which will access the Directory Server; this is normally the Directory Manager ID.

bind_password The bind DN password.

base_dn The entry DN under which to create all of the subsystem entries.

db_name The database name.

secure_conn Whether to use SSL to connect to the internal database. This is either true or false.

remove_data Whether to overwrite the data if a database of the same name exsits.

Subsystem Certificates and Keys Configuration

key_size The size of the key to generate. The recommended size for an RSA key is 1048 bits for regular operations and 2048 bits for sensitive operations.

key_type The type of key to generate; the only option is RSA.

key_algorithm

The hashing algorithm to use for the key pair. This is only used for root CA subsystems; hashing algorithms for other subsystems and sub CAs are set by editing the certificate profile. For RSA:

SHA256withRSA
SHA1withRSA
SHA256withRSA
SHA512withRSA
MD5withRSA
MD2withRSA

For ECC:

SHA256withEC (the default)
SHA1withEC
SHA384withEC
SHA512withEC

key_curvename For ECC keys. The curve to use for the key. The default is nistp256.

signing_key_type

signing_key_size

signing_key_algorithm

signing_key_curvename

signing_key_signingalgorithm

For CA signing certificates. CAs only. Sets the specific settings to generate a CA signing key and certificate.

The key_type, key_size, key_algorithm, and key_curvename parameters apply to every key and certificate generated by a susbsystem. However, each individual key can have its own parameters set separately. The parameters available to key_type, key_size, key_algorithm, and key_curvename apply to the CA signing key parameters.

ocsp_signing_key_type

ocsp_signing_key_size

ocsp_signing_key_algorithm

ocsp_signing_key_curvename

ocsp_signing_key_signingalgorithm

For OCSP signing certificates. CAs and OCSPs. Sets the specific settings to generate an OCSP signing key and certificate.

audit_signing_key_type

audit_signing_key_size

audit_signing_key_algorithm

audit_signing_key_curvename

For audit signing certificates. For CA, DRM, OCSP, TKS, and TPS. Sets the specific settings to generate an audit log signing key and certificate.

The only supported key type for audit certificates is RSA.

subsystem_key_type

subsystem_key_size

subsystem_key_algorithm

subsystem_key_curvename

For subsystem client certificates. For all subsystems. Sets the specific settings to generate an SSL client key and certificate.

sslserver_key_type

sslserver_key_size

sslserver_key_algorithm

sslserver_key_curvename

For server certificates. For all subsystems. Sets the specific settings to generate an SSL server key and certificate.

save_p12 Sets whether to export the keys and certificate information to a backup PKCS #12 file. true backs up the information; false does not back up the information. Only for the CA subsystem.

backup_pwd The password to protect the PKCS #12 backup file containing the subsystem keys and certificates. Not for use with TPS installation.

backup_fname The file to which to export the the PKCS #12 backup file.

ca_subsystem_cert_subject_name

ca_ocsp_cert_subject_name

ca_server_cert_subject_name

ca_sign_cert_subject_name

ca_audit_signing_cert_subject_name

The subject names for the CA subsystem certificates.

ra_subsystem_cert_subject_name

ra_server_cert_subject_name

ra_subsystem_cert_nickname

ra_server_cert_nickname

The subject names and nicknames for the RA subsystem certificates.

ocsp_ocsp_cert_subject_name

ocsp_server_cert_subject_name

ocsp_subsystem_cert_subject_name

ocsp_audit_signing_cert_subject_name

The subject names for the OCSP subsystem certificates.

drm_storage_cert_subject_name

drm_transport_cert_subject_name

drm_server_cert_subject_name

drm_subsystem_cert_subject_name

drm_audit_signing_cert_subject_name

The subject names for the DRM subsystem certificates.

tks_subsystem_cert_subject_name

tks_server_cert_subject_name

tks_audit_signing_cert_subject_name

The subject names for the TKS subsystem certificates.

tps_subsystem_cert_subject_name

tps_server_cert_subject_name

tps_subsystem_cert_nickname

tps_server_cert_nickname

The subject names and nicknames for the TPS subsystem certificates.

Required Subsystem Configuration

ca_hostname The hostname for the CA subsystem which will issue the certificates for a subordinate CA, RA, DRM, OCSP, TKS, or TPS subsystem.

ca_port The non-SSL port number of the CA.

ca_ssl_port The SSL end entities port number of the CA.

drm_hostname The hostname for the DRM subsystem to use to archive keys. For the TPS only.

drm_ssl_port The SSL agent port number of the DRM. For the TPS only.

tks_hostname The hostname for the TKS subsystem to use to derive keys. For the TPS only.

tks_ssl_port The SSL agent port number of the TKS. For the TPS only.

Authentication Database Configuration (TPS only)

ldap_auth_host Gives the hostname of the LDAP directory database to use for the TPS subsystem token database. Only for the TPS subsystem.

ldap_auth_port Gives the port number of the LDAP directory database to use for the TPS subsystem token database. Only for the TPS subsystem.

ldap_auth_base_dn Gives the base DN in the LDAP directory tree of the TPS token database under which to create token entries. Only for the TPS subsystem.

External CA for Issuing Certificates

external Sets whether to submit the subsystem certificates to the configured CA or to an external CA. The options are true or false. If this is not set, then the default is false.

ext_csr_file The output file to which to write the generated certificate requests for the subsystem certificates. Step one of the silent configuration process.

ext_ca_cert_file The input file for the certificates issued by the external CA. Step two of the silent configuration process.

ext_ca_cert_chain_file The input file for the CA certificate chain for the external CA issuing the certificate. Step two of the silent configuration process.

Cloning Configuration

clone Sets whether the new instance is a clone. Its possible values are true or false. If this is not set, then the default is false.

clone_p12_file The file name of the PKCS#12 file for the backed-up keys for the original instance. This must be in the /var/lib/instance_name/alias directory for the clone.

clone_p12_password The password to access the PKCS#12 file.

clone_start_tls Whether to use Start TLS with replication between the clones. This opens a secure connection over a standard port.