mendelson OFTP2 Files

mendelson opensource OFTP2
---------------------------

Thank you for choosing the mendelson opensource OFTP2 software for your secure, fast and reliable OFTP2 data transmission.

This OFTP2 product supports the full OFTP2 protocol which includes encryption, digital signatures, TLS, TLS client authentication, 
TLS Perfect Forward Secrecy, secure session authentication, certificate exchange and message routing.
It does _NOT_ work with any OFTP 1.x partner station (even not with OFTP 1.x partner stations using TCP/IP),
OFTP2 is required. OFTP1 and OFTP2  are incompatible protocols.


Requirements:
-----
*A JAVA 11 (or higher) compatible JVM platform like windows, linux, solaris, mac OS. 
    There are several providers that provide JRE packages for different OS, e.g. Adoptium (https://adoptium.net)
*Your system must be reachable from the internet 24/7, please open the ports 3305 or 6619 in your
    firewall - the ports could be configured, please see below. Beneath the inbound access of others
    your system must have outbound access to the internet. Mainly the port 3305 is the raw port and port 6619 is the SSL/TLS port.
    As OFTP2 is a asynchronous protocol your system must be always available and reachable to receive data.
*A valid Odette Id (only for productive data exchange, this product supports any id from a technical perspective).
    This Odette id could be obtained from Odette, please refer to
    https://forum.odette.org/service/oscar/oscar-explained for further information
*A key/certificate - you could buy this or work with self-signed certificates. Please
    remember that you have to ask your partners if they accept self-signed certificats. If they dont
    accept them: Ask them for the list of CA they support.
    There is a whitepaper called "ODETTE Recommendation - OFTP2 Certificate policy" which might be worth
    reading: http://www.odette.org/TSL/POL_OFTP2.txt
    Advertisment: We recommend trusted certificates from the mendelson CA http://ca.mendelson-e-c.com/

Hardware:
*A computer that is up to date - this product encrypts/signs data which could require some processing time.
*More than 12GB RAM (the more the better)
*About 240GB free harddisk space(depends on the number of messages you would like to process)



Installation:
-----
*On windows just double click the installer and follow the instructions. Afterwards start the application. The
    installation is out of the box
*Any other OS: Unpack the zip, install a java VM >= 11, edit the start script (if required, depends 
    on your OS), start the application. The installation for non-windows OS is not out of the box but it is 
    possible to set it up in a short time.



Updating an existing mendelson opensource OFTP2 installation:
-----
*Create a backup of your installation
*Delete the existing jlib directories content
*Unpack the zip to the installation or execute the installer (windows). Do not overwrite the files that
    contain your personal data like certificates.p12, certificates_ssl.p12 and the notification templates
*Ensure to bring the keystores passwords to the default (which is "test") if you have changed this in the back
*Start the OFTP2 server. It will detect the data structure of your old version and start an iterative update
    routine for the underlaying database structure to fit the current version. This allows to update from very old
    versions of the current version of mendelson opensource OFTP2.
    If additional steps are required for the update process the system will inform you.    
*Whenever something unexpected occurs during this update procedure just recover the directory using your backup - 
    this will bring the server back to exact the old state



Quick intro:
-----
The mendelson OFTP2 solution supports encryption, digital signature, compression, TLS and secure session authentication.
Before communicating to your trading partners please ensure the following things as mentioned before:
*You must have a key/certificate to sign your outbound messages and decrypt inbound messages. The key
    may be self signed if your partner accepts this. If not there is the possibility to get trusted keys at the 
    mendelson CA (https://ca.mendelson-e-c.com). 
    This version contains a graphical key/certificate manager to import/export the required keys/certificates
    in various formats. Please remember that there are two certificate manager in the system - one for the TLS, the other for
    the signature/encryption keys/certificates.
    Even if we think that the user interface of the mendelson opensource OFTP2 server is fairly easy to use
    it is recommended to be informed about basic security mechanism like PKI. Having basic knowledge about
    security will help you setting up the system and will help you in basic themes like how to get a key
    or how to work with certificates and certificate authorities.
    If you require more information about the key/certificate/CA theme please have a look at the following links:
    http://en.wikipedia.org/wiki/Public_key_infrastructure
    http://en.wikipedia.org/wiki/Public_key
    http://en.wikipedia.org/wiki/Digital_signature
    http://en.wikipedia.org/wiki/Certificate_authority
*There are some communication parameters that are not negotiable on the protocol level for OFTP2 connections, 
    this is for example the secure authentication. Please clarify all communication parameters with your partner.

There is one local station in the partner configuration, that is you. Your trading partners need to be setup 
as remote partner. Please aks your trading partners for their communication parameters and enter them into the
partner management. On the other site please clearify your own communication parameter and send them to your
partner.

*The OFTP2 server listens by default to the ports 3305 (no TLS) and 6619 (TLS). To listen to different ports/adapters please
    navigate to the "Preferences" and setup the new ports at the section "Inbound ports"
*Each partner has an outbox directory. Send your files in, they will be taken and sent to the partner. For test purpose
    you could also send files manual using the client (file-send).
*To use your own certificates and keys please navigate to the certificate manager of the product (File-Certificates). The
    certificate manager supports
    *Key import (from PEM, PKCS#12)
    *Certificate and certificate chain import from your partner (.p7b, PEM, .cer), 
        works with additional optional certificate BASE64 encoding
    *Certificate and certificate chain export for your partner (.p7b, .cer, PEM)
    *Key export (backup purpose, PKCS#12)
    *Full export of all entries as keystore file, the format is PKCS#12
    *Copy entries between the certificate managers of the system
    *Self signed key generation + integrated possibility to trust a self signed key at the mendelson CA
    *Key and certificate handling (rename, delete, set alias, ..)
*It might confuse you that you receive files from your partner without receiving an inbound connection from them
    but just establishing an outbound connection. OFTP2 is a push/pull protocoll, you could receive files on
    outbound connections. All you have to do is have an established session to your trading partner - then data
    is transferred in both directions.



Resources/Ports, Startup
-----
3305 OFTP port (could be changed: "Preferences-Inbound ports")
6619 OFTP TLS port (could be changed: "Preferences-Inbound ports")
3333 Internal DB port
1235 Client/Server port

Please keep in mind to open the firewall for your inbound ports (defaults to 3305 and/or 6619).


This is the usage to start the community edition of the mendelson OFTP2:

java de.mendelson.comm.oftp2.OFTP2 <options>
Options are:
-lang <String>: Language to use for the user interface, nonpersistent. Possible values are "en", "de", "it", "fr", "pt".
-country <String>: Country/region to use for the system, nonpersistent. Possible values are "DE", "US", "FR", "GB"...
-mode <String>: Sets up the LIGHT or DARK mode for the user interface - default is LIGHT
-importTLS: Imports a new TLS keystore file into the system and overwrites the existing. The format must be pkcs#12, the password "test".
-importSignEnc: Imports a new sign/encryption keystore file into the system and overwrites the existing. The format must be pkcs#12, the password "test".




TLS setup
-----
There must be only a single key in the TLS certificate manager (this is the TLS key your server hosts) and certificates of all your partners.
If you change the TLS key in your TLS certificate manager you must restart the OFTP2 server. To connect to partners
using TLS please check the "Connect using TLS" checkbox in the partner manager and set the receivers port
to 6619 or the port where your trading partners OFTP2 system listens on for inbound TLS connections.
To debug the TLS handshake please start the server with the java option "-Djavax.net.debug=all" (a start using a 
start script is required, this a parameter for the java command)
mendelson OFTP2 supports TLS v1.0, TLS v1.1(*), TLS v1.2(*) and TLS v1.3(*). 
If you would like to use Perfect Forward Secrecy for TLS please just enable the ciphers that start with "TLS_ECDH" 
in the port settings. Please remember that the client may request weak ciphers (and the server has to follow 
them if it supports them) - disable weak cipher if you like to but keep in mind that your partner might not 
support them.
You could bind a list of TLS protocols (e.g. TLS v1.1, TLS v1.2) to each partner for outbound connections and also to each listening port
for inbound connections. Please remember that in TLS the server offers a list of supported TLS protocols and the client choses one that it
supports, too. Means if the remote server offers TLS v1.1 and you setup just TLS 1.2 for an outbound partner there will be no successful connection.
The system is on a technical level capable to use TLS v1.3 but this is not defined in the OFTP2 protocol so far and therefor
you cannot choose it in the settings.

(*) OFTP2 versions that are older than 2015 do not support TLS v1.1 and TLS v1.2 as this is defined for the first 
time in the OFTP2 Implementation Guideline v2.3 [01/2015]. OFTP2 versions that are older than 08/2023 do not support TLS v1.3 as 
this is defined for the first  time in the OFTP2 Implementation Guideline v3.1 [08/2023].



Send files:
-----
Each partner is assigned to a poll thread of a directory and a virtual filenames. You could add additional
poll threads that are assigned to user defined virtual filenames per partner. The poll interval could be configured,
ignore patterns are supported. You could start a user defined command per partner after a file has been send
(error/without error). Please don't let the system poll a directory once a second or something like this - this will
slow down the system. Please always have a look at the number of poll threads you are running - else the system is just 
busy polling directories and not processing OFTP2 data.
The reason for the ignore patterns in the poll is to ignore files that are not fully available at the point of poll, e.g.
if you copy files to the outbound directory and not move them or if you use other transports like FTP to send files to
the outbound directory. In this case you could define a transport file extension which signals the poll process to ignore the file
and then rename the file (atomic) after it has been transferred to the outbound directory. If you are just polling the oubound directory
and ignore that copying files in there is a streaming operation it might happen that you transfer files multiple times or just 
empty files or files that are not complete.



Receive files:
-----
Every partner could have user defined virtual filename processing. Each file with a specified virtual filename
will be written to a specified directory. This could defined in the partner management. 
For a powerful integration into your process flow you could start a user defined command per partner after 
a file has been received - either on failure or on success. These user defined commands could have access to several 
parameters of the transmission - please have a look at the user interface (partner management-events) for
more information.



Notification:
-----
You could set up external mail account credentials - the mendelson opensource OFTP2 server will send mails
for several events which could be configured, too.
These events are

*certificate messages arrive
*transmissions failed
*certificates are up to expire/have been expired
*connection problems
*system problems

If you enable the certificate expire notification you will be informed 10 - 5 - 1 day before the certificate
has been expired. If this isn't your certificate but a partner certificate this is mainly not that interesting -
anyway you should monitor this issue.
Please keep in mind that the main OFTP2 security mechanism like encryption and signatures do not work if you
use expired certificates.
The grayed out option OAuth2 for SMTP mail server authorization is not part of the community edition - please buy the professional
version license if it is required for you to authorize via OAuth 2.0 or OAuth 2.1 with your mail server.



Using gateway partners/routing:
-----
The mendelson OFTP2 server supports full OFTP2 routing and message sending to partners who are 
accessible via an OFTP2 gateway partner.
If you would like to send data to a partner that is accessible via a gateway partner just configure
this in the partner management - tab "send". The mendelson opensource OFTP2 server will connect to this partner
and tell him that the destination of the data is a routed partner. Please be aware that every partner
you are sending data to and receive data from must be available - and well configured - in your
partner management. The partner icon indicates if you will connect direct to a partner or connect to it via
an other partner.
Beneath the physical routing were you send routed data to an other system you could also create a virtual routing
by adding local identities to your local station. In this case your partner will see these identities as routed
partners but you will receive them on your instance - you could also send data using an other identity
Technical spoken:
This allows to send data with a different SFIDORIG and SSIDCOD in a single instance, this also allows to receive
data with a different SFIDDEST and SSIDCOD in a single instance.
There is no limitation in the number of routed partners in this version.



Exchange certificates:
-----
This product supports the certificate exchange messages DELIVER, REPLACE and REQUEST as defined in the
OFTP2 implementation guide. Please remember that this functionality goes beyond the OFTP2 protocol definition
of RFC5024. Certificate exchange messages are not signed and encrypted. Because of this we recommend
to exchange them using SSL connections.
Using the menu "file-certificate exchange" you could send certifiates to your partners. Please don't
forget to set up the mail notification in this case - you will be informed about every certificate message
that arrives.
Before enabling certificates you received by certificate exchange messages in the product please check the
key values of the certificate to see if you should really trust it. If you are not sure if you should trust
a certificate please contact your trading partner and compare the fingerprints of the keys/certificates.



Connection strategies:
-----
There are three different strategies available to connect to a partner:
1. Connect if outbound data is available
    The system will create an outbound connection to the partner if any data is available for this partner. Your partners firewall must be configured
    for your connection to come through.
2. Connect to partner even if no outbound data is available (Poll n minutes option)
    The system will create an outbound connection even if no data is available for this partner. As OFTP2 is a push-pull protocol this will
    receive data from a partner without the need that the partner connects to you. (Partner uses connection strategy 3)
3. No outbound connection to this partner - the partner will connect
    Your system will never connect the partner - even if data is available for him. Your partner uses connection strategy 2. 




System maintenance/administration:
-----
*Its recommended to monitor the system - have a look on the user interface from time to time, let the
    system be monitored by Nagios (or similar), configure the systems mail notification and read these mails
*Configure the system to auto delete old transmission logs, this could be done in the system settings. We
    recommend to not have more than 30000 transmissions in the log as this will slow down the user interface.
*Please ensure not to make backups on the partition where the mendelson opensource OFTP2 system is running. The
    system will run into problems if there is no harddisk space left - monitoring the harddisk space is also
    recommended (e.g. windows could be configured to monitor the space of a partition and write mails, Nagios
    or PRTG is also a good option in this case)


Different cipher sets of OFTP2 systems
------
In 01/2015 Odette released the OFTP2 Implementation Guideline v2.3. This defined new cipher sets for the digital signatures,
SHA-256 and SHA-512 have been added. The mendelson OFTP2 supports them since 01/2015. Please be aware that using SHA-2 uses new
qualifier on the OFTP2 protocol level which may not be understood by your partner systems if they are older than 2015.
In 08/2023 Odette released the OFTP2 Implementation Guideline v3.1. This defined new cipher set and adds SHA3-512 and AES-256-CBC.



Upgrading to a commercial license:
-----
If you require support and software maintenance for production use of the OFTP2 server please upgrade to a 
commercial license. mendelson-e-commerce GmbH does not deliver support in any way for the community editions.
You could buy a commercial license in the mendelson online shop at http://shop.mendelson-e-c.com
The commercial version will work fine with your existing open source configuration data, there is no need to setup a new configuration,
this could be moved to the commercial version.
It also contains a detailed help system which should clarify all your questions.

The main difference between the community edition and the commercial edition is that mendelson-e-commerce GmbH does not provide any
support for the community edition. Beneath that the community edition is not a client-server system but just a desktop software.
In the commercial edition there are also some additional plugins like PostgreSQL integration, a REST API and the OAuth2 module for
mail server authorization (please refer to https://oauth.net/2/). It's also possible to create a HA cluster of multible mendelson 
OFTP2 systems using the commercial edition and use an integrated ASCII/EBCDIC converter.
Nonethless the main functionality of the community edition and the commercial edition is the same. For
a chart that compares both versions please visit

https://mendelson-e-c.com/oftp2_comparison


Any questions or feedback? Please refer to the forum http://mendelson-e-c.com/forum/oftp2
We are looking forward for your comments and questions.


---
Regards
The mendelson-e-commerce GmbH development team