Open Source API Gateway
2. Enterprise Integration Patterns

as2Sender

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 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

NameRequiredDefaultDescriptionExamples
$reffalse-Reference a component defined under components.-
as2Idfalse-Own AS2 ID, sent as AS2-From. 1 to 128 printable ASCII characters.MEMBRANE
compressionfalsenoneWhether and where messages are compressed: before_signing compresses the document, after_signing the signed document.before_signing
dispositionNotificationTofalsethe own AS2 IDValue of the Disposition-Notification-To header, which requests the MDN. Usually an email address. Partners rarely use it.as2
encryptionfalseaes256_cbcAlgorithm 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
insecureAllowExpiredCertificatesfalsefalseWhether 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
maxPayloadSizefalse104857600Maximum size of the document in bytes. Larger requests are rejected with status 413.10485760
mdnfalsesignedWhich 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
messageIdDomainfalseas2.localDomain part of the generated Message-IDs, the part after the @.example.com
signatureDigestfalsesha256Digest algorithm of the signature. It also computes the MIC that the partner returns in the MDN.sha512
subjectfalseAS2 MessageValue of the Subject header of the messages.Orders

Child Structure

ElementCardinalityDescription
key0..1Own 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.
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..1Trading partner the messages are sent to. Messages are encrypted with its certificate, and its MDNs have to be signed with it.

Can be used in