CryptMsgOpenToDecode-Funktion (wincrypt.h)

Die CryptMsgOpenToDecode-Funktion öffnet eine kryptografische Nachricht zum Decodieren und gibt ein Handle der geöffneten Nachricht zurück. Die Nachricht bleibt geöffnet, bis die Funktion CryptMsgClose aufgerufen wird.

Wichtige Änderungen, die sich auf die Behandlung von umhüllten Nachrichten auswirken, wurden an CryptoAPI vorgenommen, um die S/MIME-Interoperabilität ( Secure/Multipurpose Internet Mail Extensions ) zu unterstützen. Ausführliche Informationen finden Sie im Abschnitt Hinweise von CryptMsgOpenToEncode.

Syntax

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Parameter

[in] dwMsgEncodingType

Gibt den verwendeten Codierungstyp an. Es ist immer akzeptabel, sowohl den Zertifikat- als auch den Nachrichtencodierungstyp anzugeben, indem sie mit einem bitweisen OR-Vorgang kombiniert werden, wie im folgenden Beispiel gezeigt:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Derzeit definierte Codierungstypen sind:

• X509_ASN_ENCODING
• PKCS_7_ASN_ENCODING

[in] dwFlags

Dieser Parameter kann eines der folgenden Flags sein.

[in] dwMsgType

Gibt den Typ der zu decodierenden Nachricht an. In den meisten Fällen wird der Nachrichtentyp aus dem Nachrichtenheader bestimmt, und für diesen Parameter wird null übergeben. In einigen Fällen, insbesondere bei Internet Explorer 3.0, haben Nachrichten keine Header, und der Typ der zu decodierenden Nachricht muss in diesem Funktionsaufruf angegeben werden. Wenn der Header fehlt und null für diesen Parameter übergeben wird, schlägt die Funktion fehl.

Dieser Parameter kann einer der folgenden vordefinierten Nachrichtentypen sein.

[in] hCryptProv

Dieser Parameter wird nicht verwendet und sollte auf NULL festgelegt werden.

Windows Server 2003 und Windows XP: Gibt ein Handle an, das der Kryptografieanbieter zum Hashing der Nachricht verwenden soll. Für signierte Nachrichten wird hCryptProv für die Signaturüberprüfung verwendet. Der Datentyp dieses Parameters ist HCRYPTPROV.

Legen Sie diesen Parameter auf NULL fest, es sei denn, es gibt einen starken Grund für die Übergabe eines bestimmten Kryptografieanbieters in hCryptProv. Durch die Übergabe von NULL wird der Standard-RSA- oder DSS-Anbieter abgerufen, bevor Hash-, Signaturüberprüfungs- oder Empfängerverschlüsselungsvorgänge ausgeführt werden.

[in] pRecipientInfo

Dieser Parameter ist für die zukünftige Verwendung reserviert und muss NULL sein.

[in, optional] pStreamInfo

Wenn kein Streaming verwendet wird, muss dieser Parameter auf NULL festgelegt werden.

Wenn Streaming verwendet wird, ist der pStreamInfo-Parameter ein Zeiger auf eine CMSG_STREAM_INFO Struktur, die einen Zeiger auf einen Rückruf enthält, der aufgerufen werden soll, wenn CryptMsgUpdate ausgeführt wird oder wenn CryptMsgControl beim Decodieren einer gestreamten umhüllten Nachricht ausgeführt wird.

Bei einer signierten Nachricht wird dem Rückruf ein Block der decodierten Bytes aus dem inneren Inhalt der Nachricht übergeben.

Bei einer umhüllten Nachricht müssen Sie nach jedem Aufruf von CryptMsgUpdate überprüfen, ob die eigenschaft CMSG_ENVELOPE_ALGORITHM_PARAM verfügbar ist, indem Sie die CryptMsgGetParam-Funktion aufrufen. CryptMsgGetParam schlägt fehl, und GetLastError gibt CRYPT_E_STREAM_MSG_NOT_READY zurück, bis CryptMsgUpdate genügend Nachrichten verarbeitet hat, um die CMSG_ENVELOPE_ALGORITHM_PARAM-Eigenschaft verfügbar zu machen. Wenn die CMSG_ENVELOPE_ALGORITHM_PARAM-Eigenschaft verfügbar ist, können Sie die Empfänger durchlaufen und eine CERT_INFO-Struktur für jeden Empfänger abrufen, indem Sie die CryptMsgGetParam-Funktion verwenden, um die CMSG_RECIPIENT_INFO_PARAM-Eigenschaft abzurufen. Um einen Denial-of-Service-Angriff durch eine umhüllte Nachricht mit einem künstlich großen Headerblock zu verhindern, müssen Sie den Speicher nachverfolgen, der während dieses Prozesses an die CryptMsgUpdate-Funktion übergeben wurde. Wenn die Datenmenge einen von der Anwendung definierten Grenzwert überschreitet, bevor die eigenschaft CMSG_ENVELOPE_ALGORITHM_PARAM verfügbar ist, müssen Sie die Verarbeitung der Nachricht beenden und die CryptMsgClose-Funktion aufrufen, damit das Betriebssystem den für die Nachricht zugewiesenen Arbeitsspeicher freigibt. Ein vorgeschlagener Grenzwert ist die maximal zulässige Größe einer Nachricht. Wenn die maximale Nachrichtengröße beispielsweise 10 MB beträgt, sollte der Grenzwert für diesen Test 10 MB betragen.

Die CERT_INFO-Struktur wird verwendet, um mithilfe der CertGetSubjectCertificateFromStore-Funktion ein übereinstimmende Zertifikat in einem zuvor geöffneten Zertifikatspeicher zu finden. Wenn das richtige Zertifikat gefunden wird, wird die CertGetCertificateContextProperty-Funktion mit einem CERT_KEY_PROV_INFO_PROP_ID-Parameter aufgerufen, um eine CRYPT_KEY_PROV_INFO-Struktur abzurufen. Die -Struktur enthält die Informationen, die zum Abrufen des privaten Schlüssels des Empfängers erforderlich sind, indem CryptAcquireContext aufgerufen wird, wobei die Elemente pwszContainerName, pwszProvName, dwProvType und dwFlags der CRYPT_KEY_PROV_INFO-Struktur verwendet werden. Der abgerufene hCryptProv - und der dwKeySpec-Member der CRYPT_KEY_PROV_INFO-Struktur werden an die CryptMsgControl-Struktur als Member der CMSG_CTRL_DECRYPT_PARA-Struktur übergeben, um den Beginn der Entschlüsselung des inneren Inhalts zu ermöglichen. Der Streamingcode führt dann die Entschlüsselung durch, während die Daten eingegeben werden. Die resultierenden Klartextblöcke werden an die Rückruffunktion übergeben, die vom pfnStreamOutput-Element der CMSG_STREAM_INFO-Struktur angegeben wird, um die Ausgabe der entschlüsselten Nachricht zu verarbeiten.

Im Fall einer signierten Nachricht, die in eine umhüllte Nachricht eingeschlossen ist, kann die Klartextausgabe aus der Streamingdecodierung der umhüllten Nachricht in eine andere Streamingdecodierung eingespeist werden, um die signierte Nachricht zu verarbeiten.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion das Handle der geöffneten Nachricht zurück.

Wenn bei der Funktion ein Fehler auftritt, gibt sie NULL zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

In der folgenden Tabelle sind die Fehlercodes aufgeführt, die am häufigsten von der GetLastError-Funktion zurückgegeben werden.

Anforderungen

Weitere Informationen

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToEncode

CryptMsgUpdate

Nachrichtenfunktionen auf niedriger Ebene

Vereinfachte Nachrichtenfunktionen