Skip to content

Security Considerations

Jump to bottom
Philip Helger edited this page Apr 1, 2026 · 9 revisions

Security Considerations

Overview

This page assembles all parts of the phoss-ap architecture where security needs to be considered. AS4 message-level security (signing, encryption, certificate validation) is assumed to be properly handled by phase4 and is not covered here.

API Authentication

The REST API is the primary external interface for the Sender Backend (C2, outbound submission) and the Receiver Backend (C3, inbound reporting). All API endpoints must be protected.

  • Authentication mechanism: API token via X-Token HTTP header, configured via phase4.api.requiredtoken. The token must be present.
  • Scope: All outbound and inbound API endpoints (submit, status query, reporting).
  • Recommendation: Always configure a strong API token in production. Consider augmenting with IP allowlisting or mutual TLS for environments with stricter requirements.
  • Shutdown protection: The AP rejects new submissions during graceful shutdown, regardless of valid authentication.

Input Validation

All data entering the AP via the REST API or AS4 must be validated before processing.

Outbound API (Sender Backend input)

  • Raw document + metadata submission: Validate all required parameters (senderID, receiverID, docTypeID, processID, countryC1). Ensure identifiers conform to Peppol identifier syntax. Reject oversized payloads via spring.servlet.multipart.max-file-size / max-request-size.
  • Pre-built SBD submission: Parse and validate the SBDH structure. Ensure all required metadata fields can be extracted. Reject malformed XML before storage.
  • Optional document verification: The pluggable IDocumentVerifier SPI can enforce schema validation, Schematron rules, or custom business rules on outbound documents before AS4 sending. Configured via verification.outbound.enabled.

Inbound (Remote AP input)

  • AS4 message validation: Handled by phase4 (signature validation, certificate chain, message structure).
  • Receiver verification: Before storing the document, the AP checks whether it services the addressed receiver participant for the given document type and process via the pluggable IReceiverCheck SPI. If the receiver is not serviced, an AS4 error EBMS:0004 / PEPPOL:NOT_SERVICED is returned to C2. No database entry is created. This prevents the AP from accepting and storing documents it cannot deliver.
  • Optional document verification: The same IDocumentVerifier SPI can validate inbound documents before forwarding to the Receiver Backend. Configured via verification.inbound.enabled. Rejection triggers MLS RE response back to C2.
  • Reporting API input: Validate sbdhInstanceID and countryC4 parameters. Ensure the referenced transaction exists and has not already been reported.

Duplicate Detection and Replay Prevention

Two independent levels of duplicate detection protect against message replay and retransmission:

Level What it detects Default mode
AS4 Message ID Exact same AS4 message retransmitted reject
SBDH Instance Identifier Same Peppol envelope resent (different AS4 Message ID) reject

Each level is independently configurable (reject or store_and_flag) via configuration properties. In reject mode, the duplicate is refused at the AS4 level. In store_and_flag mode, it is stored but flagged in the database for downstream review.

Credential and Secret Management

The following secrets are present in the configuration:

Secret Configuration property Purpose
AS4 keystore password org.apache.wss4j.crypto.merlin.keystore.password Access the AP signing/decryption keystore
AS4 private key password org.apache.wss4j.crypto.merlin.keystore.private.password Access the private key within the keystore
AS4 truststore password org.apache.wss4j.crypto.merlin.truststore.password Access the AP truststore for certificate validation
SMP client truststore password smpclient.truststore.password Access the SMP client TLS truststore
Database password jdbc.password Database authentication
Flyway password flyway.jdbc.password Optional separate Flyway migration credentials
API token phase4.api.requiredtoken REST API authentication
HTTP proxy password http.proxy.password Proxy server authentication
SFTP password forwarding.sftp.password SFTP server authentication
SFTP key passphrase forwarding.sftp.keypair.passphrase Private key decryption
S3 secret access key forwarding.s3.secret-access-key AWS S3 authentication

Recommendations:

  • Never commit secrets in plain text to version control.
  • Use environment variable substitution (e.g., ${DB_PASSWORD}) or an external secret manager for production deployments.
  • Restrict file system permissions on application.properties to the service account only.
  • Rotate secrets periodically, especially API tokens and SFTP/S3 credentials.

Transport Security (TLS)

All external communication should use TLS:

Communication path Direction TLS enforcement
AS4 messaging (C2 ↔ C3) Outbound and inbound Enforced by Peppol AS4 profile (HTTPS mandatory)
SMP lookup Outbound HTTPS to SMP; truststore configured via smpclient.truststore.*
HTTP POST forwarding Outbound (to Receiver Backend) Should use HTTPS; configured via forwarding.http.endpoint
S3 forwarding Outbound (to AWS) HTTPS by default (AWS SDK)
SFTP forwarding Outbound (to SFTP server) SSH/SFTP protocol (encrypted by design)
Peppol Reporting submission Outbound HTTPS
REST API Inbound (from Sender/Receiver Backend) Should be configured with HTTPS via reverse proxy or Spring Boot TLS
CRL downloads Outbound HTTPS

Recommendation: Enforce HTTPS for all HTTP-based communication. For the REST API, either configure Spring Boot with TLS directly or deploy behind a TLS-terminating reverse proxy (nginx, Apache httpd). When using a reverse proxy, configure server.forward-headers-strategy=native so the AP correctly interprets forwarded headers.

Data at Rest

Database

  • Document paths (document_path): The database stores absolute file paths referencing document files on disk. The actual document content (which may contain sensitive business data such as invoices and orders) is stored as files in the configured storage directories (storage.inbound.path, storage.outbound.path).
  • Document hashes (document_hash): SHA-256 hashes stored for integrity verification.
  • Metadata: Sender/receiver IDs, document type IDs, and process IDs are stored alongside the file path reference.
  • Recommendation: Enable database-level encryption (e.g. PostgreSQL Transparent Data Encryption or MySQL InnoDB tablespace encryption) or full-disk encryption for the database volume. Restrict database access to the AP service account with least-privilege permissions.

Document storage directories

  • Inbound documents are stored under storage.inbound.path (default /var/phoss-ap/inbound).
  • Outbound documents are stored under storage.outbound.path (default /var/phoss-ap/outbound).
  • Risk: These directories contain the full document payloads — invoices, orders, and other sensitive business data.
  • Recommendation: Restrict file system permissions on the storage directories to the AP service account only. Use full-disk encryption or an encrypted file system for the storage volume. Apply the same backup and retention policies as for the database.

Archive tables

  • Completed transactions are moved to archive tables. The archive rows reference the same document files on disk via document_path. The same security requirements apply to both the archived database rows and the referenced files.
  • Permanently failed and rejected transactions remain in the primary tables.

phase4 message dumps

  • phase4.dump.path configures a directory for raw AS4 message dumps (request/response payloads).
  • Risk: Dumps contain full message content including business documents and cryptographic material.
  • Recommendation: Disable dumps in production (phase4.dump.path not set). If dumps are needed for debugging, restrict file system access and purge dump files promptly.

SFTP Host Key Verification

When using SFTP forwarding, the AP connects to an SFTP server to deliver documents. Without host key verification, the connection is vulnerable to man-in-the-middle attacks.

  • Configuration: forwarding.sftp.knownhostspath specifies the SSH known_hosts file.
  • Key-based authentication: Preferred over password authentication. Configure via forwarding.sftp.keypair.privatekeypath / publickeypath.
  • Recommendation: Always configure a known_hosts file in production. Use key-based authentication with passphrase-protected private keys.

S3 Access Security

When using S3 forwarding:

  • IAM roles (preferred): When running on AWS infrastructure, use IAM instance roles or ECS task roles instead of static access keys. In this case, forwarding.s3.access-key-id and forwarding.s3.secret-access-key can be omitted.
  • Static credentials: If IAM roles are not available, configure access keys with least-privilege permissions (write access to the specific bucket/prefix only).
  • Bucket policy: Restrict the S3 bucket to the AP's IAM principal. Enable server-side encryption (SSE-S3 or SSE-KMS).

HTTP Proxy Security

When the AP communicates through an outbound HTTP proxy (http.proxy.enabled=true), proxy credentials may be transmitted.

  • Scope: Proxy settings affect AS4 sending, SMP lookups, CRL downloads, and reporting submission.
  • http.proxy.nonProxyHosts: Ensure internal hosts (e.g., localhost, internal Receiver Backend) bypass the proxy.
  • Recommendation: Use authenticated proxy connections only over trusted network paths. Store proxy credentials via environment variable substitution.

Notification Security

Failure notifications (via the INotificationHandler SPI) may contain sensitive metadata such as:

  • Sender and receiver Peppol participant IDs
  • Document type identifiers
  • Error details from failed sending or forwarding attempts
  • SBDH Instance Identifiers

Recommendation: Ensure notification channels (email, Slack, webhook) are themselves secured (TLS, authentication). Avoid including full document payloads in notifications — reference the transaction by SBDH Instance ID only.

Graceful Shutdown Security

During shutdown, the AP:

  1. Stops accepting new inbound AS4 messages and outbound API submissions.
  2. Finalizes any in-flight operations.

This prevents transactions from being left in an inconsistent state. It also ensures that no messages are accepted during a period where the AP may not be able to complete processing securely (e.g., draining connections before a certificate rotation).

Audit Trail

The database design provides a built-in audit trail through:

  • Transaction records: Every outbound and inbound transaction is stored with its full metadata and status history.
  • Attempt records: Each sending or forwarding attempt is individually recorded with timestamps, outcome, and error details.
  • AS4 timestamps: as4_timestamp fields capture the exact AS4 MessageInfo/Timestamp (UTC) for MLS SLA measurement and forensic analysis.
  • Signing certificate CN: signing_cert_cn on inbound transactions records the subject CN of the signing certificate.
  • Duplicate flags: Three boolean flags per inbound transaction record whether duplicates were detected.

Recommendation: Enable jdbc.debug.sql temporarily for detailed SQL audit logging during security reviews. Consider exporting audit data to a SIEM system for monitoring.

Summary of Security Boundaries

                          ┌──────────────────────────────┐
   Sender Backend ──────► │          REST API            │ ◄── API Token
   (C2 internal)          │   (Input validation, AuthN)  │
                          └──────────┬───────────────────┘
                                     │
                          ┌──────────▼───────────────────┐
                          │      phoss-ap-core           │
                          │  (Verification, Dup Check,   │
                          │   Circuit Breaker, Retry)    │
                          └──────────┬───────────────────┘
                                     │
              ┌──────────────────────┼─────────────────────┐
              │                      │                     │
   ┌──────────▼──────────┐ ┌─────────▼──────────┐ ┌────────▼─────────┐
   │    phase4 (AS4)     │ │      Database      │ │   Forwarding     │
   │  (TLS, Signing,     │ │  (Encryption at    │ │  (TLS/SSH,       │
   │   Certificate PKI)  │ │   rest, Access     │ │   Credentials,   │
   │                     │ │   control)         │ │   Host verify)   │
   └─────────────────────┘ └────────────────────┘ └──────────────────┘
              │                                             │
   Remote AP (C3)                                  Receiver Backend
                                                   (C3 internal)

It is appreciated if you star the GitHub project if you like it.

Donation link: https://paypal.me/PhilipHelger

Clone this wiki locally