search

phax / as2-peppol

AS2 handler for the use with Peppol
Apache License 2.0
8 stars 5 forks source link
as2 client dns-lookup peppol ph-bdve sbdh smp-client validation

readme

as2-peppol

Build Status javadoc Maven Central

AS2 should no longer be used in Peppol - use phase4 instead. That's why this project is archived - ping me if you have a good reason to continue this project.

Status migration AS2 → AS4

Peppol migrated to AS4 as the mandatory transport protocol as of February 1st, 2020. The support of AS2 will be gracefully faded out. Personally I wouldn't recommend to start new Peppol AS2 projects.

See phase4 as an AS4 solution that can send and receive Peppol Messages: https://github.com/phax/phase4

Introduction

 This project contains an linkage between AS2 and Peppol. It contains an AS2-Peppol client, a servlet for reuse to receive messages and an example web application.

This library is based on my as2-lib and peppol-commons libraries.

Maven usage

Add the following to your pom.xml to use this artifact, replacing x.y.z with the effective version:

<dependency>
  <groupId>com.helger.peppol</groupId>
  <artifactId>as2-peppol-client</artifactId>
  <version>x.y.z</version>
</dependency>
<dependency>
  <groupId>com.helger.peppol</groupId>
  <artifactId>as2-peppol-servlet</artifactId>
  <version>x.y.z</version>
</dependency>

Note: prior to v5.4.0 the Maven groupId was com.helger.

The binary versions of the artifacts can be found on http://repo2.maven.org/maven2/com/helger/peppol/ It depends on several other libraries so I suggest you are going for the Maven source integration.

AS2 Peppol Client

AS2 client to easily send AS2 messages to Peppol.

When you are looking for a Peppol AS2 server component you may have a look at as2-peppol-server module.

Please have a look at the Peppol practical AP guide for a detailed description on how it works and how it fits in the overall Peppol transport infrastructure.

This project is licensed under the Apache 2 License.

Configuration

A keystore in the format JKS or PKCS12 must be available that must contain your Peppol AP certificate.

See https://github.com/phax/peppol-commons#peppol-smp-client for the list of configuration items of the Peppol SMP client.

Sending a document

A test class is src/test/java/.../MainAS2TestClient and you need to adopt the variables according to your needs to make it work.

Before being ready to send a document, the recipient participant identifier as well as the test document must be selected. This happens currently directly in the main method and you have to choose the recipient you want.

The test files reside in the src/main/resources/xml folder and are referenced via classpath relative lookups.

Usage of a proxy server

To use a proxy server, add the following items to the smp-client.properties configuration file (of course with adopted values):

http.proxyHost=1.2.3.4
http.proxyPort=8080
https.proxyHost=1.2.3.4
https.proxyPort=8080

AS2 Peppol Servlet

 A stand alone servlet that takes AS2 requests with Peppol StandardBusinessDocuments and handles them via SPI. This is not a self-contained package, but a good starting point for handling Peppol AS2 messages.

An example application that uses as2-peppol-servlet for receiving Peppol AS2 messages is my as2-peppol-server project. It may serve as a practical starting point.

This package depends on ph-commons, ph-sbdh, as2-lib and as2-servlet. This transitively includes Bouncy Castle (1.64) and javax.mail (1.6.4) among other libraries.

as2-peppol-servlet handles incoming AS2 messages, and parses them as OASIS Standard Business Documents (SBD). It does not contain extraction of the SBD content or even handling of the UBL content since the purpose of this project is reusability. For validating the SBD against Peppol rules, the project peppol-sbdh is available and for handling UBL 2.0 or 2.1 files you may have a look at my ph-ubl.

This project is licensed under the Apache 2 License.

Usage

To use this project you have to do the following:

  1. Configure the AS2 servlet as specified in the as2-servlet docs
  2. The key store must contain your Peppol AP certificate and the alias of the only entry must be the CN-value of your certificate's subject (e.g. APP_1000000001).
  3. Inside your project create an SPI implementation of the com.helger.as2servlet.sbd.IAS2IncomingSBDHandlerSPI interface to handling incoming SBD documents.

SPI implementation

SPI stands for "Service provider interface" and is a Java standard feature to enable loose but typed coupling. Read more on SPI

A dummy SPI implementation is contained in the test code of this project. Additionally you need to create a file META-INF/services/com.helger.peppol.as2servlet.IAS2IncomingSBDHandlerSPI (in the src/main/resources/ folder when using Maven) which contains a single line referencing the implementation class. An example file is located in the test resources of this project.

Known issues

AS2 Peppol Demo Server

A demo AS2 server to easily receive AS2 messages from Peppol. This project is only meant as a demo project for illustrative purposes, on how to implement a Peppol AS2 server. This server implementation writes all incoming documents to disc and does not do anything else with them! Additional or different logic must be implemented!

This AS2 server is based on my as2-lib library, as well as on as2-peppol-servlet, peppol-commons and ph-ubl. A client to send messages to this server is as2-peppol-client contained in here.

This project is licensed under the Apache 2 License.

Project structure

This project is a Java 1.8+ web application and as such meant to be used in an application server (like Tomcat, Jetty etc.).

It consists of the following major components:

Before you start

Before this project can be run in a useful way a PKCS12 keystore with your Peppol AP certificate must be provided. By default the keystore must be located in src/main/resources/keystore/ap.pilot.p12 and must have the password peppol. To change this edit the as2-server.properties file.

Btw. you need no database to run this server. If you want one just use one - but you don't need to.

Run it

There are two options:

Running locally on your machine

To do so you need to proceed the following steps:

Run already prepared application in Docker container

To do so you have Docker installed in your machine. This approach is useful if you need just run the reference implementation against your Peppol Access Point implementation.

Docker notes

The prebuild Dockerfile builds the WAR and runs it in Jetty.

Build like this: docker build --pull -t as2-peppol-server .

Run like this: docker run -d --name as2-peppol-server -p 8888:8080 as2-peppol-server

Locate your browser to http://localhost:8888 to check if it is running.

Stop like this: docker stop as2-peppol-server

And remove like this: docker rm as2-peppol-server

Test it

Now that the AS2 server is running you may have a closer look at as2-peppol-client project which lets you send AS2 messages to a server. If both client and server are configured correctly a successful message exchange should be easily possible.

Notes

Using Self-signed certificate

IMPORTANT 

* CN -- Common Name must follow Peppol AP name convention and be in format : APP_1000000XXX, for example APP_1000000312
* it uses PKCS12 keystore
* AS2 client uses predefined names for the following items:
    - aliasname must match to the certificate CN (Common Name)
    - key store password shall be 'peppol'
    - keystore filename shall be 'test-client-certs.p12' to work with *as2-peppol-client*

For example:

    $ openssl req -out teho3-certificate.csr -new -newkey rsa:2048 -nodes -keyout teho3-private.key
    $ openssl x509 -signkey teho3-private.key -in teho3-certificate.csr -req -days 365 -out teho3.cer
    $ openssl pkcs12 -export -in teho3.cer -inkey teho3-private.key -out test-client-certs.p12 -passout pass:peppol -name APP_1000000112

News and Noteworthy

My personal Coding Styleguide | On Twitter: @philiphelger | Kindly supported by YourKit Java Profiler