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
  • 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
  • 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

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)
  • 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 X.509 certificate together
  • 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 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: to the best of my knowledge the provided "physical address" is currently not used in the registration process. Only the "logical address" (the public host name) is considered.

Note: this DNS publisher entry is the reason, why the SMP-ID can only used a limited character set.

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 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)
  • 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 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
  • 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).

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
  • All DNS records for participants linked to the SMP-ID publisher record are deleted
  • The publisher DNS record is 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
  • A new DNS entry 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).
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.

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: the latest version of the SML not only creates a CNAME record for each participant but also a DNS NAPTR record pointing to the publisher entry. For the NAPTR records, a special algorithm for creating DNS names is used instead: strip-trailing(base32(sha256(lowercase(ID-VALUE))), "=") + "." + ID-SCHEME + "." + SML-ZONE-NAME

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
  • The DNS record (B-...) 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: 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!