18.2. Setting up the CA on the New Host

After you have exported the data from the existing Directory Server and Certificate System instances in Section 18.1, “Exporting Data from the Previous System”, set up the certificate authority (CA) on the new host:
  1. Enable the Certificate System repository. See Section 6.5, “Enabling the Certificate System Repository”.
  2. Install the pki-ca package:
    # yum install pki-ca
    If you require additional features, such as the Certificate System console, install the corresponding packages. For details, see Section 7.2, “Certificate System Packages”.
  3. When setting up the CA on a host that uses an IPv6 address, apply the steps described in Section 11.3, “Enabling IPv6 for a Subsystem”.
  4. Depending on your environment, this step differs.
    • When using a hardware security module (HSM):
      Create a deployment configuration file, for example /root/pki-CA-deployment.txt, with the following content:
      [DEFAULT]
      pki_instance_name=instance_name
      pki_admin_password=caadmin_password
      pki_client_pkcs12_password=pkcs12_file_password
      pki_ds_password=DS_password
      pki_hsm_enable=True
      pki_hsm_libfile=path_to_HSM_library
      pki_hsm_modulename=HSM_module_name
      pki_token_name=HSM_token_name
      pki_token_password=HSM_token_password
      pki_ds_ldap_port=389
      pki_existing=True
      
      [CA]
      pki_ca_signing_csr_path=/tmp/cs_bak/ca_signing.csr
      pki_ca_signing_cert_path=/tmp/cs_bak/ca_signing.crt
      pki_ca_signing_nickname=caSigningCert ca-pki-ca
      pki_ca_signing_token=HSM_token_name
      pki_ds_base_dn=o=pki-tomcat-CA
      pki_ds_database=instance_name-CA
      pki_serial_number_range_start=4e
      pki_request_number_range_start=30
      pki_master_crl_enable=False
      pki_cert_chain_path=/tmp/cs_bak/rootca_signing.crt
      pki_cert_chain_nickname=caSigningCert cert-top-rootca
      pki_ca_signing_record_create=False
      pki_ca_signing_serial_number=decimal_CA_signing_certificate_serial
      For descriptions of the parameters used in the previous example, see Table 18.1, “pkispawn Parameter Descriptions” at the end of this step.
    • When not using a hardware security module (HSM):
      1. Verify that the PKCS #12 file contains the CA signing certificate and key. For example:
        # pki pkcs12-cert-find --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
        ---------------
        1 entries found
        ---------------
          Certificate ID: 308b4c7d4b5efc4052aec26e49a2c5e2e14c9e90
          Serial Number: 0x1
          Nickname: caSigningCert ca-pki-ca
          Subject DN: CN=CA Signing Certificate,O=EXAMPLE
          Issuer DN: CN=CA Signing Certificate,O=EXAMPLE
          Trust Flags: CTu,Cu,Cu
          Has Key: true
        
        # pki pkcs12-key-find --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
        ---------------
        1 entries found
        ---------------
          Key ID: 308b4c7d4b5efc4052aec26e49a2c5e2e14c9e90
          Subject DN: CN=CA Signing Certificate,O=EXAMPLE
          Algorithm: RSA
        
        Note that the file can additionally contain other certificates and keys.
      2. Verify the trust flags of the CA signing certificate in the output of the previous step. Reset the flags if they are not set to CTu,Cu,Cu or if they are missing:
        # pki pkcs12-cert-mod caSigningCert cert-pki-tomcat CA \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt \
             --trust-flags "CTu,Cu,Cu"
      3. Remove all other certificates and keys, except the CA signing certificate and key, from the PKCS #12 file. For example:
        # pki pkcs12-cert-del Server-Cert root_CA_nickname \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
        
        # pki pkcs12-cert-del "subsystemCert ca-pki-ca" \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
        
        # pki pkcs12-cert-del "ocspSigningCert ca-pki-ca" \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
        
        # pki pkcs12-cert-del "auditSigningCert ca-pki-ca" \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
      4. If the CA being migrated is an intermediate CA, remove the root CA certificate from the PKCS #12 file. For example:
        # pki pkcs12-cert-del ca-pki-ca \
             --pkcs12-file /tmp/cs_bak/ca.p12 \
             --pkcs12-password-file /tmp/cs_bak/pkcs12_password.txt
      5. Create a deployment configuration file, for example /root/pki-CA-deployment.txt, with the following content:
        [DEFAULT]
        pki_instance_name=instance_name
        pki_admin_password=caadmin_password
        pki_client_pkcs12_password=pkcs12_file_password
        pki_ds_password=DS_password
        pki_ds_ldap_port=389
        pki_existing=True
        
        [CA]
        pki_ca_signing_nickname=caSigningCert ca-pki-ca
        pki_ca_signing_csr_path=/tmp/cs_bak/ca_signing.csr
        pki_pkcs12_path=/tmp/cs_bak//cs_bak/ca.p12
        pki_pkcs12_password=pkcs12_file_password
        pki_ds_base_dn=o=pki-tomcat-CA
        pki_ds_database=pki-tomcat-CA
        pki_serial_number_range_start=43
        pki_request_number_range_start=30
        pki_master_crl_enable=False
        pki_cert_chain_path=/tmp/cs_bak/rootca_signing.crt
        pki_cert_chain_nickname=caSigningCert cert-top-rootca
        pki_ca_signing_record_create=False
        pki_ca_signing_serial_number=decimal_CA_signing_certificate_serial
        For descriptions of the parameters used in the previous example, see Table 18.1, “pkispawn Parameter Descriptions”.

    Table 18.1. pkispawn Parameter Descriptions

    Parameters and Settings
    Description
    pki_hsm_* and pki_token_*
    Enables communication with the HSM. Only set these parameters when setting up a CA with HSM.
    pki_existing=True
    Sets to use the existing CA mechanism.
    pki_ca_signing_nickname
    The CA signing nickname must be exactly the same as used in the previous installation, otherwise the installer cannot find the signing key.
    pki_ca_signing_*
    Sets the paths to the certificate signing request (CSR) and the certificate files copied from the existing machine.
    pki_pkcs12_*
    Sets the path to the PKCS #12 file and the password used to decrypt the file. Do not set this parameter when deploying a CA with HSM.
    pki_ds_base_dn
    Sets the Directory Server base distinguished name (DN). The value must be the same as on the previous CA. You can find this value on the previous host in the internaldb.basedn parameter in the /var/lib/instance_name/conf/CS.cfg file.
    pki_serial_number_range_start
    The serial number is critical. The value must be higher than the last number used in the previous CA. To display which numbers are already used, see the old CA's agent interface. This parameter is set in hex format without the leading 0x prefix. The value used in the examples (4e) is 78 in decimal.
    pki_request_number_range_start
    The request number is critical. The value must be higher than the last number used in the previous CA. To display which numbers are already used, see the old CA's agent interface. The value is set in decimal format.
    pki_master_crl_enable=False
    Prevents the initial creation and publishing of a certificate revocation list (CRL) during the setup. Instead, the CRL will be imported from the old data during the database migration.
    pki_cert_chain_path and pki_cert_chain_nickname
    Set these parameters only if the old CA is an intermediate CA. In this case, set the parameters to the path to the root CA certificate file and the nickname to use when storing the certificate in the network security services (NSS) database.
    pki_ca_signing_record_create=False
    Disables the recreation of the CA signing record at the end of the pkispawn process. This enables you to import the old database.
    pki_ca_signing_serial_number
    Sets the serial number of the CA signing certificate in decimal.
    For further details and parameter descriptions, see the pkispawn(8) man page.
  5. Create the new CA using the deployment configuration file. For example:
    # pkispawn -s CA -f /root/pki-CA-deployment.txt
  6. Verify that the CA signing key ID is the same in the existing and in the new CA. For example:
    # grep "internal=" /var/lib/instance_name/conf/password.conf | \
         awk -F= '{print $2;}' > internal.txt
    # certutil -K -d /var/lib/instance_name/alias/ -f internal.txt
    ...
    < 2> rsa      7bd4dc662670ebe08a35086b054175559608ac20   caSigningCert ca-pki-ca
    ...