Archive for November, 2011

Here I will explain the technical aspects of sending and receiving documents via PEPPOL , which are the initials of “Pan-European Public Procurement OnLine.” It is a pilot project on public procurement to exchange electronic documents with the European public administration. This technical information is public, but is scattered around the Internet in forums and documents of all kinds.

Architecture

The three elements of the architecture are the AP, the SMP and an SML.

AP = Access Point. Is the service to receive documents. For example ap.b2brouter.com

SMP = Metadata Service Publisher. Is the service to publish data from participants. For example it tells you to which AP you have to send certain types of documents. An example of SMP is smp.b2brouter.com

SML = Locator Service Metadata. A DNS server that, given a recipient, tells you which SML has its data. The DNS domain zone is peppolcentral.org.

Certificates

Participants are identified and authorized via PKI X.509. The pilot project has a root CA and three intermediate CAs where “PEPPOL Test Root CA” signs the intermediate CAs.

It takes two certificates on the AP and the SMP. There is a third certificate, called STS, which is not used. These certificates must be requested if you want to participate in PEPPOL pilot .

1. The AP certificate is signed by the “PEPPOL Access Point Test CA”. Used to send and receive from other AP.
2. The SMP certificate is signed by the “Service Metadata Publisher PEPPOL Test CA”. Used to publish DNS entries in the SML.
3. The STS is signed by the “Test CA PEPPOL Security Token Service” and it is currently useless.

Send documents

In order to send something clearly we need to know the address of the recipient, and in the case of Peppol, the address of the recipient is a Participant ID, Process ID and a Document ID.

To send a document the first step is to find out which is the AP of the recipient. To do this you take the address of the recipient (participant, process and document) and use the SML and an SMP:

1. The Participant ID becomes a DNS zone using an MD5 hash, a prefix “B-” and a suffix. For example, Participant ID “9912: esb63276174” becomes “B-ae2866398fd1d4c0d35343e8464a5258.iso6523-actorid-upis.sml.peppolcentral.org”
2. The DNS zone is resolved and you get an IP. This is the IP of the SMP, which is the place where information concerning the Participant ID is. In our example, the zone resolves to CNAME smp.b2brouter.com and to the IP of then SMP.
3. Finally, HTTP is used to read the data of the Participant ID that the SMP has published in the URL http://B-ae2866398fd1d4c0d35343e8464a5258.iso6523-actorid-upis.sml.peppolcentral.org/complete/iso6523-actorid-upis::9912:esb63276174

The XML document returned by the SMP contains the reference to the AP that we seek. Within the XML there is the list of documents accepted by the participant, and for each document the list of processes. For example, to send an invoice “urn: oasis: names: specification: UBL: schema: xsd: Invoice-2:: Invoice process (…)” to the process “urn: www.cenbii.eu:profile:bii04:ver1 .0” in this case the AP would be ap.b2brouter.com .

Once you know the URL of the destination AP just send the document using what they call “Secure Trusted Asynchronous Reliable Transport”  or just START, which defines how the AP must use these 5 technologies to communicate:

• SOAP 1.1 – Simple Object Access Protocol.
• WS-Security 1.1 – a flexible and feature-rich extension to SOAP web service to apply to security.
• WS-Transfer – transfer in defining the specification of an XML representation of an WS-addressable resource – as a standard approach to accessing the message channels.
• WS-ReliableMessaging 1.1 – SOAP in Protocol That Allows messages to be delivered reliably between distributed applications.
• SAML 2.0 – Security Assertion Markup Language – an XML-based open standard for exchanging authentication and authorization data between security domains.

Luckily the reference implementation is in Java and Java already has all the necessary WS-* libraries.

Java Keystores

It is very important to be clear about which certificates to use in each element of the architecture:

• Both the client and the server need the AP certificate signed by the “Test CA PEPPOL Access Point” to send and receive. We will create a keystore, let’s name it ap.jks
• The SMP requires a certificate signed by the “Service Metadata Publisher PEPPOL Test CA” to update the DNS entries in the SML. We will create another keystore, let’s name it smp.jks
• We also need an additional keystore (the trust store) with the certificates that we trust (the ones from Peppol CAs). Let’s name it peppol-cacerts.jks

To create keystores you can use Portecle because Java’s keytool is rather cryptic. Things to consider:

1. Use the alias “1” fot the private key.
2. Use “peppol” as password for both the keystore and the private key.
3. Use the “Import CA Reply” , with the right mouse button over “1”, to add your certificate signed by the CA.
4. The AP server keystore (ap.jks) should have only one certificate because it just uses the first it founds.

Implementations

The implementations that we have used are all open source:

• Server Access Point – Java web application, Netbeans project
• Client to send to an Access Point – Java application, Netbeans project
• Metadata Server Service Publisher – Java web application, Maven Project
• Client to manage entries in the Metadata Service Publisher – Java application, Maven Project
• Client to manage entries in the Metadata Service Locator – Java desktop application, Maven Project

We’ve also developed some auxiliary tools that can be found at github.