Why OpenAS2?

OpenAS2 is the most widely used open-source AS2 server. It's free, runs on any platform with Java, and handles the full AS2 protocol: message sending, receiving, encryption, signing, and MDN processing. If you need an AS2 endpoint for testing, development, or even production use with moderate volume, OpenAS2 is a solid choice.

This guide walks through the complete setup: installation, directory structure, certificate management, partnership configuration, sending your first message, and troubleshooting the errors you'll inevitably hit.

Prerequisites

Before you start, you need:

Java 8 or later (OpenAS2 4.x works with Java 8 through 21). Check with java -version.
A machine with a static IP or hostname if you'll be receiving messages from trading partners
Port 10080 (HTTP) and/or 10443 (HTTPS) available (these are OpenAS2 defaults; you can change them)
Your trading partner's public certificate (for encrypting messages to them and verifying their signatures)
Your own key pair (OpenAS2 generates a default one, but you'll want to create a proper one for production)

Step 1: Download and Install

Download the latest release from the OpenAS2 GitHub repository:

# Download the latest release (check https://github.com/OpenAS2/OpenAs2App/releases for current version)
wget https://github.com/OpenAS2/OpenAs2App/releases/download/v4.8.0/OpenAS2Server-4.8.0.zip

# Unzip
unzip OpenAS2Server-4.8.0.zip -d /opt/openas2

# Make the startup script executable
chmod +x /opt/openas2/bin/start-openas2.sh

On Windows, download the zip and extract it to a directory like C:\OpenAS2. Use start-openas2.bat instead of the shell script.

Step 2: Understand the Directory Structure

Before changing anything, understand what's where:

/opt/openas2/
  bin/                  # Startup scripts
    start-openas2.sh    # Linux/Mac startup
    start-openas2.bat   # Windows startup
  config/               # All configuration files
    config.xml          # Main server configuration
    partnerships.xml    # Trading partner definitions
    as2_certs.p12       # Java keystore with certificates
  data/                 # Message data
    toAny/              # Drop files here to send
    toPartnerName/      # Partner-specific outbound directories
  logs/                 # Log files
  lib/                  # Java libraries (don't modify)

The three files you'll edit most:

config/config.xml for server settings (ports, logging, your AS2 ID)
config/partnerships.xml for trading partner definitions
config/as2_certs.p12 for managing certificates (via keytool commands, not direct editing)

Step 3: Configure the Server (config.xml)

Open config/config.xml. The key sections to review:

Your AS2 Identifier

Find the local partner definition. This is your AS2 identity:

<partner name="OpenAS2A" 
  as2_id="OpenAS2A" 
  x509_alias="openas2a" 
  email="as2@yourcompany.com"/>

Change as2_id to your organization's AS2 ID. This is the value that goes in the AS2-From header of outbound messages. Your trading partner needs this exact string. Convention is to use your company name or DUNS number, all uppercase, no spaces.

HTTP Receiver Settings

The receiver module configures what port OpenAS2 listens on for incoming messages:

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"
  port="10080"
  errordir="data/msgError"
  errorformat="$msg.sender.as2_id$, $msg.receiver.as2_id$, $msg.headers.message-id$"/>

For production, you'll want to put a reverse proxy (Nginx or Apache) in front of this with TLS termination on port 443, forwarding to OpenAS2's HTTP port.

HTTPS Receiver (Optional but Recommended)

To enable HTTPS directly on OpenAS2:

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"
  port="10443"
  protocol="https"
  ssl_keystore="config/ssl_certs.jks"
  ssl_keystore_password="changeit"
  ssl_protocol="TLSv1.2"/>

You'll need to create the SSL keystore separately (covered in the certificates section below).

Step 4: Set Up Certificates

OpenAS2 uses a Java PKCS12 keystore (as2_certs.p12) to store all certificates. The default password is testas2. Change this for production.

Generate Your Key Pair

If you don't already have an AS2 certificate, generate one:

# Generate a new key pair in the OpenAS2 keystore
keytool -genkeypair \
  -alias mycompany \
  -keyalg RSA \
  -keysize 2048 \
  -validity 730 \
  -storetype PKCS12 \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -dname "CN=MyCompany AS2, O=MyCompany Inc, L=City, ST=State, C=US"

This creates a self-signed certificate valid for 2 years. For production with strict partners, you may need a CA-signed certificate.

Export Your Public Certificate (To Send to Your Partner)

# Export your public certificate to share with trading partner
keytool -exportcert \
  -alias mycompany \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -file mycompany_as2_public.cer \
  -rfc

Send the .cer file to your trading partner. Never send the keystore file; it contains your private key.

Import Your Partner's Certificate

# Import trading partner's public certificate
keytool -importcert \
  -alias partnercompany \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -file partner_public_cert.cer \
  -noprompt

The alias you choose here (partnercompany) is what you'll reference in the partnership configuration.

List All Certificates in the Keystore

keytool -list \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -v

This shows every certificate, its alias, type (PrivateKeyEntry for your keys, trustedCertEntry for partner certs), and expiration date.

Step 5: Configure a Trading Partnership

Open config/partnerships.xml. Each partnership defines the relationship between you and one trading partner.

Define the Partner

First, add the remote partner definition:

<partner name="PartnerCompany"
  as2_id="PARTNERCOMPANY"
  x509_alias="partnercompany"
  email="edi@partnercompany.com"/>

The as2_id must match exactly what your partner tells you. Case-sensitive. No extra spaces.

Define the Partnership (Outbound: You to Partner)

<partnership name="MyCompany-PartnerCompany"
  sender="MyCompany"
  receiver="PartnerCompany">
  
  <!-- Partner's AS2 endpoint URL -->
  <attribute name="as2_url" value="https://partner.example.com/as2"/>
  
  <!-- Encryption: aes128-cbc, aes192-cbc, aes256-cbc, or 3des -->
  <attribute name="encrypt" value="aes256-cbc"/>
  
  <!-- Signing: sha-1, sha-256, sha-384, sha-512 -->
  <attribute name="sign" value="sha-256"/>
  
  <!-- Content type of outbound messages -->
  <attribute name="content_type" value="application/edi-x12"/>
  
  <!-- MDN settings -->
  <attribute name="as2_mdn_to" value="as2@mycompany.com"/>
  <attribute name="as2_mdn_options" 
    value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>
  
  <!-- For async MDN, uncomment and set your receipt URL -->
  <!-- <attribute name="as2_receipt_option" value="https://your-server.com:10080/as2/HttpReceiver"/> -->
</partnership>

Define the Reverse Partnership (Inbound: Partner to You)

<partnership name="PartnerCompany-MyCompany"
  sender="PartnerCompany"
  receiver="MyCompany">
  
  <attribute name="as2_url" value="https://your-server.com:10080/as2/HttpReceiver"/>
  <attribute name="encrypt" value="aes256-cbc"/>
  <attribute name="sign" value="sha-256"/>
  <attribute name="content_type" value="application/edi-x12"/>
  <attribute name="as2_mdn_to" value="edi@partnercompany.com"/>
  <attribute name="as2_mdn_options" 
    value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>
</partnership>

You need both directions defined. One for messages you send to the partner, one for messages the partner sends to you.

Step 6: Start OpenAS2

# Linux/Mac
cd /opt/openas2
./bin/start-openas2.sh

# Windows
cd C:\OpenAS2
bin\start-openas2.bat

Watch the console output. A successful startup looks like:

[INFO] - OpenAS2 Server - Version 4.8.0
[INFO] - Loading configuration...
[INFO] - Certificate store loaded: config/as2_certs.p12
[INFO] - Partnership loaded: MyCompany-PartnerCompany
[INFO] - Partnership loaded: PartnerCompany-MyCompany
[INFO] - AS2ReceiverModule started on port 10080
[INFO] - OpenAS2 Server Started

If you see errors here, check the troubleshooting section below.

Step 7: Send a Test Message

OpenAS2 uses a file-based sending mechanism. Drop a file in the correct outbound directory, and OpenAS2 picks it up and sends it.

Create a Test EDI File

# Create a minimal X12 997 test file
cat > /opt/openas2/data/toPartnerCompany/test_997.edi << 'EOF'
ISA*00*          *00*          *ZZ*MYCOMPANY      *ZZ*PARTNERCO      *230101*1200*U*00401*000000001*0*T*>~
GS*FA*MYCOMPANY*PARTNERCO*20230101*1200*1*X*004010~
ST*997*0001~
AK1*PO*1~
AK9*A*1*1*1~
SE*4*0001~
GE*1*1~
IEA*1*000000001~
EOF

OpenAS2 polls the outbound directories on an interval (default: 30 seconds). Within a minute, it should pick up the file, encrypt it, sign it, and send it to the partner's AS2 URL.

Check the Logs

# Watch the log for send activity
tail -f /opt/openas2/logs/openas2.log

A successful send shows:

[INFO] - Message sent: MyCompany-PartnerCompany, Message-ID: <OPENAS2-...-MyCompany-PartnerCompany@...>
[INFO] - MDN received: processed

A failed send shows the error with details. Check the troubleshooting section for specific errors.

Step 8: Verify You Can Receive Messages

To test inbound message reception, you need your partner (or another OpenAS2 instance) to send a message to your endpoint.

If you're running two OpenAS2 instances locally for testing:

# Instance A sends to Instance B on localhost:10080
# Instance B's partnership should have as2_url pointing to http://localhost:10080/as2/HttpReceiver

Received messages appear in the data/inbox/ directory (the exact path depends on your config.xml directory module settings).

Putting OpenAS2 Behind a Reverse Proxy

For production, don't expose OpenAS2's port directly. Use Nginx or Apache for TLS termination:

# Nginx configuration for OpenAS2
server {
    listen 443 ssl;
    server_name as2.yourcompany.com;
    
    ssl_certificate /etc/ssl/certs/as2.yourcompany.com.crt;
    ssl_certificate_key /etc/ssl/private/as2.yourcompany.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # Important: increase timeouts for large AS2 messages
    proxy_read_timeout 180s;
    proxy_send_timeout 180s;
    client_max_body_size 100M;
    
    location /as2/ {
        proxy_pass http://127.0.0.1:10080/as2/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Key settings: increase proxy_read_timeout beyond the default 60 seconds (synchronous MDN processing can take time), and set client_max_body_size high enough for your largest expected AS2 messages.

Running OpenAS2 as a System Service

For Linux servers, create a systemd service so OpenAS2 starts automatically and restarts on failure:

# /etc/systemd/system/openas2.service
[Unit]
Description=OpenAS2 Server
After=network.target

[Service]
Type=simple
User=openas2
Group=openas2
WorkingDirectory=/opt/openas2
ExecStart=/usr/bin/java -cp "lib/*" org.openas2.app.OpenAS2Server config/config.xml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable openas2
sudo systemctl start openas2
sudo systemctl status openas2

Common OpenAS2 Errors and Fixes

Here are the errors you're most likely to hit, in order of frequency.

"java.net.BindException: Address already in use"

Another process is using port 10080 (or whatever port you configured).

# Find what's using the port
lsof -i :10080

# Or on Linux
ss -tlnp | grep 10080

Fix: Stop the conflicting process, or change OpenAS2's port in config.xml.

"java.io.IOException: Keystore was tampered with, or password was incorrect"

The keystore password in config.xml doesn't match the actual password of the as2_certs.p12 file.

Fix: Verify the password. The default is testas2. If you changed the keystore password with keytool, update the corresponding keystorePassword attribute in config.xml.

"java.security.cert.CertificateException: No certificate found for alias"

The x509_alias in your partner or partnership definition doesn't match any alias in the keystore.

# List all aliases in the keystore
keytool -list -keystore config/as2_certs.p12 -storepass testas2

Fix: Make sure the alias in partnerships.xml exactly matches an alias in the keystore. Case-sensitive.

"ClassNotFoundException" or "NoClassDefFoundError"

Java can't find the OpenAS2 classes. This usually means you're running the startup command from the wrong directory, or the lib/ folder is missing JAR files.

Fix: Always start OpenAS2 from its installation directory. Verify that lib/ contains the JAR files that shipped with the distribution. If you moved or renamed files, re-extract from the original zip.

"Connection refused" When Sending

Your partner's AS2 URL is wrong, their server is down, or a firewall is blocking the connection.

# Test connectivity to partner
curl -v https://partner.example.com/as2
nc -zv partner.example.com 443

Fix: Verify the URL with your partner. Check that your outbound firewall allows HTTPS traffic to their IP.

"org.openas2.OpenAS2Exception: Partnership not found"

The AS2-From/AS2-To combination in the incoming message doesn't match any partnership in your partnerships.xml.

Fix: Check the exact AS2 IDs your partner is using. They must match the as2_id values in your partnership definition. Copy and paste from their configuration document. Watch for trailing spaces or case differences.

"Decryption failed" or "Unable to decrypt"

Your keystore doesn't contain the private key that matches the certificate your partner used to encrypt the message.

Fix: Your partner encrypted with your public certificate. Make sure the keystore has the corresponding private key entry (type PrivateKeyEntry, not trustedCertEntry). If you recently generated a new key pair, you need to send the new public certificate to your partner and have them update their configuration.

"Signature verification failed"

The partner's public certificate in your keystore doesn't match the private key they used to sign the message.

Fix: Get a fresh copy of the partner's current public certificate and re-import it into your keystore. They may have rotated their key pair without notifying you.

OpenAS2 Performance Tuning

OpenAS2 runs well for low to moderate volumes (hundreds of messages per day). For higher throughput:

Increase Java heap: Edit the startup script to add -Xmx512m or -Xmx1g to the Java command line
Reduce polling interval: The directory polling module in config.xml has an interval attribute (in seconds). Lower it for faster pickup, but don't go below 5 seconds.
Use SSD storage: OpenAS2 writes message data and logs to disk. SSD reduces I/O bottlenecks.
Rotate logs: Configure log rotation in config.xml or use external log rotation (logrotate on Linux). Unmanaged logs can fill a disk.

Validating Your OpenAS2 Setup

You've installed OpenAS2, configured certificates, defined partnerships, and sent a test message. But how do you know your configuration meets production standards? Is your encryption algorithm strong enough? Is your certificate going to expire before your next audit? Does your MDN configuration actually work end to end?

AS2 Certify can validate your OpenAS2 setup by running a comprehensive test against your endpoint. It checks every layer: TLS configuration, certificate validity and key strength, encryption and signing algorithm compliance, MDN generation and verification, and AS2 header correctness. The test produces a graded report (A through F) that tells you exactly what's production-ready and what needs fixing. Instead of discovering configuration issues when a trading partner's first real message fails, you find them during setup and fix them in one pass.