Represents an SSH session object. More...

Inheritance diagram for Session:

[legend]

Collaboration diagram for Session:

[legend]

Public Member Functions
_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...

_.Library.Status	AuthenticateWithKeyPair (_.Library.String username, _.Library.String publickeyfile, _.Library.String privatekeyfile, _.Library.String passphrase)
	Authenticate with the remote server using a public/private key pair and passphrase (for the private key). More...

_.Library.Status	AuthenticateWithKeyboardInteractive (_.Library.String username, _.Library.String lambda, context)
	Authenticate with the remote server using the "keyboard-interactive" authentication scheme. More...

_.Library.Status	AuthenticateWithUsername (_.Library.String username, _.Library.String password)
	Authenticate with the remote server using a username/password via the "password" authentication. More...

_.Library.Status	Connect (_.Library.String hostname, _.Library.Integer port, _.Library.String hostkey, _.Library.String hostkeytype)
	Connect to a remote host, specifying the hostname, and optionally the port and remote hostkey to match. More...

_.Library.Status	Disconnect ()
	Disconnect from the remote host.

_.Library.Status	Execute (_.Library.String pCommand, _.Library.String pDevice, pEnv)
	Execute a remote command on the remote system. More...

_.Library.Status	ForwardPort (_.Library.String pRemoteHost, _.Library.Integer pRemotePort, _.Library.String pDevice)
	Forwards traffic via the SSH connection to a remote host/port. More...

_.Library.Status	GetAlgorithms (_.Library.String preferences)
	Called to retrieve the current set of negotiated algorithms/methods for various categories. More...

_.Library.Status	GetSupportedAlgorithms (_.Library.String algs)
	Called to retrieve the set of supported algorithms for various categories. More...

_.Library.Status	GetTimeout (_.Library.Integer pTimeoutMS)
	Gets the timeout for SSH operations in milliseconds. More...

_.Library.Status	OpenSFTP (_.Net.SSH.SFTP sftp)
	Open up an SFTP session for SFTP activity.

_.Library.Status	SetPreferredAlgorithms (_.Library.String preferences)
	Called before connecting to a remote host to specify various preferred algorithms and methods that. More...

_.Library.Status	SetTimeout (_.Library.Integer pTimeoutMS)
	Sets the timeout for SSH operations in milliseconds. More...

_.Library.Status	VersionInfo (_.Library.String pClientVersion, _.Library.String pServerVersion)
	Retrieves the client and server SSH versions. More...

Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...

_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...

_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...

Static Public Member Functions
_.Library.Status	TestExecute (_.Library.String host, _.Library.String username, _.Library.String password, _.Library.String command, _.Library.Integer pTimeout)
	Demonstrates the execution of a remote command (by default, uname -a).

_.Library.Status	TestForwardPort (_.Library.String host, _.Library.String username, _.Library.String password, _.Library.String remotehost, _.Library.Integer remoteport)
	Demonstrates the use of port forwarding to whatismyipaddress.com via the remote SSH server.

Public Attributes
	HostKey
	Remote host key. More...

	LocalCharset
	Character set used by the local system. More...

	RemoteCharset
	Character set used by the remote server. More...

Static Public Attributes
	SSHHOSTKEYMD5 = None
	Host Key Type: MD5.

	SSHHOSTKEYSHA1 = None
	Host Key Type: SHA1.

	SSHHOSTKEYSHA256 = None
	Host Key Type: SHA256.

	SSHPORT = None
	Default SSH port.

	SSHTRACEAUTH = None
	Enables tracing of SSH authentication.

	SSHTRACECONN = None
	Enables tracing of SSH connections.

	SSHTRACEERROR = None
	Enables tracing of SSH error operations.

	SSHTRACEKEX = None
	Enables tracing of SSH key exchange.

	SSHTRACEPUBLICKEY = None
	Enables tracing of SSH public key operations.

	SSHTRACESCP = None
	Enables tracing of SSH/SCP operations.

	SSHTRACESFTP = None
	Enables tracing of SSH/SFTP operations.

	SSHTRACESOCKET = None
	Enables tracing of low level socket operations.

	SSHTRACETRANS = None
	Enables tracing of SSH transactions.

Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...

	JAVATYPE = None
	The Java type to be used when exported.

	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Private Member Functions
_.Library.Status	OnClose ()
	Clean up any resources.

Detailed Description

Represents an SSH session object.

Each SSH session object must first be connected, then authenticated with the remote system. Note that there are multiple methods of authentication, this class supports password and publickey. Once connected and authenticated, the SSH object can be used to perform SCP (Secure Copy) operations of single files to and from the remote system, it can also be used to execute remote commands, tunnel TCP traffic and forms the base connection for SFTP operations (see Net.SSH.SFTP).
The Test() method of this class illustrates some basic usage scenarios for this class.
NOTE: Net.SSH is currently not supported on OpenVMS platforms.

Member Function Documentation

◆ OnNew()

_.Library.Status OnNew ( )

This callback method is invoked by the <METHOD>New</METHOD> method to.

provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from New(). For example, if you're going to call New, passing 2 arguments, OnNew's signature could be:

Method OnNew(dob as Date = "", name as Name = "") as Status If instead of returning a Status code this returns an oref and this oref is a subclass of the current class then this oref will be the one returned to the caller of New method.

Reimplemented from RegisteredObject.

◆ AuthenticateWithKeyPair()

_.Library.Status AuthenticateWithKeyPair	(	_.Library.String	username,
		_.Library.String	publickeyfile,
		_.Library.String	privatekeyfile,
		_.Library.String	passphrase
	)

Authenticate with the remote server using a public/private key pair and passphrase (for the private key).

The private keys are PEM encoded and the public keys are in OpenSSH format.
If multiple forms of authentication are required by the server, for example /etc/ssh/sshd_config contains:

    AuthenticationMethods publickey,password

Then in this case read the "," (comma) as AND; the server will require both forms of authentication.
Calling AuthenticateWithKeyPair fails with LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED which is a bit misleading ... it's really "authenticated with partial success" so we can then try then authenticating with a password which should then succeed (or keyboard-interactive).

◆ AuthenticateWithKeyboardInteractive()

_.Library.Status AuthenticateWithKeyboardInteractive	(	_.Library.String	username,
		_.Library.String	lambda,
			context
	)

Authenticate with the remote server using the "keyboard-interactive" authentication scheme.

This requires

a callback lambda/function that will be called with a list of one or challenges to which the lambda will return the responses to the challenge(s). The lambda is invoked with the following arguments: username As String Username being authenticated instructions As String Instructions from the server (optional) prompts As List A $LIST of challenge prompt(s) promptflags As List A $LIST of flags for each of the challenge prompt(s) ByRef context A pass-by-ref context value The lambda must return a $LIST of responses, with each Nth element in the $LIST corresponding to the Nth challenge prompt. If there is no response for a prompt, then that Nth $LIST element should be empty. The allowed values for promptflags are as follows:
E Echo on. If E is missing DO NOT ECHO! (e.g. password entry) NOTE: The context can be anything of your choosing (an array, object or whatever) and it is passed by reference.
See notes in <method>AuthenticateWithKeyPair()</method> when using multiple forms of authentication.

◆ AuthenticateWithUsername()

_.Library.Status AuthenticateWithUsername	(	_.Library.String	username,
		_.Library.String	password
	)

Authenticate with the remote server using a username/password via the "password" authentication.

scheme. Note that this is NOT the same as keyboard-interactive which is typically what login sessions use.
See notes in <method>AuthenticateWithKeyPair()</method> when using multiple forms of authentication.

◆ Connect()

_.Library.Status Connect	(	_.Library.String	hostname,
		_.Library.Integer	port,
		_.Library.String	hostkey,
		_.Library.String	hostkeytype
	)

Connect to a remote host, specifying the hostname, and optionally the port and remote hostkey to match.

The hostkey helps prevent impersonation attacks, it is a hash of the remote hosts' public key as a string of ASCII hex digits representing the bytes of the hash. The type of hash is determined from the number of bits (from the number of hex chars) in the hash: MD5: 128 bits / 32 hex chars SHA1: 160 bits / 40 hex chars SHA256: 256 bits / 64 hex chars The returned host key can be specified by passing one of "MD5", "SHA1" or "SHA256" (see ..#SSHHOSTKEYxyz values), the default is "MD5". If the host key isn't available, it will be "" (e.g. MD5 in FIPS mode).

◆ Execute()

_.Library.Status Execute	(	_.Library.String	pCommand,
		_.Library.String	pDevice,
			pEnv
	)

Execute a remote command on the remote system.

In order to do I/O with the remote

command, an XDEV device instance is passed back via the pDevice parameter. This is a normal device and can be used with the USE/READ/WRITE/CLOSE commands. Note that environment variables for the remote command can be passed as an array of name/value pairs.

◆ ForwardPort()

_.Library.Status ForwardPort	(	_.Library.String	pRemoteHost,
		_.Library.Integer	pRemotePort,
		_.Library.String	pDevice
	)

Forwards traffic via the SSH connection to a remote host/port.

The traffic is sent via an XDEV device

that is opened by ForwardPort() and passed back by reference via the pDevice parameter.

◆ GetAlgorithms()

_.Library.Status GetAlgorithms ( _.Library.String preferences )

Called to retrieve the current set of negotiated algorithms/methods for various categories.

Format of the result string is as follows:

<category>=<option>[:<category1>=<option1>[:...]]

Where <category> is one of: KEX Key Exchange Methods HOSTKEY Hostkey public key algorithms CRYPT Encryption algorithms MAC MAC algorithms COMPCompression Algorithms NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref And <option> is a comma delimited list of one or more values.

◆ GetSupportedAlgorithms()

_.Library.Status GetSupportedAlgorithms ( _.Library.String algs )

Called to retrieve the set of supported algorithms for various categories.

Format of the string is as follows:

<category>=<option>[:<category1>=<option1>[:...]]

Where <category> is one of: KEX Key Exchange Methods HOSTKEY Hostkey public key algorithms CRYPT Encryption algorithms MAC MAC algorithms COMP Compression Algorithms NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref

◆ GetTimeout()

_.Library.Status GetTimeout ( _.Library.Integer pTimeoutMS )

Gets the timeout for SSH operations in milliseconds.

An infinite timeout is represented by the value of -1;

the default timeout is set to 30 seconds.

◆ SetPreferredAlgorithms()

_.Library.Status SetPreferredAlgorithms ( _.Library.String preferences )

Called before connecting to a remote host to specify various preferred algorithms and methods that.

should be used. Format of the preferences string is as follows:

<category>=<option>[:<category1>=<option1>[:...]]

Where <category> is one of: KEX Key Exchange Methods HOSTKEY Hostkey public key algorithms CRYPT Encryption algorithms MAC MAC algorithms COMPCompression Algorithms NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref And <option> is a comma delimited list of one or more values.

◆ SetTimeout()

_.Library.Status SetTimeout ( _.Library.Integer pTimeoutMS )

Sets the timeout for SSH operations in milliseconds.

An infinite timeout can be set by passing -1 to this

methods; the default timeout is set to 30 seconds.

◆ VersionInfo()

_.Library.Status VersionInfo	(	_.Library.String	pClientVersion,
		_.Library.String	pServerVersion
	)

Retrieves the client and server SSH versions.

If the server version is not available,

or if the session is not connected, then pServerVersion will be undefined. Note that the client version refers to the release of libssh2 being used.

Member Data Documentation

◆ HostKey

HostKey

Remote host key.

The hash type is determined from the

number of bits (from the number of hex chars) in the hash: MD5: 128 bits / 32 hex chars SHA1: 160 bits / 40 hex chars SHA256: 256 bits / 64 hex chars

◆ LocalCharset

LocalCharset

Character set used by the local system.

Defaults to the system call

translation table (which is likely UTF8 on UNIX).

◆ RemoteCharset

RemoteCharset

Character set used by the remote server.

Will almost certainly be

UTF-8 for any SSH server.

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Detailed Description

Member Function Documentation

◆ OnNew()

◆ AuthenticateWithKeyPair()

◆ AuthenticateWithKeyboardInteractive()

◆ AuthenticateWithUsername()

◆ Connect()

◆ Execute()

◆ ForwardPort()

◆ GetAlgorithms()

◆ GetSupportedAlgorithms()

◆ GetTimeout()

◆ SetPreferredAlgorithms()

◆ SetTimeout()

◆ VersionInfo()

Member Data Documentation

◆ HostKey

◆ LocalCharset

◆ RemoteCharset