Documentation

4.17. Locations

4.17.1. Introduction

A location configuration provides the required information to allow SFTPPlus to connect to local or remote locations in order to perform file transfers between locations.

Please consult the type configuration option to see the list of supported location types.

Locations are auto-started when a transfer or another component needs them and the location is not started and connected.

They are also fault-tolerant, allowing retries for interrupted connections.

Transfers using a failed location will also fail and will not trigger a new connection attempt for the location. In this type of scenario, the failed location must be manually started first, after resolving the initial error.

4.17.2. Adding a new location via Local Manager

A new location can be added or changed via Local Manager below. Options will differ depending on which location type is used.

See below for an example of an initial configuration with the FTPES location.

../_images/gallery-add-ftps-location.png

4.17.3. Adding a new location via text configuration

Adding a new location configuration is done by creating a new section inside the configuration file. The name of the section should be prefixed with locations/ and followed by the location’s UUID.

The location’s UUID can be any unique string used to identify the location. Once defined, the UUID should not be changed.

For more information, please see the dedicated UUID documentation.

For example, to add a new location configuration of type filesystem called Local file system:

[locations/b904e6h6-c295-4ccf-8abd-edcae4d3324f]
name = Local file system
description = File system accesses as service account.
type = filesystem

4.17.4. Location options

Each location configuration section has the following configurations:

4.17.4.1. name

Default value:

‘’

Optional:

No

From version:

2.8.0

Values:
  • Any text.
Description:

Human-readable short text used to identify this location.

4.17.4.2. description

Default value:

‘’

Optional:

Yes

From version:

2.8.0

Values:
  • Any text.
Description:

Human-readable text that describes the purpose of this location.

4.17.4.3. type

Default value:

‘’

Optional:

No

From version:

2.6.0

Values:
  • filesystem - Local file system.
  • sftp - SFTP protocol v3 over SSH v2.
  • ftp - FTP protocol without any encryption.
  • ftpse - Explicit FTPS protocol.
  • ftpsi - Implicit FTPS protocol.
  • webdavs - WebDAV over HTTPS.
  • as2 - AS2 over HTTP or HTTPS
  • azure-file - Azure File Service.
  • smb - SMB / Windows Share
Description:

This option specifies the type of the location. Each type has a set of specific configuration options

4.17.4.4. idle_connection_timeout

Default value:

300

Optional:

Yes

From version:

3.0.0

Values:
  • Number of seconds after which idle connections are disconnected.
  • 0 - To disable timeouts.
Description:

Disconnect the connection to the remote peer if the location has not received any requests for the configured number of seconds.

Keep-alive command requests are ignored, and the connection will be automatically disconnected if keep-alive is the only command requested in the configured interval.

Disconnected locations will automatically reconnect when a new request is made.

If the remote peer closed the connection before the local configured timeout, the connection is left closed, and it will be automatically recreated when a new command is requested.

Set to 0 to always keep the connection active, by forcing reconnection when the remote peer closes the connection.

4.17.4.5. idle_connection_keepalive_interval

Default value:

0

Optional:

Yes

From version:

3.0.0

Values:
  • Number of seconds
Description:

Send a keep-alive command every N seconds to avoid having the connection disconnected by the other peer due to inactivity.

Set to 0 to disable keep-alive commands.

The keep-alive command does not reset the idle connection timeout,

4.17.4.6. connection_retry_count

Default value:

12

Optional:

Yes

From version:

3.9.0

Values:
  • Number of retries
Description:

Number of times to retry connection to the location, when the initial connection fails.

Set to 0 to not retry.

4.17.4.7. connection_retry_interval

Default value:

300

Optional:

Yes

From version:

3.9.0

Values:
  • Number of seconds
Description:

Number of seconds to wait between connection attempts.

Set to 0 to retry right away without any delay.

4.17.5. Local File System Location

A local file system location is accessed using the operating system’s file system.

For now, no extra configuration options are available for this location type.

Note

For the moment, local file system locations can’t be defined from the Local Manager GUI. There is a single default local filesystem which is available inside the GUI and which can not be removed.

4.17.6. SFTP Location

An sftp location provides access to an SFTP (version 3) server over SSH (version 2). This does not include access over SCP.

As the connection is done in non-interactive mode, the identity of the remote SSH server needs to be verified, so that credentials are not sent to an untrusted remote SSH server.

To validate the remote SSH server, the fingerprint of its public key is stored as a hexadecimal string in the ssh_server_identity option.

An SSH server can authenticate users using either a password or an SSH key.

4.17.6.1. ssh_server_identity

Default value:

‘’

Optional:

No

Values:
  • MD5 Hexadecimal, delimited by colons
  • SHA1 Base64
  • SHA256 Base64
  • OpenSSH Public Key
  • X.509 certificate
  • Multiple identities on multiple lines.
  • set-on-first-connection
From version:

3.51.0

Description:

This configuration defines the identity of the remote SSH server.

It can be defined as an MD5, SHA1, or SHA256 fingerprint.

You can also define it as an OpenSSH public key or an X.509 SSL/TLS certificate.

To automatically configure with the identity of the server found during the first connection, you can use the set-on-first-connection option. For security reasons, we do not recommend this option. This option is not available for cluster operations when the remote SFTP service has more than one SSH server identity.

When you are connecting to a remote SSH / SFTP service which is deployed as a cluster or as a disaster recovery failover it is possible that each node/server from the cluster to have its own identity. You will need to configure SFTPPlus with the identity of each server by defining multiple identities on separate lines.

This configuration is mandatory and critical for securing the SSH connection. When the server’s key fingerprint cannot be verified, all connections are rejected.

4.17.6.2. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the SFTP server.
From version:

2.8.0

Description:

Address of the remote SSH server. IP or DNS name.

4.17.6.3. port

Default value:

‘’

Optional:

No

Values:
  • Number, greater than 0.
From version:

2.8.0

Description:

Port number of the remote SSH server.

4.17.6.4. username

Default value:

‘’

Optional:

No

From version:

2.8.0

Values:
  • Text.
Description:

Username used to authenticate to the remote SSH server.

4.17.6.5. password

Default value:

‘’

Optional:

Yes

From version:

2.8.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the remote SSH server. It is provided in plain text. To disable password authentication, set this to an empty string.

When ssh_private_key is defined and configured to a private key which is stored in encrypted mode, this holds the password used to decrypt the private key.

4.17.6.6. ssh_private_key

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Absolute path on the local filesystem.
  • Content of the SSH private key (Since 3.40.0).
  • Disabled or empty.
Description:

SSH private key used to authenticate to the remote SSH server. Leave it empty to disable SSH key authentication.

It can be configured with a path on the local filesystem containing the content of the SSH key.

You can also define the content of the SSH key directly as a text value. In this case the configuration will look like the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

[locations/b904e6h6-c295-4ccf-8abd-edcae4d3324f]
name = SFTP Acme Server
type = sftp
ssh_private_key = -----BEGIN RSA PRIVATE KEY-----
    Proc-Type: 4,ENCRYPTED
    DEK-Info: AES-128-CBC,ACD9A45C68DD1924FF2A1A54BE2A7BF4

    RAHH7yMbPk/vrhT5jkSDGIUdH+nG0OQpeSWcQXd4JJ6pqdJh/cw/havtxlHFp1yz
    ...
    MORE SSH KEY CONTENT
    ...
    Pkf+23OGZln2dLz/pkJkiRRzmsWgT2hUv/EK4NYRQq1kEAXLf3J6xZqLlR3ZBLJm
    -----END RSA PRIVATE KEY-----

We recommend to store the key in PEM OpenSSH format, but Putty or Tectia formats are also supported.

When the configured key is encrypted, the value configured in password is used to decrypt the key.

4.17.6.7. proxy

Default value:

‘’

Optional:

Yes

Values:
  • URI like expression.
  • socks5://12.342.421.2:8899
From version:

3.31.0

Description:

This option configures a proxy to be used when making connection to the remote server.

When no port is defined, it will use port 1080.

Leave it empty to disable proxy usage.

For now, only the SOCKS5 without authentication is supported. The DNS resolution will be delegated to the SOCKS server.

4.17.6.8. ssh_cipher_list

Default value:

secure

Optional:

Yes

Values:
  • List of accepted key exchanges, HMACs and ciphers names.
  • all
  • secure
  • fips
From version:

3.11.0

To version:

None

Description:

The full name for each key exchange, HMAC or cipher should be used as comma separated values.

This will configure the symmetrical encryption, asymmetrical encryption, hash-based message authentication code, and key exchange algorithms.

The special keyword secure contains all the algorithms that we currently consider secure. Should this list of algorithms be updated to exclude any new ciphers that have been considered weak, SFTPPlus will need to be upgraded to the version that contains the updated secure list of algorithms.

The keyword all is available for configuring all the supported algorithms. This is provided mainly to help with backward compatibility and will also enable weak ciphers.

Warning

Configuring all ciphers will also enabled ciphers which are no longer considered secure by modern standards.

A pre-defined set of FIPS 140-2 approved ciphers is available by using the special fips keyword in this configuration. When FIPS 140-s ciphers are enabled, any other configured cipher in the list is ignored.

If an unsupported name is used, the component will fail to start.

When the all keyword is used, all other values are ignored. When the secure keyword is used, all other values are ignored, including fips and explicit ciphers. When the fips keyword is used, any explicit cipher configuration is ignored.

Only one option from all, secure, or fips should be used at a single time.

4.17.7. FTP Location

An ftp location provides access to an FTP server over the unencrypted mode.

Only username and password credentials are supported.

4.17.7.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.0.0

Description:

Address of the FTP server. IP or host name.

4.17.7.2. port

Default value:

21

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.0.0

Description:

Port number to connect to the FTP server.

4.17.7.3. username

Default value:

‘’

Optional:

No

From version:

3.0.0

Values:
  • Text.
Description:

Username used to authenticate to the FTP server.

4.17.7.4. password

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the FTP server.

It is defined in plain text format and sent over the network in plain text without any transport protection.

4.17.8. debug

Default value:

‘No’

Optional:

Yes

Values:
  • Yes
  • No
From version:

4.0.0

Description:

When enabled, the location will emit events with id 20000, containing low-level debug messages for the file transfer protocol.

Warning

When this is enabled, emitted events may include used password in plain text.

4.17.9. Explicit FTPS Location

An explicit ftps location provides access to an Explicit FTPS server.

Note

The explicit FTPS location is an experimental feature.

4.17.9.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.13.0

Description:

Address of the server. IP or host name.

In order to check the identity of the remote server the address should be provided as FQDN. IP addresses are not supported by the server identity validation process.

4.17.9.2. port

Default value:

21

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.13.0

Description:

Port number to connect to the server.

4.17.9.3. username

Default value:

‘’

Optional:

No

From version:

3.13.0

Values:
  • Text.
Description:

Username used to authenticate to the server.

4.17.9.4. password

Default value:

‘’

Optional:

Yes

From version:

3.13.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the server.

It is defined in plain text format and sent over the network protected by the TLS protocol.

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

4.17.9.6. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Certificate in PEM text format (Since 3.40.0).
  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

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

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.9.7. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.9.8. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.9.9. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.

  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.9.10. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
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.

Set it to Disabled, 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 ssl_certificate_authority is not enabled.

4.17.9.11. 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 ssl_certificate_authority is not enabled.

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

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.

4.17.9.13. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2 tlsv1.3

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
  • tlsv1.3
From version:

1.7.4

Description:

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

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.

4.17.9.14. ftps_ccc

Default value:

Disabled

Optional:

Yes

From version:

3.13.0

Values:
  • Passive
  • Disabled
  • Empty
Description:

This option specifies whether the security of the FTPS command connection should be downgraded to plain text after authentication.

Leave it empty to keep the command connection secure.

When this option is enabled, the SSL/TLS layer is shutdown after authenticating. The rest of the control channel communication will be done over an unencrypted connection.

For more details about using this configuration option please check the dedicated documentation for the FTPS CCC modes.

4.17.10. Implicit FTPS Location

An implicit ftps location provides access to an Implicit FTPS server.

Note

The implicit FTPS location is an experimental feature.

4.17.10.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.13.0

Description:

Address of the server. IP or host name.

In order to check the identity of the remote server the address should be provided as FQDN. IP addresses are not supported by the server identity validation process.

4.17.10.2. port

Default value:

990

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.13.0

Description:

Port number to connect to the server.

4.17.10.3. username

Default value:

‘’

Optional:

No

From version:

3.13.0

Values:
  • Text.
Description:

Username used to authenticate to the server.

4.17.10.4. password

Default value:

‘’

Optional:

Yes

From version:

3.13.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the server.

It is defined in plain text format and sent over the network protected by the TLS protocol.

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

4.17.10.6. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Certificate in PEM text format (Since 3.40.0).
  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

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

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.10.7. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.10.8. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.10.9. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.

  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.10.10. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
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.

Set it to Disabled, 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 ssl_certificate_authority is not enabled.

4.17.10.11. 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 ssl_certificate_authority is not enabled.

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

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.

4.17.10.13. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2 tlsv1.3

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
  • tlsv1.3
From version:

1.7.4

Description:

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

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.

4.17.11. WebDAV over HTTPS Location

A webdavs location provides access to a WebDAV server over a protected HTTPS connection.

SharePoint Online is the only WebDAV server currently supported. Only username and password credentials are supported to authenticate against the WebDAV server provided by SharePoint Online as part of the Office 365 claims-based authentication.

It is assumed that the WebDAV server handles the path in a case-insensitive manner. Please get in touch if your WebDAV server is case-sensitive.

Unlike a web browser, to protect the HTTPS connection you will have to explicitly configure the list of trusted CA and the location of the CRLs.

4.17.11.1. url

Default value:

‘’

Optional:

No

Values:
  • URL
From version:

4.11.0

Description:

Full URL address of the WebDAV server root page.

For SharePoint Online you can define it as:

url = https://YOUR-SITE.sharepoint.com

For generic WebDAV servers you can define it as:

url = https://files.example.com
or
url = https://files.example.com/path/webdav/resource

Or if you need a custom port number use:

url = https://files.example.com/path/webdav/resource

When this is defined as an http:// URL, the SSL configuration options are ignored.

4.17.11.2. username

Default value:

‘’

Optional:

No

From version:

3.20.0

Values:
  • Text.
Description:

Username used to authenticate to the WebDAV server.

4.17.11.3. password

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the WebDAV server.

It is defined in plain text format and sent over the network protected by the HTTPS connection.

4.17.11.4. proxy

Default value:

‘’

Optional:

Yes

Values:
  • URI like expression.
  • connect://12.342.421.2:3128
From version:

3.20.0

Description:

This configuration adds the proxy used to connect to the final URL.

For now, only the HTTP/1.1 CONNECT tunneling proxy method is supported.

4.17.11.5. authentication_method

Default value:

‘sharepoint-online’

Optional:

Yes

Values:
  • sharepoint-online
  • basic-authentication-scheme
From version:

4.12.0

Description:

The authentication method to use for connecting to the WebDAV server.

The default value of sharepoint-online is used for the Microsoft SharePoint Online cloud service authenticated via the Microsoft single sign-on process.

Another supported method is basic-authentication-scheme, the HTTP “Basic” access authentication, as per RFC 7617.

4.17.11.6. allow_insecure_http

Default value:

‘No’

Optional:

Yes

Values:
  • Yes
  • No
From version:

4.12.0

Description:

When set to Yes, the WebDAV connection is made via insecure HTTP instead of HTTPS.

Warning

This is useful for testing or troubleshooting, but is strongly discouraged in production, because it sends all communication including passwords and data as plaintext over the network.

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

4.17.11.8. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Certificate in PEM text format (Since 3.40.0).
  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

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

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.11.9. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.11.10. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.11.11. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.

  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.11.12. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
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.

Set it to Disabled, 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 ssl_certificate_authority is not enabled.

4.17.11.13. 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 ssl_certificate_authority is not enabled.

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

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.

4.17.11.15. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2 tlsv1.3

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
  • tlsv1.3
From version:

1.7.4

Description:

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

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.

4.17.12. AS2 over HTTPS or HTTP Location

An as2 location allows sending files to a remote AS2 server.

The as2 location can only be used for sending files over AS2. If you need to receive files over the AS2 protocol, you will need to configure the HTTP file transfer service.

Unlike a typical web browser connection, to protect an AS2 HTTPS connection you will have to explicitly configure the list of trusted CAs and the location of the CRLs.

4.17.12.1. url

Default value:

‘’

Optional:

No

Values:
  • .
From version:

4.5.0

Description:

Receiving URL for your partner.

SFTPPlus will use this URL to send files to your AS2 partner.

When this is defined as an http:// URL, the SSL configuration options are ignored.

4.17.12.2. username

Default value:

‘’

Optional:

Yes

From version:

4.5.0

Values:
  • Text.
Description:

Username used to authenticate to the remote AS2 partner server.

Leave it empty when the remote AS2 partner doesn’t require authentication.

4.17.12.3. password

Default value:

‘’

Optional:

Yes

From version:

4.5.0

Values:
  • Plain text password.
  • Empty.
Description:

This option specifies the password used to connect to the remote AS2 partner server.

It is ignored when username is empty.

4.17.12.4. as2_own_identifier

Default value:

‘’

Optional:

No

From version:

4.5.0

Values:
  • Text.
Description:

Identifier for your own local AS2 organization sending the files.

4.17.12.5. as2_own_certificate

Default value:

‘General server SSL certificate’

Optional:

No

From version:

4.5.0

Values:
  • PEM certificate.
  • PEM certificate and PEM private key.
Description:

Certificate for your own local AS2 organization used when signing files sent to a remote AS2 partner.

The certificate should be configured in PEM format.

This configuration can also contain the private key associated to the certificate.

This can be empty when sending unsigned files.

4.17.12.6. as2_own_private_key

Default value:

‘General server SSL private key’

Optional:

No

From version:

4.5.0

Values:
  • PEM private key.
Description:

Certificate for your own local AS2 organization used when signing files sent to a remote AS2 partner.

The certificate should be configured in PEM format.

This configuration can also contain the private key associated to the certificate.

4.17.12.7. as2_partner_identifier

Default value:

‘’

Optional:

No

From version:

4.5.0

Values:
  • Text.
Description:

Identifier for the remote AS2 partner receiving the files.

4.17.12.8. as2_partner_certificates

Default value:

‘’

Optional:

No

From version:

4.5.0

Values:
  • PEM certificate
  • Multiple PEM certificates
Description:

Certificate in PEM format used to encrypt files sent to the AS2 partner and to validate the received signed MDN.

You can define multiple PEM certificates for the case in which the partner uses different certificates for signing and encryption.

Old and new PEM certificates can be defined at the same time for a partner’s certificate rollover.

When sending encrypted files, the first configured PEM certificate will be used for the encryption operation.

4.17.12.9. as2_send_security

Default value:

‘signed-and-encrypted’

Optional:

yes

From version:

4.5.0

Values:
  • signed-and-encrypted
  • signed
  • encrypted
  • disabled
Description:

This defines the method used to secure the file transfers on top of the standard security provided by the HTTPS protocol.

When encrypting file content, the first certificate defined at as2_partner_certificates is used.

When signing file content, the digest/hashing algorithm defined in as2_signature_algorithm is used.

When defined as disabled, files are sent unsigned and unencrypted.

4.17.12.10. as2_mdn_receipt

Default value:

‘sync-signed’

Optional:

yes

From version:

4.5.0

Values:
  • sync-signed
  • sync-unsigned
  • disabled
Description:

This defines the method used to request the message disposition notifications (MDN) receipt.

When requesting a signed MDN, it will make the request using the digest/hashing algorithm defined in as2_signature_algorithm.

When defined as disabled, it will not request an MDN receipt.

4.17.12.11. as2_encryption_algorithm

Default value:

‘aes256’

Optional:

yes

From version:

4.5.0

Values:
  • 3des
  • aes128
  • aes192
  • aes256
Description:

Symmetric encryption algorithm used to encrypt sent files.

All algorithms use the Cipher Block Chaining (CBC) mode and PKCS#1 v1.5 padding.

4.17.12.12. as2_signature_algorithm

Default value:

‘sha256’

Optional:

yes

From version:

4.5.0

Values:
  • md5
  • sha1
  • sha224
  • sha256
  • sha348
  • sha512
Description:

Digest / Hashing algorithm used when signing sent files and requesting the MDN receipt.

4.17.12.13. as2_content_type

Default value:

‘application/octet-stream’

Optional:

Yes

From version:

4.5.0

Values:
  • MIME content type
Description:

MIME content type used when sending AS2 files.

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

4.17.12.15. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Certificate in PEM text format (Since 3.40.0).
  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

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

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.12.16. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on the local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.12.17. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.12.18. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.

  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.12.19. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
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.

Set it to Disabled, 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 ssl_certificate_authority is not enabled.

4.17.12.20. 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 ssl_certificate_authority is not enabled.

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

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.

4.17.12.22. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2 tlsv1.3

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
  • tlsv1.3
From version:

1.7.4

Description:

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

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.

4.17.13. Azure File Service Location

An azure-file location provides access over HTTPS to the Azure File Service of an Azure Storage account.

The files stored in Azure File Service shares are accessible via the SMB protocol and HTTP API. Azure Files is specifically a network file system. SFTPPlus will use the HTTPS-based API to manage the files.

The HTTPS connections will use the default list of secure ciphers and will accept TLS v1.0, TLS v1.1 and TLS v1.2 protocols.

Note

Unsecured HTTP access is not available.

Note

The current implementation is tested using General-purpose v2 (GPv2) accounts.

Only storage account names with access keys are currently supported. Please get in touch if you plan to use Azure Active Directory or shared access signatures.

The path / url to the Azure File storage is case-sensitive.

When using Azure File locations, the source or destination path will be defined as the name of the share (to or from where files are transferred) followed by the targeted directory inside that share. The path will look like /SHARE-NAME/DIR-IN-ROOT/PARENT-DIR.

The requests made by SFTPPlus to the Azure Storage server are done using the sftpplus-azure-file-UUID format. Where UUID is a unique identifier for this location. This can be used inside Azure Storage Analytics to identify the operations done by this location. The request ID will look like:

x-ms-client-request-id: sftpplus-azure-file-60ec1329-cc5d-416e-81b9-7c22

4.17.13.1. username

Default value:

‘’

Optional:

No

From version:

3.36.0

Values:
  • Text.
Description:

Name of the Azure Storage Account.

4.17.13.2. password

Default value:

‘’

Optional:

Yes

From version:

3.36.0

Values:
  • Plain text.
Description:

Any of the two access keys for the Azure storage account.

It should be specified in Base64 format. This is the default format presented by the Azure Portal.

4.17.14. SMB / Windows Share Location

An smb location provides access to an SMB version 3 (Server Message Block or Windows Share) server over TCP. This does not include access over UDP or version 1 or 2.

The location only requires configuring the server address and credentials. The actual share names and paths used for a file transfer are defined as part of the transfer path configuration.

The communication with the SMB server is encrypted and all messages are signed. Contact us if you need access to legacy Windows shares that don’t support encryption or message signing.

Warning

When accessing an Azure Files share authenticated using storage account key from outside the Azure cloud, it is highly recommended to secure your connection to the Azure cloud using private endpoints, site-to-site, or point-to-site VPN. Azure Files storage account key authentication is based on NTLM and is vulnerable to man-in-the-middle attacks.

Note

On-premises Active Directory Domain Services or Azure Active Directory Domain Services authentication methods via Kerberos are not yet supported.

4.17.14.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the server.
From version:

4.13.0

Description:

Address of the remote SSH server. IP or DNS name.

If you are using Azure Files the address will have the following format: ACCOUNT_NAME.file.core.windows.net where ACCOUNT_NAME is replaced with your Azure Storage account name.

4.17.14.2. port

Default value:

445

Optional:

No

Values:
  • Number, greater than 0.
From version:

4.13.0

Description:

Port number of the remote server.

4.17.14.3. username

Default value:

‘’

Optional:

No

From version:

4.13.0

Values:
  • Text.
Description:

Username or storage account name used to authenticate to the remote server.

Anonymous (guest) access is not yet supported. Contact us if you need support for connecting to a Windows Share without a username and password.

4.17.14.4. password

Default value:

‘’

Optional:

No

From version:

4.13.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password or key used to connect to the remote server. It is provided in plain text.