PingIDM 7.5.0

CA-signed certificates

You can use existing CA-signed certificates to secure connections and data by importing the certificates into the keystore, and referencing them your boot.properties file. Use the keytool command to import an existing certificate into the keystore.

Import CA-signed certificates

The following process imports a CA-signed certificate into the keystore, with the alias example-com. Replace this alias with the alias of your certificate:

  1. Stop the server if it is running.

  2. Back up your existing openidm/security/keystore and openidm/security/truststore files.

  3. Use the keytool command to import your existing certificate into the keystore, substituting your specific information:

    example-cert.p12

    The name of your certificate file.
    srcstorepass

    The certificate password.
    example-com

    The existing certificate alias.
    destination keystore password

    The password for the keystore.

    		 
    keytool \
-importkeystore \
-srckeystore example-cert.p12 \
-srcstoretype PKCS12 \
-srcstorepass changeit \
-srcalias example-com \
-destkeystore keystore.jceks \
-deststoretype JCEKS \
-destalias openidm-localhost
Importing keystore example-cert.p12 to keystore.jceks...
Enter destination keystore password: changeit

    The keytool command creates a trusted certificate entry with the specified alias and associates it with the imported certificate. The certificate is imported into the keystore with the alias openidm-localhost. If you want to use a different alias, you must modify your resolver/boot.properties file to reference that alias, as shown in the following step.

    The certificate entry password must be the same as the IDM keystore password. If the source certificate entry password is different from the target keystore password, use the -destkeypass option with the same value as the -deststorepass option to make the certificate password match the target keystore password. If you do not make these passwords the same, no error is generated when you import the certificate (or when you read the certificate entry in the destination keystore), but IDM will fail to start with the following exception:

    java.security.UnrecoverableKeyException: Given final block not properly padded.

  4. If you specified an alias other than openidm-localhost for the new certificate, change the value of openidm.https.keystore.cert.alias in your resolver/boot.properties file to that alias. For example, if your new certificate alias is example-com, change the boot.properties file as follows:

    openidm.https.keystore.cert.alias=example-com

  5. Restart the server.

Delete certificates

When using CA-signed certificates for encryption, it is a best practice to delete all unused default certificates from the keystore and truststore using the keytool command, as shown in the following examples:

  • To delete the openidm-localhost certificate from the keystore:

    keytool \
-delete \
-alias openidm-localhost \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype JCEKS \
-storepass changeit

  • To delete the openidm-localhost certificate from the truststore:

    keytool \
-delete \
-alias openidm-localhost \
-keystore /path/to/openidm/security/truststore \
-storepass changeit

You can use similar commands to delete custom certificates from the keystore and truststore, specifying the certificate alias in the request.

Delete root CA certificates

The Java and IDM truststore files include a number of root CA certificates. Although the probability of a compromised root CA certificate is low, it is a best practice to delete unused root CA certificates.

To review the list of root CA certificates in the IDM truststore:

keytool \
-list \
-keystore /path/to/openidm/security/truststore \
-storepass changeit

On UNIX/Linux systems, you can find additional lists of root CA certificates in files named cacerts. These include root CA certificates associated with your Java environment, typically located in the ${JAVA_HOME}/jre/lib/security/cacerts directory.

Before making changes to Java environment keystore files, verify any Java-related cacerts files are up-to-date and that you have a supported Java version installed.

You can delete root CA certificates with the keytool command. For example, to remove the hypothetical examplecomca2 certificate from the truststore:

keytool \
-delete \
-keystore /path/to/openidm/security/truststore \
-storepass changeit \
-alias examplecomca2

On Windows systems, you can manage certificates with the Microsoft Management Console (MMC) snap-in tool. For more information, refer to Working With Certificates.