Documentation

5.3. SSH (SFTP and SCP)

This page describes the configuration options available for the SSH service, using SFTP and SCP file transfer protocols.

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.

Note

There is no restriction to having an 1:1 relation between an account and the list of public SSH keys. The same list (i.e. same local file) can be associated with multiple accounts.

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

../_images/Accounts-Allowed-SSH-Keys.png

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.

../_images/Groups-Allowed-SSH-Keys.png

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.

Warning

Make sure that the file path is set correctly, otherwise the server will fail to read the authorized SSH keys file and issue a No such file or directory error.

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

To version

None

Description

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

5.3.6. name

Default value

undefined-service-name

Optional

No

Values

  • Any text.

From version

2.0.0

To version

None

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 Local Manager services.

From version

2.10.0

To version

None

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

To version

None

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

To version

None

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

To version

None

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

To version

None

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

To version

None

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

To version

None

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.

When the configured RSA or DSA keys are encrypted, the values configured in rsa_private_key_password or dsa_private_key_password are used to decrypt those keys.

5.3.18. rsa_private_key_password

Default value

Empty

Optional

Yes

Values

  • Password for the RSA private key as text.

From version

1.7.19

To version

None

Description

The password is used for decrypting the stored RSA private key, in the case that it is stored encrypted on disk.

This option will be removed in a future V5 release.

5.3.19. dsa_private_key_password

Default value

Empty

Optional

Yes

Values

  • Password for the DSA private key as text.

From version

1.7.19

Description

The password is used for decrypting the stored DSA private key, in the case that it is stored encrypted on disk.

This option will be removed in a future V5 release.

5.3.20. 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.22. ignore_create_permissions

Default value

No

Optional

Yes

Values

  • No

  • Yes

From version

1.7.13

To version

None

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

To version

None

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.

5.2. FTP / Explicit FTPS / Implicit FTPS
5.4. HTTP / HTTPS