openssl_cms_decrypt — Funktion · PHP-Referenz

Signatur

Beschreibung

openssl_cms_decrypt entschlüsselt eine nach dem CMS-Standard (RFC 5652) verschlüsselte Nachricht. CMS ist der Nachfolger von PKCS#7 und wird häufig in S/MIME-E-Mails sowie in anderen sicherheitskritischen Datenübertragungsszenarien eingesetzt. Die Funktion liest die verschlüsselte Nachricht aus einer Datei, entschlüsselt sie mit dem angegebenen Zertifikat und dem zugehörigen privaten Schlüssel und schreibt den Klartext in eine Ausgabedatei.

Der $certificate-Parameter identifiziert den Empfänger der Nachricht. Der optionale $private_key-Parameter enthält den zugehörigen privaten Schlüssel zur Entschlüsselung. Falls null übergeben wird, versucht PHP, den privaten Schlüssel aus dem Zertifikat selbst zu extrahieren (wenn dieser dort enthalten ist).

Über den Parameter $encoding kann das Format der Eingabedatei gesteuert werden. Mögliche Werte sind OPENSSL_ENCODING_SMIME für base64-kodierte S/MIME-Nachrichten, OPENSSL_ENCODING_DER für binäres DER-Format sowie OPENSSL_ENCODING_PEM für PEM-kodierte Nachrichten.

Diese Funktion ist besonders nützlich bei der Verarbeitung verschlüsselter E-Mails (S/MIME), beim sicheren Dateiempfang oder wenn Anwendungen CMS-basierte Nachrichten empfangen und deren Inhalt weiterverarbeiten müssen.

Parameter

Name	Typ	Default	Beschreibung
$input_filename Pflicht	string		Pfad zur Eingabedatei, die die verschlüsselte CMS-Nachricht enthält.
$output_filename Pflicht	string		Pfad zur Ausgabedatei, in die der entschlüsselte Klartext geschrieben wird.
$certificate Pflicht	OpenSSLCertificate\|string		Das Empfängerzertifikat, das zur Identifikation des Entschlüsselungsempfängers verwendet wird. Kann ein `OpenSSLCertificate`-Objekt oder ein Dateipfad (z. B. `file://pfad/zum/cert.pem`) bzw. ein PEM-String sein.
$private_key	OpenSSLAsymmetricKey\|OpenSSLCertificate\|string\|array\|null	null	Der private Schlüssel, der zum angegebenen Zertifikat gehört. Kann ein `OpenSSLAsymmetricKey`-Objekt, ein PEM-String, ein Dateipfad oder ein Array der Form `[key, passphrase]` sein. Bei `null` wird versucht, den Schlüssel aus dem Zertifikat zu extrahieren.
$encoding	int	OPENSSL_ENCODING_SMIME	Das Kodierungsformat der Eingabedatei. Mögliche Werte: `OPENSSL_ENCODING_SMIME` (Standard, S/MIME mit Base64), `OPENSSL_ENCODING_DER` (binäres DER) oder `OPENSSL_ENCODING_PEM` (PEM-Format).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück. Bei einem Fehler (z. B. falscher Schlüssel, ungültige Datei, nicht unterstütztes Format) wird false zurückgegeben. Fehlermeldungen können über openssl_error_string() abgerufen werden.

Beispiele

Einfaches Entschlüsseln einer S/MIME-CMS-Nachricht

<?php
// Zertifikat und privaten Schlüssel laden
$certificate = openssl_x509_read(file_get_contents('/pfad/zum/empfaenger.crt'));
$privateKey  = openssl_pkey_get_private(
    file_get_contents('/pfad/zum/empfaenger.key'),
    'mein_geheimes_passwort'
);

$inputFile  = '/pfad/zur/verschluesselten_nachricht.eml';
$outputFile = '/pfad/zur/entschluesselten_nachricht.txt';

if (openssl_cms_decrypt($inputFile, $outputFile, $certificate, $privateKey)) {
    echo 'Entschlüsselung erfolgreich.' . PHP_EOL;
    echo 'Klartext:' . PHP_EOL;
    echo file_get_contents($outputFile);
} else {
    echo 'Fehler bei der Entschlüsselung:' . PHP_EOL;
    while ($error = openssl_error_string()) {
        echo $error . PHP_EOL;
    }
}

Entschlüsselung erfolgreich. Klartext: Dies ist der geheime Nachrichteninhalt.

Entschlüsseln einer DER-kodierten CMS-Nachricht

<?php
// Zertifikat und Schlüssel als Dateipfade angeben
$certificate = 'file:///pfad/zum/empfaenger.crt';
$privateKey  = [
    'file:///pfad/zum/empfaenger.key',
    'mein_geheimes_passwort'
];

$inputFile  = '/pfad/zur/nachricht.der';
$outputFile = '/tmp/entschlüsselt.txt';

$success = openssl_cms_decrypt(
    $inputFile,
    $outputFile,
    $certificate,
    $privateKey,
    OPENSSL_ENCODING_DER
);

if ($success) {
    echo 'DER-Nachricht erfolgreich entschlüsselt.' . PHP_EOL;
} else {
    echo 'Entschlüsselung fehlgeschlagen: ' . openssl_error_string() . PHP_EOL;
}

DER-Nachricht erfolgreich entschlüsselt.

// Wichtig · Fallstricke

Sicherheitshinweise:

Private Schlüssel sollten niemals im Webroot gespeichert oder über HTTP erreichbar sein. Verwende stets Dateipfade außerhalb des öffentlich zugänglichen Verzeichnisses.
Passwörter für private Schlüssel sollten nicht im Quellcode gespeichert werden. Verwende Umgebungsvariablen oder sichere Konfigurationsmechanismen.
Die Ausgabedatei enthält den unverschlüsselten Klartext — stelle sicher, dass deren Dateiberechtigungen und Speicherort angemessen gesichert sind.
Fehler sollten im Produktivbetrieb nur intern protokolliert und nicht an den Endbenutzer ausgegeben werden, da OpenSSL-Fehlermeldungen interne Details preisgeben können.

Hinweis zur Verfügbarkeit: Die Funktion wurde mit PHP 8.0 eingeführt und ersetzt die ältere PKCS#7-basierte Funktion openssl_pkcs7_decrypt. Für neue Anwendungen sollte openssl_cms_decrypt bevorzugt werden.

Siehe auch

openssl_cms_encrypt openssl_cms_sign openssl_cms_verify openssl_pkcs7_decrypt openssl_error_string openssl_pkey_get_private