Package net.schmizz.sshj
Class SSHClient
- java.lang.Object
-
- net.schmizz.sshj.SocketClient
-
- net.schmizz.sshj.SSHClient
-
- All Implemented Interfaces:
RemoteAddressProvider
,java.io.Closeable
,java.lang.AutoCloseable
,SessionFactory
public class SSHClient extends SocketClient implements java.io.Closeable, SessionFactory
Secure SHell client API. Before connection is established, host key verification needs to be accounted for. This is done byspecifying
one or moreHostKeyVerifier
objects. Database of known hostname-key pairs in the OpenSSH"known_hosts"
format can beloaded
for host key verification. User authentication can be performed by any of theauth*()
method.startSession()
caters to the most typical use case of starting asession
channel and executing a remote command, starting a subsystem, etc. If you wish to request X11 forwarding for some session, firstregister
aConnectListener
forx11
channels.Local
andremote
port forwarding is possible. There are also utility method for easily creatingSCP
andSFTP
implementations. A simple example:final SSHClient client = new SSHClient(); client.loadKnownHosts(); client.connect("hostname"); try { client.authPassword("username", "password"); final Session session = client.startSession(); try { final Command cmd = session.exec("true"); cmd.join(1, TimeUnit.SECONDS); } finally { session.close(); } } finally { client.disconnect(); }
Where a password or passphrase is required, if you're extra-paranoid use thechar[]
based method. Thechar[]
will be blanked out after use.
-
-
Field Summary
Fields Modifier and Type Field Description protected UserAuth
auth
ssh-userauth
serviceprotected Connection
conn
ssh-connection
servicestatic int
DEFAULT_PORT
Default port for SSHprotected org.slf4j.Logger
log
protected LoggerFactory
loggerFactory
Loggerprotected java.nio.charset.Charset
remoteCharset
character set of the remote machineprotected Transport
trans
Transport layer
-
Method Summary
Modifier and Type Method Description void
addAlgorithmsVerifier(AlgorithmsVerifier verifier)
Add aAlgorithmsVerifier
which will be invoked for verifying negotiated algorithms.void
addHostKeyVerifier(java.lang.String fingerprint)
Add aHostKeyVerifier
that will verify any host that's able to claim a host key with the givenfingerprint
.void
addHostKeyVerifier(HostKeyVerifier verifier)
Add aHostKeyVerifier
which will be invoked for verifying host key during connection establishment and future key exchanges.void
auth(java.lang.String username, java.lang.Iterable<AuthMethod> methods)
Authenticateusername
using the suppliedmethods
.void
auth(java.lang.String username, AuthMethod... methods)
Authenticateusername
using the suppliedmethods
.void
authGssApiWithMic(java.lang.String username, javax.security.auth.login.LoginContext context, org.ietf.jgss.Oid supportedOid, org.ietf.jgss.Oid... supportedOids)
Authenticateusername
using the"gssapi-with-mic"
authentication method, given a login context for the peer GSS machine and a list of supported OIDs.void
authPassword(java.lang.String username, char[] password)
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication..void
authPassword(java.lang.String username, java.lang.String password)
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.void
authPassword(java.lang.String username, PasswordFinder pfinder)
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.void
authPassword(java.lang.String username, PasswordFinder pfinder, PasswordUpdateProvider newPasswordProvider)
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.void
authPublickey(java.lang.String username)
Authenticateusername
using the"publickey"
authentication method, with keys from some common locations on the file system.void
authPublickey(java.lang.String username, java.lang.Iterable<KeyProvider> keyProviders)
Authenticateusername
using the"publickey"
authentication method.void
authPublickey(java.lang.String username, java.lang.String... locations)
Authenticateusername
using the"publickey"
authentication method, with keys from one or morelocations
in the file system.void
authPublickey(java.lang.String username, KeyProvider... keyProviders)
Authenticateusername
using the"publickey"
authentication method.void
close()
Same asdisconnect()
.void
disconnect()
Disconnects from the connected SSH server.protected void
doKex()
Do key exchange.Connection
getConnection()
java.nio.charset.Charset
getRemoteCharset()
Returns the character set used to communicate with the remote machine for certain strings (like paths).RemotePortForwarder
getRemotePortForwarder()
java.net.InetSocketAddress
getRemoteSocketAddress()
Get Remote Socket Address from TransportTransport
getTransport()
UserAuth
getUserAuth()
boolean
isAuthenticated()
boolean
isConnected()
KeyProvider
loadKeys(java.lang.String location)
Returns aKeyProvider
instance created from a location on the file system where an unencrypted private key file (does not require a passphrase) can be found.KeyProvider
loadKeys(java.lang.String location, char[] passphrase)
Utility function for creating aKeyProvider
instance from given location on the file system.KeyProvider
loadKeys(java.lang.String location, java.lang.String passphrase)
Convenience method for creating aKeyProvider
instance from alocation
where an encrypted key file is located.KeyProvider
loadKeys(java.lang.String privateKey, java.lang.String publicKey, PasswordFinder passwordFinder)
Creates aKeyProvider
instance from passed strings.KeyProvider
loadKeys(java.lang.String location, PasswordFinder passwordFinder)
Creates aKeyProvider
instance from given location on the file system.KeyProvider
loadKeys(java.security.KeyPair kp)
Creates aKeyProvider
from suppliedKeyPair
.void
loadKnownHosts()
Attempts loading the user'sknown_hosts
file from the default locations, i.e.void
loadKnownHosts(java.io.File location)
Adds aOpenSSHKnownHosts
object created from the specified location as a host key verifier.DirectConnection
newDirectConnection(java.lang.String hostname, int port)
Create aDirectConnection
channel that connects to a remote address from the server.LocalPortForwarder
newLocalPortForwarder(Parameters parameters, java.net.ServerSocket serverSocket)
Create aLocalPortForwarder
that will listen based onparameters
using the boundserverSocket
and forward incoming connections to the server; which will further forward them tohost:port
.SCPFileTransfer
newSCPFileTransfer()
SFTPClient
newSFTPClient()
StatefulSFTPClient
newStatefulSFTPClient()
Stateful FTP client is required in order to connect to Serv-U FTP servers.protected void
onConnect()
On connection establishment, also initializes the SSH transport viaTransport.init(java.lang.String, int, java.io.InputStream, java.io.OutputStream)
anddoKex()
.X11Forwarder
registerX11Forwarder(ConnectListener listener)
Register alistener
for handling forwarded X11 channels.void
rekey()
Does key re-exchange.void
setRemoteCharset(java.nio.charset.Charset remoteCharset)
Sets the character set used to communicate with the remote machine for certain strings (like paths)Session
startSession()
Opens asession
channel.void
useCompression()
Addszlib
compression to preferred compression algorithms.-
Methods inherited from class net.schmizz.sshj.SocketClient
connect, connect, connect, connect, connect, connect, connectVia, connectVia, getConnectTimeout, getLocalAddress, getLocalPort, getRemoteAddress, getRemoteHostname, getRemotePort, getSocket, getSocketFactory, getTimeout, makeInetSocketAddress, setConnectTimeout, setSocketFactory, setTimeout
-
-
-
-
Field Detail
-
DEFAULT_PORT
public static final int DEFAULT_PORT
Default port for SSH- See Also:
- Constant Field Values
-
loggerFactory
protected final LoggerFactory loggerFactory
Logger
-
log
protected final org.slf4j.Logger log
-
trans
protected final Transport trans
Transport layer
-
auth
protected final UserAuth auth
ssh-userauth
service
-
conn
protected final Connection conn
ssh-connection
service
-
remoteCharset
protected java.nio.charset.Charset remoteCharset
character set of the remote machine
-
-
Constructor Detail
-
SSHClient
public SSHClient()
Default constructor. Initializes this object usingDefaultConfig
.
-
-
Method Detail
-
addHostKeyVerifier
public void addHostKeyVerifier(HostKeyVerifier verifier)
Add aHostKeyVerifier
which will be invoked for verifying host key during connection establishment and future key exchanges.- Parameters:
verifier
-HostKeyVerifier
instance
-
addAlgorithmsVerifier
public void addAlgorithmsVerifier(AlgorithmsVerifier verifier)
Add aAlgorithmsVerifier
which will be invoked for verifying negotiated algorithms.- Parameters:
verifier
-AlgorithmsVerifier
instance
-
addHostKeyVerifier
public void addHostKeyVerifier(java.lang.String fingerprint)
Add aHostKeyVerifier
that will verify any host that's able to claim a host key with the givenfingerprint
. The fingerprint can be specified in either an MD5 colon-delimited format (16 hexadecimal octets, delimited by a colon), or in a Base64 encoded format for SHA-1 or SHA-256 fingerprints. Valid examples are:- "SHA1:2Fo8c/96zv32xc8GZWbOGYOlRak="
- "SHA256:oQGbQTujGeNIgh0ONthcEpA/BHxtt3rcYY+NxXTxQjs="
- "MD5:d3:5e:40:72:db:08:f1:6d:0c:d7:6d:35:0d:ba:7c:32"
- "d3:5e:40:72:db:08:f1:6d:0c:d7:6d:35:0d:ba:7c:32"
- Parameters:
fingerprint
- expected fingerprint in colon-delimited format (16 octets in hex delimited by a colon)- See Also:
SecurityUtils.getFingerprint(java.security.PublicKey)
-
auth
public void auth(java.lang.String username, AuthMethod... methods) throws UserAuthException, TransportException
Authenticateusername
using the suppliedmethods
.- Parameters:
username
- user to authenticatemethods
- one or more authentication method- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
auth
public void auth(java.lang.String username, java.lang.Iterable<AuthMethod> methods) throws UserAuthException, TransportException
Authenticateusername
using the suppliedmethods
.- Parameters:
username
- user to authenticatemethods
- one or more authentication method- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPassword
public void authPassword(java.lang.String username, java.lang.String password) throws UserAuthException, TransportException
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.- Parameters:
username
- user to authenticatepassword
- the password to use for authentication- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPassword
public void authPassword(java.lang.String username, char[] password) throws UserAuthException, TransportException
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.. Thepassword
array is blanked out after use.- Parameters:
username
- user to authenticatepassword
- the password to use for authentication- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPassword
public void authPassword(java.lang.String username, PasswordFinder pfinder) throws UserAuthException, TransportException
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.- Parameters:
username
- user to authenticatepfinder
- thePasswordFinder
to use for authentication- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPassword
public void authPassword(java.lang.String username, PasswordFinder pfinder, PasswordUpdateProvider newPasswordProvider) throws UserAuthException, TransportException
Authenticateusername
using the"password"
authentication method and as a fallback basic challenge-response authentication.- Parameters:
username
- user to authenticatepfinder
- thePasswordFinder
to use for authenticationnewPasswordProvider
- thePasswordUpdateProvider
to use when a new password is being requested from the user.- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPublickey
public void authPublickey(java.lang.String username) throws UserAuthException, TransportException
Authenticateusername
using the"publickey"
authentication method, with keys from some common locations on the file system. This method relies on~/.ssh/id_rsa
and~/.ssh/id_dsa
. This method does not provide a way to specify a passphrase.- Parameters:
username
- user to authenticate- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPublickey
public void authPublickey(java.lang.String username, java.lang.Iterable<KeyProvider> keyProviders) throws UserAuthException, TransportException
Authenticateusername
using the"publickey"
authentication method.KeyProvider
instances can be created using any of the of theloadKeys()
method provided in this class. In case multiplekeyProviders
are specified; authentication is attempted in order as long as the"publickey"
authentication method is available.- Parameters:
username
- user to authenticatekeyProviders
- one or moreKeyProvider
instances- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPublickey
public void authPublickey(java.lang.String username, KeyProvider... keyProviders) throws UserAuthException, TransportException
Authenticateusername
using the"publickey"
authentication method.KeyProvider
instances can be created using any of theloadKeys()
method provided in this class. In case multiplekeyProviders
are specified; authentication is attempted in order as long as the"publickey"
authentication method is available.- Parameters:
username
- user to authenticatekeyProviders
- one or moreKeyProvider
instances- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authPublickey
public void authPublickey(java.lang.String username, java.lang.String... locations) throws UserAuthException, TransportException
Authenticateusername
using the"publickey"
authentication method, with keys from one or morelocations
in the file system. In case multiplelocations
are specified; authentication is attempted in order as long as the"publickey"
authentication method is available. If there is an error loading keys from any of them (e.g. file could not be read, file format not recognized) that key file it is ignored. This method does not provide a way to specify a passphrase.- Parameters:
username
- user to authenticatelocations
- one or more locations in the file system containing the private key- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
authGssApiWithMic
public void authGssApiWithMic(java.lang.String username, javax.security.auth.login.LoginContext context, org.ietf.jgss.Oid supportedOid, org.ietf.jgss.Oid... supportedOids) throws UserAuthException, TransportException
Authenticateusername
using the"gssapi-with-mic"
authentication method, given a login context for the peer GSS machine and a list of supported OIDs. Supported OIDs should be ordered by preference as the SSH server will choose the first OID that it also supports. At least one OID is required- Parameters:
username
- user to authenticatecontext
-LoginContext
for the peer GSS machinesupportedOid
- first supported OIDsupportedOids
- other supported OIDs- Throws:
UserAuthException
- in case of authentication failureTransportException
- if there was a transport-layer error
-
disconnect
public void disconnect() throws java.io.IOException
Disconnects from the connected SSH server.SSHClient
objects are not reusable therefore it is incorrect to attempt connection after this method has been called. This method should be called from afinally
construct after connection is established; so that proper cleanup is done and the thread spawned by the transport layer for dealing with incoming packets is stopped.- Overrides:
disconnect
in classSocketClient
- Throws:
java.io.IOException
-
getConnection
public Connection getConnection()
- Returns:
- the associated
Connection
instance.
-
getRemoteSocketAddress
public java.net.InetSocketAddress getRemoteSocketAddress()
Get Remote Socket Address from Transport- Specified by:
getRemoteSocketAddress
in interfaceRemoteAddressProvider
- Returns:
- Remote Socket Address or null when not connected
-
getRemoteCharset
public java.nio.charset.Charset getRemoteCharset()
Returns the character set used to communicate with the remote machine for certain strings (like paths).- Returns:
- remote character set
-
getRemotePortForwarder
public RemotePortForwarder getRemotePortForwarder()
- Returns:
- a
RemotePortForwarder
that allows requesting remote forwarding over this connection.
-
getUserAuth
public UserAuth getUserAuth()
- Returns:
- the associated
UserAuth
instance. This allows access to information like theauthentication banner
, whether authentication was at leastpartially successful
.
-
isAuthenticated
public boolean isAuthenticated()
- Returns:
- whether authenticated.
-
isConnected
public boolean isConnected()
- Overrides:
isConnected
in classSocketClient
- Returns:
- whether connected.
-
loadKeys
public KeyProvider loadKeys(java.security.KeyPair kp)
Creates aKeyProvider
from suppliedKeyPair
.- Parameters:
kp
- the key pair- Returns:
- the key provider ready for use in authentication
-
loadKeys
public KeyProvider loadKeys(java.lang.String location) throws java.io.IOException
Returns aKeyProvider
instance created from a location on the file system where an unencrypted private key file (does not require a passphrase) can be found. Simply callsloadKeys(String, PasswordFinder)
with thePasswordFinder
argument asnull
.- Parameters:
location
- the location for the key file- Returns:
- the key provider ready for use in authentication
- Throws:
SSHException
- if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpathjava.io.IOException
- if the key file format is not known, if the file could not be read, etc.
-
loadKeys
public KeyProvider loadKeys(java.lang.String location, char[] passphrase) throws java.io.IOException
Utility function for creating aKeyProvider
instance from given location on the file system. Creates a one-offPasswordFinder
usingPasswordUtils.createOneOff(char[])
, and callsloadKeys(String, PasswordFinder)
.- Parameters:
location
- location of the key filepassphrase
- passphrase as a char-array- Returns:
- the key provider ready for use in authentication
- Throws:
SSHException
- if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpathjava.io.IOException
- if the key file format is not known, if the file could not be read, etc.
-
loadKeys
public KeyProvider loadKeys(java.lang.String location, PasswordFinder passwordFinder) throws java.io.IOException
Creates aKeyProvider
instance from given location on the file system. Currently the following private key files are supported:- PKCS8 (OpenSSH uses this format)
- PEM-encoded PKCS1
- Putty keyfile
- openssh-key-v1 (New OpenSSH keyfile format)
- Parameters:
location
- the location of the key filepasswordFinder
- thePasswordFinder
that can supply the passphrase for decryption (may benull
in case keyfile is not encrypted)- Returns:
- the key provider ready for use in authentication
- Throws:
SSHException
- if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpathjava.io.IOException
- if the key file format is not known, if the file could not be read, etc.
-
loadKeys
public KeyProvider loadKeys(java.lang.String location, java.lang.String passphrase) throws java.io.IOException
Convenience method for creating aKeyProvider
instance from alocation
where an encrypted key file is located. CallsloadKeys(String, char[])
with a character array created from the suppliedpassphrase
string.- Parameters:
location
- location of the key filepassphrase
- passphrase as a string- Returns:
- the key provider for use in authentication
- Throws:
java.io.IOException
- if the key file format is not known, if the file could not be read etc.
-
loadKeys
public KeyProvider loadKeys(java.lang.String privateKey, java.lang.String publicKey, PasswordFinder passwordFinder) throws java.io.IOException
Creates aKeyProvider
instance from passed strings. Currently only PKCS8 format private key files are supported (OpenSSH uses this format).- Parameters:
privateKey
- the private key as a stringpublicKey
- the public key as a string if it's not included with the private keypasswordFinder
- thePasswordFinder
that can supply the passphrase for decryption (may benull
in case keyfile is not encrypted)- Returns:
- the key provider ready for use in authentication
- Throws:
SSHException
- if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpathjava.io.IOException
- if the key file format is not known, etc.
-
loadKnownHosts
public void loadKnownHosts() throws java.io.IOException
Attempts loading the user'sknown_hosts
file from the default locations, i.e.~/.ssh/known_hosts
and~/.ssh/known_hosts2
on most platforms. Adds the resultingOpenSSHKnownHosts
object as a host key verifier. For finer control over which file is used, seeloadKnownHosts(File)
.- Throws:
java.io.IOException
- if there is an error loading from both locations
-
loadKnownHosts
public void loadKnownHosts(java.io.File location) throws java.io.IOException
Adds aOpenSSHKnownHosts
object created from the specified location as a host key verifier.- Parameters:
location
- location forknown_hosts
file- Throws:
java.io.IOException
- if there is an error loading from any of these locations
-
newLocalPortForwarder
public LocalPortForwarder newLocalPortForwarder(Parameters parameters, java.net.ServerSocket serverSocket)
Create aLocalPortForwarder
that will listen based onparameters
using the boundserverSocket
and forward incoming connections to the server; which will further forward them tohost:port
. The returned forwarder'slisten()
method should be called to actually start listening, this method just creates an instance.- Parameters:
parameters
- parameters for the forwarding setupserverSocket
- bound server socket- Returns:
- a
LocalPortForwarder
-
newDirectConnection
public DirectConnection newDirectConnection(java.lang.String hostname, int port) throws java.io.IOException
Create aDirectConnection
channel that connects to a remote address from the server. This can be used to open a tunnel to, for example, an HTTP server that is only accessible from the SSH server, or opening an SSH connection via a 'jump' server.- Parameters:
hostname
- name of the host to connect to from the server.port
- remote port number.- Throws:
java.io.IOException
-
registerX11Forwarder
public X11Forwarder registerX11Forwarder(ConnectListener listener)
Register alistener
for handling forwarded X11 channels. Without having done this, an incoming X11 forwarding will be summarily rejected. It should be clarified that multiple listeners for X11 forwarding over a single SSH connection are not supported (and don't make much sense). So a subsequent call to this method is only going to replace the registeredlistener
.- Parameters:
listener
- theConnectListener
that should be delegated the responsibility of handling forwardedX11Forwarder.X11Channel
's- Returns:
- an
X11Forwarder
that allows tostop acting
on X11 requests from server
-
newSCPFileTransfer
public SCPFileTransfer newSCPFileTransfer()
- Returns:
- Instantiated
SCPFileTransfer
implementation.
-
newSFTPClient
public SFTPClient newSFTPClient() throws java.io.IOException
- Returns:
- Instantiated
SFTPClient
implementation. - Throws:
java.io.IOException
- if there is an error starting thesftp
subsystem- See Also:
StatefulSFTPClient
-
newStatefulSFTPClient
public StatefulSFTPClient newStatefulSFTPClient() throws java.io.IOException
Stateful FTP client is required in order to connect to Serv-U FTP servers.- Returns:
- Instantiated
SFTPClient
implementation. - Throws:
java.io.IOException
- if there is an error starting thesftp
subsystem
-
rekey
public void rekey() throws TransportException
Does key re-exchange.- Throws:
TransportException
- if an error occurs during key exchange
-
setRemoteCharset
public void setRemoteCharset(java.nio.charset.Charset remoteCharset)
Sets the character set used to communicate with the remote machine for certain strings (like paths)- Parameters:
remoteCharset
- remote character set ornull
for default
-
startSession
public Session startSession() throws ConnectionException, TransportException
Description copied from interface:SessionFactory
Opens asession
channel. The returnedSession
instance allowsexecuting a remote command
,starting a subsystem
, orstarting a shell
.- Specified by:
startSession
in interfaceSessionFactory
- Returns:
- the opened
session
channel - Throws:
ConnectionException
TransportException
- See Also:
Session
-
useCompression
public void useCompression() throws TransportException
Addszlib
compression to preferred compression algorithms. There is no guarantee that it will be successfully negotiated. If the client is already connected renegotiation is done; otherwise this method simply returns (and compression will be negotiated during connection establishment).- Throws:
java.lang.ClassNotFoundException
- ifJZlib
is not in classpathTransportException
- if an error occurs during renegotiation
-
onConnect
protected void onConnect() throws java.io.IOException
On connection establishment, also initializes the SSH transport viaTransport.init(java.lang.String, int, java.io.InputStream, java.io.OutputStream)
anddoKex()
.- Throws:
java.io.IOException
-
doKex
protected void doKex() throws TransportException
Do key exchange.- Throws:
TransportException
- if error during kex
-
close
public void close() throws java.io.IOException
Same asdisconnect()
.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
java.io.IOException
-
-