com.enterprisedt.net.ftp.ssh
Class SCPClient

java.lang.Object
  com.enterprisedt.net.ftp.ssh.SCPClient

Direct Known Subclasses:

SSHFTPClient

public class SCPClient
extends java.lang.Object

SCPClient implements SCP (SSH secure copy).

Connections are established when the connect() is invoked. Before it is called, the remote host must be defined, and host verification and client authentication should be configured.

Host Validation is the process of verifying that a host that is being connected to is the host that was requested. Host validation is done through an instance of SSHFTPValidator or a subclass thereof. By default, SCPClient, has an instance of this class that is available by means of the getValidator() method. Unless specialized validation functionality is required, initialization of validation functionality may be done simply by invoking methods on this object.

There are four approaches to setting up host validation:

1. Disabling host validation. In general this represents a security weakness and should therefore be used only when testing code. This mode is selected as follows:

      ftpClient.getValidator().setHostValidationEnabled(false); 
    

2. Initialize from a hosts file: A list of known hosts and their public keys are loaded from a file. The format of the file is similar to that used in OpenSSH. Each line contains the name of a host, the type of key it has, and its key (in base-64 printable form). For example:

    jackspc ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIE...
    

   If there are more than one host using a given key the host-name may be replaced by a comma-separated list of host-names. Wildcards may not be used. A host-file is loaded as follows:

      ftpClient.getValidator().loadKnownHosts("~/.ssh/known_hosts");
    

3. Initialize programmatically: Host public keys may be loaded from individual files as follows:

      ftpClient.getValidator().addKnownHost("host1pk.pub");
      ftpClient.getValidator().addKnownHost("host2pk.pub");
    

   Public keys should be in OpenSSH or SECSH format.

Client Authentication is the method used by the server to authenticate clients. Different servers will enforce different policies for authenticating clients. SCPClient currently offers two authentication methods:

1. User-name/Password Authentication involves simply passing a user-name/password to the server for authentication. This is set up simply by by calling setAuthentication as follows:

      ftpClient.setAuthentication("jack", "my_ftp_password");
    

2. Public Key Authentication involves using a private/public key pair to authenticate the client. The key pair must be in a file in OpenSSH or SECSH format and the name is passed as follows:

      ftpClient.setAuthentication("myprivatekey", "jack", "my_keyfile_password");
    

   The user-name is the name of the user on the SFTP server, but the passphrase is the password for the key-file (if there is a password).

Version:

$Revision: 1.5 $

Author:

Bruce Blackshaw

Field Summary

protected com.enterprisedt.net.j2ssh.authentication.SshAuthenticationClient	authenticator J2SSH authenticator.
protected com.enterprisedt.net.j2ssh.configuration.SshConnectionProperties	connProps J2SSH SshConnectionProperties instance.
static int	DEFAULT_PORT Default SSH port.
protected int	deleteCount Count of deleted files
protected int	downloadCount Count of downloaded files
protected com.enterprisedt.util.license.EDTProduct	expectedProduct The expected product contained in our license
protected java.lang.String	id Id of instance
protected com.enterprisedt.util.license.LicensePropertiesBase	license The license details
protected com.enterprisedt.net.j2ssh.authentication.SshAuthenticationClient	retryAuthenticator J2SSH authenticator.
protected com.enterprisedt.net.j2ssh.SshClient	ssh J2SSH SshClient instance.
protected int	uploadCount Count of uploaded files
protected SSHFTPValidator	validator Encapsulation and extension of J2SSH AbstractKnownHostsKeyVerification.

Constructor Summary

SCPClient()
Constructs an SCP client.

Method Summary

protected void	checkConnection(boolean shouldBeConnected) Checks if the client has connected to the server and throws an exception if it hasn't.
void	connect() Connects to the server at the address and port number defined in the constructor.
boolean	connected() Is the client currently connected?
protected void	connectSSH() Connects to the server at the address and port number defined in the constructor.
void	disableAllAlgorithms() Disables all algorithms.
void	disableAllAlgorithms(int algorithmType) Disables all algorithms of a particular type.
java.lang.String	executeCommand(java.lang.String command) Execute a command on the remote server.
void	get(java.lang.String localPath, java.lang.String remoteFile) Download a file
int	getDeleteCount() Get the number of files deleted since the count was reset
int	getDownloadCount() Get the number of files downloaded since the count was reset
SSHFTPAlgorithm[]	getEnabledAlgorithms() Returns an array containing all enabled algorithms (of all types).
SSHFTPAlgorithm[]	getEnabledAlgorithms(int algorithmType) Returns an array containing all enabled algorithms of a particular type.
SSHFTPPublicKey	getHostPublicKey() Provides access to the current server's public key.
static SSHFTPPublicKey	getHostPublicKey(java.lang.String remoteHost) Helper method that may be used to obtain a server's public key without instantiating an SCPClient.
static SSHFTPPublicKey	getHostPublicKey(java.lang.String remoteHost, int remotePort) Helper method that may be used to obtain a server's public key without instantiating an SCPClient.
java.lang.String	getId() Get the identifying string for this instance
java.lang.String	getRemoteHost()
int	getRemotePort() Returns the SSH port of the remote host.
int	getTimeout()
int	getTransportProvider() Get the currently set transport provider
int	getUploadCount() Get the number of files uploaded since the count was reset
SSHFTPValidator	getValidator() Returns a reference to the current host validator.
boolean	isAlgorithmEnabled(SSHFTPAlgorithm algorithm) Returns true if the given algorithm is enabled.
java.lang.String	put(java.lang.String localPath, java.lang.String remoteFile) Upload a file.
void	quit()
void	quitImmediately()
void	resetDeleteCount() Reset the count of deleted files to zero.
void	resetDownloadCount() Reset the count of downloaded files to zero.
void	resetUploadCount() Reset the count of uploaded files to zero.
void	setAlgorithmEnabled(SSHFTPAlgorithm algorithm, boolean enable) Enable/disable the given algorithm.
void	setAuthentication(java.io.InputStream inStr, java.lang.String userName, java.lang.String keyFilePassphrase) Set up the SFTP client to authenticate using a private/public key-pair.
void	setAuthentication(java.lang.String user, SSHAuthPrompt[] prompts) Set up keyboard-interactive (KBI) authentication by supplying an array of responses to possible prompts by the SSH server
void	setAuthentication(java.lang.String userName, java.lang.String password) Set up user-name/password authentication.
void	setAuthentication(java.lang.String keyFileName, java.lang.String userName, java.lang.String keyFilePassphrase) Set up the SFTP client to authenticate using a private/public key-pair.
void	setAuthentication(java.lang.String keyFileName, java.lang.String userName, java.lang.String keyFilePassphrase, java.lang.String userPassword) Set up the SFTP client to authenticate using a private/public key-pair, followed by password authentication.
void	setId(java.lang.String id) Set the identifying string for this instance
void	setProxyParams(ProxyParameters params) Setup the parameters required for using a proxy
void	setRemoteHost(java.lang.String remoteHost)
void	setRemotePort(int port) Set the SSH port of the remote host.
void	setTimeout(int millis)
void	setTransportProvider(int provider) Set the type of transport provider to use.
void	setValidator(SSHFTPValidator validator) Sets the host validator.
java.lang.String	system() Get a string representing the remote system.
java.lang.String	toString() String representation
protected void	validateAlgorithms() Check to see if at least one of each type of algorithm is enabled.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT

Default SSH port.

See Also:

Constant Field Values

ssh

protected com.enterprisedt.net.j2ssh.SshClient ssh

J2SSH SshClient instance.

connProps

protected com.enterprisedt.net.j2ssh.configuration.SshConnectionProperties connProps

J2SSH SshConnectionProperties instance.

validator

protected SSHFTPValidator validator

Encapsulation and extension of J2SSH AbstractKnownHostsKeyVerification.

authenticator

protected com.enterprisedt.net.j2ssh.authentication.SshAuthenticationClient authenticator

J2SSH authenticator.

retryAuthenticator

protected com.enterprisedt.net.j2ssh.authentication.SshAuthenticationClient retryAuthenticator

J2SSH authenticator.

id

protected java.lang.String id

Id of instance

downloadCount

protected int downloadCount

Count of downloaded files

uploadCount

protected int uploadCount

Count of uploaded files

deleteCount

protected int deleteCount

Count of deleted files

expectedProduct

protected final com.enterprisedt.util.license.EDTProduct expectedProduct

The expected product contained in our license

license

protected com.enterprisedt.util.license.LicensePropertiesBase license

The license details

Constructor Detail

SCPClient

public SCPClient()

Constructs an SCP client. The class description describes how to use the SCP client to obtain a connection with a remote host.

Method Detail

getId

public java.lang.String getId()

Get the identifying string for this instance

setId

public void setId(java.lang.String id)

Set the identifying string for this instance

Parameters:

id - identifying string

system

public java.lang.String system()
                        throws FTPException,
                               java.io.IOException

Get a string representing the remote system.

Returns:

system string

Throws:

FTPException

java.io.IOException

getDownloadCount

public int getDownloadCount()

Get the number of files downloaded since the count was reset

Returns:

download file count

resetDownloadCount

public void resetDownloadCount()

Reset the count of downloaded files to zero.

getUploadCount

public int getUploadCount()

Get the number of files uploaded since the count was reset

Returns:

upload file count

resetUploadCount

public void resetUploadCount()

Reset the count of uploaded files to zero.

getDeleteCount

public int getDeleteCount()

Get the number of files deleted since the count was reset

Returns:

deleted file count

resetDeleteCount

public void resetDeleteCount()

Reset the count of deleted files to zero.

getValidator

public SSHFTPValidator getValidator()

Returns a reference to the current host validator. By default this is an instance of SSHFTPValidator. If customized host validation is required then setValidator() should be used to set up the client to use a subclass of SCPClient.

Returns:

Returns the host validator.

setValidator

public void setValidator(SSHFTPValidator validator)
                  throws FTPException

Sets the host validator. By default this is set to an instance of SCPClient. If customized host validation is required then this method should be used to set up the client to use a subclass of SCPClient.

Parameters:

validator - The host validator to set.

Throws:

FTPException

getHostPublicKey

public static SSHFTPPublicKey getHostPublicKey(java.lang.String remoteHost)
                                        throws FTPException

Helper method that may be used to obtain a server's public key without instantiating an SCPClient. This method returns an SSHFTPPublicKey object whose SSHFTPPublicKey.write(OutputStream, int) method may be used to write the public key to a file. The method will return null if a public key could not be retrieved. Logging may be used to discover any connection problems. If more advanced settings are required then an instance of SCPClient should be used.

Parameters:

remoteHost - Address of the server whose public key is to be fetched.

Returns:

An instance of SSHFTPPublicKey representing

Throws:

FTPException

getHostPublicKey

public static SSHFTPPublicKey getHostPublicKey(java.lang.String remoteHost,
                                               int remotePort)
                                        throws FTPException

Helper method that may be used to obtain a server's public key without instantiating an SCPClient. This method returns an SSHFTPPublicKey object SSHFTPPublicKey.write(OutputStream,int) method may be used to write the public key to a file. The method will return null if a public key could not be retrieved. Logging may be used to discover any connection problems. If more advanced settings are required then an instance of SCPClient should be used.

Parameters:

remoteHost - Address of the server whose public key is to be fetched.

remotePort - Port of the server whose public key is to be fetched.

Returns:

An instance of SSHFTPPublicKey representing

Throws:

FTPException

getHostPublicKey

public SSHFTPPublicKey getHostPublicKey()

Provides access to the current server's public key. This member is only valid after an attempt has been made to connect to the server. It is null before the first connection attempt is made.

This method is particularly useful if the server's public key is not available by other means. In such cases a connection attempt should be made without adding any known hosts. This attempt will fail, but getHostPublicKey() may be used afterwards to obtain the public key. The SSHFTPPublicKey.write(OutputStream,int) method may be used to write it to a file for use in subsequent connections.

Note that null may be returned after a connection attempt is made if the attempt failed before public keys were exchanged between the client and the server.

Returns:

Returns the server's public key.

setAuthentication

public void setAuthentication(java.lang.String userName,
                              java.lang.String password)
                       throws FTPException

Set up user-name/password authentication. The user-name and password must be recognized by the SFTP server. This method must be called before an attempt to connect to the SFTP server is made (i.e. before the connect method is invoked). This method first attempts to use password authentication, and if that fails, falls back to keyboard-interactive authentication via password

Parameters:

userName - User-name as set up on the SFTP server.

password - Password as set up on the SFTP server.

Throws:

FTPException - Thrown if an SFTP-related error occurs.

setAuthentication

public void setAuthentication(java.lang.String user,
                              SSHAuthPrompt[] prompts)
                       throws FTPException

Set up keyboard-interactive (KBI) authentication by supplying an array of responses to possible prompts by the SSH server

Parameters:

user - user to login as

prompts - prompt responses supplied to pass the server authentication prompts

Throws:

FTPException

setAuthentication

public void setAuthentication(java.lang.String keyFileName,
                              java.lang.String userName,
                              java.lang.String keyFilePassphrase)
                       throws java.io.IOException,
                              FTPException

Set up the SFTP client to authenticate using a private/public key-pair. The private key is loaded from a file. The SFTP server must have been set up with the public key before this authentication method is used. This method must be called before an attempt to connect to the SFTP server is made (i.e. before the connect method is invoked).

The key-file can be in either OpenSSH format (generated by default by ssh-keygen) or SECSH format.

The file may or may not be password protected depending on how it was generated.

Parameters:

keyFileName - File containing the private key.

userName - User-name as set up on the server.

keyFilePassphrase - (Optional) Key-file passphrase.

Throws:

java.io.IOException - Thrown if the key-file could not be read.

SSHFTPException - Thrown if an SFTP-related error occurred.

FTPException

setAuthentication

public void setAuthentication(java.io.InputStream inStr,
                              java.lang.String userName,
                              java.lang.String keyFilePassphrase)
                       throws java.io.IOException,
                              FTPException

Set up the SFTP client to authenticate using a private/public key-pair. The private key is loaded from an input-stream. The SFTP server must have been set up with the public key before this authentication method is used. This method must be called before an attempt to connect to the SFTP server is made (i.e. before the connect method is invoked).

The key-file can be in either OpenSSH format (generated by default by ssh-keygen) or SECSH format.

The file may or may not be password protected depending on how it was generated.

Parameters:

inStr - InputStream containing the private key.

userName - User-name as set up on the server.

keyFilePassphrase - (Optional) Key-file passphrase.

Throws:

java.io.IOException - Thrown if the key-file could not be read.

SSHFTPException - Thrown if an SFTP-related error occurred.

FTPException

setAuthentication

public void setAuthentication(java.lang.String keyFileName,
                              java.lang.String userName,
                              java.lang.String keyFilePassphrase,
                              java.lang.String userPassword)
                       throws java.io.IOException,
                              FTPException

Set up the SFTP client to authenticate using a private/public key-pair, followed by password authentication. The private key is loaded from a file. The SFTP server must have been set up with the public key before this authentication method is used. This method must be called before an attempt to connect to the SFTP server is made (i.e. before the connect method is invoked).

The key-file can be in either OpenSSH format (generated by default by ssh-keygen) or SECSH format.

The file may or may not be password protected depending on how it was generated.

Parameters:

keyFileName - File containing the private key.

userName - User-name as set up on the server.

keyFilePassphrase - (Optional) Key-file passphrase.

userPassword - User's password

Throws:

java.io.IOException - Thrown if the key-file could not be read.

SSHFTPException - Thrown if an SFTP-related error occurred.

FTPException

validateAlgorithms

protected void validateAlgorithms()
                           throws SSHFTPException

Check to see if at least one of each type of algorithm is enabled.

Throws:

SSHFTPException - Thrown if one algorithm-type has no enabled algorithms.

getEnabledAlgorithms

public SSHFTPAlgorithm[] getEnabledAlgorithms()

Returns an array containing all enabled algorithms (of all types).

Returns:

An array of all enabled algorithms.

getEnabledAlgorithms

public SSHFTPAlgorithm[] getEnabledAlgorithms(int algorithmType)
                                       throws SSHFTPException

Returns an array containing all enabled algorithms of a particular type.

Parameters:

algorithmType - Type of algorithms to return (See SSHFTPAlgorithm).

Returns:

An array of all enabled algorithms of the given type.

Throws:

SSHFTPException - Thrown if the given algorithm-type is invalid.

disableAllAlgorithms

public void disableAllAlgorithms(int algorithmType)
                          throws SSHFTPException

Disables all algorithms of a particular type. Note that one algorithm of each type must be enabled before you can connect to a server.

Parameters:

algorithmType - Type of algorithms to return (See SSHFTPAlgorithm).

Throws:

SSHFTPException

disableAllAlgorithms

public void disableAllAlgorithms()

Disables all algorithms. Note that one algorithm of each type must be enabled before you can connect to a server.

setAlgorithmEnabled

public void setAlgorithmEnabled(SSHFTPAlgorithm algorithm,
                                boolean enable)

Enable/disable the given algorithm.

Parameters:

algorithm - Algorithm to enable/disable.

enable - Flag indicating whether the algorithm should be enabled or disabled.

isAlgorithmEnabled

public boolean isAlgorithmEnabled(SSHFTPAlgorithm algorithm)

Returns true if the given algorithm is enabled.

Parameters:

algorithm - Algorithm to return status of.

getRemoteHost

public java.lang.String getRemoteHost()

setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws FTPException

Throws:

FTPException

getRemotePort

public int getRemotePort()

Returns the SSH port of the remote host. The default is 22.

Returns:

Returns the SSH port of the remote host.

setRemotePort

public void setRemotePort(int port)
                   throws FTPException

Set the SSH port of the remote host. This may only be done if the client is not already connected to the server. The default is 22.

Parameters:

port - The port to set.

Throws:

FTPException - Thrown if the client is already connected to the server.

setProxyParams

public void setProxyParams(ProxyParameters params)

Setup the parameters required for using a proxy

Parameters:

params - parameter object

setTransportProvider

public void setTransportProvider(int provider)

Set the type of transport provider to use. Default is standard sockets

Parameters:

provider - provider integer

getTransportProvider

public int getTransportProvider()

Get the currently set transport provider

Returns:

int

getTimeout

public int getTimeout()

setTimeout

public void setTimeout(int millis)
                throws FTPException

Throws:

FTPException

connect

public void connect()
             throws java.io.IOException,
                    FTPException

Connects to the server at the address and port number defined in the constructor. Please refer to the class description for information on configuration steps that must be taken before this method is called.

Throws:

java.io.IOException - Thrown if there is a TCP/IP-related error.

FTPException - Thrown if client is already connected or if there is a configuration error, or if a connection could not be established.

connectSSH

protected void connectSSH()
                   throws java.io.IOException,
                          FTPException

Connects to the server at the address and port number defined in the constructor. Please refer to the class description for information on configuration steps that must be taken before this method is called.

Throws:

java.io.IOException - Thrown if there is a TCP/IP-related error.

FTPException - Thrown if client is already connected or if there is a configuration error, or if a connection could not be established.

executeCommand

public java.lang.String executeCommand(java.lang.String command)
                                throws FTPException,
                                       java.io.IOException

Execute a command on the remote server. This opens a new session channel to execute the command.

Parameters:

command - command to execute

Returns:

string with the command output

Throws:

FTPException

java.io.IOException

checkConnection

protected void checkConnection(boolean shouldBeConnected)
                        throws FTPException

Checks if the client has connected to the server and throws an exception if it hasn't. This is only intended to be used by subclasses

Throws:

FTPException - Thrown if the client has not connected to the server.

connected

public boolean connected()

Is the client currently connected?

Returns:

true if connected, false otherwise

put

public java.lang.String put(java.lang.String localPath,
                            java.lang.String remoteFile)
                     throws java.io.IOException,
                            FTPException

Upload a file.

Parameters:

localPath - path of local file to be uploaded

remoteFile - path of remote file to upload to

Throws:

java.io.IOException

FTPException

get

public void get(java.lang.String localPath,
                java.lang.String remoteFile)
         throws java.io.IOException,
                FTPException

Download a file

Parameters:

localPath - path of local file to download to

remoteFile - path of remote file

Throws:

java.io.IOException

FTPException

quit

public void quit()
          throws java.io.IOException,
                 FTPException

Throws:

java.io.IOException

FTPException

quitImmediately

public void quitImmediately()
                     throws java.io.IOException,
                            FTPException

Throws:

java.io.IOException

FTPException

toString

public java.lang.String toString()

String representation

Overrides:

toString in class java.lang.Object