Signatur
Beschreibung
Mit openssl_pkcs12_export_to_file() wird ein X.509-Zertifikat, der zugehörige private Schlüssel und optional eine Zertifikatskette (CA-Bundle) im PKCS#12-Format (auch bekannt als PFX) in eine Datei geschrieben. Das PKCS#12-Format ist ein weit verbreitetes Austauschformat für Zertifikate und wird u. a. von Webservern, E-Mail-Clients und Betriebssystem-Zertifikatspeichern unterstützt.
Der Inhalt der Exportdatei wird mit einem Passwort (passphrase) symmetrisch verschlüsselt. Ohne dieses Passwort kann die Datei nicht importiert werden. Das Passwort sollte daher ausreichend komplex sein und sicher übertragen werden.
Über den Parameter options lassen sich zusätzliche Zertifikate (z. B. Intermediate-CAs) sowie ein lesbarer Anzeigename (friendly_name) übergeben. Typische Schlüssel sind extracerts für ein Array zusätzlicher PEM-Zertifikate und friendly_name für einen beschreibenden Namen des Eintrags.
Diese Funktion ist besonders nützlich beim Bereitstellen von TLS-Zertifikaten für Anwendungen, die PFX/PKCS#12-Dateien erwarten (z. B. IIS, Java-Keystores via Konvertierung oder Mobile-Device-Management-Systeme). Für die reine String-Ausgabe ohne Dateiexport steht openssl_pkcs12_export() zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $certificate Pflicht | OpenSSLCertificate|string | Das zu exportierende X.509-Zertifikat als OpenSSLCertificate-Objekt (ab PHP 8.0) oder als PEM-kodierter String bzw. Dateipfad mit dem Präfix file://. |
|
| $output_filename Pflicht | string | Absoluter oder relativer Pfad der Ausgabedatei, in die das PKCS#12-Paket geschrieben wird. Das Verzeichnis muss existieren und für PHP beschreibbar sein. | |
| $private_key Pflicht | OpenSSLAsymmetricKey|OpenSSLCertificate|array|string | Der zum Zertifikat gehörende private Schlüssel. Kann ein OpenSSLAsymmetricKey-Objekt, ein PEM-String, ein Dateipfad (file://...) oder ein Array der Form [key, passphrase] für passwortgeschützte Schlüssel sein. |
|
| $passphrase Pflicht | string | Passwort, mit dem die PKCS#12-Datei verschlüsselt wird. Wird beim späteren Import benötigt. Ein leerer String deaktiviert den Passwortschutz (nicht empfohlen). | |
| $options | array | [] | Optionales assoziatives Array mit zusätzlichen Einstellungen. Unterstützte Schlüssel: extracerts (Array zusätzlicher PEM-Zertifikate für die CA-Kette) und friendly_name (lesbarer Anzeigename des Zertifikateintrags). |
Rückgabewert
true zurück, wenn die PKCS#12-Datei erfolgreich erstellt wurde. Bei einem Fehler (z. B. ungültiges Zertifikat, nicht beschreibbares Verzeichnis oder Schlüssel passt nicht zum Zertifikat) wird false zurückgegeben. Fehlermeldungen können über openssl_error_string() abgerufen werden.Beispiele
Selbstsigniertes Zertifikat als PKCS#12-Datei exportieren
<?php
// Privaten Schlüssel erzeugen
$privateKey = openssl_pkey_new([
'private_key_bits' => 2048,
'private_key_type' => OPENSSL_KEYTYPE_RSA,
]);
// CSR erzeugen
$dn = [
'commonName' => 'example.com',
'organizationName' => 'Meine Firma GmbH',
'countryName' => 'DE',
];
$csr = openssl_csr_new($dn, $privateKey);
// Selbstsigniertes Zertifikat erzeugen (gültig 365 Tage)
$certificate = openssl_csr_sign($csr, null, $privateKey, 365);
// Als PKCS#12-Datei exportieren
$outputFile = '/tmp/mein-zertifikat.pfx';
$passphrase = 'geheimesPasswort123!';
$options = [
'friendly_name' => 'example.com Zertifikat',
];
if (openssl_pkcs12_export_to_file($certificate, $outputFile, $privateKey, $passphrase, $options)) {
echo "PKCS#12-Datei erfolgreich erstellt: {$outputFile}" . PHP_EOL;
} else {
echo 'Fehler beim Erstellen der PKCS#12-Datei: ' . openssl_error_string() . PHP_EOL;
}
openssl_pkey_free($privateKey);
Zertifikat mit Intermediate-CA-Kette exportieren
<?php
// Vorhandene PEM-Dateien laden
$certPem = file_get_contents('/etc/ssl/certs/mein-server.crt');
$keyPem = file_get_contents('/etc/ssl/private/mein-server.key');
$intermediatePem = file_get_contents('/etc/ssl/certs/intermediate-ca.crt');
$certificate = openssl_x509_read($certPem);
$privateKey = openssl_pkey_get_private($keyPem);
if ($certificate === false || $privateKey === false) {
die('Zertifikat oder Schlüssel konnte nicht geladen werden: ' . openssl_error_string());
}
$options = [
'friendly_name' => 'Produktions-Zertifikat',
'extracerts' => [$intermediatePem],
];
$success = openssl_pkcs12_export_to_file(
$certificate,
'/var/export/server-bundle.pfx',
$privateKey,
's3cur3P@ssphrase',
$options
);
if ($success) {
echo 'PKCS#12-Bundle mit CA-Kette erfolgreich exportiert.' . PHP_EOL;
} else {
echo 'Export fehlgeschlagen: ' . openssl_error_string() . PHP_EOL;
}
// Wichtig · Fallstricke
Sicherheitshinweise:
- Die exportierte PKCS#12-Datei enthält den privaten Schlüssel im Klartext (verschlüsselt nur durch das Passwort). Stellen Sie sicher, dass Dateisystemberechtigungen restriktiv gesetzt sind (
chmod 600) und die Datei nicht in öffentlich zugänglichen Verzeichnissen abgelegt wird. - Verwenden Sie niemals ein leeres Passwort für produktive Zertifikate. Ohne Passwort ist der private Schlüssel nach dem Entpacken sofort zugänglich.
- Übertragen Sie die Passphrase niemals zusammen mit der PKCS#12-Datei über denselben unsicheren Kanal.
- Ab PHP 8.0 werden ressourcenbasierte Parameter (
resource) durch Objekte (OpenSSLCertificate,OpenSSLAsymmetricKey) ersetzt. Alter Code mitopenssl_x509_read()-Ressourcen funktioniert weiterhin, erzeugt aber Deprecation-Hinweise. - Fehler werden über die interne OpenSSL-Fehlerwarteschlange gemeldet; lesen Sie diese mit
openssl_error_string()in einer Schleife aus, um alle Fehlermeldungen zu erhalten.