openssl_pkey_new — Funktion · PHP-Referenz

Signatur

openssl_pkey_new(array $options = []): OpenSSLAsymmetricKey|false

Beschreibung

openssl_pkey_new() generiert ein neues asymmetrisches Schlüsselpaar auf Basis der übergebenen Konfigurationsoptionen. Das zurückgegebene Ressource-Objekt (ab PHP 8.0: OpenSSLAsymmetricKey) repräsentiert den privaten Schlüssel und enthält implizit auch den zugehörigen öffentlichen Schlüssel. Letzterer lässt sich mit openssl_pkey_get_details() extrahieren.

Typische Anwendungsfälle sind die Erzeugung von RSA-Schlüsseln für TLS-Zertifikate, SSH-ähnliche Authentifizierung, digitale Signaturen oder asymmetrische Verschlüsselung. Über das $options-Array kann der Schlüsseltyp (private_key_type), die Schlüssellänge (private_key_bits) sowie eine OpenSSL-Konfigurationsdatei (config) angegeben werden.

Für Elliptic Curve-Schlüssel (EC) muss zusätzlich curve_name gesetzt werden (z. B. 'prime256v1'). Eine Liste verfügbarer Kurven liefert openssl_get_curve_names(). Ohne explizite Angaben erzeugt die Funktion standardmäßig einen RSA-Schlüssel mit 2048 Bit.

Der erzeugte Schlüssel sollte mit openssl_pkey_export() oder openssl_pkey_export_to_file() gesichert und mit einem Passwort geschützt werden. Bei Fehler gibt die Funktion false zurück; Fehlerdetails sind über openssl_error_string() abrufbar.

Parameter

Name Typ Default Beschreibung

$options

array

[]

Name	Typ	Default	Beschreibung
$options	array	[]	Optionales Konfigurationsarray. Mögliche Schlüssel: `private_key_bits` (int) – Schlüssellänge in Bit (z. B. 2048, 4096 für RSA) `private_key_type` (int) – Schlüsseltyp: `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC` `curve_name` (string) – Name der EC-Kurve, z. B. `'prime256v1'` oder `'secp384r1'` `config` (string) – Pfad zu einer alternativen `openssl.cnf`-Datei `encrypt_key` (bool) – Gibt an, ob der exportierte Schlüssel verschlüsselt werden soll `encrypt_key_cipher` (int) – Cipher-Konstante für die Schlüsselverschlüsselung

Optionales Konfigurationsarray. Mögliche Schlüssel:

private_key_bits (int) – Schlüssellänge in Bit (z. B. 2048, 4096 für RSA)
private_key_type (int) – Schlüsseltyp: OPENSSL_KEYTYPE_RSA, OPENSSL_KEYTYPE_DSA, OPENSSL_KEYTYPE_DH, OPENSSL_KEYTYPE_EC
curve_name (string) – Name der EC-Kurve, z. B. 'prime256v1' oder 'secp384r1'
config (string) – Pfad zu einer alternativen openssl.cnf-Datei
encrypt_key (bool) – Gibt an, ob der exportierte Schlüssel verschlüsselt werden soll
encrypt_key_cipher (int) – Cipher-Konstante für die Schlüsselverschlüsselung

Rückgabewert

Typ

OpenSSLAsymmetricKey|false

Beschreibung

Bei Erfolg ein OpenSSLAsymmetricKey-Objekt (vor PHP 8.0: eine resource), das den erzeugten privaten Schlüssel repräsentiert. Bei Fehler wird false zurückgegeben.

Beispiele

RSA-Schlüsselpaar erzeugen und exportieren

<?php
// Neuen RSA-4096-Schlüssel erzeugen
$privateKey = openssl_pkey_new([
    'private_key_bits' => 4096,
    'private_key_type' => OPENSSL_KEYTYPE_RSA,
]);

if ($privateKey === false) {
    while ($error = openssl_error_string()) {
        echo 'OpenSSL-Fehler: ' . $error . PHP_EOL;
    }
    exit(1);
}

// Privaten Schlüssel als PEM-String exportieren (mit Passwortschutz)
openssl_pkey_export($privateKey, $privatePem, 'meinGeheimesPasswort');
echo $privatePem;

// Öffentlichen Schlüssel extrahieren
$details = openssl_pkey_get_details($privateKey);
echo $details['key']; // Öffentlicher Schlüssel als PEM

-----BEGIN ENCRYPTED PRIVATE KEY----- ... -----END ENCRYPTED PRIVATE KEY----- -----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----

Elliptic-Curve-Schlüssel (EC) mit Kurve prime256v1 erzeugen

<?php
// EC-Schlüssel auf Basis der Kurve prime256v1 (NIST P-256) erzeugen
$ecKey = openssl_pkey_new([
    'private_key_type' => OPENSSL_KEYTYPE_EC,
    'curve_name'       => 'prime256v1',
]);

if ($ecKey === false) {
    die('Schlüsselerzeugung fehlgeschlagen: ' . openssl_error_string());
}

$details = openssl_pkey_get_details($ecKey);
echo 'Schlüsseltyp : ' . $details['type'] . PHP_EOL;
echo 'Kurvennamen  : ' . $details['ec']['curve_name'] . PHP_EOL;
echo 'Bits         : ' . $details['bits'] . PHP_EOL;

// Unverschlüsselten privaten Schlüssel exportieren
openssl_pkey_export($ecKey, $pem);
echo $pem;

Schlüsseltyp : 6 Kurvennamen : prime256v1 Bits : 256 -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----

// Wichtig · Fallstricke

Sicherheitshinweise:

Für RSA sollten mindestens 2048 Bit verwendet werden; 4096 Bit empfehlen sich für langlebige Schlüssel.
Private Schlüssel niemals ohne Passwortschutz auf der Festplatte speichern. openssl_pkey_export() und openssl_pkey_export_to_file() unterstützen eine Passphrase als dritten Parameter.
Auf Windows-Systemen kann OpenSSL eine gültige openssl.cnf benötigen. Falls Fehler auftreten, den Pfad explizit über 'config' im $options-Array angeben.
Ab PHP 8.0 wurde der Rückgabewert von resource auf OpenSSLAsymmetricKey geändert. Code, der auf is_resource() prüft, muss angepasst werden.
Die verfügbaren Schlüsseltypen hängen von der installierten OpenSSL-Version ab. EC-Unterstützung erfordert mindestens OpenSSL 1.0.2.

Siehe auch

openssl_pkey_export openssl_pkey_export_to_file openssl_pkey_get_details openssl_pkey_get_public openssl_pkey_get_private openssl_get_curve_names openssl_csr_new openssl_error_string