5.3.1. Introduction¶

Both the SFTP and the SCP protocols make use of the SSH protocol for low-level encryption of transferred data. Due to this, SFTPPlus uses a generic SSH service that provides support for both sftp and scp services. SFTP and SCP can be independently enabled.

Multiple SSH services can share the same set of RSA and DSA host keys.

5.3.2. Configuring SSH key-based authentication on the server¶

An account can have both password and SSH keys authentication methods enabled at the same time. At connection time, the SSH server and client will perform a negotiation step and the server will use only one method for authenticating the session.

Password authentication can be disabled for an account, in which case the server will force the client to use SSH keys for authentication.

An account is configured with one or many public SSH keys (a list). When the same account is used to connect from multiple machines, you will want to generate one pair of SSH keys for each machine, so that a private key never leaves the machine on which it is used.

For each account, there is an associated local file. It contains the public SSH keys, in OpenSSH public key format, accepted during the authentication.

To add a public key, you will have to copy the content of the public key from the file usually named KEY_NAME.pub and paste it on a new line into the file containing the list of allowed SSH keys.

There are two main approaches for configuring SSH keys for an account:

1. Only the server's administrators can manage the list of allowed SSH keys. In this case the file containing allowed SSH keys is stored somewhere outside the account's home folder.

2. Allow an account to have access to its own list of allowed SSH keys. Server administrators can still manage the list. The file with the list of allowed public SSH keys is stored inside the account's home folder. This is similar to OpenSSH configuration, where the list is stored in .ssh/authorized_keys file.

5.3.3. Web Manager GUI configuration¶

Configuring the list of authorized SSH keys for an Account:

Create a local file where public SSH keys associated with this account are stored. In our example, the file is located at c:\\Users\\sftp_access\\John_keys

Go to the account's configuration page and enter the path in the Allowed SSH Keys Path field.

For the above configuration, the account's home folder is in c:\\Users\\John and it has no access to manage its own SSH keys.

Configuring the list of authorized SSH keys for a Group:

Note that the path must contain the ${USER} value as a placeholder linking to the username.

In the example above, the file path included ${USER}. The text file equivalent:

[groups/bdfe8e48-5100-4d8a-bac1-441ebc04f9a7]
name = Support_Group
ssh_authorized_keys_path = /home/${USER}/.ssh/authorized_keys

In the above examples, the server will read the authorized SSH keys file located at /path_to/john/authorized_keys for a ${USER} called john.

If the path does not include the ${USER} value, it is appended at the end.

Therefore, a file path of /authorized_keys is read as /path_to/authorized_keys/john for a ${USER} called john.

5.3.4. Text file configuration¶

The ssh_authorized_keys_path option from the configuration file specifies the path to the file containing the list of allowed SSH RSA/DSA public keys for each user.

In text file configuration, the path can contain the ${USER} value:

[groups/DEFAULT_GROUP]
ssh_authorized_keys_path = /home/${USER}/.ssh/authorized_keys

When john is authenticated, the server will seek out the authorized SSH keys file /home/john/.ssh/authorized_keys/.

To disable SSH key-based authentication leave this value empty, as in the example below:

[groups/DEFAULT_GROUP]
ssh_authorized_keys_path =

Below you can find the list of available configuration options.

5.3.5. enabled¶

Default value:

Yes

Optional:

Yes

Values:

• Yes - to automatically start the service when the server is started.

• No - to leave the service stopped when the server is started.

From version:

1.6.0

Description:

When a service is not automatically started, it can still be manually started afterwards from the Web Manager.

5.3.6. name¶

Default value:

undefined-service-name

Optional:

No

Values:

• Any text.

From version:

2.0.0

Description:

Human-readable short string used to identify this service.

5.3.7. type¶

Default value:

''

Optional:

No

Values:

• ftp - for FTP and Explicit FTPS services.

• ftpsi - for Implicit FTPS services.

• ssh - for SSH services providing the SFTP and SCP protocols.

• http - for HTTP services.

• http-redirect - for HTTP Redirection services.

• https - for HTTPS services.

• monitor - for local file system monitor services.

• manager - for Web Manager services.

From version:

2.10.0

Description:

The main option which defines what protocol will be used for this service.

FTP and Explicit FTPS are using the same ftp protocol type, since both protocols can be served by the same service.

Note

The sftp option is also available for backward compatibility, and has the same effect as the ssh option.

5.3.8. address¶

Default value:

'127.0.0.1'

Optional:

No

Values:

• Host name resolving to an IPv4 address

• Fully qualified domain name resolving to an IPv4 address

• IPv4 address

• IPv6 address

• 0.0.0.0

From version:

1.7.0

Description:

Host name or IP used to listen for incoming connections.

To accept connections on all available IPv4 interfaces, use the 0.0.0.0 address.

To accept connections on all available IPv6 interfaces, use the :: address.

Note

On some operating systems (for example Linux) setting the address. to :: will listen to all available IPv6 and IPv4 addresses.

Note

This option is ignored for services of type monitor.

5.3.9. port¶

Default value:

''

Optional:

No

Values:

• Port number used for incoming connections.

From version:

1.7.0

Description:

To avoid conflicts between different services on the same local machine, this must be a unique port number. On Unix-like systems, a root account is usually required for using ports below 1024.

Note

This option is ignored for services of type monitor.

5.3.10. description¶

Default value:

''

Optional:

Yes

Values:

• Any text describing the role of this service.

From version:

1.8.0

Description:

This can be used for attaching notes to a service.

5.3.11. authentications¶

Default value:

''

Optional:

Yes

Values:

• Comma separated list of authentication UUIDs.

From version:

3.2.0

To version:

Description:

Comma-separated list of UUIDs for the authentication methods enabled for this service.

The list should be ordered by priority. The service will try to use the first authentication from the list, and continue with the following method if the user is not accepted.

If this configuration option is empty or is left out the global authentication methods are used.

Note

This configuration option is ignored for the monitor service as this service does not authenticate clients.

5.3.12. debug¶

Default value:

'No'

Optional:

Yes

Values:

• Yes

• No

From version:

3.48.0

Description:

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

Configuration changes are applied only to new connections. Existing connections respect the debug configuration in use when they were initiated.

Warning

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

5.3.13. idle_connection_timeout¶

Default value:

300

Optional:

Yes

Values:

• Positive number

From version:

1.7.19

Description:

This is defined as the number of seconds after which idle connections are disconnected.

The service will close the connection if a client connection is idle for a configurable amount of time. Any authenticated connections are automatically logged out.

When set to 0 or a negative number, it will use the default value.

5.3.14. maximum_concurrent_connections¶

Default value:

10000

Optional:

Yes

Values:

• Number of maximum concurrent connections accepted by the service.

• 0 - To disable the limit.

From version:

1.7.19

Description:

Maximum number of allowed concurrent connections for this service.

This limit is imposed by each service, and it is not a global limit for all services active on the server.

5.3.15. sftp¶

Default value:

Yes

Optional:

Yes

Values:

• No - To disable SFTP support.

• Yes - To enable SFTP support.

From version:

2.5.0

Description:

Enable/Disable support for the SFTP protocol.

5.3.16. scp¶

Default value:

No

Optional:

Yes

Values:

• No - To disable SCP support.

• Yes - To enable SCP support.

From version:

2.5.0

Description:

Enable/Disable support for the SCP protocol.

5.3.17. ssh_host_private_keys¶

Default value:

Empty

Optional:

Yes

Values:

• Absolute path on the local filesystem.

• Multiple absolute paths on the local filesystem, one per line.

• Text version of a SSH private key.

• Multiple concatenated SSH private keys in PEM format.

• Empty.

From version:

4.9.0

Description:

One or more SSH host private keys used by default for the SSH-based services (SFTP/SCP).

It can be one or more concatenated SSH private keys in PEM format.

It's important to start each line with at least one space character and keep the number of leading spaces constant:

[server/b904e6h6-c295-4ccf-8abd-edcae4d3324f]
name = SFTP Internal Server
type = sftp
rsa_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-----
    -----BEGIN DSA PRIVATE KEY-----
    H7yMbPk/vrhT5jkSDGIUdH+nG0OQpeSWcQXd4JJ6pqdJh/cw/havtxlHFp1yz
    MORE SSH KEY CONTENT
    OGZln2dLz/pkJkiRRzmsWgT2hUv/EK4NYRQq1kEAXLf3J6xZqLlR3ZBLJm
    -----END DSA PRIVATE KEY-----

For Putty keys, since they are not using a PEM format, only a single private key is supported. If you have to use multiple Putty keys here, convert them to a PEM format such as the OpenSSH one.

You can also configure it with one or more absolute paths on the local filesystem to files containing private SSH keys. One path per line.

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

5.3.18. dh_prime_size¶

Default value:

1024, ideal

Optional:

Yes

Values:

• Pair of comma-separated values: absolute minimum, preferred size.

From version:

3.46.0

Description:

This option controls the size of the prime number used during the Diffie-Hellman group exchange.

This is a single pair of comma-separated values.

The first value defines the absolute minimum size. The authentication will fail if the maximum remote peer is smaller than the minimum size.

The following sizes are supported:

• 1024

• 1536

• 2048

• 3072

• 4096

• 6144

• 8192

The second value defines the negotiated size used based on sizes announced by the client. The available are:

• minimum - Use the minimum value supported by the client and server.

• ideal - Use the ideal value advertised by the client.

• maximum - Use the maximum value supported by the client.

As an example, when this is configured as dh_prime_size = 2048, ideal and the client is advertising a minimum of 1024, an ideal value of 2048 and a maximum of 4086, the used value is 2048.

5.3.19. banner¶

Default value:

SFTPPlus

Optional:

Yes

Values:

• Any text message.

From version:

1.6.0

Description:

Message used by the service to welcome new SFTP client connections.

5.3.20. ignore_create_permissions¶

Default value:

No

Optional:

Yes

Values:

• No

• Yes

From version:

1.7.13

Description:

Some SFTP clients, like the OpenSSH SFTP client, will always preserve file and folder permissions and attributes even if -p option is not used in the client.

To work around this problem, the server can be configured to ignore the client request to set the permissions and attributes when creating a file or folder.

This also ignores setting the permissions and attributed for opened files, not only for opened files which were just created.

When permissions are ignored, the default file mode (666) is applied.

Before setting the permission, the configured umask value is first masked against the permissions.

Note

In the case in which you want to mirror the local permissions and attributes, use the SFTP client's dedicated command for setting the permissions.

5.3.21. ssh_cipher_list¶

Default value:

secure

Optional:

Yes

Values:

• List of accepted key exchanges, HMACs and cipher names.

• all

• secure

• fips

From version:

3.11.0

Description:

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

You can find all the names of the supported algorithms on SSH cryptography page.

The configuration must include at least one algorithm from each of:

• ciphers

• HMACs

• key exchanges

For example, to only allow AES256 in CTR mode with SHA256 HMAC hash and Diffie-Hellman group 14 key exchange with sha256 algorithms, the configuration is:

ssh_cipher_list = aes256-ctr, hmac-sha2-256, diffie-hellman-group14-sha256

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

We recommend using the latest version of SFTPPlus, for automatic enforcement of any newly-deprecated ciphers via the secure list.

When we update this list of algorithms to exclude any newly-deprecated ciphers, your SFTPPlus installations automatically enforce our changes when upgraded to a version that contains the updated secure list of algorithms.

The keyword all is available for configuring all the supported algorithms, including weak ciphers. This is provided mainly to help with backward compatibility.

Warning

Configuring all ciphers also enables ciphers 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 fails 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.