phpseclib API Documentation
Class

Net_SSH2

class Net_SSH2

Pure-PHP implementation of SSHv2.

Properties

string $identifier The SSH identifier
object $fsock The Socket Object
int $bitmap Execution Bitmap
string $errors Error information
array|false $server_identifier Server Identifier
array|false $kex_algorithms Key Exchange Algorithms
int $kex_dh_group_size_min Minimum Diffie-Hellman Group Bit Size in RFC 4419 Key Exchange Methods
int $kex_dh_group_size_preferred Preferred Diffie-Hellman Group Bit Size in RFC 4419 Key Exchange Methods
int $kex_dh_group_size_max Maximum Diffie-Hellman Group Bit Size in RFC 4419 Key Exchange Methods
array|false $server_host_key_algorithms Server Host Key Algorithms
array|false $encryption_algorithms_client_to_server Encryption Algorithms: Client to Server
array|false $encryption_algorithms_server_to_client Encryption Algorithms: Server to Client
array|false $mac_algorithms_client_to_server MAC Algorithms: Client to Server
array|false $mac_algorithms_server_to_client MAC Algorithms: Server to Client
array|false $compression_algorithms_client_to_server Compression Algorithms: Client to Server
array|false $compression_algorithms_server_to_client Compression Algorithms: Server to Client
array|false $languages_server_to_client Languages: Server to Client
array|false $languages_client_to_server Languages: Client to Server
int $encrypt_block_size Block Size for Server to Client Encryption
int $decrypt_block_size Block Size for Client to Server Encryption
object $decrypt Server to Client Encryption Object
object $encrypt Client to Server Encryption Object
object $hmac_create Client to Server HMAC Object
object $hmac_check Server to Client HMAC Object
int $hmac_size Size of server to client HMAC
string $server_public_host_key Server Public Host Key
string $session_id Session identifer
string $exchange_hash Exchange hash
array $message_numbers Message Numbers
array $disconnect_reasons Disconnection Message 'reason codes' defined in RFC4253
array $channel_open_failure_reasons SSHMSGCHANNELOPENFAILURE 'reason codes', defined in RFC4254
array $terminal_modes Terminal Modes
array $channel_extended_data_type_codes SSHMSGCHANNELEXTENDEDDATA's datatypecodes
int $send_seq_no Send Sequence Number
int $get_seq_no Get Sequence Number
array $server_channels Server Channels
array $channel_buffers Channel Buffers
array $channel_status Channel Status
array $packet_size_client_to_server Packet Size
array $message_number_log Message Number Log
array $message_log Message Log
int $window_size The Window Size
array $window_size_server_to_client Window size, server to client
array $window_size_client_to_server Window size, client to server
string $signature Server signature
string $signature_format Server signature format
array $interactiveBuffer Interactive Buffer
int $log_size Current log size
$timeout Timeout
$curTimeout Current Timeout
resource $realtime_log_file Real-time log file pointer
int $realtime_log_size Real-time log file size
bool $signature_validated Has the signature been validated?
$realtime_log_wrap Real-time log file wrap boolean
$quiet_mode Flag to suppress stderr from output
int $last_packet Time of first network activity
int $exit_status Exit status returned from ssh if any
bool $request_pty Flag to request a PTY when using exec()
bool $in_request_pty_exec Flag set while exec() is running when using enablePTY()
bool $in_subsystem Flag set after startSubsystem() is called
string $stdErrorLog Contents of stdError
string $last_interactive_response The Last Interactive Response
array $keyboard_requests_responses Keyboard Interactive Request / Responses
string $banner_message Banner Message
bool $is_timeout Did read() timeout or return normally?
string $log_boundary Log Boundary
int $log_long_width Log Long Width
int $log_short_width Log Short Width
string $host Hostname
int $port Port Number
int $windowColumns Number of columns for terminal window size
int $windowRows Number of columns for terminal window size
int $crypto_engine Crypto Engine
System_SSH_Agent $agent A SystemSSHAgent for use in the SSH2 Agent Forwarding scenario

Methods

Net_SSH2 Net_SSH2(mixed $host, int $port = 22, int $timeout = 10)

Default Constructor.

setCryptoEngine(int $engine)

Set Crypto Engine Mode

bool _connect()

Connect to an SSHv2 server

string _generate_identifier()

Generates the SSH identifier

_key_exchange(string $kexinit_payload_server)

Key Exchange

int|null _encryption_algorithm_to_key_size(string $algorithm)

Maps an encryption algorithm name to the number of key bytes.

bool login($username)

Login

bool _login($username)

Login Helper

bool _login_helper(string $username, string $password = null)

Login Helper

bool _keyboard_interactive_login(string $username, string $password)

Login via keyboard-interactive authentication

bool _keyboard_interactive_process()

Handle the keyboard-interactive requests / responses.

bool _ssh_agent_login(string $username, System_SSH_Agent $agent)

Login with an ssh-agent provided key

bool _privatekey_login($username, $privatekey)

Login with an RSA private key

setTimeout(mixed $timeout)

Set Timeout

getStdError()

Get the output from stdError

string exec(string $command, Callback $callback = null)

Execute Command

bool _initShell()

Creates an interactive shell

int _get_interactive_channel()

Return the channel to be used with read() / write()

int _get_open_channel()

Return an available open channel

string read(string $expect = '', int $mode = NET_SSH2_READ_SIMPLE)

Returns the output of an interactive shell

bool write(string $cmd)

Inputs a command into an interactive shell.

bool startSubsystem(string $subsystem)

Start a subsystem.

bool stopSubsystem()

Stops a subsystem.

reset()

Closes a channel

isTimeout()

Is timeout?

disconnect()

Disconnect

__destruct()

Destructor.

bool isConnected()

Is the connection still active?

bool isAuthenticated()

Have you successfully been logged in?

string _get_binary_packet()

Gets Binary Packets

string _filter($payload)

Filter Binary Packets

enableQuietMode()

Enable Quiet Mode

disableQuietMode()

Disable Quiet Mode

bool isQuietModeEnabled()

Returns whether Quiet Mode is enabled or not

enablePTY()

Enable request-pty when using exec()

disablePTY()

Disable request-pty when using exec()

bool isPTYEnabled()

Returns whether request-pty is enabled or not

mixed _get_channel_packet($client_channel, $skip_extended = false)

Gets channel data

bool _send_binary_packet(string $data, string $logged = null)

Sends Binary Packets

_append_log($message_number, $message)

Logs data packets

bool _send_channel_packet(int $client_channel, string $data)

Sends channel data

bool _close_channel(int $client_channel, bool $want_reply = false)

Closes and flushes a channel

bool _disconnect(int $reason)

Disconnect

string _string_shift(string $string, int $index = 1)

String Shift

_define_array()

Define Array

array|false|string getLog()

Returns a log of the packets that have been sent and received.

string _format_log(array $message_log, array $message_number_log)

Formats a log for printing

string _format_log_helper(array $matches)

Helper function for formatlog

_on_channel_open()

Helper function for agent->onchannel_open()

mixed _array_intersect_first(array $array1, array $array2)

Returns the first value of the intersection of two arrays or false if the intersection is empty.

string getErrors()

Returns all errors

string getLastError()

Returns the last error

string getServerIdentification()

Return the server identification.

array getKexAlgorithms()

Return a list of the key exchange algorithms the server supports.

array getServerHostKeyAlgorithms()

Return a list of the host key (public key) algorithms the server supports.

array getEncryptionAlgorithmsClient2Server()

Return a list of the (symmetric key) encryption algorithms the server supports, when receiving stuff from the client.

array getEncryptionAlgorithmsServer2Client()

Return a list of the (symmetric key) encryption algorithms the server supports, when sending stuff to the client.

array getMACAlgorithmsClient2Server()

Return a list of the MAC algorithms the server supports, when receiving stuff from the client.

array getMACAlgorithmsServer2Client()

Return a list of the MAC algorithms the server supports, when sending stuff to the client.

array getCompressionAlgorithmsClient2Server()

Return a list of the compression algorithms the server supports, when receiving stuff from the client.

array getCompressionAlgorithmsServer2Client()

Return a list of the compression algorithms the server supports, when sending stuff to the client.

array getLanguagesServer2Client()

Return a list of the languages the server supports, when sending stuff to the client.

array getLanguagesClient2Server()

Return a list of the languages the server supports, when receiving stuff from the client.

string getBannerMessage()

Returns the banner message.

mixed getServerPublicHostKey()

Returns the server public host key.

false|int getExitStatus()

Returns the exit status of an SSH command or false.

int getWindowColumns()

Returns the number of columns for the terminal window size.

int getWindowRows()

Returns the number of rows for the terminal window size.

setWindowColumns(int $value)

Sets the number of columns for the terminal window size.

setWindowRows(int $value)

Sets the number of rows for the terminal window size.

setWindowSize(int $columns = 80, int $rows = 24)

Sets the number of columns and rows for the terminal window size.

Details

at line 886
public Net_SSH2 Net_SSH2(mixed $host, int $port = 22, int $timeout = 10)

Default Constructor.

$host can either be a string, representing the host, or a stream resource.

Parameters

mixed $host
int $port
int $timeout

Return Value

Net_SSH2

See also

self::login()

at line 1004
public setCryptoEngine(int $engine)

Set Crypto Engine Mode

Possible $engine values: CRYPTMODEINTERNAL, CRYPTMODEMCRYPT

Parameters

int $engine

at line 1015
public bool _connect()

Connect to an SSHv2 server

Return Value

bool

at line 1135
public string _generate_identifier()

Generates the SSH identifier

You should overwrite this method in your own class if you want to use another identifier

Return Value

string

at line 1165
public _key_exchange(string $kexinit_payload_server)

Key Exchange

Parameters

string $kexinit_payload_server

at line 1904
public int|null _encryption_algorithm_to_key_size(string $algorithm)

Maps an encryption algorithm name to the number of key bytes.

Parameters

string $algorithm Name of the encryption algorithm

Return Value

int|null Number of bytes as an integer or null for unknown

at line 1948
public bool login($username)

Login

The $password parameter can be a plaintext password, a Crypt_RSA object or an array

Parameters

$username

Return Value

bool

See also

self::_login()

at line 1964
public bool _login($username)

Login Helper

Parameters

$username

Return Value

bool

See also

self::_login_helper()

at line 1995
public bool _login_helper(string $username, string $password = null)

Login Helper

Parameters

string $username
string $password

Return Value

bool

at line 2171
public bool _keyboard_interactive_login(string $username, string $password)

Login via keyboard-interactive authentication

See {@link http://tools.ietf.org/html/rfc4256 RFC4256} for details. This is not a full-featured keyboard-interactive authenticator.

Parameters

string $username
string $password

Return Value

bool

at line 2202
public bool _keyboard_interactive_process()

Handle the keyboard-interactive requests / responses.

Return Value

bool

at line 2317
public bool _ssh_agent_login(string $username, System_SSH_Agent $agent)

Login with an ssh-agent provided key

Parameters

string $username
System_SSH_Agent $agent

Return Value

bool

at line 2340
public bool _privatekey_login($username, $privatekey)

Login with an RSA private key

Parameters

$username
$privatekey

Return Value

bool

at line 2443
public setTimeout(mixed $timeout)

Set Timeout

$ssh->exec('ping 127.0.0.1'); on a Linux host will never return and will run indefinitely. setTimeout() makes it so it'll timeout. Setting $timeout to false or 0 will mean there is no timeout.

Parameters

mixed $timeout

at line 2453
public getStdError()

Get the output from stdError

at line 2469
public string exec(string $command, Callback $callback = null)

Execute Command

If $callback is set to false then NetSSH2::getchannelpacket(NETSSH2CHANNEL_EXEC) will need to be called manually. In all likelihood, this is not a feature you want to be taking advantage of.

Parameters

string $command
Callback $callback

Return Value

string

at line 2617
public bool _initShell()

Creates an interactive shell

Return Value

bool

See also

self::read()
self::write()

at line 2721
public int _get_interactive_channel()

Return the channel to be used with read() / write()

Return Value

int

See also

self::read()
self::write()

at line 2739
public int _get_open_channel()

Return an available open channel

Return Value

int

at line 2763
public string read(string $expect = '', int $mode = NET_SSH2_READ_SIMPLE)

Returns the output of an interactive shell

Returns when there's a match for $expect, which can take the form of a string literal or, if $mode == NETSSH2READ_REGEX, a regular expression.

Parameters

string $expect
int $mode

Return Value

string

See also

self::write()

at line 2808
public bool write(string $cmd)

Inputs a command into an interactive shell.

Parameters

string $cmd

Return Value

bool

See also

self::read()

at line 2837
public bool startSubsystem(string $subsystem)

Start a subsystem.

Right now only one subsystem at a time is supported. To support multiple subsystem's stopSubsystem() could accept a string that contained the name of the subsystem, but at that point, only one subsystem of each type could be opened. To support multiple subsystem's of the same name maybe it'd be best if startSubsystem() generated a new channel id and returns that and then that that was passed into stopSubsystem() but that'll be saved for a future date and implemented if there's sufficient demand for such a feature.

Parameters

string $subsystem

Return Value

bool

See also

self::stopSubsystem()

at line 2899
public bool stopSubsystem()

Stops a subsystem.

Return Value

bool

See also

self::startSubsystem()

at line 2913
public reset()

Closes a channel

If read() timed out you might want to just close the channel and have it auto-restart on the next read() call

at line 2925
public isTimeout()

Is timeout?

Did exec() or read() return because they timed out or because they encountered the end?

at line 2935
public disconnect()

Disconnect

at line 2951
public __destruct()

Destructor.

Will be called, automatically, if you're supporting just PHP5. If you're supporting PHP4, you'll need to call disconnect().

at line 2962
public bool isConnected()

Is the connection still active?

Return Value

bool

at line 2973
public bool isAuthenticated()

Have you successfully been logged in?

Return Value

bool

at line 2987
public string _get_binary_packet()

Gets Binary Packets

See '6. Binary Packet Protocol' of rfc4253 for more info.

Return Value

string

See also

self::_send_binary_packet()

at line 3080
public string _filter($payload)

Filter Binary Packets

Because some binary packets need to be ignored...

Parameters

$payload

Return Value

string

See also

self::_get_binary_packet()

at line 3205
public enableQuietMode()

Enable Quiet Mode

Suppress stderr from output

at line 3217
public disableQuietMode()

Disable Quiet Mode

Show stderr in output

at line 3231
public bool isQuietModeEnabled()

Returns whether Quiet Mode is enabled or not

Return Value

bool

See also

self::enableQuietMode()
self::disableQuietMode()

at line 3241
public enablePTY()

Enable request-pty when using exec()

at line 3251
public disablePTY()

Disable request-pty when using exec()

at line 3265
public bool isPTYEnabled()

Returns whether request-pty is enabled or not

Return Value

bool

See also

self::enablePTY()
self::disablePTY()

at line 3279
public mixed _get_channel_packet($client_channel, $skip_extended = false)

Gets channel data

Returns the data as a string if it's available and false if not.

Parameters

$client_channel
$skip_extended

Return Value

mixed

at line 3497
public bool _send_binary_packet(string $data, string $logged = null)

Sends Binary Packets

See '6. Binary Packet Protocol' of rfc4253 for more info.

Parameters

string $data
string $logged

Return Value

bool

See also

self::_get_binary_packet()

at line 3555
public _append_log($message_number, $message)

Logs data packets

Makes sure that only the last 1MB worth of packets will be logged

Parameters

$message_number
$message

at line 3633
public bool _send_channel_packet(int $client_channel, string $data)

Sends channel data

Spans multiple SSHMSGCHANNEL_DATAs if appropriate

Parameters

int $client_channel
string $data

Return Value

bool

at line 3681
public bool _close_channel(int $client_channel, bool $want_reply = false)

Closes and flushes a channel

Net_SSH2 doesn't properly close most channels. For exec() channels are normally closed by the server and for SFTP channels are presumably closed when the client disconnects. This functions is intended for SCP more than anything.

Parameters

int $client_channel
bool $want_reply

Return Value

bool

at line 3714
public bool _disconnect(int $reason)

Disconnect

Parameters

int $reason

Return Value

bool

at line 3735
public string _string_shift(string $string, int $index = 1)

String Shift

Inspired by array_shift

Parameters

string $string
int $index

Return Value

string

at line 3752
public _define_array()

Define Array

Takes any number of arrays whose indices are integers and whose values are strings and defines a bunch of named constants from it, using the value as the name of the constant and the index as the value of the constant. If any of the constants that would be defined already exists, none of the constants will be defined.

at line 3774
public array|false|string getLog()

Returns a log of the packets that have been sent and received.

Returns a string if NETSSH2LOGGING == NETSSH2LOGCOMPLEX, an array if NETSSH2LOGGING == NETSSH2LOGSIMPLE and false if !defined('NETSSH2LOGGING')

Return Value

array|false|string

at line 3800
public string _format_log(array $message_log, array $message_number_log)

Formats a log for printing

Parameters

array $message_log
array $message_number_log

Return Value

string

at line 3835
public string _format_log_helper(array $matches)

Helper function for formatlog

For use with pregreplacecallback()

Parameters

array $matches

Return Value

string

at line 3849
public _on_channel_open()

Helper function for agent->onchannel_open()

Used when channels are created to inform agent of said channel opening. Must be called after channel open confirmation received

at line 3865
public mixed _array_intersect_first(array $array1, array $array2)

Returns the first value of the intersection of two arrays or false if the intersection is empty.

The order is defined by the first parameter.

Parameters

array $array1
array $array2

Return Value

mixed False if intersection is empty, else intersected value.

at line 3881
public string getErrors()

Returns all errors

Return Value

string

at line 3892
public string getLastError()

Returns the last error

Return Value

string

at line 3907
public string getServerIdentification()

Return the server identification.

Return Value

string

at line 3920
public array getKexAlgorithms()

Return a list of the key exchange algorithms the server supports.

Return Value

array

at line 3933
public array getServerHostKeyAlgorithms()

Return a list of the host key (public key) algorithms the server supports.

Return Value

array

at line 3946
public array getEncryptionAlgorithmsClient2Server()

Return a list of the (symmetric key) encryption algorithms the server supports, when receiving stuff from the client.

Return Value

array

at line 3959
public array getEncryptionAlgorithmsServer2Client()

Return a list of the (symmetric key) encryption algorithms the server supports, when sending stuff to the client.

Return Value

array

at line 3972
public array getMACAlgorithmsClient2Server()

Return a list of the MAC algorithms the server supports, when receiving stuff from the client.

Return Value

array

at line 3985
public array getMACAlgorithmsServer2Client()

Return a list of the MAC algorithms the server supports, when sending stuff to the client.

Return Value

array

at line 3998
public array getCompressionAlgorithmsClient2Server()

Return a list of the compression algorithms the server supports, when receiving stuff from the client.

Return Value

array

at line 4011
public array getCompressionAlgorithmsServer2Client()

Return a list of the compression algorithms the server supports, when sending stuff to the client.

Return Value

array

at line 4024
public array getLanguagesServer2Client()

Return a list of the languages the server supports, when sending stuff to the client.

Return Value

array

at line 4037
public array getLanguagesClient2Server()

Return a list of the languages the server supports, when receiving stuff from the client.

Return Value

array

at line 4053
public string getBannerMessage()

Returns the banner message.

Quoting from the RFC, "in some jurisdictions, sending a warning message before authentication may be relevant for getting legal protection."

Return Value

string

at line 4067
public mixed getServerPublicHostKey()

Returns the server public host key.

Caching this the first time you connect to a server and checking the result on subsequent connections is recommended. Returns false if the server signature is not signed correctly with the public host key.

Return Value

mixed

at line 4212
public false|int getExitStatus()

Returns the exit status of an SSH command or false.

Return Value

false|int

at line 4226
public int getWindowColumns()

Returns the number of columns for the terminal window size.

Return Value

int

at line 4237
public int getWindowRows()

Returns the number of rows for the terminal window size.

Return Value

int

at line 4248
public setWindowColumns(int $value)

Sets the number of columns for the terminal window size.

Parameters

int $value

at line 4259
public setWindowRows(int $value)

Sets the number of rows for the terminal window size.

Parameters

int $value

at line 4271
public setWindowSize(int $columns = 80, int $rows = 24)

Sets the number of columns and rows for the terminal window size.

Parameters

int $columns
int $rows