Setup Peppol AP

This page explains how to setup a Peppol AP from scratch. AP is the abbreviation for Access Point which is the technical endpoint for sending and receiving business documents. See the Dictionary for more abbreviations.

Since 2020-02-01 AS4 is the mandatory transport protocol in the Peppol eDelivery network and AS2 transport protocol got an upgrade to "Peppol AS2 v2" (see details below).
This page was originally created for AS2 and is now partially extended for AS4 - more details to come.

There are a few known possibilities (I'm aware of) on how to build/run a Peppol AccessPoint.

  • Oxalis is a prebuild solution. It is an Open Source project written in Java. It supports AS2 and AS4 but comes without professional support. Especially the interoperability of the AS4 implementation is not good as they passed the CEF conformance test only partially.
  • Holodeck B2B is also a prebuild solution. It is an Open Source project written in Java. It supports AS2 and AS4 and comes with commercial support.
  • The solutions described in this document are:
    phase4 as the AS4 communication channel for sending and receiving Peppol AS4 messages.
    as2-lib as the AS2 communication channel and as2-peppol-servlet for receiving Peppol AS2 messages.
    No external AS2/AS4 software is required for using these projects, so I'm presenting fully self-contained Open Source solutions. Both solutions are used by commercial vendors around the globe.

Table of contents
  1. Prerequisites
  2. AS4 specifics
    1. AS4 Message structure
    2. AS4 AccessPoint receiver
    3. AS4 AccessPoint sender
  3. AS2 specifics
    1. AS2 Message structure
    2. AS2 AccessPoint receiver
    3. AS2 AccessPoint sender

Prerequisites

Before you can start you need to have the following information in place:

  1. As the very first step you need to sign the TIAs (Transport Infrastructure Agreements) with OpenPEPPOL AISBL
  2. Afterwards you need to apply for an AP certificate at OpenPEPPOL. This certificate is required to run the AP.
  3. At least one of the default Peppol BIS v2 (processes) must be implemented (according to the TIAs). A list of all available BISs is available on the Peppol website.
  4. You should have a look at the official Peppol AS4 profile and optionally at official Peppol AS2 specification.
  5. You should have a look at the official Peppol Envelope specification (SBDH).
  6. You should be familiar with Java
  7. Basic knowledge about Apache Tomcat (and optionally a web server) should be present

AS4 as a transport protocol (mandatory)

The Peppol AS4 profile is based on the CEF eDelivery AS4 1.14 profile which in turn is a (non-perfect) profile of the OASIS AS4 profile v1.0 which (you guessed it) is a profile of the OASIS ebXML Messaging V3.

AS4 Message structure

Peppol adds a specific limitation on the usage of AS4. AS4 Messages must be signed and encrypted. AS4 messages must have exactly one encrypted payload which is a Standard Business Document (SBD). Peppol AS4 message MUST use the MIME encoding for message transmission.

AS4 AccessPoint receiver

See the official phase4 documentation on phase4-peppol-servlet for details.

AS4 AccessPoint sender

See the official phase4 documentation on phase4-peppol-client for details.

AS2 as a transport protocol (optional)

AS2 is a transport protocol specified in RFC 4130. AS2 version 1.1 adding compression is specified in RFC 5402. The MDN is specified in RFC 3798. Algorithm names are defined in RFC 5751 (S/MIME 3.2) which supersedes RFC 3851 (S/MIME 3.1).

AS2 Message structure

An AccessPoint is a technical adapter for sending and receiving Peppol UBL documents. The following images shows the overall structure of a transmitted AS2 message in a very simplified way:

Peppol AS2 message structure

The outermost container is an S/MIME (Secure / Multipurpose Internet Mail Extensions) message. It is a basic MIME message including signature data. One MIME part of the message is the so called Standard Business Document Header (SBDH). It is a UN/CEFACT standard for merging XML documents with relevant metadata into a single XML document. Peppol maintains its own Envelope specification that is based on SBDH. Finally inside the SBDH the main UBL business document is contained. The complete UBL 2.1 specifications can be downloaded from the OASIS UBL web site.

Implementation

This section points to projects that help in implementing the different layers of an AS2 message. If you are already familiar with these concepts you may simply skip this section.

  • S/MIME: to read and write S/MIME messages The Legion of the Bouncy Castle provides tools for it. It is licensed under an MIT-like license. The latest version 1.62 is used within as2-lib for S/MIME handling. The relevant Maven artefacts are: 
        <dependency>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcmail-jdk15on</artifactId>
      <version>1.64</version>
    </dependency>
    <dependency>
      <groupId>com.sun.mail</groupId>
      <artifactId>jakarta.mail</artifactId>
      <version>1.6.4</version>
    </dependency>
  • SBDH: to read an write SBDH messages I created a Java library called ph-sbdh which uses JAXB generated objects. Additionally the Java library peppol-sbdh can be used on top of ph-sbdh as it adds the Peppol specific requirements. Both libraries are licensed under the Apache 2.0 license. The relevant Maven artefacts are: 
        <dependency>
      <groupId>com.helger</groupId>
      <artifactId>ph-sbdh</artifactId>
      <version>4.1.0</version>
    </dependency>
    <dependency>
      <groupId>com.helger</groupId>
      <artifactId>peppol-sbdh</artifactId>
      <version>8.0.0</version>
    </dependency>
  • UBL 2.1: to read an write UBL messages I created a Java library called ph-ubl which uses JAXB generated objects. This library is licensed under the Apache 2.0 license. The relevant Maven artefacts are: 
        <dependency>
      <groupId>com.helger</groupId>
      <artifactId>ph-ubl21</artifactId>
      <version>6.2.1</version>
    </dependency>

AS2 AccessPoint receiver

An example project that shows how to receive Peppol documents via AS2 can be found in the as2-peppol-server project. It uses as2-lib, ph-ubl and peppol-sbdh to receive messages from arbitrary Peppol AS2 receivers. It requires no external AS2 handler (like Mendelson) and no mandatory database setup. as2-peppol-server is a Java 1.8+ project and licensed under Apache 2.0 license.

Detailed setup description can be found directly on the as2-peppol-server project page.

AS2 AccessPoint sender

An example project that shows how to send Peppol documents via AS2 can be found in the as2-peppol-client project. It uses as2-lib, ph-ubl and peppol-sbdh to send messages to arbitrary Peppol AS2 receivers. as2-peppol-client is a Java 1.8+ project and licensed under Apache 2.0 license.

The steps to send a document are outlined as follows:

  1. As a prerequisite, you need to know the following things:
    1. The UBL document to be send. How you create your UBL file is out of scope!
    2. The Peppol participant ID of the receiver (e.g. 0088:test). The determination of the recipient ID is not in scope for Peppol!
    3. Your Peppol sender participant ID. There is no fixed way how to determine this. If you are registered as a Peppol recipient, than please use your recipient ID as your sender ID. If you are not registered as a sender have a look at the latest Peppol policy for use of identifiers as well as the Participant Identifier Scheme code lists and search the VAT scheme suitable for your country (at the end of the list). Assuming you are from San Marino and your VAT number is 123456 than use the following sender ID: 9951:123456.
    4. You need to know the Peppol document type identifier and Peppol process identifier in which you want to send the document. If you are unsure what document type and process the receiver supports you can use the Participant information tool contained in this page to determine the details.
    5. You need to have a valid Peppol AP certificate for sending documents to the Peppol network.
  2. Perform an SMP lookup on the recipient ID and the document type ID to retrieve a list of all endpoints and extract the one using the transportProfile busdox-transport-as2-ver1p0 (for AS2; for AS4 it is peppol-transport-as4-v2_0). From this endpoint use EndpointReference as the destination URL and also remember the certificate of the recipient. It is later needed to extract the as2-to ID.
  3. Next thing to do is to create an SBDH document. Using the peppol-sbdh library this can be performed in very few steps:
    1. Create an instance of com.helger.peppol.sbdh.PeppolSBDHDocument which is filled with the UBL document, the sender participant ID, the receiver participant ID, the document type ID and the process ID (all stated in the prerequisites above).
    2. Convert the PeppolSBDHDocument to a StandardBusinessDocument using the PeppolSBDHDocumentWriter utility class.
  4. For setting up the AS2 client request some additional input is needed:
    1. A PKCS12 keystore containing your Peppol AP certificate. If you only have a JKS keystore, you can easily convert it to a PKCS12 keystore using the great Portecle tool by exporting the certificate and the public key. You need to enter a password for the newly created keystore upon export.
    2. The password to access the PKCS12 keystore.
    3. Your AS2 ID (as2-from), which must be the common name of your Peppol AP certificate subject (e.g. APP_1000000001).
    4. The alias of the certificate in the PKCS12 keystore to be used. Ideally it is equal to your AS2 ID for easy matching but this is just an idea.
    5. The AS2 ID of the receiver (as2-to), which must be the common name of the recipients Peppol AP certificate subject (e.g. APP_1000000002) received via the previous SMP lookup.
    6. The public key of the receiver as an X.509 certificate. This is exactly the certificate received from the previous SMP lookup.
  5. Finally the AS2 message can be send synchronously and the MDN can be received synchronously.
You must be logged in to post a comment!