ssh2_connect — Funktion · PHP-Referenz

Signatur

ssh2_connect(string $host, int $port = 22, array $methods = [], array $callbacks = []): resource|false

Beschreibung

ssh2_connect() öffnet eine SSH2-Verbindung zum angegebenen Host und Port. Die Funktion gehört zur PECL-Erweiterung ssh2 und muss daher explizit installiert und in der php.ini aktiviert werden. Der Rückgabewert ist eine Verbindungsressource, die für alle weiteren SSH2-Funktionen wie ssh2_auth_password(), ssh2_sftp() oder ssh2_exec() benötigt wird.

Über das optionale Array $methods können Kryptographie-Algorithmen für den Handshake explizit konfiguriert werden, z. B. bevorzugte Schlüsselaustauch-, Verschlüsselungs- und MAC-Algorithmen. Das ist sinnvoll, wenn bestimmte schwache Algorithmen auf dem Server deaktiviert werden sollen oder wenn maximale Kompatibilität mit älteren SSH-Servern gewährleistet werden muss.

Das optionale Array $callbacks erlaubt es, PHP-Callable-Funktionen zu registrieren, die bei bestimmten Ereignissen aufgerufen werden – etwa zur Überprüfung des Server-Host-Keys (hostkey) oder zur Verhandlung von Verbindungsparametern. Besonders die Überprüfung des Host-Keys ist aus Sicherheitsgründen empfehlenswert, um Man-in-the-Middle-Angriffe zu verhindern.

Nach dem Verbindungsaufbau muss sich der Client mit einer der verfügbaren Authentifizierungsmethoden (Passwort, Public-Key, Keyboard-Interactive usw.) authentifizieren, bevor SSH-Befehle ausgeführt oder Dateien übertragen werden können.

Parameter

Name	Typ	Default	Beschreibung
$host Pflicht	string		Hostname oder IP-Adresse des SSH-Servers, zu dem die Verbindung hergestellt werden soll.
$port	int	22	TCP-Port des SSH-Servers. Standardmäßig `22`; kann angepasst werden, wenn der Server auf einem anderen Port lauscht.
$methods	array	[]	Assoziatives Array zur Konfiguration von Kryptographie-Methoden. Mögliche Schlüssel sind u. a. `kex` (Schlüsselaustausch), `client_to_server` und `server_to_client` (jeweils mit Unter-Schlüsseln `crypt`, `mac`, `comp`).
$callbacks	array	[]	Assoziatives Array mit PHP-Callables für Verbindungsereignisse. Wichtigster Schlüssel: `hostkey` – eine Funktion zur Überprüfung des Server-Host-Keys, die `true` zurückgeben muss, wenn der Key akzeptiert wird.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt eine SSH2-Verbindungsressource zurück, die für nachfolgende SSH2-Funktionen verwendet wird. Bei einem Fehler (z. B. Host nicht erreichbar oder Verbindung abgelehnt) wird false zurückgegeben.

Beispiele

Einfache SSH2-Verbindung mit Passwort-Authentifizierung

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

if ($connection === false) {
    die('Verbindung zum SSH-Server fehlgeschlagen.');
}

// Authentifizierung mit Benutzername und Passwort
if (!ssh2_auth_password($connection, 'meinbenutzer', 'geheimesPasswort')) {
    die('Authentifizierung fehlgeschlagen.');
}

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

echo $output;

Verbindung mit Host-Key-Überprüfung und Public-Key-Authentifizierung

<?php
// Bekannter Fingerprint des Servers (vorher ermitteln und sicher speichern)
$knownFingerprint = 'a1:b2:c3:d4:e5:f6:07:08:09:0a:0b:0c:0d:0e:0f:10';

$callbacks = [
    'hostkey' => function (string $message, string $hostkey, $resource) use ($knownFingerprint): bool {
        $fingerprint = ssh2_fingerprint($resource, SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX);
        if ($fingerprint !== $knownFingerprint) {
            error_log('SSH Host-Key stimmt nicht überein! Möglicher MITM-Angriff.');
            return false;
        }
        return true;
    },
];

$connection = ssh2_connect('ssh.example.com', 22, [], $callbacks);

if ($connection === false) {
    die('Verbindung oder Host-Key-Überprüfung fehlgeschlagen.');
}

// Authentifizierung mit Public Key
if (!ssh2_auth_pubkey_file(
    $connection,
    'meinbenutzer',
    '/home/user/.ssh/id_rsa.pub',
    '/home/user/.ssh/id_rsa',
    'optionalePassphrase'
)) {
    die('Public-Key-Authentifizierung fehlgeschlagen.');
}

echo 'Erfolgreich verbunden und authentifiziert.' . PHP_EOL;

Erfolgreich verbunden und authentifiziert.

// Wichtig · Fallstricke

Sicherheitshinweis: Ohne Überprüfung des Server-Host-Keys (über den hostkey-Callback) ist die Verbindung anfällig für Man-in-the-Middle-Angriffe. In Produktivumgebungen sollte der Fingerprint des Servers stets gegen einen vorher gespeicherten, bekannten Wert verglichen werden.

Passwörter im Code: Passwörter oder Passphrases sollten niemals hartcodiert im Quelltext stehen. Besser ist die Verwendung von Umgebungsvariablen oder sicheren Konfigurationsdateien außerhalb des Web-Roots.

PECL-Abhängigkeit: ssh2_connect() ist kein Bestandteil der PHP-Kernbibliothek. Die PECL-Erweiterung ssh2 muss separat installiert werden (pecl install ssh2) und basiert auf libssh2. Alternativ kann die Bibliothek phpseclib verwendet werden, die kein natives Modul benötigt.

Ressource vs. Objekt: In älteren Versionen der Erweiterung wird eine PHP-Ressource zurückgegeben. Zukünftige Versionen können auf PHP-Objekte umstellen – der Rückgabewert sollte daher stets mit === false auf Fehler geprüft werden.

Siehe auch

ssh2_auth_password ssh2_auth_pubkey_file ssh2_exec ssh2_sftp ssh2_fingerprint ssh2_disconnect