[DOC-CVS] [doc-en] master: Document ssh2_auth_pubkey() from pecl/ssh2 v1.4 (#5010)
[email protected] (Christian Weiske via GitHub) Thu, 5 Mar 2026 12:50:39 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Christian Weiske (cweiske)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2026-03-05T12:50:36Z
Commit: https://github.com/php/doc-en/commit/74ef2355c59e814d14f75a0792d22727be72f137
Raw diff: https://github.com/php/doc-en/commit/74ef2355c59e814d14f75a0792d22727be72f137.diff
Document ssh2_auth_pubkey() from pecl/ssh2 v1.4 (#5010)
Changelog: https://pecl.php.net/package-info.php?package=ssh2&version=1.4
Changed paths:
A reference/ssh2/functions/ssh2-auth-pubkey.xml
M reference/ssh2/functions/ssh2-auth-pubkey-file.xml
M reference/ssh2/functions/ssh2-connect.xml
M reference/ssh2/versions.xml
Diff:
diff --git a/reference/ssh2/functions/ssh2-auth-pubkey-file.xml b/reference/ssh2/functions/ssh2-auth-pubkey-file.xml
index bcbe76c1f271..c93364bf7e49 100644
--- a/reference/ssh2/functions/ssh2-auth-pubkey-file.xml
+++ b/reference/ssh2/functions/ssh2-auth-pubkey-file.xml
@@ -3,7 +3,7 @@
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-auth-pubkey-file">
<refnamediv>
<refname>ssh2_auth_pubkey_file</refname>
- <refpurpose>Authenticate using a public key</refpurpose>
+ <refpurpose>Authenticate using a public key read from a file</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -37,6 +37,7 @@
<term><parameter>username</parameter></term>
<listitem>
<simpara>
+ Name of the user to authenticate as on the remote server.
</simpara>
</listitem>
</varlistentry>
@@ -103,7 +104,7 @@ if (ssh2_auth_pubkey_file($connection, 'username',
&reftitle.notes;
<note>
<simpara>
- The underlying libssh library doesn't support partial auths very cleanly
+ The underlying libssh library doesn't support partial auths very cleanly.
That is, if you need to supply both a public key and a password it will
appear as if this function has failed. In this particular case a failure
from this call may just mean that auth hasn't been completed yet. You
@@ -114,6 +115,13 @@ if (ssh2_auth_pubkey_file($connection, 'username',
</note>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>ssh2_auth_pubkey</function></member>
+ </simplelist>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/reference/ssh2/functions/ssh2-auth-pubkey.xml b/reference/ssh2/functions/ssh2-auth-pubkey.xml
new file mode 100644
index 000000000000..29196fc92279
--- /dev/null
+++ b/reference/ssh2/functions/ssh2-auth-pubkey.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-auth-pubkey">
+ <refnamediv>
+ <refname>ssh2_auth_pubkey</refname>
+ <refpurpose>Authenticate using a public key in a variable</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>bool</type><methodname>ssh2_auth_pubkey</methodname>
+ <methodparam><type>resource</type><parameter>session</parameter></methodparam>
+ <methodparam><type>string</type><parameter>username</parameter></methodparam>
+ <methodparam><type>string</type><parameter>pubkey</parameter></methodparam>
+ <methodparam><type>string</type><parameter>privkey</parameter></methodparam>
+ <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>
+ Authenticate using a public key in a variable.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <variablelist>
+ <varlistentry>
+ <term><parameter>session</parameter></term>
+ <listitem>
+ <simpara>
+ An SSH connection link identifier, obtained from a call to
+ <function>ssh2_connect</function>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>username</parameter></term>
+ <listitem>
+ <simpara>
+ Name of the user to authenticate as on the remote server.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pubkey</parameter></term>
+ <listitem>
+ <simpara>
+ Public key in OpenSSH's format. It should look something like:
+ <literal>ssh-rsa AAAAB3NzaC1yc2EAAA....NX6sqSnHA8= rsa-key-20121110</literal>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>privkey</parameter></term>
+ <listitem>
+ <simpara>
+ Private OpenSSH key. It should begin with:
+ <literal>-----BEGIN RSA PRIVATE KEY-----</literal>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>passphrase</parameter></term>
+ <listitem>
+ <simpara>
+ If <parameter>privkey</parameter> is encrypted (which it should
+ be), the <parameter>passphrase</parameter> must be provided.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ &return.success;
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Authentication using a public key</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));
+$publicKey = file_get_contents('/home/username/.ssh/id_rsa.pub');
+$privateKey = file_get_contents('/home/username/.ssh/id_rsa');
+
+if (ssh2_auth_pubkey($connection, 'username',
+ $publicKey,
+ $privateKey, 'secret')) {
+ echo "Public Key Authentication Successful\n";
+} else {
+ die('Public Key Authentication Failed');
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <note>
+ <simpara>
+ The underlying libssh library doesn't support partial auths very cleanly.
+ That is, if you need to supply both a public key and a password it will
+ appear as if this function has failed. In this particular case a failure
+ from this call may just mean that auth hasn't been completed yet. You
+ would need to ignore this failure and continue on and call
+ <function>ssh2_auth_password</function> in order to complete
+ authentication.
+ </simpara>
+ </note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>ssh2_auth_pubkey_file</function></member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/ssh2/functions/ssh2-connect.xml b/reference/ssh2/functions/ssh2-connect.xml
index 1a05d4d86606..5a6ce331655b 100644
--- a/reference/ssh2/functions/ssh2-connect.xml
+++ b/reference/ssh2/functions/ssh2-connect.xml
@@ -288,6 +288,7 @@ if (!$connection) die('Connection failed');
<member><function>ssh2_fingerprint</function></member>
<member><function>ssh2_auth_none</function></member>
<member><function>ssh2_auth_password</function></member>
+ <member><function>ssh2_auth_pubkey</function></member>
<member><function>ssh2_auth_pubkey_file</function></member>
<member><function>ssh2_disconnect</function></member>
</simplelist>
diff --git a/reference/ssh2/versions.xml b/reference/ssh2/versions.xml
index b6aa2faaad49..24bf2fa898e4 100644
--- a/reference/ssh2/versions.xml
+++ b/reference/ssh2/versions.xml
@@ -8,6 +8,7 @@
<function name='ssh2_auth_hostbased_file' from='PECL ssh2 >= 0.9.0'/>
<function name='ssh2_auth_none' from='PECL ssh2 >= 0.9.0'/>
<function name='ssh2_auth_password' from='PECL ssh2 >= 0.9.0'/>
+ <function name='ssh2_auth_pubkey' from='PECL ssh2 >= 1.4.0'/>
<function name='ssh2_auth_pubkey_file' from='PECL ssh2 >= 0.9.0'/>
<function name='ssh2_connect' from='PECL ssh2 >= 0.9.0'/>
<function name='ssh2_disconnect' from='PECL ssh2 >= 1.0'/>