ssh2_auth_hostbased_file — Funktion · PHP-Referenz

Signatur

ssh2_auth_hostbased_file(resource $session, string $username, string $hostname, string $pubkeyfile, string $privkeyfile, string $passphrase = '', string $local_username = ''): bool

Beschreibung

ssh2_auth_hostbased_file() führt eine SSH-Authentifizierung basierend auf einem Host-Schlüsselpaar durch. Dabei wird der öffentliche Schlüssel des aufrufenden Hosts beim SSH-Server vorgewiesen, um die Identität des Hosts (und des zugehörigen Benutzers) zu bestätigen. Diese Methode unterscheidet sich von der einfachen Public-Key-Authentifizierung, da sie nicht nur den Benutzer, sondern auch den Host authentifiziert.

Die Funktion gehört zur PECL-Erweiterung ssh2 und erfordert, dass die Erweiterung installiert und geladen ist. Sie eignet sich besonders für automatisierte Server-zu-Server-Kommunikation, bei der der Server selbst als vertrauenswürdiger Host beim Zielserver bekannt ist.

Der SSH-Server muss so konfiguriert sein, dass er hostbased Authentication akzeptiert (in sshd_config: HostbasedAuthentication yes). Andernfalls schlägt die Authentifizierung fehl, auch wenn Schlüssel und Passphrase korrekt sind.

Üblicherweise wird zunächst eine SSH-Verbindung mit ssh2_connect() hergestellt, bevor diese Authentifizierungsmethode aufgerufen wird.

Parameter

Name	Typ	Beschreibung
$session Pflicht	resource	Eine aktive SSH-Verbindungsressource, die zuvor mit `ssh2_connect()` erstellt wurde.
$username Pflicht	string	Der Benutzername auf dem entfernten SSH-Server, mit dem die Sitzung authentifiziert werden soll.
$hostname Pflicht	string	Der Hostname des lokalen Hosts, wie er dem SSH-Server bekannt ist. Dieser Name muss mit dem im `known_hosts`-Eintrag des Servers übereinstimmen.
$pubkeyfile Pflicht	string	Pfad zur Datei mit dem öffentlichen Host-Schlüssel (z. B. `/etc/ssh/ssh_host_rsa_key.pub`).
$privkeyfile Pflicht	string	Pfad zur Datei mit dem privaten Host-Schlüssel (z. B. `/etc/ssh/ssh_host_rsa_key`). Dieser Schlüssel muss für den PHP-Prozess lesbar sein.
$passphrase	string	Optionale Passphrase zum Entsperren des privaten Schlüssels, falls dieser verschlüsselt ist. Leer lassen, wenn kein Passwort gesetzt ist.
$local_username	string	Optionaler lokaler Benutzername, unter dem die Verbindung lokal läuft. Wird er nicht angegeben, wird der Wert von `username` verwendet.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Authentifizierung erfolgreich war, andernfalls false. Bei einem Fehler wird zusätzlich eine PHP-Warnung ausgegeben.

Beispiele

Grundlegende hostbased SSH-Authentifizierung

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

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

// Host-basierte Authentifizierung mit Schlüsseldateien
$authenticated = ssh2_auth_hostbased_file(
    $connection,
    'deploy',                          // Remote-Benutzername
    'local.example.com',               // Lokaler Hostname
    '/etc/ssh/ssh_host_rsa_key.pub',   // Öffentlicher Host-Schlüssel
    '/etc/ssh/ssh_host_rsa_key'        // Privater Host-Schlüssel
);

if ($authenticated) {
    echo 'Authentifizierung erfolgreich!' . PHP_EOL;

    // SSH-Befehl ausführen
    $stream = ssh2_exec($connection, 'uname -a');
    stream_set_blocking($stream, true);
    echo stream_get_contents($stream);
} else {
    die('Authentifizierung fehlgeschlagen.');
}
?>

Authentifizierung erfolgreich! Linux remote.example.com 5.15.0-76-generic #83-Ubuntu SMP ...

Authentifizierung mit verschlüsseltem privaten Schlüssel und lokalem Benutzer

<?php
$connection = ssh2_connect('backup.example.com', 22);

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

// Mit Passphrase und explizitem lokalen Benutzer
$result = ssh2_auth_hostbased_file(
    $connection,
    'backupuser',                        // Ziel-Benutzer auf dem Server
    'appserver.internal',               // Hostname dieses Servers
    '/etc/ssh/ssh_host_ed25519_key.pub', // Öffentlicher Schlüssel
    '/etc/ssh/ssh_host_ed25519_key',     // Privater Schlüssel
    'geheime-passphrase',               // Passphrase des privaten Schlüssels
    'www-data'                          // Lokaler Benutzer (z. B. Webserver-User)
);

if ($result) {
    echo 'Verbindung als backupuser hergestellt.' . PHP_EOL;
    $sftp = ssh2_sftp($connection);
    // SFTP-Operationen ...
} else {
    echo 'Authentifizierung fehlgeschlagen. Server-Logs prüfen.' . PHP_EOL;
}
?>

Verbindung als backupuser hergestellt.

// Wichtig · Fallstricke

Sicherheitshinweise:

Der private Host-Schlüssel (/etc/ssh/ssh_host_*_key) ist normalerweise nur für root lesbar. Der PHP-Prozess (z. B. als www-data) muss entsprechende Berechtigungen erhalten, was ein erhebliches Sicherheitsrisiko darstellt. Erwägen Sie stattdessen die Authentifizierung per Benutzer-Schlüsselpaar mit ssh2_auth_pubkey_file().
Speichern Sie Passphrasen niemals im Klartext im Code. Verwenden Sie Umgebungsvariablen oder sichere Konfigurationsdateien.
Die hostbased Authentication gilt als weniger sicher als Public-Key-Authentifizierung auf Benutzerebene, da kompromittierte Hosts automatisch Zugang zu allen konfigurierten Zielen erhalten.
Diese Funktion erfordert die PECL-Erweiterung ssh2 (pecl install ssh2) sowie die Bibliothek libssh2.
Auf dem Zielserver muss in der /etc/ssh/sshd_config die Option HostbasedAuthentication yes gesetzt und der Hostkey in /etc/ssh/shosts.equiv oder ~/.shosts eingetragen sein.

Siehe auch

ssh2_connect ssh2_auth_pubkey_file ssh2_auth_password ssh2_auth_agent ssh2_exec ssh2_sftp