SMP and SML interactions

This page outlines how SMP and SML play together. The SML (Service Metadata Locator) is only central component in the Peppol eDelivery Network. The SMP (Service Metadata Publisher) is a decentralized registry for technical metadata.

Note: this information presented here shows the Peppol way which is different from the latest OASIS BDXL way. The SML currently used by Peppol (BDMSL operated by EC DG DIGIT) supports both ways, but this page ignores the non-Peppol aspects.

Table of contents
  1. Prerequisites
  2. Create SMP at SML
  3. Update SMP at SML
  4. Delete SMP from SML
  5. Create participant in SMP and SML
  6. Delete participant from SMP and SML
  7. References

Prerequisites

This page takes the following assumptions:

  • You have a running instance of an SMP server (that follows the Peppol SMP specification)
  • The SMP server runs on a publicly accessible web server that has a DNS name assigned
  • You have a Peppol SMP X.509 certificate that is compatible with the SML you want to interact with (production certificate for SML, test certificate for SMK)
  • You have chosen a so called SMP-ID that must not be changed afterwards
  • For the old style CNAME lookup (until October 31st, 2025):
    • The SMP server is reachable in the root ("/") path of that domain
    • The SMP server exposes the mandatory read-only APIs on port 80 without https
  • For the new style NAPTR lookup (from November 1st, 2025):
    • The SMP server exposes the mandatory read-only APIs on port 443 with https

Create SMP at SML

Every SMP must initially be registered to the SML. That needs to happen exactly once. Therefore you need to provide the following elements:

  • SMP X.509 certificate
  • SMP-ID
  • IP address of the machine (physical address).
    This may be defaulted to 1.1.1.1 as the public URL is the only mandatory part used by the SML.
  • Public URL of the SMP (logical address)

The following actions are taking place on the SML side:

  • The X.509 certificate is validated
  • The uniqueness of the SMP-ID is verified
  • The consistency of the provided parameters is checked
  • A local database entry is created, that links the SMP-ID and parts of the X.509 certificate together
  • For the old style CNAME lookup (until October 31st, 2025):
    • A new DNS entry in the form of SMP-ID.publisher.DNSZONE is created. This is the so-called publisher entry.
      SMP-ID is the input parameter.
      DNSZONE is the DNS zone in which the SML operates - for the production SML that is edelivery.tech.ec.europa.eu and for the test SMK this is acc.edelivery.tech.ec.europa.eu.
      The DNS entry itself is either a CNAME record (if the public URL is a domain name) or an A record (if the public URL consists of an IP address).
    • See e.g. http://brz.publisher.edelivery.tech.ec.europa.eu for an example of the SMP-ID BRZ on the production SML or http://brz-test-smp.publisher.acc.edelivery.tech.ec.europa.eu for an example with the SMP-ID BRZ-TEST-SMP on the test SMK. Both links bring you to the respective SMP instances.
    • Note: this DNS publisher entry is the reason, why the SMP-ID can only used a limited character set.
  • For the new style NAPTR lookup (from November 1st, 2025):
    • No such specific DNS entry is created - that is the reason, why an SMP URL affects all participant DNS entries

Note: this intermediate DNS record is helpful, if the public URL of an SMP changes. Instead of changing all participants that are linked to an SMP (which can be very many) only this single DNS record is changed, because all participant records are just CNAME records pointing to this "publisher" record.

Note: when using phoss SMP you have a GUI to do this smoothly at "Administration | SML | SML registration". Alternatively you can perform it via the SMP-SML Tools on this site.

Update SMP at SML

If the public URL or domain name of an SMP changes, this information must be propagated to the respective SML. The change of an SMP-ID is not foreseen, so this value must stay consistent. The change of an SMP certificate (e.g. because of expiration) can also not be done with this process. BDMSL foresees a specific process for this that is described at Peppol Certificate update.

The following elements are needed to update the SMP registration in the SML:

  • SMP X.509 certificate (must be the same as for initial registration)
  • SMP-ID (must be the same as for initial registration)
  • IP address of the machine (physical address).
    This may be defaulted to 1.1.1.1 as the public URL is the only mandatory part used by the SML.
  • Public URL of the SMP (logical address)

The following actions are taking place on the SML side:

  • The X.509 certificate is validated
  • The existence of the SMP-ID is verified
  • It is checked whether the SMP-ID is linked to the provided X.509 certificate
  • The consistency of the provided parameters is checked
  • The local database entry, that links the SMP-ID and X.509 certificate together, is updated
  • For the old style CNAME lookup (until October 31st, 2025):
    • The destination of the publisher DNS record (SMP-ID.publisher.DNSZONE) is updated to the new public URL. The DNS entry itself is either a CNAME record (if the public URL is a domain name) or an A record (if the public URL consists of an IP address).
  • For the new style NAPTR lookup (from November 1st, 2025):
    • Each participant linked to the provided SMP-ID needs an update to it DNS record

Note: when using phoss SMP you have a GUI to do this smoothly at "Administration | SML | SML registration". Alternatively you can perform it via the SMP-SML Tools on this site.

Delete SMP from SML

If an SMP leaves the network, after all participants were migrated to different SMPs, it must unregister itself from the SML.

Note: don't test this functionality if you already have participants registered, since all participant DNS entries will also be deleted.

The following elements are needed to delete the SMP registration from the SML:

  • SMP X.509 certificate (must be the same as for initial registration)
  • SMP-ID (must be the same as for initial registration)

The following actions are taking place on the SML side:

  • The X.509 certificate is validated
  • The existence of the SMP-ID is verified
  • It is checked whether the SMP-ID is linked to the X.509 certificate
  • The local database entries for all participants that are linked to that SMP-ID are deleted
  • The local database entry for the provided SMP-ID is deleted
  • For the old style CNAME lookup (until October 31st, 2025):
    • All DNS records for participants linked to the SMP-ID publisher record are deleted
    • The publisher DNS record is deleted
  • For the new style NAPTR lookup (from November 1st, 2025):
    • All DNS records for participants linked to the SMP-ID are deleted

Note: when using phoss SMP you have a GUI to do this smoothly at "Administration | SML | SML registration". Alternatively you can perform it via the SMP-SML Tools on this site.

Create participant in SMP and SML

Before you can register new participants, ensure you registered your SMP to the SML as stated above.

Each participant must be registered at the SML so that it can be addressed in the network. The following elements need to be provided to make it work:

  • SMP X.509 certificate
  • SMP-ID
  • Participant ID

The following actions are taking place on the SML side:

  • The X.509 certificate is validated
  • The existence of the SMP-ID is verified
  • It is checked whether the SMP-ID is linked to the X.509 certificate
  • The consistency of the provided parameters is checked
  • A local database entry is created, that links the SMP-ID and the participant identifier
  • For the old style CNAME lookup (until October 31st, 2025):
    • A new DNS CNAME record in the form of "B-"+hexstring(md5(lowercase(ID-VALUE)))+"."+ID-SCHEME+"."+DNSZONE is created.
      ID-SCHEME is part of the input parameter - the scheme part of the participant identifier (usually this is iso6523-actorid-upis)
      ID-VALUE is also part of the input parameter - the value part of the participant identifier
      DNSZONE is the DNS zone in which the SML operates - for the production SML that is edelivery.tech.ec.europa.eu and for the test SMK this is acc.edelivery.tech.ec.europa.eu.
      The DNS entry itself is a CNAME record pointing to the SMP publisher entry which in turn is itself a reference to the URL or IP provided at the SMP to SML registration process (see above).
    • Example: The URL created from e.g. the participant identifier iso6523-actorid-upis::9915:b is http://B-4bbe13b091709af417e9ef61c2e59678.iso6523-actorid-upis.edelivery.tech.ec.europa.eu. This is a reference to the publisher entry http://brz.publisher.edelivery.tech.ec.europa.eu created at the registration process (see above). Both links lead to the same IP and therefore to the same SMP instance.
  • For the new style NAPTR lookup (from November 1st, 2025):
    • A DNS NAPTR record in the form of strip-trailing(base32(sha-256(lowercase(ID-VALUE))),"=")+"."+ID-SCHEME+"."+DNSZONE is created.
      ID-SCHEME is part of the input parameter - the scheme part of the participant identifier (usually this is iso6523-actorid-upis)
      ID-VALUE is also part of the input parameter - the value part of the participant identifier
      DNSZONE is the DNS zone in which the SML operates - for the production SML that is edelivery.tech.ec.europa.eu and for the test SMK this is acc.edelivery.tech.ec.europa.eu.
      The DNS entry itself is a NAPTR record pointing to the SMP URL (!) provided at the SMP to SML registration process (see above).

Note: the changes to the DNS may not be directly visible to you, because the propagation of new entries can take up to 24 hours to be replicated to all distributed nodes.

Note: when using phoss SMP this is done implicitly if you create a service group but only if SML connection is enabled.

Delete participant from SMP and SML

If a participant is no longer needed, it must be manually unregistered from the SML.

The following elements are needed to delete the SMP registration from the SML:

  • SMP X.509 certificate (must be the same as for initial registration)
  • Participant ID

The following actions are taking place on the SML side:

  • The X.509 certificate is validated
  • The existence of the Participant ID is verified
  • It is checked whether the Participant ID is linked to the X.509 certificate
  • The local database entry for the provided Participant ID is deleted
  • For the old style CNAME lookup (until October 31st, 2025):
    • The DNS CNAME record (B-...) for that Participant ID is deleted
  • For the new style NAPTR lookup (from November 1st, 2025):
    • The DNS NAPTR record for that Participant ID is deleted

Note: the changes to the DNS may not be directly visible to you, because the propagation of new entries can take up to 24 hours to be replicated to all distributed nodes.

Note: of course the SML deletes both node types (CNAME and NAPTR) - it is just differentiated here for alignment with the Peppol migrations

Note: when using phoss SMP this is done implicitly if you delete a service group but only if SML connection is enabled.

References

You must be logged in to post a comment!