ssh2_auth_pubkey_file — Funktion · PHP-Referenz

Signatur

ssh2_auth_pubkey_file(resource $session, string $username, string $pubkeyfile, string $privkeyfile, string $passphrase = ''): bool

Beschreibung

ssh2_auth_pubkey_file() führt eine Public-Key-Authentifizierung für eine bestehende SSH-Verbindung durch. Dabei werden der öffentliche und der private Schlüssel aus Dateien auf dem lokalen Dateisystem gelesen. Diese Methode gilt als sicherer als die Passwort-Authentifizierung, da kein Passwort über das Netzwerk übertragen wird.

Die Funktion wird typischerweise nach dem Aufbau einer SSH-Verbindung mit ssh2_connect() aufgerufen. Der öffentliche Schlüssel muss im OpenSSH-Format vorliegen, der private Schlüssel im PEM-Format. Ist der private Schlüssel mit einer Passphrase geschützt, muss diese als letzter Parameter übergeben werden.

Die Funktion gehört zur PECL-Erweiterung ssh2, die separat installiert werden muss. Sie eignet sich besonders für automatisierte Server-zu-Server-Kommunikation, Deployment-Skripte oder den Zugriff auf entfernte Systeme ohne interaktive Passworteingabe.

Der öffentliche Schlüssel (pubkeyfile) muss auf dem Zielserver in der Datei ~/.ssh/authorized_keys hinterlegt sein.
Die Pfade zu den Schlüsseldateien müssen für den PHP-Prozess lesbar sein.
Dateiberechtigungen sollten restriktiv gesetzt sein (z. B. 600 für private Schlüssel).

Parameter

Name	Typ	Beschreibung
$session Pflicht	resource	Eine SSH-Verbindungsressource, die zuvor mit `ssh2_connect()` erstellt wurde.
$username Pflicht	string	Der Benutzername, mit dem die Authentifizierung auf dem entfernten Server stattfinden soll.
$pubkeyfile Pflicht	string	Absoluter oder relativer Pfad zur Datei mit dem öffentlichen Schlüssel (z. B. `/home/user/.ssh/id_rsa.pub`). Muss im OpenSSH-Format vorliegen.
$privkeyfile Pflicht	string	Absoluter oder relativer Pfad zur Datei mit dem privaten Schlüssel (z. B. `/home/user/.ssh/id_rsa`). Muss im PEM-Format vorliegen.
$passphrase	string	Optionale Passphrase zum Entschlüsseln des privaten Schlüssels, falls dieser passwortgeschützt ist.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei erfolgreicher Authentifizierung zurück, false bei einem Fehler (z. B. falsche Schlüssel, nicht lesbarer Schlüssel oder Authentifizierungsfehler auf dem Server).

Beispiele

Einfache Public-Key-Authentifizierung ohne Passphrase

<?php
// SSH-Verbindung aufbauen
$connection = ssh2_connect('example.com', 22);

if (!$connection) {
    die('Verbindung fehlgeschlagen.');
}

// Authentifizierung mit Schlüsselpaar
$authenticated = ssh2_auth_pubkey_file(
    $connection,
    'deploy',
    '/home/deploy/.ssh/id_rsa.pub',
    '/home/deploy/.ssh/id_rsa'
);

if (!$authenticated) {
    die('Authentifizierung fehlgeschlagen.');
}

echo 'Erfolgreich authentifiziert!' . PHP_EOL;

// Befehl auf dem entfernten Server ausführen
$stream = ssh2_exec($connection, 'ls /var/www');
stream_set_blocking($stream, true);
echo stream_get_contents($stream);

Erfolgreich authentifiziert! html myapp logs

Authentifizierung mit passwortgeschütztem privaten Schlüssel

<?php
$host = 'deploy.example.com';
$port = 22;
$user = 'webuser';
$pubKey  = '/etc/deploy/keys/id_rsa.pub';
$privKey = '/etc/deploy/keys/id_rsa';
$passphrase = 'meinGeheimesPasswort';

$connection = ssh2_connect($host, $port, [
    'hostkey' => 'ssh-rsa'
]);

if (!$connection) {
    throw new RuntimeException('SSH-Verbindung zu ' . $host . ' konnte nicht hergestellt werden.');
}

if (!ssh2_auth_pubkey_file($connection, $user, $pubKey, $privKey, $passphrase)) {
    throw new RuntimeException('Public-Key-Authentifizierung für Benutzer "' . $user . '" fehlgeschlagen.');
}

// SFTP-Sitzung für Dateiübertragung starten
$sftp = ssh2_sftp($connection);
$remoteFile = 'ssh2.sftp://' . intval($sftp) . '/var/www/myapp/deploy.log';

file_put_contents($remoteFile, date('Y-m-d H:i:s') . ': Deployment erfolgreich.' . PHP_EOL, FILE_APPEND);
echo 'Deployment-Log aktualisiert.' . PHP_EOL;

Deployment-Log aktualisiert.

// Wichtig · Fallstricke

Sicherheitshinweise:

Die Datei des privaten Schlüssels sollte ausschließlich für den PHP-Prozess-Benutzer lesbar sein (Dateiberechtigung 600 oder restriktiver). Zu offene Berechtigungen können dazu führen, dass libssh2 die Authentifizierung verweigert.
Speichern Sie private Schlüssel niemals im Web-Root oder an öffentlich zugänglichen Speicherorten.
Verwenden Sie nach Möglichkeit passwortgeschützte private Schlüssel, auch wenn die Passphrase im Skript abgelegt werden muss — das ist sicherer als ungeschützte Schlüssel.
Pfade zu Schlüsseldateien sollten niemals aus Benutzereingaben stammen, da sonst Path-Traversal-Angriffe möglich sind.
Diese Funktion setzt die PECL-Erweiterung ssh2 voraus, die auf den meisten Standard-PHP-Installationen nicht enthalten ist und separat installiert werden muss (pecl install ssh2).
Die Erweiterung nutzt intern die Bibliothek libssh2. Je nach Version können bestimmte Schlüsselformate (z. B. OpenSSH-Format für private Schlüssel ab OpenSSH 6.5) nicht unterstützt werden. In solchen Fällen hilft es, den Schlüssel mit ssh-keygen -p -m PEM ins klassische PEM-Format zu konvertieren.

Siehe auch

ssh2_connect ssh2_auth_password ssh2_auth_agent ssh2_auth_none ssh2_exec ssh2_sftp