Flesh out ssh2_connect()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175728 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sara Golemon 2004-12-27 23:18:43 +00:00
parent 84649cab8c
commit 9066a2ede4

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.ssh2-connect">
<refnamediv>
@ -18,10 +18,252 @@
<methodparam choice="opt"><type>array</type><parameter>callbacks</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Establish a connection to a remote SSH server and return a resource on success, false on error
</simpara>
<simpara>
<parameter>methods</parameter> may be an associative array with up to four parameters
as described below.
</simpara>
<para>
<table>
<title><parameter>methods</parameter> may be an associative array
with any or all of the following parameters.</title>
<tgroup cols="3">
<thead>
<row>
<entry>Index</entry>
<entry>Meaning</entry>
<entry>Supported Values*</entry>
</row>
</thead>
<tbody>
<row>
<entry>kex</entry>
<entry>
List of key exchange methods to advertise, coma separated
in order of preference.
</entry>
<entry>
<literal>diffie-hellman-group1-sha1</literal>,
<literal>diffie-hellman-group4-sha1</literal>, and
<literal>diffie-hellman-group-exchange-sha1</literal>
</entry>
</row>
<row>
<entry>hostkey</entry>
<entry>
List of hostkey methods to advertise, come separated
in order of preference.
</entry>
<entry>
<literal>ssh-rsa</literal> and
<literal>ssh-dss</literal>
</entry>
</row>
<row>
<entry>client_to_server</entry>
<entry>
Associative array containing crypt, compression, and
message authentication code (MAC) method preferences
for messages sent from client to server.
</entry>
<entry/>
</row>
<row>
<entry>server_to_client</entry>
<entry>
Associative array containing crypt, compression, and
message authentication code (MAC) method preferences
for messages sent from client to server.
</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
</para>
<simpara>
* - Supported Values are dependent on methods supported by underlying library.
See <ulink url="&url.libssh2;">libssh2</ulink> documentation for additional
information.
</simpara>
<para>
<table>
<title>
<parameter>client_to_server</parameter> and
<parameter>server_to_client</parameter> may be an associative array
with any or all of the following parameters.
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Index</entry>
<entry>Meaning</entry>
<entry>Supported Values*</entry>
</row>
</thead>
<tbody>
<row>
<entry>crypt</entry>
<entry>List of crypto methods to advertise, coma separated
in order of preference.</entry>
<entry>
<literal>rijndael-cbc@lysator.liu.se</literal>,
<literal>aes256-cbc</literal>,
<literal>aes192-cbc</literal>,
<literal>aes128-cbc</literal>,
<literal>3des-cbc</literal>,
<literal>blowfish-cbc</literal>,
<literal>cast128-cbc</literal>,
<literal>arcfour</literal>, and
<literal>none**</literal>
</entry>
</row>
<row>
<entry>comp</entry>
<entry>List of compression methods to advertise, coma separated
in order of preference.</entry>
<entry>
<literal>zlib</literal> and
<literal>none</literal>
</entry>
</row>
<row>
<entry>mac</entry>
<entry>List of MAC methods to advertise, come separated
in order of preference.</entry>
<entry>
<literal>hmac-sha1</literal>,
<literal>hmac-sha1-96</literal>,
<literal>hmac-ripemd160</literal>,
<literal>hmac-ripemd160@openssh.com</literal>, and
<literal>none**</literal>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<title>Crypt and MAC method "<literal>none</literal>"</title>
<simpara>
For security reasons, <literal>none</literal> is disabled by the underlying
<ulink url="&url.libssh2;">libssh2</ulink> library unless explicitly enabled
during build time by using the appropriate ./configure options. See documentation
for the underlying library for more information.
</simpara>
</note>
<para>
<table>
<title><parameter>callbackss</parameter> may be an associative array
with any or all of the following parameters.</title>
<tgroup cols="3">
<thead>
<row>
<entry>Index</entry>
<entry>Meaning</entry>
<entry>Prototype</entry>
</row>
</thead>
<tbody>
<row>
<entry>ignore</entry>
<entry>
Name of function to call when an
<constant>SSH2_MSG_IGNORE</constant>
packet is received
</entry>
<entry>void ignore_cb($message)</entry>
</row>
<row>
<entry>debug</entry>
<entry>
Name of function to call when an
<constant>SSH2_MSG_DEBUG</constant>
packet is received
</entry>
<entry>void debug_cb($message, $language, $always_display)</entry>
</row>
<row>
<entry>macerror</entry>
<entry>
Name of function to call when a
packet is received but the message authentication
code failed. If the callback returns &true;,
the mismatch will be ignored, otherwise the
connection will be terminated.
</entry>
<entry>bool macerror_cb($packet)</entry>
</row>
<row>
<entry>disconnect</entry>
<entry>
Name of function to call when an
<constant>SSH2_MSG_DISCONNECT</constant>
packet is received
</entry>
<entry>void disconnect_cb($reason, $message, $language)</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<example>
<title>
Open a connection forcing 3des-cbc when sending packets,
any strength aes cipher when receiving packets,
no compression in either direction,
and Group1 key exchange.
</title>
<programlisting role="php">
<![CDATA[
<?php
/* Notify the user if the server terminates the connection */
function my_ssh_disconnect($reason, $message, $language) {
printf("Server disconnected with reason code [%d] and message: %s\n",
$reason, $message);
}
$methods = array(
'kex' => 'diffie-hellman-group1-sha1',
'client_to_server' => array(
'crypt' => '3des-cbc',
'comp' => 'none'),
'server_to_client' => array(
'crypt' => 'aes256-cbc,aes192-cbc,aes128-cbc',
'comp' => 'none'));
$callbacks = array('disconnect' => 'my_ssh_disconnect');
$connection = ssh2_connect('shell.example.com', 22, $methods, $callbacks);
if (!$connect) die('Connection failed');
?>
]]>
</programlisting>
</example>
<simpara>
Once connected, the client should verify the server's hostkey
using <function>ssh2_fingerprint</function>, then authenticate
using either password or public key.
</simpara>
<simpara>
See Also:
<function>ssh2_fingerprint</function>,
<function>ssh2_auth_none</function>,
<function>ssh2_auth_password</function>, and
<function>ssh2_auth_pubkey_file</function>
</simpara>
</refsect1>
</refentry>