PEPPOL Certificate update

This article tries to give an overview over the steps necessary to perform a certificate update in the PEPPOL network. It is suggested to read the introduction to the PEPPOL PKI before continuing here.

Background information

Short note: the information provided here is meant to be as product independent as possible, so if you have tool specific questions, please contact your vendor directly.

Another note: for an AP certificate update you must make sure to update the certificate in your Access Point software and in all SMP entries that point to your AP. For an SMP certificate update, you only need to update your SMP software.

The terminology in this article differentiates between keystore and truststore. A keystore is considered the collection of your private keys that might not be disclosed to the public.
A truststore on the contrary is a collection of public certificates that are trustworthy. Usually an application has one keystore and one truststore. Both types can contain different private keys and/or public certificates, that are accessed by so called aliases. Both keystore and truststore usually require a password to access it. Additionally each key entry (alias) can have it's own password, that may be different from the password to access the file.
PEPPOL does not provide a common truststore, but I assembled some common truststores that can be found at https://github.com/phax/peppol-commons/tree/master/peppol-commons/src/main/resources/truststore and try to serve different requirements. E.g. phoss SMP uses the complete-truststore.jks by default. Truststores are usually public and should not contain secret keys. Theoretically keystore and truststore can reside in the same file, but that is considered bad practice.

The PEPPOL PKI update that happened in 2018 was a special case of a certificate update, because it required to update the truststore as well, because a completely new PKI was introduced. Regular certificate updates only contain updates of keystores.

Updating an Access Point certificate

The AP certificate update consists of two basic steps:

  1. update the the AP software itself
  2. update the certificate in all endpoints SMP endpoints

It's important that the AP certificate contains the full chain together with the key, as a single alias in the keystore. phoss SMP Wiki contains an explanation how this can be achieved for the SMP certificate using commandline commands. It can be used equivalently for AP certificates.

Update the AP software

The update of the AP software is vendor specific. Usually you have to either provide a new keystore file, containing the new private key (with the full chain) or you update your existing keystore file and add the new private key. If you added a new private key to an existing keystore, you might need to update the configuration as well, and provide the new alias.
Note: some AP software may need a special keystore that only contains a single key. Please contact your vendor for specific questions.

Update the SMP endpoints

The public part of your AP certificate is referenced in all SMP endpoint that link to your Access Point. Therefore this certificate must also be updated immediately after you updated the AP software, as this certificate is used by sending clients, to verify the integrity of your technical acknowledgement (AS2 MDN or AS4 Receipt). The SMP usually expects your PEM encoded public certificate.
When using phoss SMP you can use the "Bulk change certificate" page to update the certificates of all relevant endpoints at once.
Note: never publish your AP private key in an SMP endpoint

Note: besides the change in the AP and the SMP endpoints, the AP certificate must not be updated in any other PEPPOL component.

Updating an SMP certificate

The SMP certificate update consists of two basic steps:

  1. notify the SML about your new certificate, ideally ahead of time
  2. update the the SMP software itself

It's important that the SMP certificate contains the full chain together with the key, as a single alias in the keystore. phoss SMP Wiki contains an explanation how this can be achieved using commandline commands.

Notifying the SML

Updating the SML is mandatory - you must do this.
Note: remember to only use test SMP certificates with the SMK and production SMP certificates with the SML.

The SML links your SMP-ID with your SMP certificate and your public endpoint URL. In case of a certificate update, the SML offers a special Webservice interface to indicate a future certificate change. This interface can only be used, if the certificate exchange happens in the future, and the date provided must at least be tomorrow (the day after the date of request). Additionally your existing certificate may not be expired yet. You can perform this certificate update request e.g. via this site but keep in mind that this requires your private key. Common SMP software like phoss SMP contains this functionality "out of the box".
Note: the SML only needs the public certificate of your new SMP certificate - don't provide them with your private key!
Note: you need to manually update your SMP certificate in your SMP software at exactly the date you specified in that update request, otherwise you won't be able to perform changes in the SML.

If your certificate is already expired, you need to contact CEF support and provide the following information: old certificate subject and serial as well as new certificate subject and serial.
Note: you may already update your SMP software with the new certificate, because the old certificate is anyway useless.
Note: no further action or service call to the SML is necessary, if you are using this manual process.

Update the SMP software

The update of your SMP certificate in your SMP software heavily depends on the software used. In most cases, the keystore is referenced in some kind of configuration file. Either you update that keystore or you configure a completely new keystore.
E.g. in phoss SMP the keystore is configured in two properties files: smp-server.properties and pd-client.properties. If you provide a new keystore, ensure to adopt the path in both files. A restart of the SMP web application is required to make it work, if the path changed. If you modified the existing keystore, no restart is required if you manually press the "Reload keystore" button in the administration GUI. After a certificate change it is recommended to visit the "Certificate information" page, to check if the modification was successful or not.

Note: the SMP ID must not be changed during the update process. The SMP ID must never change.
Note: no special action is needed for PEPPOL Directory. All business card will be available, independent of the certificate status.

You must be logged in to post a comment!