2.3. Dynamic Discovery Client

2.3.1. Purpose of the guide

This guide shows you how to integrate the Dynamic Discovery Client (DDC) as an independent component within your project. It aims to familiarise technical decision-makers, developers and testers with the eDelivery Dynamic Discovery infrastructure, providing insights into using the DDC for evaluating the SMP API and SML Dynamic Discovery processes.

2.3.1.1. What you will achieve

By the conclusion of this guide, you will have learnt how to use eDelivery’s DDC sample command-line interface (CLI) to:

  • Locate and retrieve SMP documents from both EU SEND SMP instances and GitLab repositories.

  • Conduct document searches using custom NAPTR services (for example, "Meta:CPPA").

  • Configure DDC’s TLS Client Authentication for SMP document retrieval.

  • Verify Service Metadata signatures.

  • Directly fetch SMP Service Metadata, bypassing DNS lookup.

2.3.1.2. What you will need

  • Approximately 30 minutes.

  • A basic to medium understanding of Dynamic Discovery processes.

  • Java 8 or higher installed.

  • BIND 9 dig tool for DNS queries.

  • The DDC .jar file.

  • Access to Bash or an equivalent shell.

2.3.1.3. How to complete this guide

Familiarise yourself with the Dynamic Discovery service and DDC features through brief feature descriptions and step-by-step instructions provided below.

2.3.2. Introduction

The Dynamic Discovery Client (DDC) serves as a pivotal tool within the Dynamic Discovery process. It allows for the identification and retrieval of message exchange capabilities from counterparties.

This document serves as a guide for utilising the DDC, detailing both its operation as a standalone command-line interface (CLI) component and its Access Point integration as a library.

The DDC performs the following to discover those capabilities:

  • First, it locates the Service Metadata Publisher (SMP) where the counterparty has published its Service Metadata. It does this by sending a DNS query to the Service Metadata Locator (SML) DNS.

  • Secondly, it sends an HTTP GET request to the SMP and obtains the counterparty’s service capabilities metadata document.

Diagram

2.3.3. Step-by-step guide

Below find a step-by-step guide to the process of using the DDC to discover and fetch the counterparty’s message exchange capabilities metadata document.

2.3.3.1. Step 1: Download eDelivery Dynamic Discovery Client

Download the DDC sample. You can do it in the following ways:

wget -O ddc.jar https://ec.europa.eu/digital-building-blocks/artifact/repository/eDelivery/eu/europa/ec/dynamic-discovery/dynamic-discovery-cli/2.1.1/dynamic-discovery-cli-2.1.1.jar

  • Use your web browser (click here). Then, rename the downloaded file to ddc.jar to simplify the next steps.

2.3.3.2. Step 2: Execute ddc client commands

This step introduces you to basic DDC operations, such as finding SMP locations and fetching metadata.

Our DDC client is a Java application: ensure Java 8 or higher is installed on your computer.

Launch the DDC client via the terminal to display the available commands and their descriptions:

java -jar ddc.jar
Commands:

 -dns        Command discovers SMP location
 -get        Command discovers and fetch metadata from SMP
 -h,--help   Prints help

Use "java -jar ddc.jar -command_name --help" for usage of command_name.

The -dns command discovers the SMP location for the given participant identifier with the following options:

usage: java -jar ddc.jar -dns [-options]

'dns' options:

 -d,--domain <arg>                 Network DNS domain: eq.:
                                   acc.edelivery.tech.ec.europa.eu
 -dns                              Command discovers SMP location
 -h,--help                         Prints help
 -o,--output <arg>                 Output filename. If file already exists
                                   it is overwritten. If not provided,
                                   output is printed to console
 -ri,--resource-identifier <arg>   party identifier: ex: 0088:98765digit
 -rs,--resource-scheme <arg>       party identifier: iso6523-actorid-upis
 -s,--services <arg>               Comma separated NAPTR service value as:
                                   Meta:SMP,meta:cppa
 -t,--dns-type <arg>               List of DNS record types, CNAME,NAPTR

Use "java -jar ddc.jar -dns --help" for usage of command_name.

The -get command discovers and fetches metadata from the SMP.

usage: java -jar ddc.jar -get [-options]

'get' options:

 -d,--domain <arg>                    Network DNS domain: eq.:
                                      acc.edelivery.tech.ec.europa.eu
 -get                                 Command discovers and fetch metadata
                                      from SMP
 -h,--help                            Prints help
 -kf,--keystore-filepath <arg>        Client TLS keystore file path
 -kp,--keystore-password <arg>        Client TLS keystore password
 -kt,--keystore-type <arg>            Client TLS keystore type: Default
                                      PKCS12
 -o,--output <arg>                    Output filename. If file already
                                      exists it is overwritten. If not
                                      provided, output is printed to
                                      console
 -ri,--resource-identifier <arg>      party identifier: ex:
                                      0088:98765digit
 -rs,--resource-scheme <arg>          party identifier:
                                      iso6523-actorid-upis
 -s,--services <arg>                  Comma separated NAPTR service value
                                      as: Meta:SMP,meta:cppa
 -si,--subresource-identifier <arg>   Subresource identifier: ex: Invoice
 -ss,--subresource-scheme <arg>       Subresource identifier:org:xml
 -t,--dns-type <arg>                  List of DNS record types,
                                      CNAME,NAPTR
 -tf,--truststore-filepath <arg>      TLS truststore file path
 -tp,--truststore-password <arg>      TLS truststore password
 -tt,--truststore-type <arg>          TLS truststore type: Default PKCS12

Use "java -jar ddc.jar -get --help" for usage of command_name.
2.3.3.3. Step 3: Discover SMP service for participant

Now that we have successfully executed our first command, we can discover and fetch a sample document. For this, we will use the DDC to identify the message exchange capabilities metadata for the following Participant Identifier: , urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001.

The participant published its data on the eDelivery EU SEND SMP service with the following SML DNS domain: test.acc.edelivery.tech.ec.europa.eu.

The following command discovers and fetches the OASIS SMP 1.0 ServiceGroup document from the EU SEND SMP:

java -jar ddc.jar -dns -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001  -d test.acc.edelivery.tech.ec.europa.eu -t CNAME,NAPTR

Note the following parameters:

  • -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001: Participant Identifier.

  • -d test.acc.edelivery.tech.ec.europa.eu: DNS domain name of the SML service.

  • -t CNAME,NAPTR: List of DNS record types to query. If list is not given, only NAPTR records are queried.

The output to the previous command is the following:

Resolving DNS for participant: [ParticipantIdentifier{identifier='urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001', scheme='null'}] and domain: [test.acc.edelivery.tech.ec.europa.eu]

CNAME query: B-70c708123575f9c8e308f5abbdaf979a.test.acc.edelivery.tech.ec.europa.eu
B-70c708123575f9c8e308f5abbdaf979a.test.acc.edelivery.tech.ec.europa.eu.	60	IN	CNAME	SMP-SHS-ACC-TEST.publisher.test.acc.edelivery.tech.ec.europa.eu.
SMP-SHS-ACC-TEST.publisher.test.acc.edelivery.tech.ec.europa.eu.	60	IN	CNAME	smp-ext-acc.eusfx.ec.europa.eu.
smp-ext-acc.eusfx.ec.europa.eu.	2706	IN	CNAME	ip-star-eusfx.ec.europa.eu.


NAPTR query: B4FBLI2PMR6YHV4TBK27AB6LFYTG4GQAITDM4O74IUE7CPEINVGQ.test.acc.edelivery.tech.ec.europa.eu
B4FBLI2PMR6YHV4TBK27AB6LFYTG4GQAITDM4O74IUE7CPEINVGQ.test.acc.edelivery.tech.ec.europa.eu.	60	IN	NAPTR	100 10 "U" "Meta:SMP" "!.*!https://smp-ext-acc.eusfx.ec.europa.eu/!" .
2.3.3.4. Step 4: Fetch OASIS SMP 1.0 ServiceGroup document from eDelivery EU SEND SMP service

In this chapter we will discover and retrieve an OASIS SMP 1.0 ServiceGroup document for the following Participant Identifier: urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001.

The document is part of the OASIS SMP 1.0 specification, which contains a list of documents for which Service Metadata capabilities are published by the participant.

To discover and retrieve the document, use the -get command:

java -jar ddc.jar -get  -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001 -d test.acc.edelivery.tech.ec.europa.eu -o service-group.xml

Note the following parameters:

  • -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001: Participant Identifier.

  • -d test.acc.edelivery.tech.ec.europa.eu: DNS domain name of the SML service.

  • -o service-group.xml: File name for the retrieved document. If the file already exists, it is overwritten. If not provided, the output is printed to the console.

Our document has been saved as service-group.xml. Here is its content:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceGroup xmlns="http://docs.oasis-open.org/bdxr/ns/SMP/2016/05">
    <ParticipantIdentifier scheme="urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide">party-id-001
    </ParticipantIdentifier>
    <ServiceMetadataReferenceCollection>
        <ServiceMetadataReference
                href="https://smp-ext-acc.eusfx.ec.europa.eu/urn%3Aoasis%3Anames%3Atc%3Aebcore%3Apartyid-type%3Aunregistered%3Asmp-guide%3Aparty-id-001/services/message-exchange%3A%3Aconnectivity-document-01"/>
    </ServiceMetadataReferenceCollection>
</ServiceGroup>

The file was retrieved from the eDelivery EU SEND SMP service. The SMP instance’s address (https://smp-ext-acc.eusfx.ec.europa.eu) was discovered using the DNS query as described in the previous chapter. To retrieve the document, the DDC client appended the Participant Identifier to the SMP URL address as in the example below:

https://smp-ext-acc.eusfx.ec.europa.eu/urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001
2.3.3.5. Step 5: Fetch sub-resource document: OASIS SMP 1.0 Service Metadata from eDelivery EU SEND SMP service

The OASIS SMP 1.0 ServiceMetadata document is part of the OASIS SMP 1.0 specification, which contains the endpoint information for a specific document type and process identifier that an entity can receive in the network. A client can request a ServiceMetadata document from an SMP service to discover the transport methods, certificates, and other details that are required to exchange business documents with the participant.

To retrieve the ServiceMetadata document with the message-exchange::connectivity-document-01 ID for the participant urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001, use the following command:

java -jar ddc.jar -get -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001 \
      -si connectivity-document-01 \
      -ss message-exchange  \
      -d test.acc.edelivery.tech.ec.europa.eu  \
      -o service-metadata.xml

Note the following parameters:

  • -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001: Participant Identifier.

  • -d test.acc.edelivery.tech.ec.europa.eu: DNS domain name of the SML service.

  • -si connectivity-document-01: Sub-resource identifier.

  • -ss message-exchange: Sub-resource scheme.

  • -o service-metadata.xml: File name for the retrieved document. If the file already exists, it is overwritten. If not provided, the output is printed to the console.

Our document has been saved as service-metadata.xml. Here is its content:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SignedServiceMetadata xmlns="http://docs.oasis-open.org/bdxr/ns/SMP/2016/05">
    <ServiceMetadata>
        <ServiceInformation>
            <ParticipantIdentifier scheme="urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide">
                party-id-001
            </ParticipantIdentifier>
            <DocumentIdentifier scheme="message-exchange">connectivity-document-01</DocumentIdentifier>
            <ProcessList>
                <Process>
                    <ProcessIdentifier scheme="mmessage-service-type">submit-message</ProcessIdentifier>
                    <ServiceEndpointList>
                        <Endpoint transportProfile="bdxr-transport-ebms3-as4-v1p0">
                            <EndpointURI>https://my-ap-address.local</EndpointURI>
                            <Certificate>Q2VydGlmaWNhdGUgZGF0YSA=</Certificate>
                            <ServiceDescription>Service for submitting messages</ServiceDescription>
                            <TechnicalContactUrl>www.my-company.eu</TechnicalContactUrl>
                        </Endpoint>
                    </ServiceEndpointList>
                </Process>
            </ProcessList>
        </ServiceInformation>
    </ServiceMetadata>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <DigestValue>e5riWHrertUkilvKGRmNY8clcrOk3YToAreumZyq7XY=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>im9n8cRJ...GA27YzA==
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName>CN=EUSEND_SMP_ACC,OU=EUSEND,OU=SMP_ACC,OU=CEF_eDelivery.europa.eu,O=eDelivery
                    Support,C=BE
                </X509SubjectName>
                <X509Certificate>MIIFyDCC...fTI=</X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
</SignedServiceMetadata>
2.3.3.6. Step 6: Fetch document from git repository

Because the retrieval of the document uses a basic HTTP GET request, the DDC can be used to fetch documents from any HTTP server beyond the dedicated SMP services. In this example we will fetch a sample document from a git repository.

The document is published at Gitlab: https://code.europa.eu/edelivery/cppa3/-/tree/main/cpp/.

The participant has the following Participant Identifier: iso6523-actorid-upis::0088:test:cppa3.

For that participant, the following NAPTR record was added to the SML service:

DLORA46AHSNQ56YTTUBALSYNTZYLHQ7JROBAUJJMR6D2TUF6CFJA.iso6523-actorid-upis.test.acc.edelivery.tech.ec.europa.eu 100 10 "U" "meta:cppa3" "!.*!https://code.europa.eu/edelivery/cppa3/-/raw/main/cpp/!" .

The DNS NAPTR record can be validated with the following DDC command:

java -jar ddc.jar -dns -ri 0088:test:cppa3 -rs iso6523-actorid-upis -s meta:cppa3 -d acc.edelivery.tech.ec.europa.eu

Note the following parameters:

  • -ri 0088:test:cppa3: Participant identifier, the Id part of the participant identifier.

  • -rs iso6523-actorid-upis: Participant identifier scheme.

  • -d test.acc.edelivery.tech.ec.europa.eu: DNS domain name of the SML service.

  • -s Meta:CPPA3: NAPTR service value to search for. By default, the DDC client searches for the Meta:SMP service value, but it can be configured to search for other service values as well such as CPPA/CPP documents in this case.

The same DNS query can be executed using the Bind9 dig command, but when using dig, we have to create a query string/domain DLORA46AHSNQ56YTTUBALSYNTZYLHQ7JROBAUJJMR6D2TUF6CFJA.iso6523-actorid-upis.test.acc.edelivery.tech.ec.europa.eu manually. The following command can be used to execute the DNS query:

dig DLORA46AHSNQ56YTTUBALSYNTZYLHQ7JROBAUJJMR6D2TUF6CFJA.iso6523-actorid-upis.acc.edelivery.tech.ec.europa.eu NAPTR

To retrieve the document the participant/resource identifier, use the following command -get:

java -jar ddc.jar -pi 0088:test:cppa3 -ps iso6523-actorid-upis -s meta:cppa3 -d acc.edelivery.tech.ec.europa.eu -o data.xml

Our document has been saved as data.xml.

2.3.3.7. Step 7: Direct document fetch

In some cases the user may want to fetch the document directly from the known SMP instance without the DNS lookup. The DDC can be configured to fetch the document directly from the known SMP instance. The following example shows how to fetch the document directly from the known SMP instance.

java -jar ddc.jar -get  -ri urn:oasis:names:tc:ebcore:partyid-type:unregistered:smp-guide:party-id-001 \
    -smp https://smp-ext-acc.eusfx.ec.europa.eu/ \
    -o direct-fetch.xml

Note the following parameters:

2.3.4. Further reading

For a summary of the knowledge discussed until now and recommendations for next steps, see the next guide. :toc:

← Previous: Introduction to Dynamic Delegation Discovery System (DDDS) infrastructure | ↑ Up: How to: Guides | ⌂ Home: DomiSMP 5.0 | Next: DomiSMP as a Spring Boot application →