AS2 Server#
Introduction#
SFTPPlus can receive files using the EDIINT AS2 protocol defined in the RFC 4130 standard.
This page covers receiving files over AS2. If you want to send files over AS2, check the dedicated HTTP AS2 transfer documentation page.
Received content can be confirmed using the message disposition acknowledgment (MDN) method defined in RFC 8098.
File content can be compressed as defined in RFC 5402, encapsulated in a CMS (Cryptographic Message Syntax) MIME entity.
HTTP method#
The AS2 messages should be sent using the POST HTTP request verb/method.
The HEAD HTTP verb checks whether an AS2 request can authenticate without triggering a file transfer. It requires non-empty AS2-From and AS2-To headers; missing headers return 401 Unauthorized. When the partner profile requires HTTP Basic authentication, the request must also provide valid credentials.
HTTPS security#
The AS2 connections are secured at the transport layer by the HTTPS protocol. In this regard, the SFTPPlus AS2 server is configured just like any other HTTPS server. The SFTPPlus HTTPS server allows transferring files over web browser, AS2, REST, WebDAV by using a shared HTTPS server. There is no need to set up separate HTTPS servers for each file transfer type.
HTTPS client certificates do not authenticate AS2 requests.
Check the dedicated HTTPS server documentation page, to learn more about how to configure the HTTPS security.
For legacy transfers, SFTPPlus allows exchanging AS2 files over an HTTP server.
Configuration example#
The SFTPPlus HTTPS server can be configured to receive files over AS2. Select the as2_local_profile on the HTTP or HTTPS service, and configure the AS2 URL path on that profile. The URL path tells SFTPPlus to handle requests there as AS2 messages.
Below is a configuration example. In the following sections of this page, we will discuss the details of each configuration part and AS2 operation like authentication, encryption, MDN, etc.
The public AS2 site is available at the https://example.tld/as2receive URL, where the as2receive URL path is defined by the as2_receive_name configuration option:
[services/9ac4-1054-f0e4]
name = HTTPS with AS2 File Transfer Service
type = https
as2_local_profile = as2-local-profile-uuid
as2_pending_path = /as2/pending
as2_receive_path = /as2/receive
[profiles/as2-local-profile-uuid]
name = ACME local AS2 identity
type = as2-local
as2_identifier = ACME Org
as2_receive_name = as2receive
private_certificate = as2-server-certificate-uuid
[profiles/johnd-as2-partner]
name = John D AS2 partner
type = as2-partner
as2_identifier = johnd
trusted_certificates = johnd-certificates-uuid
as2_require_http_authentication = no
[profiles/janer-as2-partner]
name = Jane R AS2 partner
type = as2-partner
as2_identifier = janer
trusted_certificates = janer-certificates-uuid
as2_require_http_authentication = yes
[accounts/4a48fbf4-d029]
name = johnd
home_folder_path = C:/Users/JohnD
as2_partner_profile = johnd-as2-partner
[accounts/758185de-d029]
name = janer
home_folder_path = C:/Users/JaneR
as2_partner_profile = janer-as2-partner
password = $6$rounds=80000$GE5tScXoFSfkMgBd$cDi7KLiu8X5gKkXC8d9FblkKG46p
default_permissions = allow-full-control
path_permissions =
*.exe, deny-full-control
[vault-items/as2-server-certificate-uuid]
type = private-certificate
name = AS2 server certificate
content =
----BEGIN RSA PRIVATE KEY-----
MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
EXAMPLE key with different armour
Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
MORE CERTIFICATE CONTENT
JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
-----END CERTIFICATE-----
[vault-items/johnd-certificates-uuid]
type = trusted-certificates
name = AS2 certificates for user John D
content = -----BEGIN CERTIFICATE-----
MIICpTCCAg6gAwIBAgIIP8vt0MYYvNIwDQYJKoZIhvcNAQELBQAwRjELMAkGA1
MORE CERTIFICATE CONTENT
JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICoDCCAgmgAwIBAgIIKk0/vqmeDb4wDQYJKoZIhvcNAQELBQAwODELMAkGA1UE
MORE CERTIFICATE CONTENT
6sXcntbQ8jyu8fNCjoVKGUe9gsgZOK2KapWxU7HzvulVQslcOcWG3mM=
-----END CERTIFICATE-----
[vault-items/janer-certificates-uuid]
type = trusted-certificates
name = AS2 certificates for user Jane R
content = -----BEGIN CERTIFICATE-----
BAYTAkdCMQ8wDQYDVQQKEwZDaGV2YWgxFDASBgNVBAsTC0NoZXZhaCBUZXN0MRIw
EAYDVQQDEwlsb2NhbGhvc3QwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAM6h
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
ulGy7rwJI9Me95aG53BrjMbBKk1qaHuNXa3PJjcgVmPelwPcbzk5Wl4E57dLN+eh
4Rf/Qyi9HBdtrDf19OzBmBs7W7pO9LPo5/usHlyVAgMBAAGjZDBiMBMGA1UdJQQM
-----END CERTIFICATE-----
With the above configuration, files received via AS2 for account johnd are temporarily stored in C:/Users/JohnD/as2/pending. The signature of those files is checked against the certificates in the trusted-certificates vault item selected by the johnd partner profile. Once the AS2 transfer is complete and the AS2 content is validated, the files are moved to C:/Users/JohnD/as2/receive.
The files received by the janer account are temporarily stored in C:/Users/JaneR/as2/pending and then moved into C:/Users/JaneR/as2/receive. Both accounts use the service's selected local profile. The connections for janer will need to be authenticated using an username and password via the HTTP Basic authentication method. Without a valid HTTP username and password, the AS2 messages are rejected. This behaviour is controlled by the partner profile's as2_require_http_authentication configuration option.
At the same time, any file with a name ending in .exe uploaded by account janer is rejected.
Note
Encrypted received messages should be encrypted using an RSA key. DSA public key-based encryption is not supported. Contact us if you need to encrypt AS2 messages using DSA.
When signed files are received, SFTPPlus validates their signatures using the trusted certificates selected by the account's partner profile. Accounts need a selected partner profile to receive AS2 messages. An account with a missing or disabled partner profile cannot receive AS2 messages, but can still use other file transfer protocols. An account that selects a profile of the wrong type or has invalid trusted certificates cannot log in to any service until the configuration is corrected.
When encrypted files are received, SFTPPlus decrypts them using the private key selected by private_certificate on the service's as2-local profile.
When signed message disposition notifications (MDN) are requested, SFTPPlus signs them using the same private key from the selected local profile.
If private_certificate on the local profile is empty, SFTPPlus uses the server's default private certificate. If neither certificate is configured, encrypted messages and requests for signed MDNs are rejected with HTTP status 400 before the file is accepted.
The digest algorithm requested for signing the MDN can differ from the algorithm used to sign the received file. SFTPPlus validates the file using its signature algorithm and signs the MDN using the requested receipt algorithm. For signed files, the Received-Content-MIC field in the MDN uses the file's signature algorithm. For example, a file signed with SHA-256 can request an MDN signed with SHA-512, and the MDN will contain a SHA-256 content MIC.
AS2 message authentication#
You add an incoming AS2 partner by creating a normal SFTPPlus file transfer account. Associate the account with an as2-partner profile to configure signature validation and AS2 HTTP authentication requirements. For messages without HTTP authentication, the account name must match the partner ID in AS2-From. For HTTP Basic authenticated messages, the HTTP username identifies the account and must match AS2-From. The account continues to supply its username, password, expiration date, groups, source IP rules, and file storage settings.
The default AS2 user authentication is done by checking the signature of the received files. This implies that the file needs to be fully received before validating the user identity.
Non-authenticated AS2 messages are supported and the account name will match the value of the AS2-From HTTP header. Set as2_require_http_authentication to No on the associated partner profile to allow this.
While the AS2 messages are received, the partial files, and the files that are not yet validated, are stored in the home path as configured for each user, in a sub-directory defined by the as2_pending_path configuration.
After the AS2 message is fully received and validated, the files from the AS2 messages are stored in the home path as configured for each user, in a sub-directory defined by the as2_receive_path configuration.
Files received via AS2 will have to comply with the general security policy and permissions, similar to any other file transfer protocol.
Below is an example in which the configuration will allow a partner with ID AS2 Trade aMjV9XxNTFO to send AS2 messages without HTTP authentication. It is highly recommended to restrict the source IP for this account, as without HTTP authentication anyone can send messages for this account, just by knowing the name of the trading partner:
[profiles/partner]
type = as2-partner
name = AS2 Trade profile
as2_identifier = AS2 Trade aMjV9XxNTFO
as2_require_http_authentication = No
[accounts/4a48fbf4-d029]
name = AS2 Trade aMjV9XxNTFO
home_folder_path = C:/Users/JohnD
as2_partner_profile = partner
source_ip_filter = allow 24.12.231.0/24
If you can deploy a configuration in which source IP filtering is enabled, we recommend to add a long and hard to guess value for your trading partner. This is why the above example uses the aMjV9XxNTFO value in the AS2 Trade aMjV9XxNTFO partner name.
Anonymous or HTTP Basic authentication#
With the default method, anyone from the Internet with access to your HTTPS/AS2 server can push files over the AS2 protocol.
We recommend requiring HTTP Basic authentication for incoming AS2 messages. When HTTP authentication is not required, the AS2 request uses the AS2-From identity to select an account. Presenting an HTTPS client certificate alone does not authenticate the request.
For HTTP authenticated requests, SFTPPlus uses the username found in the AS2 HTTP authentication request to recognize and authorize an AS2 partner. The AS2-From value must match the authenticated username.
File name#
SFTPPlus will try to use the Content-Disposition HTTP header as the file name of the received AS2 message.
If no Content-Disposition header is found in the AS2 request describing the name of the required file, SFTPPlus will store the received data using the default name post-upload-{uuid}, where {uuid} is replaced with a unique identifier. To use a different filename for this case, define the post_default_filename configuration option.
See the file name placeholders for the variables available in post_default_filename.
Async MDN delivery#
The delivery for asynchronous(ASYNC) MDN is retried 5 times, waiting 1 minutes for the first retry, then 2 minutes, and waiting 1 minute more with each retry.
The async MDN HTTPS request is made using the same TLS methods and ciphers configured for the HTTPS service over which the initial AS2 message was received.
When the remote partner is requesting an async MDN over HTTPS, the remote HTTPS connection is authenticated using the HTTPS SSL/TLS certificates configured on the account's partner profile as as2_async_mdn_https_trusted_certificates.
Our recommendation is to set up file transfers with your AS2 partner using synchronous MDN. This simplify the network configuration and provides improved security.
Setting as2_async_mdn_https_trusted_certificates to an empty value disables async MDN support entirely. Setting it to disabled values allows async MDN but disables the security check of the remote peer's certificate.
Asynchronous MDN response delivery errors will emit a dedicated failure event.
No extra event is emitted on the successful delivery of synchronous or asynchronous MDNs, other than the general event for the successful receiving of the AS2 message.