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 as2Sender delivers documents to a trading partner over AS2.
Internal systems post the plain document, e.g. an EDIFACT order, to the API. The interceptor turns the request into an AS2 message to the partner and sends it to the target of the API, the AS2 URL of the partner. The Content-Type of the request becomes the content type of the document, the filename of a Content-Disposition header its file name. The other request headers are not sent to the partner.
The interceptor verifies the MDN of the partner: its signature against the partner's certificate, that it refers to the message, and the MIC, which proves that the partner received the document unchanged. The client gets status 200 with the Message-ID, the disposition and the MIC as JSON if the partner confirmed the message, otherwise status 502 with the reason. Only synchronous MDNs in the HTTP response are supported.
Put the interceptor directly into the flow of the API, not into request, otherwise the MDN is not checked. Interceptors after it must not change the request body: 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.
as2Sender:
as2Id: <own AS2 ID>
keystore: ... | key: ...
partner:
as2Id: <AS2 ID of the partner>
certificate:
location: <PEM file>
[ signatureDigest: sha1 | sha256 | sha384 | sha512 ]
[ encryption: none | triple_des | aes128_cbc | aes192_cbc | aes256_cbc ]
[ compression: none | before_signing | after_signing ]
[ mdn: signed | unsigned | none ]
[ subject: <subject> ]
[ dispositionNotificationTo: <address> ]
[ messageIdDomain: <domain> ]
[ maxPayloadSize: <bytes> ]
[ insecureAllowExpiredCertificates: true | false ]
Example Configuration
api:
port: 2001
path:
uri: /acme
flow:
- as2Sender:
as2Id: MEMBRANE
keystore:
location: membrane.p12
password: secret
keyAlias: membrane
partner:
as2Id: ACME
certificate:
location: acme.pem
compression: before_signing
target:
url: https://as2.acme.example.com/as2
api:
port: 2001
path:
uri: /acme
flow:
- as2Sender:
as2Id: MEMBRANE
keystore:
location: membrane.p12
password: secret
keyAlias: membrane
partner:
as2Id: ACME
certificate:
location: acme.pem
compression: before_signing
target:
url: https://as2.acme.example.com/as2
Syntax
as2Sender:
'$ref': <string>
as2Id: <string>
compression: none
dispositionNotificationTo: <string>
encryption: none
insecureAllowExpiredCertificates: <boolean>
key: {}
keystore: {}
maxPayloadSize: <int>
mdn: none
messageIdDomain: <string>
partner: {}
signatureDigest: sha1
subject: <string>
as2Sender:
'$ref': <string>
as2Id: <string>
compression: none
dispositionNotificationTo: <string>
encryption: none
insecureAllowExpiredCertificates: <boolean>
key: {}
keystore: {}
maxPayloadSize: <int>
mdn: none
messageIdDomain: <string>
partner: {}
signatureDigest: sha1
subject: <string>
Attributes
| Name | Required | Default | Description | Examples |
|---|---|---|---|---|
| $ref | false | - | Reference a component defined under components. | - |
| as2Id | false | - | Own AS2 ID, sent as AS2-From. 1 to 128 printable ASCII characters. | MEMBRANE |
| compression | false | none | Whether and where messages are compressed: before_signing compresses the document, after_signing the signed document. | before_signing |
| dispositionNotificationTo | false | the own AS2 ID | Value of the Disposition-Notification-To header, which requests the MDN. Usually an email address. Partners rarely use it. | as2 |
| encryption | false | aes256_cbc | Algorithm messages are encrypted with, or none. Encryption needs an RSA certificate of the partner. Use triple_des only for partners that do not support AES. | aes128_cbc |
| insecureAllowExpiredCertificates | false | false | Whether certificates outside their validity period are used, both the own certificate and that of the partner. Insecure: MDNs signed with the expired certificate of the partner are still accepted, 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 sends no messages as soon as a certificate expires. | true |
| maxPayloadSize | false | 104857600 | Maximum size of the document in bytes. Larger requests are rejected with status 413. | 10485760 |
| mdn | false | signed | Which MDN is requested from the partner: signed, unsigned or none. Only a signed MDN proves that the partner received the message. Without an MDN, a 2xx status of the partner counts as delivered. | unsigned |
| messageIdDomain | false | as2.local | Domain part of the generated Message-IDs, the part after the @. | example.com |
| signatureDigest | false | sha256 | Digest algorithm of the signature. It also computes the MIC that the partner returns in the MDN. | sha512 |
| subject | false | AS2 Message | Value of the Subject header of the messages. | Orders |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| key | 0..1 | Own private key and certificate in PEM format, which sign the messages. 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..1 | Trading partner the messages are sent to. Messages are encrypted with its certificate, and its MDNs have to be signed with it. |