How to Change Access Point Sign Certificate?

Owned by Petteri Kivimäki
Last updated: Mar 09, 2023

By default, the Access Point has a self-signed sign certificate that's automatically generated during the Access Point installation process. Uploading a new certificate is possible using the Access Point UI (PMode → Parties → Select party → Edit → Certificate → Import). However, recreating the private key and applying for a new certificate is not possible through the Access Point UI. Instead, the operation requires shell access to the Access Point.

Step-by-step guide

The Access Point sign certificate can be changed by following the steps described below.

  1. First, take backup copy of the keystore file:

    cp -a /etc/harmony-ap/ap-keystore.jks /etc/harmony-ap/ap-keystore.jks.bak

  2. Generate a new private key and certificate signing request (CSR) by running the command:

    openssl req -x509 -newkey rsa:3072 -keyout harmony-ap-new.key -out harmony-ap-new.crt -days 365 -nodes
  3. Enter your CSR details.

  4. Locate and open the newly created CSR ("/etc/harmony-ap/harmony-ap-new.crt") in a text editor and copy all the text including:

    /etc/harmony-ap/harmony-ap-new.crt
    -----BEGIN CERTIFICATE REQUEST-----
And
-----END CERTIFICATE REQUEST-----
  5. Paste the contents of the CSR file in a local text file on your workstation.
  6. Purchase a certficate from a trusted Certificate Authority (CA) using the CSR file.
  7. Once the CA has issued the certificate, rename the certificate file to "harmony-ap-new.crt", and copy it to "/etc/harmony-ap/" directory on the Access Point.

  8. Create a PKCS#12 container ("/etc/harmony-ap/harmony-ap.p12") that includes the new key and certificate, and the certificate chain. Write down the container password ("<container_password>").

    The "<cert_alias>" placeholder MUST be replaced with the party name of the key owner. More information about the alias is available here.

    openssl pkcs12 -export -in harmony-ap-new.crt -inkey harmony-ap-new.key -out harmony-ap.p12 -name <cert_alias> -CAfile ca_bundle.crt -caname cacert
  9. Check the password of the keystore file from the "/etc/harmony-ap/domibus.properties" configuration file. The password is stored in the "domibus.security.keystore.password" property. Write down the password ("<ap_keystore_password>").

  10. Import the PKCS#12 container into the Access Point keystore.

    The "<cert_alias>" placeholder MUST be replaced with the party name of the key owner. More information about the alias is available here.

    keytool -J-Dkeystore.pkcs12.legacy -importkeystore -deststorepass <ap_keystore_password> -destkeypass <ap_keystore_password> -destkeystore /etc/harmony-ap/ap-keystore.jks -srckeystore /etc/harmony-ap/harmony-ap.p12 -srcstoretype PKCS12 -srcstorepass <container_password> -alias <cert_alias>

  11. Update the file permissions.

    chown -R harmony-ap:harmony-ap /etc/harmony-ap
chmod -R 0751 /etc/harmony-ap

  12. Restart the "harmony-ap" service.

    systemctl restart harmony-ap
  13. Check that the log file ("/var/log/harmony-ap/catalina.out") doesn't contain any sign key related errors.
  14. In case something goes wrong, restore the original files, and restart the "harmony-ap" service.