Open Source API Gateway
2. Enterprise Integration Patterns

as2Receiver

Version

AS2 (RFC 4130) is a protocol for exchanging business documents such as EDI messages over HTTP. Messages are signed, encrypted and compressed with S/MIME, and the receiver confirms each one with a signed receipt, the MDN. The as2Receiver makes an API an AS2 endpoint.

The interceptor decrypts, decompresses and verifies incoming messages and forwards the payload, e.g. the EDI document, to the backend with the Content-Type of the payload. When the backend has answered, the interceptor replaces its response with the MDN. The MDN reports the message as processed if the backend answered with a 2xx status, otherwise as failed. It also reports the message as failed if an interceptor after the as2Receiver fails while handling the response, even if the backend accepted the payload. A message that fails verification is not forwarded: the sender gets an error MDN, or status 400 or 403 if it did not request an MDN. A message that is too large gets status 413. Only synchronous MDNs in the HTTP response are supported.

Put the interceptor directly into the flow of the API, not into request, otherwise no MDN is sent. Interceptors that change the body must not run before it: the signature covers the exact bytes.

The interceptor needs the Membrane AS2 Extension. Without the extension Membrane does not start. Contact predic8 for the extension.

 as2Receiver:
   as2Id: <own AS2 ID>
   keystore: ... | key: ...
   partners:
     - as2Id: <AS2 ID of the partner>
       certificate:
         location: <PEM file>
     ...
   [ requireSigned: true | false ]
   [ requireEncrypted: true | false ]
   [ maxPayloadSize: <bytes> ]
   [ insecureAllowExpiredCertificates: true | false ]
 

Example Configuration

api:
port: 2000
path:
uri: /as2
flow:
- as2Receiver:
as2Id: MEMBRANE
keystore:
location: membrane.p12
password: secret
keyAlias: membrane
partners:
- as2Id: ACME
certificate:
location: acme.pem
requireEncrypted: true
target:
url: http://erp.example.com/inbound
api:
   port: 2000
   path:
     uri: /as2
   flow:
     - as2Receiver:
         as2Id: MEMBRANE
         keystore:
           location: membrane.p12
           password: secret
           keyAlias: membrane
         partners:
           - as2Id: ACME
             certificate:
               location: acme.pem
         requireEncrypted: true
   target:
     url: http://erp.example.com/inbound

Syntax

as2Receiver:
'$ref': <string>
as2Id: <string>
insecureAllowExpiredCertificates: <boolean>
key: {}
keystore: {}
maxPayloadSize: <int>
partners:
- <partner>
requireEncrypted: <boolean>
requireSigned: <boolean>
as2Receiver:
  '$ref': <string>
  as2Id: <string>
  insecureAllowExpiredCertificates: <boolean>
  key: {}
  keystore: {}
  maxPayloadSize: <int>
  partners:
    - <partner>
  requireEncrypted: <boolean>
  requireSigned: <boolean>

Attributes

NameRequiredDefaultDescriptionExamples
$reffalse-Reference a component defined under components.-
as2Idfalse-Own AS2 ID. The AS2-To header of incoming messages has to match it, and MDNs are sent from it. 1 to 128 printable ASCII characters.MEMBRANE
insecureAllowExpiredCertificatesfalsefalseWhether certificates outside their validity period are used, both the own certificate and those of the partners. Insecure: a partner whose certificate has expired is still authenticated, even though the partner may no longer protect the key. Use it only for the time a partner needs to renew its certificate. Otherwise Membrane does not start with such a certificate, and while it runs it rejects messages as soon as a certificate expires.true
maxPayloadSizefalse104857600Maximum size of the payload in bytes. It also limits decompression, so a small compressed message cannot expand into a huge payload. Larger messages are rejected. Requests with a body larger than twice this size plus 1 MB are rejected before decryption.10485760
requireEncryptedfalsefalseWhether unencrypted messages are rejected. Decryption needs an RSA key.true
requireSignedfalsetrueWhether unsigned messages are rejected. The sender of an unsigned message is not authenticated, so anyone can send one in the name of a partner.false

Child Structure

ElementCardinalityDescription
key0..1Own private key and certificate in PEM format, which decrypt incoming messages and sign MDNs. Set either a keystore or a key. The first certificate belongs to the key.
keystore0..1Loads a private key and its certificate chain from a keystore file, to be presented as this side's identity during a TLS handshake (or, inside wsSecurity, to sign a message). See tutorials/web-services-security/50-Sign-And-Validate-Body.yaml.
partner0..*Trading partners that may send messages. A message is assigned to a partner by its AS2-From header, and its signature is verified only against that partner's certificate. Messages from other senders are rejected.

Can be used in