as2

WAARP AS2

A high-performance, compliant AS2 (Applicability Statement 2) protocol implementation in Go. This library provides both Client and Server capabilities for exchanging structured business data securely over HTTP/S, following RFC 4130.

Features

• Full AS2 Version 1.1 Support
• Security: S/MIME signing and encryption (AES-128/256, DES, 3DES).
• Transport: HTTP and HTTPS support.
• Reliability: Synchronous and Asynchronous MDN (Message Disposition Notification) support.
• Compression: Support for compressed data (RFC 5402).
• Flexibility: Interchangeable storage backends for Messages and Partners.
• Modern Go: Built with log/slog for structured logging and standard net/http.

Installation

go get code.waarp.fr/lib/as2

Usage

1. AS2 Server

The server listens for incoming AS2 messages, handles decryption/verification, and automatically sends MDNs.

package main

import (
	"log/slog"
	"os"
	
	"code.waarp.fr/lib/as2"
)

func main() {
	// 1. Configure the Logger
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

	// 2. Load Certificates (for signing MDNs and decrypting messages)
	mdnCert, mdnKey, _ := as2.LoadCertKey("mdn_cert.pem", "mdn_key.pem")
	decryptCert, decryptKey, _ := as2.LoadCertKey("decrypt_cert.pem", "decrypt_key.pem")

	// 3. Initialize Server with Options
	server := as2.NewServer(
		as2.WithLogger(logger),
		as2.WithLocalAS2ID("MY_COMPANY_AS2_ID"),
		as2.WithInboundDecryptIdentity(decryptCert, decryptKey), // Enable decryption
		as2.WithMDNSigner(mdnCert, mdnKey),                      // Enable signed MDNs
		// Optional: Define custom storage or file handling
		// as2.WithFileHandler(myCustomHandler),
	)

	// 4. Start Listening
	if err := server.ListenAndServe(":8080"); err != nil {
		logger.Error("Server failed", "error", err)
	}
}

2. AS2 Client

The client sends messages to remote AS2 partners and processes the returned MDN.

package main

import (
    "context"
    "code.waarp.fr/lib/as2"
)

func main() {
    client := as2.NewClient(as2.WithClientAS2ID("MY_COMPANY_AS2_ID"))
    
    // Define the partner configuration
    partner := &as2.Partner{
        AS2ID:     "PARTNER_AS2_ID",
        SendUrl:   "http://partner.example.com/as2",
        // Load partner's public certificate for encryption/verification
        CertChain: loadPartnerPublicCerts(), 
    }

    // Send a message
    data := []byte("ISA*00*...") // EDI payload
    
    opts := as2.NewSendOptions(
        as2.WithFileName("invoice_123.edi"),
        as2.WithContentType("application/edi-x12"),
        as2.WithRequestMDN(true),
        as2.WithSignedMDN(true), // Request Signed MDN
    )

    // Enable Signing and Encryption for this message
    opts.Sign = as2.DefaultSignPKCS7
    opts.Encrypt = as2.DefaultEncryptPKCS7

    result, err := client.Send(context.TODO(), partner, data, opts)
    if err != nil {
        panic(err)
    }

    if result.MDN != nil {
        println("MDN Received:", result.MDN.Disposition)
    }
}

API Reference

Client API

NewClient(opts ...ClientOption) *Client

Creates a new AS2 Client.

Client.Send(ctx, partner, payload, opts) (*SendResult, error)

Sends a message to the specified Partner. Returns a SendResult containing the HTTP status and the parsed MDN (if synchronous).

Send Configuration

NewSendOptions(opts ...SendOption) *SendOptions

Helper to create the options struct with defaults. Alternatively, you can instantiate &SendOptions{} directly.

Server API

NewServer(opts ...ServerOption) *Server

Creates a new AS2 Server.

3. Handling Asynchronous MDNs

To receive asynchronous MDNs (when a partner sends receipts back to a different URL), the server provides a dedicated MDNHandler.

func main() {
    // ... initialize your main server ...

    // Create the MDN Handler
    mdnHandler := as2.NewMDNHandler(logger, messageStore, partnerStore)
    
    // Register it on your HTTP multiplexer
    http.Handle("/as2/mdn", mdnHandler)
    
    // OR: The main Server struct automatically handles this if you use Server.ListenAndServe.
    // However, if you are integrating into an existing HTTP stack:
    // mdnh := server.MDNHandler() 
    // mux.Handle("/as2/mdn", mdnh)
}

MDNHandler.ServeHTTP(w, r)

Implements http.Handler. It:

1. Validates AS2-specific headers (e.g., AS2-Version).
2. Parses the MDN payload (supporting multipart/report and multipart/signed).
3. Verifies the MIC (Message Integrity Check) against the original message (retrieved via MessageStore).
4. Logs the receipt status.

Note: For standard usage via as2.NewServer(...), this handler is automatically configured and mounted if you use the provided ListenAndServe methods. You only need to manually instantiate it if you are building a custom HTTP routing layer.

Server.ListenAndServe(addr string) error

Starts the HTTP server on the given address.

Server.ListenAndServeTLS(addr, certFile, keyFile string) error

Starts the HTTPS server on the given address using the provided certificate and key files.

Server.Serve(l net.Listener) error

Serves AS2 requests on the provided net.Listener.

Server.ServeTLS(l net.Listener, certFile, keyFile string) error

Serves HTTPS AS2 requests on the provided net.Listener.

Server.Shutdown(ctx context.Context) error

Gracefully shuts down the server, waiting for active connections to complete.

Request Processing Order

The server enforces checks in the following strict order for every incoming request:

1. Payload Size Limit: The server reads the entire request body into memory. If the size exceeds WithMaxBodyBytes (default 100MB), the connection is closed or a 400 Bad Request is returned.
2. Authentication: If configured, WithHTTPAuthFunc is executed. The function receives the request with the fully read body.
3. Method & Basic Headers: Validates the HTTP Method (POST), Host header, and Content-Type.
4. AS2 Headers: Validates the presence and format of AS2-From and AS2-To.
5. Strict Checks: If WithStrict(true) is set (default), verifies that AS2-To matches the server's LocalAS2ID.

Types & Interfaces

Partner

Represents a trading partner.

type Partner struct {
    AS2ID     string              // Partner's AS2 Identifier
    SendUrl   string              // Partner's AS2 URL (for sending messages)
    CertChain []*x509.Certificate // Partner's Public Certificates (for encryption and verification)
}

MessageStore

Interface for message persistence (duplicate checking and MDN storage).

• Record(ctx, msgID, mdn, ...)
• GetMDN(ctx, msgID)

PartnerStore

Interface for partner lookup.

• GetByAS2From(ctx, id)

Advanced Configuration

Custom Signing & Encryption (Client)

You can override the default PKCS#7 signing and encryption logic by providing your own functions via WithSignFunc and WithEncryptFunc. This is useful if you need to use a specific cryptographic library (e.g., OpenSSL CGO bindings) or hardware security modules (HSM).

Key Type Definitions

// SignFunc creates a multipart/signed entity.
// It must return the full Content-Type (including boundary/micalg), the signed body, and the micalg used.
type SignFunc func(
    ctx context.Context,
    entity []byte,              // The MIME entity to sign (headers + body)
    signerCert *x509.Certificate,
    signerKey any,              // Private key
    digest MICAlg,              // Requested digest algorithm (e.g., "sha256")
) (contentType string, signed []byte, micalg string, err error)

// EncryptFunc wraps the entity in an enveloped-data structure.
// It must return the Content-Type (application/pkcs7-mime), the encrypted bytes, and the algorithm used.
type EncryptFunc func(
    ctx context.Context,
    entity []byte,              // The full MIME entity to encrypt
    recipients []*x509.Certificate,
) (contentType string, encrypted []byte, algo string, err error)

Server Authentication

By default, the AS2 Server does not enforce any HTTP authentication (auth is done via AS2-To/AS2-From headers and optional signature verification).

To secure the HTTP transport layer (e.g., Basic Auth, Bearer Token), you can provide a custom HTTPAuthFunc. This function is executed after the body is read but before any AS2 processing.

func main() {
    as2.NewServer(
        as2.WithHTTPAuthFunc(func(r *http.Request) bool {
            // Example: Enforce Basic Auth
            user, pass, ok := r.BasicAuth()
            if !ok {
                return false
            }
            return user == "admin" && pass == "secret"
        }),
    )
}

Technical Choices & Architecture

Language & Runtime

Written in Go for its strong concurrency primitives (goroutines), type safety, and efficient net/http standard library. AS2 requires handling heavy I/O and cryptographic operations; Go is well-suited for high-throughput environments.

Cryptography (S/MIME)

We utilize github.com/smallstep/pkcs7 for low-level interaction with Cryptographic Message Syntax (CMS).

• Why? The Go standard library crypto/x509 does not provide high-level S/MIME or PKCS#7 building blocks required for AS2 (EnvelopedData, SignedData).
• Algorithms: We enforce strict algorithm normalization. While MD5 and SHA-1 are supported for backward compatibility with legacy AS2 systems, SHA-256 and AES-256 are preferred and default.

Storage Abstraction

The system is designed with Dependency Injection for storage:

• PartnerStore: Interface to retrieve partner profiles (keys, certificates, URLs).
• MessageStore: Interface to persist message logs and MDNs.
• Default: In-memory implementations are provided for testing/lightweight usage, but production use should implement these interfaces with a database (SQL, Redis, etc.).

Logging

Uses Go's standard log/slog (introduced in Go 1.21).

• Why? Provides structured, level-based logging with practically zero overhead when disabled. It allows easy integration with log aggregators (Elastic, Datadog) without enforcing a third-party dependency.

Protocol Implementation Status

This implementation is checked against RFC 4130.