How to use SFTP (introduction)

SSHFTPClient should be used when secure file transfers are required via SFTP. FTPClient and ProFTPClient do not support secure transfers. SSLFTPClient supports the FTPS protocol, which is unrelated to SFTP.

To run the examples on Windows, you can download a free trial of CompleteFTP, a Windows SFTP server, from this link. CompleteFTP also supports FTPS.

The basic elements of configuring an SFTP connection are:

Server Validation: Ensuring the SSH server is validated is an important issue in SFTP. By default an attempt will be made to validate the server using the client's local store of server public keys. Typically, the server's public key is stored in either a file containing that single key, or in a file often called known_hosts which can contain a number of public keys for different servers. When the client connects to the server, the server's public key is returned and compared with the available public keys stored in the client.
Client Authentication: Clients are authenticated by either username and password, or private key and private key passphrase. In the first case, the user requires an account on the server that is set up for SFTP access. In the second case, the user's public key must be registered with the server (typically by copying it into an authorized_keys file on the server), and the user's private key must be loaded by the client. A third method known as keyboard-interactive authentication is also supported.

Validation of Server Public Keys

Usage of server validation is strongly recommended since it virtually eliminates the possibility of communicating with the wrong server. While developing code, however, the programmer might like to postpone any possible validation issues by disabling server validation. Note that server validation should never be disabled on production systems.

All operations related to server validation are delegated to an instance of SSHFTPValidator (or a subclass thereof). This instance maintains a list of server public keys that are authorized. It can be accessed through the SSHFTPClient.getValidator() method.

To disable server validation, see How to use SFTP (without server validation).

By default server validation is enabled. This means that the server's public key must added to the validator's local store of public keys for a connection to be successful.

There are two ways that the client can load server public keys into the validator's store - via the known_hosts file or by explicitly loading a public key from a file.

Client Authentication

The most commonly used forms of client authentication are by username/password or by public/private keys. Note that some SFTP servers are set up to disallow password authentication by default, in which case username/password connection attempts will fail unless password authentication is enabled in the server configuration file.

For details on each method of client authentication, see:

Keypair Generation

See How to use SFTP (keypair generation) for details on generating SSH keypairs for use in SFTP.