11.2. Silently Configuring Subsystems

NOTE

Before running pkisilent, first run pkicreate to create the instance.
There are slight differences in the options used to configure the different subsystem types:
  • Different security domain settings. A CA can host a security domain, so it has special configuration options to create a security domain. All other subsystems (as well as CAs) must join an existing security domain.

    TIP

    It is recommended that every CA have its own security domain, because each system within the security domain depends on having the security domain running and accessible. However, subordinate CAs can only be configured within the root CA's security domain using the pkisilent script.
  • Different numbers and types of SSL ports. The CA, DRM, OCSP, and TKS each have three SSL ports admin, agents, and users), while the RA and TPS both have two SSL ports (client and non-client).
  • Different numbers and types of certificates.
  • Different required subsystems. Every subsystem must, at a minimum, specify which CA will sign and issue its certificates, while a CA has the option of self-signing its certificates. The TPS also relies on a TKS and optional DRM, which can also be specified at configuration.
  • Different database configuration. The RA uses a SQLite database as its internal databases, while all other subsystems use an LDAP directory. The TPS uses two separate LDAP directories, one as its internal database and the other as an authentication directory to help manage its users.
For all of that, the usage of pkisilent is still pretty similar between the subsystems. They use the same options to identify the instance to configure, back up their keys, and configure their users, and even though the parameters are slightly different in name, the configuration concepts (like cloning or generating certificates) are the same.

NOTE

Any spaces in the arguments used with pkisilent must be escaped.
Example 11.2, “Configuring a Root CA” configures a CA, creates a new security domain, backs up its keys, and self-signs its certificates. All of the parameters should be on a single line.

Example 11.2. Configuring a Root CA

pkisilent ConfigureCA -cs_hostname localhost 
          -cs_port 9445 
          -subsystem_name "pki-ca2" 
          -client_certdb_dir /tmp/ 
          -client_certdb_pwd password 
          -preop_pin sYY8er834FG9793fsef7et5 
          -domain_name "testca" 
          -admin_user admin 
          -admin_email "admin@example.com" 
          -admin_password secret 
          -agent_name "jsmith"
          -agent_key_size 2048 
          -agent_key_type rsa 
          -agent_cert_subject "cn=ca\ agent\ cert" 
          -ldap_host server 
          -ldap_port 389 
          -secure_conn false
          -remove_data true
          -bind_dn "cn=directory\ manager" 
          -bind_password secret 
          -base_dn "o=pki-ca2" 
          -db_name "server.example.com-pki-ca2" 
          -key_size 2048 
          -key_type rsa 
          -key_algorithm SHA256withRSA 
          -backup_pwd password 
          -backup_fname /export/backup.p12 
          -ca_subsystem_cert_subject_name "cn=ca\ subsystem\ cert,o=testca\ domain" 
          -ca_ocsp_cert_subject_name "cn=ocsp\ signing\ cert,o=testca\ domain" 
          -ca_server_cert_subject_name "cn=ca\ client\ cert,o=testca\ domain" 
          -ca_sign_cert_subject_name "cn=ca\ signing\ cert,o=testca\ domain" 
          -ca_audit_signing_cert_subject_name "cn=audit\ signing\ cert,o=testca\ domain"
          -token_name "internal"

A subordinate CA — along with the DRM, OCSP, and TKS — is configured to join an existing security domain and to have its certificates signed by an existing Certificate System CA (by default; it is also possible to use an external CA, as in Section 11.5, “Performing Silent Configuration Using an External CA”). All of the parameters should be on a single line.

Example 11.3. Configuring a Subordinate CA

pkisilent ConfigureCA -cs_hostname localhost 
          -cs_port 9445 
          -subsystem_name "pki-ca2" 
          -client_certdb_dir /tmp/ 
          -client_certdb_pwd password 
          -preop_pin sYY8er834FG9793fsef7et5 
          -sd_hostname "domain.example.com" 
          -sd_admin_port 9445 
          -sd_agent_port 9443 
          -sd_ssl_port 9444 
          -sd_admin_name admin 
          -sd_admin_password secret 
          -admin_user admin 
          -admin_email "admin@example.com" 
          -admin_password secret
          -agent_name "jsmith" 
          -agent_key_size 2048 
          -agent_key_type rsa 
          -agent_cert_subject "cn=ca\ agent\ cert" 
          -ldap_host server 
          -ldap_port 389 
          -secure_conn false
          -remove_data true
          -bind_dn "cn=directory\ manager" 
          -bind_password secret 
          -base_dn "o=pki-ca2" 
          -db_name "server.example.com-pki-ca2" 
          -key_size 2048 
          -key_type rsa 
          -save_p12 true 
          -backup_pwd password 
          -backup_fname /export/backup.p12 
          -ca_hostname server.example.com 
          -ca_port 9180 
          -ca_ssl_port 9443 
          -ca_subsystem_cert_subject_name "cn=ca\ subsystem\ cert,o=testca\ domain" 
          -ca_ocsp_cert_subject_name "cn=ocsp\ signing\ cert,o=testca\ domain" 
          -ca_server_cert_subject_name "cn=ca\ client\ cert,o=testca\ domain" 
          -ca_sign_cert_subject_name "cn=ca\ signing\ cert,o=testca\ domain" 
          -ca_audit_signing_cert_subject_name "cn=audit\ signing\ cert,o=testca\ domain"
          -token_name "internal"

A DRM, TKS, and OCSP subsystem is largely the same as a subordinate CA, but without the -save_p12 option. All of the parameters should be on a single line.

Example 11.4. Configuring a DRM

pkisilent ConfigureDRM -cs_hostname localhost
          -cs_port 9445
          -subsystem_name "pki-kra"
          -client_certdb_dir /tmp/
          -client_certdb_pwd password
          -preop_pin sYY8er834FG9793fsef7et5
          -domain_name "example\ domain"
          -sd_hostname "domain.example.com"
          -sd_admin_port 9445
          -sd_agent_port 9443
          -sd_ssl_port 9444
          -sd_admin_name admin
          -sd_admin_password secret
          -admin_user admin 
          -admin_email "admin@example.com"
          -admin_password secret
          -agent_key_size 2048
          -agent_key_type rsa
          -agent_cert_subject "cn=drm\ agent\ cert"
          -agent_name "jsmith"
          -ldap_host server
          -ldap_port 389
          -secure_conn false
          -remove_data true
          -bind_dn "cn=directory\ manager"
          -bind_password secret
          -base_dn "o=pki-kra"
          -db_name "server.example.com-pki-kra"
          -key_size 2048
          -key_type rsa
          -backup_pwd password
          -ca_hostname server.example.com
          -ca_port 9180
          -ca_ssl_port 9443
          -drm_subsystem_cert_subject_name "cn=drm\ subsystem\ cert,o=example\ domain"
          -drm_transport_cert_subject_name "cn=drm\ transport\ cert,o=example\ domain"
          -drm_server_cert_subject_name "cn=drm\ client\ cert,o=example\ domain"
          -drm_storage_cert_subject_name "cn=drm\ storage\ cert,o=example\ domain"
          -drm_audit_signing_cert_subject_name "cn=drm\ audit\ signing\ cert,o=example\ domain"
          -token_name "internal"

The RA, unlike the other subsystems, does not use an LDAP database, so it does not specify the same database parameters as the other subsystems. In this example, the keys for the RA are not automatically backed up and there is no audit log signing certificate, since the RA is the only subsystem which does not support signed audit logs.

Example 11.5. Configuring an RA

pkisilent ConfigureRA -cs_hostname localhost 
          -cs_port 9445 
          -subsystem_name "pki-ra2" 
          -client_certdb_dir /tmp/ 
          -client_certdb_pwd password 
          -preop_pin sYY8er834FG9793fsef7et5 
          -domain_name "example\ domain"
          -sd_hostname "domain.example.com" 
          -sd_admin_port 9445 
          -sd_agent_port 9443 
          -sd_ssl_port 9444 
          -sd_admin_name admin 
          -sd_admin_password secret 
          -admin_user admin 
          -admin_email "admin@example.com" 
          -admin_password secret 
          -agent_name "jsmith"
          -agent_key_size 2048 
          -agent_key_type rsa 
          -agent_cert_subject "cn=ra\ agent\ cert" 
          -ca_hostname server.example.com 
          -ca_port 9180 
          -ca_ssl_port 9443 
          -key_size 2048 
          -key_type rsa 
          -ra_subsystem_cert_subject_name "cn=ra\ subsystem\ cert,o=testca\ domain" 
          -ra_server_cert_subject_name "cn=ra\ client\ cert,o=testca\ domain"
          -token_name ="internal"

A TPS requires the most parameters, since it depends on having a CA, DRM, and TKS configured and uses two LDAP databases, along with joining an existing security domain. However, since the TPS cannot be cloned, it is not required to back up its keys to a PKCS #12 file.

Example 11.6. Configuring a TPS

pkisilent ConfigureTPS -cs_hostname localhost 
          -cs_port 9445 
          -subsystem_name "pki-tps2" 
          -client_certdb_dir /tmp/ 
          -client_certdb_pwd password 
          -preop_pin sYY8er834FG9793fsef7et5 
          -domain_name "example\ domain"
          -sd_hostname "domain.example.com" 
          -sd_admin_port 9445 
          -sd_agent_port 9443 
          -sd_ssl_port 9444 
          -sd_admin_name admin 
          -sd_admin_password secret 
          -admin_user admin 
          -admin_email "admin@example.com" 
          -admin_password secret 
          -agent_name "jsmith"
          -agent_key_size 2048 
          -agent_key_type rsa 
          -agent_cert_subject "cn=tps\ agent\ cert" 
          -ldap_host server 
          -ldap_port 389 
          -secure_conn false
          -remove_data true
          -bind_dn "cn=directory\ manager" 
          -bind_password secret 
          -base_dn "o=pki-tps2" 
          -db_name "server.example.com-pki-tps2" 
          -ca_hostname server.example.com 
          -ca_port 9180 
          -ca_ssl_port 9443 
          -tks_hostname server.example.com 
          -tks_ssl_port 13443 
          -drm_hostname server.example.com 
          -drm_ssl_port 10443 
          -key_size 2048 
          -key_type rsa 
          -tps_subsystem_cert_subject_name "cn=tps\ subsystem\ cert,o=testca\ domain" 
          -tps_server_cert_subject_name "cn=tps\ client\ cert,o=testca\ domain" 
          -tps_audit_signing_cert_subject_name "cn=audit\ signing\ cert,o=testca\ domain" 
          -ldap_auth_host auth.example.com 
          -ldap_auth_port 389 
          -ldap_auth_base_dn "ou=tps,ou=People,dc=example,dc=com"
          -token_name "internal"