Signatur
Beschreibung
openssl_pkey_export_to_file() schreibt einen privaten asymmetrischen Schlüssel im PEM-Format (Privacy Enhanced Mail) in eine Datei auf dem Dateisystem. Die Funktion eignet sich besonders dann, wenn Schlüssel persistent gespeichert werden sollen, etwa für TLS-Zertifikate, Code-Signing oder sichere Kommunikationsinfrastruktur.
Der Schlüssel kann optional mit einer Passphrase verschlüsselt werden, sodass er ohne diese nicht verwendet werden kann. Das schützt den privaten Schlüssel vor unbefugtem Zugriff selbst dann, wenn die Datei in falsche Hände gelangt. Intern wird dafür standardmäßig AES-128-CBC verwendet, sofern nicht über $options ein anderer Cipher vorgegeben wird.
Der Parameter $options akzeptiert ein assoziatives Array mit OpenSSL-Konfigurationswerten (z. B. cipher_algo, config), mit dem das Verhalten der Schlüsselerzeugung und -kodierung gesteuert werden kann. Wird null übergeben, gelten die systemweiten OpenSSL-Standardwerte.
Die Zieldatei wird vom Webserver-Prozess erzeugt; es ist daher wichtig, die Dateiberechtigungen restriktiv zu setzen (z. B. chmod 600) und die Datei außerhalb des Web-Roots zu speichern, um unbefugten Zugriff zu verhindern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | OpenSSLAsymmetricKey|array|string | Der zu exportierende private Schlüssel. Kann ein OpenSSLAsymmetricKey-Objekt (seit PHP 8.0), ein Array im Format [zertifikat, passphrase] oder ein PEM-kodierter String sein. |
|
| $output_filename Pflicht | string | Pfad zur Zieldatei, in die der Schlüssel geschrieben werden soll. Der Prozess muss Schreibrechte auf diesen Pfad haben. | |
| $passphrase | ?string | null | Optionale Passphrase, mit der der exportierte Schlüssel verschlüsselt wird. Wird null oder ein leerer String übergeben, wird der Schlüssel unverschlüsselt gespeichert. |
| $options | ?array | null | Optionales Array mit OpenSSL-Konfigurationsoptionen, z. B. ['config' => '/pfad/zu/openssl.cnf']. Überschreibt die systemweiten Standardwerte. |
Rückgabewert
true zurück, wenn der Schlüssel erfolgreich in die Datei geschrieben wurde. Im Fehlerfall (z. B. fehlende Schreibrechte, ungültiger Schlüssel) wird false zurückgegeben. Fehlermeldungen lassen sich mit openssl_error_string() abrufen.Beispiele
RSA-Schlüssel erzeugen und verschlüsselt in Datei speichern
<?php
// Neuen RSA-Schlüssel mit 4096 Bit erzeugen
$key = openssl_pkey_new([
'private_key_bits' => 4096,
'private_key_type' => OPENSSL_KEYTYPE_RSA,
]);
if ($key === false) {
die('Schlüsselerzeugung fehlgeschlagen: ' . openssl_error_string());
}
$datei = '/var/secure/keys/mein_privater_schluessel.pem';
$passphrase = 'sEhr$icheres-Pa55wort';
$erfolg = openssl_pkey_export_to_file($key, $datei, $passphrase);
if ($erfolg) {
chmod($datei, 0600); // Nur Eigentümer darf lesen/schreiben
echo "Schlüssel erfolgreich gespeichert.\n";
} else {
echo 'Fehler beim Speichern: ' . openssl_error_string() . "\n";
}Bereits vorhandenen Schlüssel ohne Passphrase exportieren
<?php
// Vorhandenen PEM-Schlüssel einlesen und unverschlüsselt erneut speichern
$pemInhalt = file_get_contents('/var/secure/keys/verschluesselt.pem');
$key = openssl_pkey_get_private($pemInhalt, 'alte-passphrase');
if ($key === false) {
die('Schlüssel konnte nicht geladen werden: ' . openssl_error_string());
}
$ziel = '/var/secure/keys/unverschluesselt.pem';
if (openssl_pkey_export_to_file($key, $ziel)) {
chmod($ziel, 0600);
echo "Unverschlüsselter Schlüssel wurde gespeichert.\n";
} else {
echo 'Fehler: ' . openssl_error_string() . "\n";
}// Wichtig · Fallstricke
Sicherheitshinweis: Private Schlüssel dürfen niemals im Web-Root gespeichert werden, da sie sonst über den Webserver abrufbar sein könnten. Speichere sie stets außerhalb des Document-Roots und setze restriktive Dateisystemrechte (chmod 600).
Unverschlüsselte Schlüssel: Wird keine Passphrase übergeben, liegt der Schlüssel im Klartext in der Datei. In Produktionsumgebungen sollte immer eine starke Passphrase verwendet werden, sofern kein automatischer Dienst den Schlüssel einlesen muss.
Fehlerdiagnose: Im Fehlerfall gibt die Funktion lediglich false zurück. Detaillierte OpenSSL-Fehlermeldungen können iterativ per openssl_error_string() ausgelesen werden, da OpenSSL intern einen Fehler-Stack pflegt.
PHP 8.0+: Das früher verwendete resource-Handle für Schlüssel wurde durch die Klasse OpenSSLAsymmetricKey ersetzt. Älterer Code, der is_resource() prüft, muss angepasst werden.