Signatur
Beschreibung
ssh2_publickey_add sendet einen öffentlichen Schlüssel an das Public-Key-Subsystem einer SSH2-Verbindung. Das Subsystem ermöglicht es, auf einem entfernten Server autorisierte Schlüssel programmatisch zu verwalten – also hinzuzufügen, aufzulisten und zu entfernen –, ohne manuell ~/.ssh/authorized_keys zu bearbeiten.
Die Funktion gehört zur PECL-Erweiterung ssh2 und erfordert eine aktive SSH2-Verbindung sowie ein zuvor mit ssh2_publickey_init initialisiertes Public-Key-Subsystem-Handle.
Der Parameter blob enthält den Roh-Binärinhalt des öffentlichen Schlüssels (nicht Base64-kodiert). Mit dem optionalen Parameter overwrite kann festgelegt werden, ob ein bereits vorhandener Schlüssel mit demselben Algorithmus und Blob überschrieben werden soll. Über attributes können zusätzliche Metadaten (z. B. Kommentare) als assoziatives Array übergeben werden.
Diese Funktion eignet sich besonders für automatisierte Deployment-Prozesse oder Verwaltungsskripte, bei denen SSH-Zugriff für bestimmte Benutzer programmatisch eingerichtet werden muss.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $pkey Pflicht | resource | Ein aktives Public-Key-Subsystem-Handle, das mit ssh2_publickey_init erstellt wurde. |
|
| $algoname Pflicht | string | Name des Schlüsselalgorithmus, z. B. 'ssh-rsa', 'ssh-dss' oder 'ecdsa-sha2-nistp256'. |
|
| $blob Pflicht | string | Der binäre Roh-Inhalt des öffentlichen Schlüssels. Bei einem Base64-kodierten Schlüssel (wie in authorized_keys) muss zuvor base64_decode() aufgerufen werden. |
|
| $overwrite | bool | false | Gibt an, ob ein bereits vorhandener identischer Schlüssel überschrieben werden soll. Bei false schlägt die Funktion fehl, wenn der Schlüssel bereits existiert. |
| $attributes | array | [] | Optionales assoziatives Array mit zusätzlichen Attributen (Metadaten) für den Schlüssel, z. B. ['comment' => 'deploy-key']. |
Rückgabewert
true bei Erfolg zurück, andernfalls false. Im Fehlerfall (z. B. Schlüssel existiert bereits und overwrite ist false) wird false zurückgegeben.Beispiele
Public Key per SSH2-Subsystem hinzufügen
<?php
// Verbindung aufbauen
$connection = ssh2_connect('example.com', 22);
ssh2_auth_password($connection, 'admin', 'geheimes_passwort');
// Public-Key-Subsystem initialisieren
$pkey = ssh2_publickey_init($connection);
// Base64-kodierten öffentlichen Schlüssel einlesen und dekodieren
$pubkeyBase64 = 'AAAAB3NzaC1yc2EAAAADAQABAAABgQC2...';
$blob = base64_decode($pubkeyBase64);
// Schlüssel hinzufügen
$result = ssh2_publickey_add($pkey, 'ssh-rsa', $blob, false, ['comment' => 'deploy-key']);
if ($result) {
echo "Schlüssel erfolgreich hinzugefügt.\n";
} else {
echo "Fehler beim Hinzufügen des Schlüssels.\n";
}
?>Schlüssel mit overwrite überschreiben
<?php
$connection = ssh2_connect('example.com', 22);
ssh2_auth_publickey($connection, 'deployer', '/home/deployer/.ssh/id_rsa.pub', '/home/deployer/.ssh/id_rsa');
$pkey = ssh2_publickey_init($connection);
// Schlüssel aus Datei laden
$pubkeyLine = trim(file_get_contents('/tmp/new_deploy_key.pub'));
$parts = explode(' ', $pubkeyLine);
$algo = $parts[0]; // z. B. 'ssh-rsa'
$blob = base64_decode($parts[1]); // Roh-Bytes des Schlüssels
// Vorhandenen Schlüssel überschreiben
$result = ssh2_publickey_add($pkey, $algo, $blob, true);
echo $result ? "Schlüssel aktualisiert.\n" : "Aktualisierung fehlgeschlagen.\n";
?>// Wichtig · Fallstricke
Sicherheitshinweise:
- Das SSH2-Public-Key-Subsystem (RFC 4819) wird nicht von allen SSH-Servern unterstützt. OpenSSH unterstützt es standardmäßig nicht. Prüfe vorab, ob der Zielserver das Subsystem aktiviert hat.
- Stelle sicher, dass nur vertrauenswürdige Schlüssel hinzugefügt werden. Das Hinzufügen eines kompromittierten Schlüssels gewährt dem Angreifer dauerhaften Zugang zum Server.
- Diese Funktion gehört zur PECL-Erweiterung
ssh2, die separat installiert werden muss (pecl install ssh2). - Der
blob-Parameter muss der rohe Binärkörper des Schlüssels sein. Inauthorized_keys-Dateien ist dieser Teil Base64-kodiert und muss erst mitbase64_decode()dekodiert werden.