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
| Name | Required | Default | Description | Examples |
|---|---|---|---|---|
| $ref | false | - | Reference a component defined under components. | - |
| as2Id | false | - | 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 |
| insecureAllowExpiredCertificates | false | false | Whether 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 |
| maxPayloadSize | false | 104857600 | Maximum 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 |
| requireEncrypted | false | false | Whether unencrypted messages are rejected. Decryption needs an RSA key. | true |
| requireSigned | false | true | Whether 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
| Element | Cardinality | Description |
|---|---|---|
| key | 0..1 | Own 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. |
| keystore | 0..1 | Loads 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. |
| partner | 0..* | 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. |