Net::AS2::PSGI - AS2 Protocol Plack application
This documentation is for AS2 Protocol Version 1.0.
### Create an AS2 PSGI Server my $view_app = Net::AS2::PSGI->to_view_app(); my $server_app = Net::AS2::PSGI->to_server_app();
This module defines an AS2 Protocol compliant Plack application.
The AS2 Protocol is specified by RFC 4130. This protocol defines a secure peer-to-peer data transfer with receipt using HTTP. The receipt is called a Message Disposition Notification (MDN) and is specified by RFC 3798.
The Public certificates between each partnership are exchanged independently. i.e. The AS2 protocol does not allow for the public certificate to be downloaded, they must be exchanged before any AS2 communication can occur.
Implementations of the AS2 Protocol extend the original RFC 4130 to allow for transfer over HTTPS and use of newer signing algorithms, e.g. the SHA-2 family.
The AS2 Protocol defines two modes, Synchronous and Asynchronous.
The supported AS2 Protocol version is 1.0. Version 1.1 (compression) is not supported.
In this mode the data is POSTed from the sender to the receiver and the response is the MDN receipt.
In this mode the data is POSTed from the sender to the receiver but the response only confirms the data was sent.
The receiver on completion of receiving the data, POSTs the MDN receipt for the data back to the sender.
The server uses the following directories.
This directory contains Private and Public Certificate pairings and the Public Certificate for each defined Partnership.
For security, this directory and the files within it should not be world readable.
An alternative, is to either supply the key and certificate text strings directly in the Net::AS2 hash or supply an alternative directory per partnership, using the CertificateDirectory Net::AS2 hash key.
CertificateDirectory
This directory contains JSON files that each define a partnership between two AS2 Protocol Servers. The partnership file contains the key names defined in Net::AS2.
Subdirectories may be used, with the whole relative path being used to define the partnership name.
This directory will contain either files received from a partnership transfer or an MDN after sending data to a partnership.
The directory structure is as follows:
The subdirectory structure is created and named after the partnership file (without the .json extension). For security, this directory structure is created with owner read/write only.
The files being transferred between this partnership are then stored under the following directories:
Files here are being sent to the partner, but no receipt has been received yet.
Files here have been sent to the partner and a receipt has been received.
Files here are being received from the partner, but no receipt has been sent yet.
Files here have been received from the partner and a receipt has been sent.
Class Method for initialising the AS2 directory structures.
Class Method returning PSGI application for 'POST'ing to the given api .
api
api is one of:
Class Method returning PSGI application for 'GET'ting a view of partnership data.
Class Method returning PSGI application for AS2.
API Method implementing AS2.
All API methods receive a Plack request as their one and only argument.
To send data to a partner, a POST request is created with a URL of the form /send/partnership
partnership
The data is sent as the content of the POST request along with the following headers:
The AS2 Message ID.
The Message ID is validated to ensure it conforms to RFC 822.
In Asynchronous mode, the received MDN will include this value as the Original Message ID, thus tying the two independent POST requests (send and MDN receipt) together, to complete the transfer.
Original Message ID
The Content-Type of the data being sent.
The subject is an arbitrary brief one-line string.
To receive data from a partner, a POST request is received via a URL of the form /receive/partnership
The data is received as the content of the POST request along with the following headers:
The Message ID is validated to ensure it conforms to RFC 2822.
The Content-Type of the data being received.
The AS2 Protocol version, it should be in the form 1.x. Only 1.0 is supported.
See RFC 4130 for further details about the different version numbers.
The partner's AS2 ID.
This value should match the PartnerId in the partnership.json file.
partnership.json
The receiver's (i.e. this application's) AS2 ID.
This value should match the MyId in the partnership.json file.
Optional This header is only defined if digital signatures are requested.
This header contains the requirements for the digital signature. An example is:
signed-receipt-protocol=required, pkcs7-signature; signed-receipt-micalg=required, sha256
Optional This header is only defined for Asynchronous mode.
This header defines a URL for the receiver to POST the MDN receipt to, once the data has been received.
Sends an MDN message to a partner.
The POST request is created with a URL of the form /MDNsend/partnership along with the following headers:
In the RECEIVING directory, the file containing the saved MDN state of the given Message ID is read and an MDN response is created from the content. The MDN response is POSTed to the partner.
If the POST fails, the POST response code and content is stored in a file called Message-Id.Timestamp: %F-%H-%M-%S.mdn-failed in the RECEIVING directory and the POST response code is returned.
Message-Id
Timestamp: %F-%H-%M-%S
Otherwise, the data file is moved from the RECEIVING directory to RECEIVED and the MDN state file is moved from the RECEIVING directory to RECEIVED and renamed to have a .sent extension. If the MDN message is not indicating success, the data filename is also renamed to have a .failed extension.
Receives an MDN receipt from a partner.
The POST request is received via a URL of the form /MDNreceive/partnership
The received MDN is decoded.
If the receipt is for a successful transfer, the Original Message ID is extracted and the file in the SENDING directory is moved to the SENT directory and its contents replaced with the decoded MDN details.
Otherwise, the MDN details are stored in SENDING directory with a filename called UNKNOWN.MDN.Message-Id with a 200 HTTP response being returned.
View a given partnership configuration.
The request is received via a URL of the form /view/partnership
The actual content of the cached private key or certificates are not displayed, replaced instead by "...".
This module has an /examples directory. It contains an example PSGI application, its base configuration file, a systemd service for starman and an nginx conf file with SSL configurations. There is also some basic configuration files to get you started with partnering up with an instance of https://github.com/phax/as2-server.
The module's /t testing directory, includes test cases that forks AS2 Plack::Test applications, and then tests transferring files between using AS2 synchronous and AS2 asynchronous transfer modes.
Net::AS2
RFC 4130, RFC 3798 RFC 822, RFC 2822
This software is copyright (c) 2019 by Catalyst IT, <ajm@cpan.org>
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
No bugs known
The AS2 Protocol Version 1.1 (compression) is not supported.
Unlike other AS2 software, this module does not provide a means to send file to partners simply by copying a file to a designated 'send' directory. That functionality could probably be created by combining AnyEvent, Twiggy and this PSGI interface.
This module is not certificated by any AS2 body. This module creates a basic AS2 server.
When using this server, you must have reviewed and be responsible for all the actions and inactions caused by this server.
More legal jargon follows:
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Andrew Maguire ajm@cpan.org
To install Net::AS2::PSGI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::AS2::PSGI
CPAN shell
perl -MCPAN -e shell install Net::AS2::PSGI
For more information on module installation, please visit the detailed CPAN module installation guide.