Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 20. Upgrading from Certificate System 9 to Certificate System 10

Users are recommended to upgrade to the most recent version of Red Hat Certificate System to get security and bug fixes through the Errata-Support channel. Currently, the most recent versions are RHCS 9.7 on RHEL 7.9 and RHCS 10.8 on RHEL 8.10.

20.1. Migrating a CA
Copiar o link

A Certificate System migration using the existing certificate files requires the following steps:

  1. Section 20.1.1, “Exporting data from the previous system”
  2. Section 20.1.2, “Verifying the PKCS12 file”
  3. Section 20.1.3, “Setting up the CA on the new host”
  4. Section 20.1.4, “Importing the old data into the new CA”
  5. Section 20.1.5, “Reassigning users to default groups”

20.1.1. Exporting data from the previous system
Copiar o link

Before you set up the new Certificate System instance, export the data of the current certificate authority (CA) using the steps below. In this example, the CA’s instance name is <pki-rootCA> and is located at /var/lib/pki/<instance_name>.

  1. Export the CA signing certificate and key. 

    # grep internal= /var/lib/pki/<instance_name>/conf/password.conf | awk -F= '{print $2;}' > internal.txt
# echo <Secret.123> > password.txt
# PKCS12Export -d /var/lib/pki/<instance_name>/alias -p internal.txt -o ca.p12 -w password.txt
    Copy to Clipboard Toggle word wrap

  2. Export the Certificate Signing Requests (CSR). 

    # echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > ca_signing.csr
# sed -n "/^ca.signing.certreq=/ s/[=]*=// p" < /var/lib/pki/<instance_name>/ca/conf/CS.cfg >> ca_signing.csr
# echo "-----END NEW CERTIFICATE REQUEST-----" >> ca_signing.csr
    Copy to Clipboard Toggle word wrap

  3. If the old CA is an intermediate CA (with a single root CA in the chain), extract the root CA from the NSS database: 

    # certutil -L -d /var/lib/pki/<instance_name>/alias/ -n root_CA_nickname -a > ca_rootca_signing.crt
    Copy to Clipboard Toggle word wrap

  4. Back up the internal LDAP database:

    1. Find the name of the CA database by checking the value of internaldb.database in the CA’s CS.cfg: 

      # grep internaldb.database /etc/pki/<instance_name>/ca/CS.cfg
	internaldb.database=<CS_database_name>
      Copy to Clipboard Toggle word wrap

    2. Export this database to a .ldif file using the instance-specific script generated by setup-ds.pl when the instance was created: 

      # cd /usr/lib64/dirsrv/<instance_name>
# ./db2ldif -n "<CS_database_name>" -a /tmp/old_ca.ldif
      Copy to Clipboard Toggle word wrap

      The db2ldif command runs as the DB user, so it needs a destination folder with writing permissions.

  5. Transfer the old_ca.ldif, ca_p12, ca_signing.csr files to the new CA machine. If the CA being migrated is also an intermediate CA, transfer the ca_rootca_signing.crt as well.

20.1.2. Verifying the PKCS12 file
Copiar o link

On the new CA, a new database instance runs on the standard port (389). The PKCS12 file contains all the system certificates for the old system. Verify that the file includes the CA signing certificate and the key.

Note

In FIPS mode, you must run the pki pkcs12 commands with an NSS database. For more information, see the pki-pkcs12 CLI.

  1. Find the CA signing certificate and the key. 

    $ echo "<Secret.123>" > password.txt
$ pki pkcs12-cert-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-key-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt
    Copy to Clipboard Toggle word wrap

  2. Verify the presence of the trust flags of the CA signing certificate. If the flags are not "CTu,Cu,Cu" or they are missing, add them. 

    $ pki pkcs12-cert-mod "<caSigningCert cert-pki-rootCA>" \ --pkcs12-file ca.p12 --pkcs12-password-file password.txt \ --trust-flags "CTu,Cu,Cu"
    Copy to Clipboard Toggle word wrap

  3. Remove other certificates and keys. 

    $ pki pkcs12-cert-del "<Server-Cert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<subsystemCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<ocspSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<auditSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
    Copy to Clipboard Toggle word wrap

  4. If the CA being migrated is also an intermediate CA, remove the root CA certificate from the PKCS#12 file. 

    $ pki pkcs12-cert-del "<Top-level Root CA Signing Certificate>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
    Copy to Clipboard Toggle word wrap

20.1.3. Setting up the CA on the new host
Copiar o link

After you have exported the data from the existing instance, create and set up the certificate authority (CA) on the new host.

  1. Create a configuration file for pkispawn, for example CA.cfg, using the parameters of the old CA. This instance runs on the standard port (389). 

    [DEFAULT]
	pki_instance_name=<new_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_csr_path=<path/to/ca_signing.csr>
	pki_ca_signing_cert_path=<path/to/ca_signing.crt>
	pki_ca_signing_nickname=<caSigningCert cert-nickname>
	pki_ds_base_dn=<o=pki-tomcat-CA>
	pki_ds_database=<instance_name-CA>
	pki_master_crl_enable=False
    Copy to Clipboard Toggle word wrap

    If the old CA is an intermediate CA, add the following two lines to the configuration file. They correspond to the path to the root CA certificate and the nickname to use when storing the certificate in the NSS database. 

    pki_cert_chain_path=<rootca_signing.crt>
pki_cert_chain_nickname=<caSigningCert cert-pki-ca>
    Copy to Clipboard Toggle word wrap

  2. Run pkispawn on the new host to create the new CA instance: 

    # pkispawn -s CA -f ca.cfg -vv
    Copy to Clipboard Toggle word wrap
Note

For instructions on how to set up a new DS instance for the new CA, see Installing Red Hat Directory Server.

20.1.4. Importing the old data into the new CA
Copiar o link

After you have created the new CA instance, import the data into the new CA database:

  1. Stop the CA service. 

    # systemctl stop pki-tomcatd@<instance_name>.service
    Copy to Clipboard Toggle word wrap

  2. Optional: Back up the CA database on the new host. 

    # dsctl -v idm-qe-01 db2bak
    Copy to Clipboard Toggle word wrap

    The backup is stored in the /var/lib/dirsrv/<instance_name>/bak/<host_name-time_stamp>/ directory.

  3. Remove the certificate entry for the signing certificate from the new RHEL 8 internal database. 

    # ldapdelete -x -w <password< -D 'cn=Directory Manager' "cn=<serial_number<,ou=certificateRepository,ou=ca,o=pki-tomcat-CA"
    Copy to Clipboard Toggle word wrap

    The entry is now imported from the old data, so that the CRL attributes in that entry point to the correct entries.

  4. Import the data into the new database: 

    # ldapmodify -x -W <password> -D 'cn=Directory Manager' -a -c -f <path/to/old_ca.ldif>
    Copy to Clipboard Toggle word wrap

    The ldapmodify utility only adds new entries and does not update existing entries, created when you installed the CA.

  5. Optional: Verify the output in the import.log file. You can search for failed actions, such as ldap_add: Invalid syntax (21).

  6. Remove the directory entry for the old security domain. 

    # ldapmodify -W <password> -x -D "cn=Directory Manager"
dn: cn=<server.example.com:9445>,cn=CAList,ou=Security Domain,<o=pki-tomcat-CA>
changetype: delete
    Copy to Clipboard Toggle word wrap

  7. Enable the ca.crl.MasterCRL.enable parameter in the /etc/pki/<instance_name>/ca/CS.cfg file, to have the CA act as the certificate revocation list (CRL) master: 

    ca.crl.MasterCRL.enable=true
    Copy to Clipboard Toggle word wrap

  8. Restart the CA service: 

    # systemctl start pki-tomcatd@<instance_name>
    Copy to Clipboard Toggle word wrap

20.1.5. Reassigning users to default groups
Copiar o link

Add members to the default groups manually, using the ldapmodify utility or the pki utility.

  1. Set up the client: 

    # pki -c <password> client-init
Client initialized
    Copy to Clipboard Toggle word wrap 
    # pk12util -i ~/.dogtag/<instance_name>/ca_admin_cert.p12 -d ~/.dogtag/nssdb/
Enter Password or Pin for "NSS Certificate DB":
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL
    Copy to Clipboard Toggle word wrap

  2. Add the user account to the Administrators and Security Domain Administrators groups: 

    # pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user_name> "Certificate Manager Agents"
    Copy to Clipboard Toggle word wrap

    The default (bootstrap) admin users in RHCS 9 and RHCS 10 have the same default roles, that is the same group membership. However, if you have a non-default admin user or have customized the admin roles in RHCS 9, those changes might not be migrated properly. In this case, reconfigure the roles in RHCS 10: 

    # pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user> "Administrators"
# pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user> "Security Domain Administrators"
    Copy to Clipboard Toggle word wrap

If you want to make sure the certificate has been migrated successfully, check its existence on the new host by running the ca-cert-find command.

20.2. Migrating a KRA
Copiar o link

Simple KRA migration requires the following steps:

  1. Section 20.2.1, “Setting up the KRA on the new host”
  2. Section 20.2.2, “Exporting contents from the previous system”
  3. Section 20.2.3, “Importing the data into the new KRA”
  4. Section 20.2.4, “Validating the presence of migrated keys from the KRA Agent Page”

The KRA located on alpha.example.com contains the data, while the KRA located on omega.example.com does not exist yet.

Expand
HostnamePKI KRA Version

alpha.example.com

PKI KRA 10.5 on RHCS 9.7

omega.example.com

PKI KRA 10.13 on RHCS 10.4

20.2.1. Setting up the KRA on the new host
Copiar o link

On omega.example.com as the root user:

  1. Install and configure a new PKI 10.13 KRA on omega.example.com.

  2. Stop the KRA instance. 

    # systemctl stop pki-tomcatd@<pki-kra>
    Copy to Clipboard Toggle word wrap

  3. Create a directory to export all required files. 

    # mkdir -p /export/pki
    Copy to Clipboard Toggle word wrap

  4. Export KRA storage certificates to a file. You will need the KRA storage certificate later to re-encrypt the decrypted old data from the KRA on alpha. In the following example, the file is called omega.crt: 

    # cd /var/lib/pki/<pki-kra>/alias/
# pki-server cert-export kra_storage -i <pki-kra> --cert-file <omega.crt>
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 8 (0x8)
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: O = example.com Security Domain, OU = topology-02-CA, CN = CA Signing Certificate
        Validity
            Not Before: Dec 19 10:58:02 2019 GMT
            Not After : Dec  8 10:58:02 2021 GMT
        Subject: O = example.com Security Domain, OU = topology-02-KRA, CN = DRM Storage Certificate
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:99:c1:f6:f4:0d:75:67:ff:58:3a:28:ee:34:f1:
                    40:0a:e1:5b:f3:9d:f4:c2:5a:1e:d0:d5:0c:62:c1:
    Copy to Clipboard Toggle word wrap
  5. Move the omega.crt file to the /export/pki directory.

  6. Stop the Directory Server. 

    # systemctl stop dirsrv@omega
    Copy to Clipboard Toggle word wrap
    Note

    If db2ldif is missing, install the 389-ds-base-legacy-tools package.

  7. Extract the KRA LDAP database configurations. You will need the new KRA LDAP database configurations for transforming the old data to the new. 

    # /usr/lib64/dirsrv/slapd-omega/db2ldif -n <pki-kra-KRA> -a /tmp/omega.ldif
    Copy to Clipboard Toggle word wrap

  8. Move the /tmp/omega.ldif file to the /export/pki directory. 

    # mv /tmp/omega.ldif /export/pki/
    Copy to Clipboard Toggle word wrap

20.2.2. Exporting contents from the previous system
Copiar o link

On alpha.example.com as the root user:

  1. Create a common directory: 

    # mkdir -p /export/pki
    Copy to Clipboard Toggle word wrap

  2. Stop the Directory Server. In this example, the server is named alpha: 

    # systemctl stop dirsrv@alpha
    Copy to Clipboard Toggle word wrap

  3. Generate the LDIF from the KRA LDAP database: 

    # /usr/lib64/dirsrv/slapd-alpha/db2ldif -n <pki-kra-KRA> -a /tmp/alpha.ldif
    Copy to Clipboard Toggle word wrap

  4. Move the /tmp/alpha.ldif file to /export/pki directory: 

    # mv /tmp/alpha.ldif /export/pki/
    Copy to Clipboard Toggle word wrap

  5. Copy the KRA NSS security databases to the data area: 

    # cp -p /var/lib/pki/<pki-kra>/alias/* /export/pki/
    Copy to Clipboard Toggle word wrap

  6. Go to the /export/pki directory: 

    # cd /export/pki
    Copy to Clipboard Toggle word wrap

  7. Obtain the flat-file containing the new KRA’s storage certificate from omega.example.com: 

    sftp root@omega.example.com
sftp> cd /export/pki
sftp> get omega.crt
sftp> quit
    Copy to Clipboard Toggle word wrap

  8. Obtain the internal password: 

    # cat /var/lib/<instance_name>/conf/password.conf
    Copy to Clipboard Toggle word wrap

  9. Run the KRATool on alpha.example.com: 

    # KRATool \
    -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg \
    -source_ldif_file /export/pki/alpha.ldif \
    -target_ldif_file /export/pki/alpha2omega.ldif \
    -log_file /tmp/KRATool_26_05_2023.log \
    -source_pki_security_database_path /export/pki/ \
    -source_storage_token_name "Internal Key Storage Token" \
    -source_storage_certificate_nickname "<storageCert cert-pki-tomcat KRA>" \
    -target_storage_certificate_file /export/pki/omega.crt \
    -source_kra_naming_context alpha.example.com \
    -target_kra_naming_context omega.example.com \
    -unwrap_algorithm AES \
    -process_requests_and_key_records_only

PROCESSING KRATOOL CONFIG FILE: ................................... FINISHED.
SUCCESSFULLY processed kratool config file!
Initializing source PKI security databases in '/export/pki/'.
Retrieving token from CryptoManager.
Retrieving source storage token called 'Internal Key Storage Token'.
Retrieving source storage cert with nickname of 'storageCert cert-pki-tomcat KRA'.

BEGIN: Obtaining the private key from the source storage token . . .
Enter password for Internal Key Storage Token
**

FINISHED: Obtaining the private key from the source storage token.
BEGIN: Obtaining the public key from the target storage certificate . . .
FINISHED: Obtaining the public key from the target storage certificate.
PROCESSING: xxxxxxxxxxxxxxxxxxxxxxxxx......
SUCCESSFULLY converted source LDIF file --> target LDIF file!

FINISHED "KRATool -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg -source_ldif_file /export/pki/alpha.ldif -target_ldif_file /export/pki/alpha2omega.ldif -log_file /tmp/DRMTool_20_05_2021.log -source_pki_security_database_path /export/pki/ -source_storage_token_name 'Internal Key Storage Token' -source_storage_certificate_nickname 'storageCert cert-pki-tomcat KRA' -target_storage_certificate_file /export/pki/omega.crt -source_pki_security_database_pwdfile '/export/pki/password.cfg' -source_kra_naming_context 'alpha.example.com' -target_kra_naming_context 'omega.example.com' -process_requests_and_key_records_only"
    Copy to Clipboard Toggle word wrap
    Note

    Alternatively, you can create a plain-text file protected from unauthorized access containing one and only password that will be automatically accessed by a certificate or a certificate database. Add this file to KRATool with the -source_pki_security_database_pwdfile <path_to_PKI_password_file> command-line option.

  10. Copy the alpha2omega.ldif file to omega.example.com: 

    sftp root@omega.example.com
sftp> cd /export/pki
sftp> put alpha2omega.ldif
sftp> quit
    Copy to Clipboard Toggle word wrap

20.2.3. Importing the data into the new KRA
Copiar o link

On omega.example.com as the root user:

  1. Go to /export/pki directory. 

    # cd /export/pki
    Copy to Clipboard Toggle word wrap

  2. Concatenate the ldif files: 

    # cat omega.ldif alpha2omega.ldif > omega_alpha.ldif
    Copy to Clipboard Toggle word wrap

  3. Import the omega_alpha.ldif file into the LDAP database associated with the PKI KRA: 

    # /usr/lib64/dirsrv/slapd-omega/ldif2db -n <pki-kra-KRA> -i /export/pki/omega_alpha.ldif
    Copy to Clipboard Toggle word wrap

  4. Start the Directory Server: 

    # systemctl start dirsrv@omega
    Copy to Clipboard Toggle word wrap

  5. Start the KRA instance. 

    # systemctl start pki-tomcatd@<pki-kra>
    Copy to Clipboard Toggle word wrap

20.2.4. Validating the presence of migrated keys from the KRA Agent Page
Copiar o link

The last step is to perform key recovery of migrated keys from the KRA Agent page. 

[root@pki1 pki]# pki -d /root/nssdb/ -p 21080 -n '<PKI Administrator - example.com Security Domain>' kra-key-find
Enter password for Internal Key Storage Token

----------------
3 key(s) matched
----------------
  Key ID: 0x1
  Algorithm: 1.2.840.113549.1.1.1
  Size: 1024
  Owner: UID=alpha1

  Key ID: 0x2
  Algorithm: 1.2.840.113549.1.1.1
  Size: 1024
  Owner: UID=alpha2

  Key ID: 0x3
  Algorithm: 1.2.840.113549.1.1.1
  Size: 1024
  Owner: UID=alpha3
----------------------------
Number of entries returned 3
----------------------------
Copy to Clipboard Toggle word wrap

20.2.5. Post-Upgrade Testing
Copiar o link

Follow the key recovery operation for user key archived before upgrade.

Procedure 21.1. Key Recovery Test

  1. Display the base64 user certificate created before upgrade. 

    # <pki -n 'PKI Administrator - example.com>' -c <Secret.123> ca-cert-export <0xd>
  Serial Number: 0xd
  Subject DN: UID=alpha
  Issuer DN: CN=CA Signing Certificate,OU=pki-tomcat,O=example.com Security Domain
  Status: VALID
  Not Valid Before: Wed Jun 07 01:49:07 EDT 2023
  Not Valid After: Mon Dec 04 01:49:

----BEGIN CERTIFICATE----
MIIDODCCAiCgAwIBAgIBDTANBgkqhkiG9w0BAQsFADBtMTUwMwYDVQQKDCxpZG1xZS5sYWIuZW5n
LmJvcy5yZWRoYXQuY29tIFNlY3VyaXR5IERvbWFpbjETMBEGA1UECwwKcGtpLXRvbWNhdDEfMB0G
A1UEAwwWQ0EgU2lnbmluZyBDZXJ0aWZpY2F0ZTAeFw0yMzA2MDcwNTQ5MDdaFw0yMzEyMDQwNjQ5

            [...output truncated...]

EJyoMFM+RaAcTh+C3S0JZEoKlAS3UlJOMxk3BFZdWpv7ia+1faV6LFPZSCZ/m8i2c3KZNxFW2xv1
DTIIVc7a1uEDApVDHf5aFcm0nGpEVeK+yvP4r1eD
----END CERTIFICATE----
    Copy to Clipboard Toggle word wrap
  2. Use this certificate to generate a key recovery request through KRA Agent UI.

  3. Approve the recovery request. 

    # pki -c <Secret.123> -n '<PKI Administrator - example.com Security Domain>' -p 8443 -P https kra-key-request-review <0x2> --action approve
-----
Result
------
Request ID: 0x2
Type: recovery
Status: approved
    Copy to Clipboard Toggle word wrap
  4. Download the key from the KRA UI.
Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat