Example: Full AS2 Message Exchange (Advanced)
This example illustrates a more advanced AS2 message exchange, with encryption and signing, between two AS2 partners that both run FlowForce Server. Before you follow this tutorial, make sure that you have already followed the previous one, which covers the basics, see Example: Full AS2 Message Exchange (Simple).
This example illustrates the most complex communication scenario between two AS2 partners (the twelfth permutation out of twelve possible permutations according to section 2.4.2 of RFC 4130), which essentially means the following:
•The sender sends encrypted AS2 data
•The sender sends signed AS2 data
•The sender requests that the receiver returns a signed MDN in reply to the message
•The same sender and receiver are used as in the previous example, respectively: Hermes (FlowForce Server on Linux) and Apollo (FlowForce Server on Windows)
•Hermes wants to send to Apollo an encrypted and signed message, and requires a signed MDN in return
•Apollo and Hermes are both running on a local private network.
•The receiving AS2 server (Apollo) will accept HTTP requests from unauthenticated clients (that is, the AS2 service will be accessible publicly).
•FlowForce Server Advanced Edition must be installed and licensed on both Apollo and Hermes machines.
•On both Apollo and Hermes servers, the FlowForce Web administration interface must be up and running on the configured host and port (for example, http://apollo:8082 and http://hermes:8082, assuming that "apollo" and "hermes" are the respective host names). See also Defining the Network Settings.
Set up Apollo's certificates
In this configuration step, the following takes place:
1.Apollo generates a public certificate and a private key and imports both into FlowForce Server.
2.Apollo sends the public certificate (without the private key) to Hermes.
3.Hermes imports Apollo's public certificate into FlowForce Server.
Why this is necessary:
•Before sending the message to Apollo, Hermes needs Apollo's public key to encrypt it. Upon receiving the message from Hermes, Apollo will decrypt it using his own private key.
•Before sending the MDN requested by Hermes, Apollo will sign it using his own private key. Upon receiving the signed MDN, Hermes needs Apollo's public certificate to verify the signature.
For the scope of this example, we will generate a self-signed certificate using the OpenSSL library (https://www.openssl.org/) included with Cygwin (https://cygwin.com/). This is for demo purposes only; in a real life scenario, you might want to use other tools to generate the SSL certificate, or you might have it already available in your organization.
To generate the self-signed certificate for Apollo, open the Cygwin terminal and type the following:
openssl req -x509 -newkey rsa:2048 -keyout apollo_private.pem -out apollo_public.pem -days 365
When prompted to enter a pass phrase, type the password under which you would like to encrypt the private key, and remember it. You will later need this password to import the certificate into FlowForce Server. Go through all wizard steps, and enter all the required fields ("Country", "State or Province Name", "Locality Name", "Organization Name", "Department Name", "Common Name", and "Email").
When you finish the wizard, the command above generates two files, apollo_private.pem, and apollo_public.pem, in Cygwin's home directory (for example, C:\cygwin64\home\<user>\, if you installed Cygwin to C:\cygwin64). Because this pair can only be uploaded as one single file into FlowForce Server, run the following additional command to copy the public certificate into the private key file:
cat apollo_public.pem >> apollo_private.pem
On the Apollo machine, log on to FlowForce Server, click the Configuration menu, and then click Create > Create Certificate.
Enter the certificate name and description, click Browse and select the apollo_private.pem file create previously. Make sure to enter the password that you created earlier in this step, and click Save.
The public+private certificate pair is now imported into Apollo's FlowForce Server. Notice that the icon and descriptive text indicate that this certificate file contains both:
To send the public key to Hermes, copy the apollo_public.pem file to Hermes machine. Next, log on to FlowForce Server on Hermes machine and import it using the same steps as above (this time a private key is not present in the file, so no password is necessary).
Notice that the icon and descriptive text indicate that this certificate file contains only the public certificate (no private key).
Set up Hermes's certificates
In this configuration step, the following takes place:
1.Hermes generates a public certificate and a private key and imports it into FlowForce Server
2.Hermes sends the public certificate (without the private key) to Apollo
3.Apollo imports Hermes's public certificate into FlowForce Server
Why this is necessary:
•Before sending the message to Apollo, Hermes will sign it using his own private key.
•Upon receiving the message from Hermes, Apollo will verify the signature of the message using Hermes's public certificate.
First, create Hermes's public certificate and private key, following the same steps as for Apollo. Be sure to replace the file names:
openssl req -x509 -newkey rsa:2048 -keyout hermes_private.pem -out hermes_public.pem -days 365
In addition, the "Organization name", "Common Name", etc. must be those of Hermes:
Next, combine both files into a single one using the command:
cat hermes_public.pem >> hermes_private.pem
Next, import hermes_private.pem into FlowForce Server on Hermes machine:
Next, copy hermes_public.pem to Apollo machine and import it into FlowForce Server:
Enable AS2 encryption, signing, and MDN signature verification on Hermes
On Hermes machine, edit the APOLLO partner settings as follows:
Enable AS2 decryption, MDN signing, and signature verification on Apollo
On Apollo machine, edit the HERMES partner settings as follows:
Process the MDN
According to the requirements stated above, Hermes requires that Apollo send an MDN to acknowledge the AS2 transmission. We can compute the status of the incoming MDN (success, failure) with the help of as2-success expression function. To achieve this, log on to FlowForce on Hermes machine, and open the "send-as2" job created previously in Example: Full AS2 Message Exchange (Simple). Next, modify the job as shown below:
Note the following:
•The result of the first execution step, of type "AS2 MDN", is now declared (See the field Assign this step's result to).
•The Abort on error check box is cleared, since execution must continue to the next step.
•The second execution step calls the /system/compute function. This function computes a Boolean expression with the help of as2-success function. The latter takes as argument the MDN returned by the first execution step.
Send the AS2 message
You are now ready to send the encrypted and signed AS2 message from Hermes to Apollo. On Hermes machine, copy an .edi file to the directory configured previously /home/altova/as2/outgoing. When the directory polling interval elapses (60 seconds, by default), the trigger is executed, and the job sends the file to the AS2 service on Apollo machine. The directory C:\as2\incoming on Apollo machine should now contain the message sent by Hermes, for example:
To see if the job has failed or has executed successfully, check the system's log (you may need to do this not only on Hermes, but also on the Apollo machine). For more information, see Viewing the Job Log.
The log contains information about any errors that may occur in relation to this transmission. For example, if Hermes sends unencrypted data but Apollo expects it to be encrypted, then the job fails and a corresponding message is logged.