Chapter 11. Silent Configuration

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

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.
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/lib/instance_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.
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 OCSP signing key parameters.
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.
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 audit log signing key parameters.
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.
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 SSL client key parameters.
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.
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 SSL server key parameters.
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.