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.
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.
The AP certificate update consists of two basic steps:
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.
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 ("pointer") to be used.
Note: some AP software may need a special keystore that only contains a single key. Please contact your vendor for specific questions.
The public part of your AP certificate is referenced in all SMP endpoints 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 (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.
Warning: never publish your AP private key in an SMP endpoint
Note: when you use "SMP forwarding" (one SMP instance routing different document types for one participant ID to different APs), you must also inform the forwarding SMP about your new public AP certificate. There is no standardized process to do this. Never share the private AP key with the forwarding SMP.
Note: besides the change in the AP and the SMP endpoints, the AP certificate must not be updated in any other Peppol component.
The SMP certificate update consists of two basic steps:
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.
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 SMK/SML links your SMP-ID with your SMP certificate and your public SMP URL.
In case of a certificate update, the SML offers a special SOAP 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).
The SML will replace the certificate at the provided date at 02:00am Brussels Time (CET/CEST).
Additionally, your existing certificate may not be expired yet for this to work.
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: 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 anymore.
Warning: the SML only needs the public certificate of your new SMP certificate - don't provide them with your private key!
If your certificate is already expired, you need to contact EC eDelivery support by email and provide the following information:
-----BEGIN CERTIFICATE-----
and end with -----END CERTIFICATE-----
)
Note: you may already update your SMP software with the new SMP 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.
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.
In recent phoss SMP versions, the keystore is configured in one properties file: application.properties
.
If the keystore path changed, a restart of the SMP web application is required to make it work.
If you modified the existing keystore on the fly, 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 changes were accepted 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 Cards will be available, independent of the certificate status.