AS2 Profiles#

Introduction#

Profiles describe local AS2 identities and remote trading partners. They are stored in dedicated [profiles/UUID] sections and are separate from user accounts.

An AS2 location selects one local profile and one partner profile for sending files. Locations define outgoing encryption, signatures, compression, and MDN handling.

SFTPPlus transfers handle the actual movement of files over AS2. They define which files to send, when to send them, and which AS2 location to use as the destination. The selected location supplies the message processing rules and references the local and trading partner profiles.

An HTTP or HTTPS service accepts incoming AS2 requests. The account associated with an incoming message determines where its files are stored. The HTTP or HTTPS service selects the local AS2 profile whose URL name and private certificate are used for receiving.

An account defined in the main configuration can select a partner profile for incoming signed-message validation, the AS2 HTTP authentication requirement, and asynchronous MDN HTTPS trust. Accounts returned by external authentication methods cannot receive AS2 messages. The account continues to supply its username, password, expiration date, groups, source IP rules, and file storage settings. Profiles do not define an account home folder. An account needs a selected partner profile to receive AS2 messages.

name#

Default value:

Empty

Optional:

No

From version:

6.3.0

Values:

Text

Description:

A name to identify this AS2 profile in the configuration and Web Manager.

description#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

Text

Description:

An administrator note describing the purpose of this AS2 profile.

type#

Default value:

None

Optional:

No

From version:

6.3.0

Values:

  • as2-local

  • as2-partner

Description:

Selects the profile's configuration type. Use as2-local for the local identity when sending or receiving AS2 files, and as2-partner for the remote trading partner.

enabled#

Default value:

Yes

Optional:

Yes

From version:

6.3.0

Values:

  • Yes

  • No

Description:

Enables the profile for use by AS2 locations and incoming HTTP or HTTPS services. If either selected profile is disabled, the AS2 location fails to start, and transfers using that location fail to send files. A disabled local profile cannot be used to receive AS2 files.

as2_identifier#

Default value:

Empty

Optional:

No

From version:

6.3.0

Values:

Text

Description:

The protocol identifier agreed with the trading partner. When sending, the local profile supplies AS2-From and the partner profile supplies AS2-To. Incoming messages continue to use account authentication; the local profile selects only the receive URL and private certificate.

as2_receive_name#

Default value:

as2receive

Optional:

Yes

From version:

6.3.0

Values:

URL path, or empty for /as2receive

Description:

Available for as2-local profiles. Defines the URL path where an HTTP or HTTPS service accepts incoming AS2 messages for this local identity. For example, as2_receive_name = as2receive accepts messages at /as2receive. A nested path such as /as2/receive is also supported. When the option is absent or empty, the URL is /as2receive. Set it to / explicitly to receive at the root URL. HTTP and HTTPS services reference the profile through as2_local_profile. Each service exposes the URL path of its selected local profile.

private_certificate#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

UUID of a private-certificate vault item, or empty

Description:

Available for as2-local profiles. Selects the private key and certificate used to sign outgoing messages, decrypt received files, and sign MDN responses. When empty, the server's default private certificate is used.

trusted_certificates#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

UUID of a trusted-certificates vault item, or empty

Description:

Available for as2-partner profiles. The first certificate encrypts outgoing files. All certificates can validate signed MDN receipts, allowing certificate rollover. The same certificates validate incoming signed files for accounts that select this partner profile. Configure certificates when the location requests encryption or signed receipts.

url#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

HTTP or HTTPS URL

Description:

Available for as2-partner profiles. The partner endpoint receiving outgoing files. Leave empty when no outgoing AS2 messages are sent to this partner. HTTPS uses the profile's TLS configuration.

username#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

Text

Description:

Available for as2-partner profiles. Username sent for HTTP authentication to the partner's receiving endpoint.

Leave empty when the partner does not require HTTP authentication.

password#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

Text

Description:

Available for as2-partner profiles. Password sent to the partner endpoint for outgoing AS2 messages.

as2_require_http_authentication#

Default value:

Yes

Optional:

Yes

From version:

6.3.0

Values:

  • Yes

  • No

Description:

Available for as2-partner profiles. Controls whether incoming AS2 messages associated with this partner profile require HTTP authentication. Accounts without a selected partner profile cannot receive AS2 messages.

as2_async_mdn_https_trusted_certificates#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

  • UUID of a trusted-certificates vault item

  • Empty

  • disabled

Description:

Available for as2-partner profiles. Selects the trusted certificates used to validate the partner's HTTPS server during asynchronous MDN delivery for accounts that select this profile. Leave it empty to disable asynchronous MDN delivery. Set it to disabled to allow asynchronous MDN delivery without validating the partner's HTTPS server certificate.

as2_check_method#

Default value:

head

Optional:

Yes

From version:

6.3.0

Values:

  • head

  • get

Description:

Available for as2-partner profiles. HTTP method used to check the receiving endpoint before sending files.

tls_trusted_certificates#

Default value:

set-on-first-connection

Optional:

Yes

Values:

  • Vault item UUID

  • set-on-first-connection

  • pin-public-key

  • disable-identity-security

From version:

5.22.0

Description:

This is used to validate the identity of the remote server.

Remote server identity can only be validated when the remote address or URL is configured using a fully-qualified domain name. IP-based validation would always fail as this is not a method accepted by Certificate Authorities (CAs).

Warning

When disable-identity-security is set, the identity of the remote server is not validated. All remote servers are accepted without validating their TLS/SSL certificates. Communication is encrypted and data is protected in transit. This can result in an encrypted connection to an unknown server.

When set-on-first-connection is used, the Certificate Authority of the remote server is configured automatically. The set-on-first-connection configuration value is automatically replaced by the actual CA chain of the remove server on the very first connection. For all subsequent connections, the server identity is validated against the automatically configured CA chain.

When pin-public-key is set, SFTPPlus accepts server certificates that have the same public key as the one discovered during the first connection to this server. This is used to implement certificate and public key pinning. SFTPPlus only pins the public key. This can be used for self-signed server certificates.

You can configure the client to validate the server's identity based on a fixed list of public keys. In this way, you can implement public key pinning. When public key validation is used, the public key infrastructure (PKI) certificate policies are not enforced. For example, the server certificate is accepted even if it's expired or issued for a different hostname.

Only servers using certificates signed by one of the configured Certificate Authorities are allowed to communicate with this client.

ssl_domains#

Default value:

Empty

Optional:

Yes

Values:

  • Fully qualified domain name (FQDN)

  • Comma separated list of fully qualified domain names

  • Empty

From version:

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let's Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

You can generate a certificate with multiple domain names (Subject Alternative Name - SAN), by defining a comma-separated list of domain names. The first name from the list is used as the common name of the certificate, while the remaining names are used for the SAN extension.

For this option to be used, you need to define a lets-encrypt resource.

tls_private_certificate#

Default value:

Empty

Optional:

Yes

Values:

  • UUID of a private-certificates vault item.

  • Empty

From version:

5.20.0

Description:

The private key and certificate to be used by this component for TLS communication.

This certificate is sent to the remote peer during the SSL/TLS handshake process.

When left empty, the default certificate is used.

ssl_certificate_revocation_list#

Default value:

Empty

Optional:

Yes

Values:

  • Comma separated list of CRL paths or HTTP URLs.

  • crl-distribution-points

  • ${MICROSOFT_IT_CRL}

  • Empty

From version:

1.6.0

Description:

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

  • file:///unix/absolute/test-ca.crl

  • file://c:\\windows\\absolute\\test-ca.crl

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

  • http://example.com/some.crl

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Leave it empty to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer's certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP-based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if tls_trusted_certificates or tls_mutual_certification_authorities are not enabled.

ssl_certificate_revocation_list_refresh#

Default value:

0

Optional:

Yes

Values:

  • Number of seconds

  • 0

From version:

2.8.0

Description:

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if tls_trusted_certificates or tls_mutual_certification_authorities are not enabled.

ssl_cipher_list#

Default value:

secure

Optional:

Yes

Values:

  • List of SSL/TLS ciphers in OpenSSL format.

  • secure

From version:

1.7.4

Description:

This defined the list of ciphers accepted by this component while communicating over the network.

The special keyword secure contains all the algorithms that we currently consider secure.

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

When left empty, it will default to the secure configuration.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

ssl_allowed_methods#

Default value:

secure

Optional:

Yes

Values:

  • secure

  • all

  • tlsv1.0

  • tlsv1.1

  • tlsv1.2

  • tlsv1.3

From version:

1.7.4

Description:

This defines the comma-separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Set this to secure to allow only the TLS methods that are currently considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might be changed in the future. Any other configured value is ignored.

Set this to all to allow any supported SSL or TLS method. Any other configured value is ignored.

Currently, the following methods are officially supported:

  • tlsv1 or tlsv1.0, which is TLS 1.0.

  • tlsv1.1, which is TLS 1.1.

  • tlsv1.2, which is TLS 1.2.

  • tlsv1.3, which is TLS 1.3.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

Support for tlsv1.3 was added in version 3.47.0.

Prior to version 4.17.0, this was configured as a space separated value.