CryptMsgControl-Funktion (wincrypt.h)

Die CryptMsgControl-Funktion führt einen Steuerungsvorgang aus, nachdem eine Nachricht durch einen letzten Aufruf der CryptMsgUpdate-Funktion decodiert wurde. Die von dieser Funktion bereitgestellten Steuerungsvorgänge werden zur Entschlüsselung, Signatur- und Hashüberprüfung sowie zum Hinzufügen und Löschen von Zertifikaten, Zertifikatsperrlisten (Certificate Revocation Lists , CRLs), Signierern und nicht authentifizierten Attributen verwendet.

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. Weitere Informationen finden Sie in den Hinweisen zur CryptMsgOpenToEncode-Funktion .

Syntax

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Parameter

[in] hCryptMsg

Ein Handle einer kryptografischen Nachricht, auf die ein Steuerelement angewendet werden soll.

[in] dwFlags

Der folgende Wert wird definiert, wenn der dwCtrlType-Parameter einer der folgenden Ist:

• CMSG_CTRL_DECRYPT
• CMSG_CTRL_KEY_TRANS_DECRYPT
• CMSG_CTRL_KEY_AGREE_DECRYPT
• CMSG_CTRL_MAIL_LIST_DECRYPT

Wert	Bedeutung
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Das Handle für den Kryptografieanbieter wird beim letzten Aufruf der CryptMsgClose-Funktion freigegeben. Dieses Handle wird nicht freigegeben, wenn die CryptMsgControl-Funktion fehlschlägt.

 

Wenn der dwCtrlType-Parameter keinen Entschlüsselungsvorgang angibt, legen Sie diesen Wert auf Null fest.

[in] dwCtrlType

Der Typ des auszuführenden Vorgangs. Die derzeit definierten Nachrichtensteuerungstypen und der Strukturtyp, der an den parameter pvCtrlPara übergeben werden soll, sind in der folgenden Tabelle dargestellt.

Wert	Bedeutung
CMSG_CTRL_ADD_ATTR_CERT 14 (0xE)	Ein BLOB , das die codierten Bytes des Attributzertifikats enthält.
CMSG_CTRL_ADD_CERT 10 (0xA)	Eine CRYPT_INTEGER_BLOB-Struktur , die die codierten Bytes des Zertifikats enthält, das der Nachricht hinzugefügt werden soll.
CMSG_CTRL_ADD_CMS_SIGNER_INFO 20 (0x14)	Eine CMSG_CMS_SIGNER_INFO-Struktur , die Signiererinformationen enthält. Dieser Vorgang unterscheidet sich von CMSG_CTRL_ADD_SIGNER , da die Signiererinformationen die Signatur enthalten.
CMSG_CTRL_ADD_CRL 12 (0xC)	Ein BLOB, das die codierten Bytes der CRL enthält, die der Nachricht hinzugefügt werden soll.
CMSG_CTRL_ADD_SIGNER 6 (0x6)	Eine CMSG_SIGNER_ENCODE_INFO-Struktur , die die Signiererinformationen enthält, die der Nachricht hinzugefügt werden sollen.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR 8 (0x8)	Eine CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA-Struktur , die den Index des Signierers und ein BLOB enthält, das die nicht authentifizierten Attributinformationen enthält, die der Nachricht hinzugefügt werden sollen.
CMSG_CTRL_DECRYPT 2 (0x2)	Eine CMSG_CTRL_DECRYPT_PARA Struktur, die zum Entschlüsseln der Nachricht für den angegebenen Schlüsseltransportempfänger verwendet wird. Dieser Wert gilt für RSA-Empfänger. Dieser Vorgang gibt an, dass die CryptMsgControl-Funktion den Empfängerindex durchsucht, um die Informationen zum Schlüsseltransportempfänger abzurufen. Wenn die Funktion fehlschlägt, gibt GetLastErrorCRYPT_E_INVALID_INDEX zurück, wenn kein Schlüsseltransportempfänger gefunden wird.
CMSG_CTRL_DEL_ATTR_CERT 15 (0xF)	Der Index des zu entfernenden Attributzertifikats.
CMSG_CTRL_DEL_CERT 11 (0xB)	Der Index des Zertifikats, das aus der Nachricht gelöscht werden soll.
CMSG_CTRL_DEL_CRL 13 (0xD)	Der Index der Zertifikatsperrliste, die aus der Nachricht gelöscht werden soll.
CMSG_CTRL_DEL_SIGNER 7 (0x7)	Der Index des zu löschenden Signierers.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR 9 (0x9)	Eine CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA-Struktur , die einen Index enthält, der den Signierer und den Index angibt, der das zu löschende nicht authentifizierte Attribut des Signaturgebers angibt.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE 21 (0x15)	Eine CERT_STRONG_SIGN_PARA-Struktur , die zum Durchführen einer starken Signaturüberprüfung verwendet wird. Um nach einer starken Signatur zu suchen, geben Sie diesen Steuerelementtyp vor dem Aufruf von CryptMsgGetAndVerifySigner oder vor dem Aufruf von CryptMsgControl mit den folgenden Steuerelementtypen an: CMSG_CTRL_VERIFY_SIGNATURE CMSG_CTRL_VERIFY_SIGNATURE_EX Nachdem die Signatur erfolgreich überprüft wurde, sucht diese Funktion nach einer starken Signatur. Wenn die Signatur nicht stark ist, schlägt der Vorgang fehl, und der Wert GetLastError wird auf NTE_BAD_ALGID festgelegt.
CMSG_CTRL_KEY_AGREE_DECRYPT 17 (0x11)	Eine CMSG_CTRL_KEY_AGREE_DECRYPT_PARA-Struktur , die zum Entschlüsseln der Nachricht für den angegebenen Schlüsselvereinbarungssitzungsschlüssel verwendet wird. Die Schlüsselvereinbarung wird mit Diffie-Hellman Verschlüsselung/Entschlüsselung verwendet.
CMSG_CTRL_KEY_TRANS_DECRYPT 16 (0x10)	Eine CMSG_CTRL_KEY_TRANS_DECRYPT_PARA-Struktur , die zum Entschlüsseln der Nachricht für den angegebenen Schlüsseltransportempfänger verwendet wird. Schlüsseltransport wird mit RSA-Ver-/Entschlüsselung verwendet.
CMSG_CTRL_MAIL_LIST_DECRYPT 18 (0x12)	Eine CMSG_CTRL_MAIL_LIST_DECRYPT_PARA Struktur, die verwendet wird, um die Nachricht für den angegebenen Empfänger mithilfe eines zuvor verteilten Schlüsselverschlüsselungsschlüssels (KEK) zu entschlüsseln.
CMSG_CTRL_VERIFY_HASH 5 (0x5)	Dieser Wert wird nicht verwendet.
CMSG_CTRL_VERIFY_SIGNATURE 1 (0x1)	Eine CERT_INFO-Struktur , die den Signierer der Nachricht identifiziert, deren Signatur überprüft werden soll.
CMSG_CTRL_VERIFY_SIGNATURE_EX 19 (0x13)	Eine CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA-Struktur , die den Signiererindex und den öffentlichen Schlüssel zum Überprüfen der Nachrichtensignatur angibt. Der öffentliche Schlüssel des Signierers kann eine CERT_PUBLIC_KEY_INFO-Struktur , ein Zertifikatkontext oder ein Zertifikatkettenkontext sein.

[in] pvCtrlPara

Ein Zeiger auf eine Struktur, die durch den Wert von dwCtrlType bestimmt wird.

dwCtrlType-Wert	Bedeutung
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT oder CMSG_CTRL_MAIL_LIST_DECRYPT, und die gestreamte Umschlagnachricht wird decodiert.	Die Decodierung erfolgt so, als ob der gestreamte Inhalt entschlüsselt würde. Wenn vor diesem Aufruf verschlüsselte gestreamte Inhalte angesammelt wurden, wird ein Teil oder der gesamte Klartext , der sich aus der Entschlüsselung des Verschlüsselungstexts ergibt, über die Rückruffunktion zurück an die Anwendung übergeben, die im Aufruf der CryptMsgOpenToDecode-Funktion angegeben ist. Hinweis Beim Streamen einer umhüllten Nachricht wird die CryptMsgControl-Funktion erst aufgerufen, wenn das Abrufen der Verfügbarkeit der CMSG_ENVELOPE_ALGORITHM_PARAM erfolgreich ist. Wenn die Abfrage nicht erfolgreich ist, tritt ein Fehler auf. Eine Beschreibung dieses Abrufs finden Sie unter der Funktion CryptMsgOpenToDecode .
CMSG_CTRL_VERIFY_HASH	Der aus dem Inhalt der Nachricht berechnete Hash wird mit dem in der Nachricht enthaltenen Hash verglichen.
CMSG_CTRL_ADD_SIGNER	pvCtrlPara verweist auf eine CMSG_SIGNER_ENCODE_INFO-Struktur , die die Signiererinformationen enthält, die der Nachricht hinzugefügt werden sollen.
CMSG_CTRL_DEL_SIGNER	Nach dem Löschen sind alle anderen Signerindizes, die für diese Nachricht verwendet werden, nicht mehr gültig und müssen durch Aufrufen der CryptMsgGetParam-Funktion erneut erfasst werden.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	Nach dem Löschen sind alle anderen nicht authentifizierten Attributindizes, die für diesen Signierer verwendet werden, nicht mehr gültig und müssen durch Aufrufen der CryptMsgGetParam-Funktion erneut angefordert werden.
CMSG_CTRL_DEL_CERT	Nach dem Löschen sind alle anderen Zertifikatindizes, die für diese Nachricht verwendet werden, nicht mehr gültig und müssen durch Aufrufen der CryptMsgGetParam-Funktion erneut angefordert werden.
CMSG_CTRL_DEL_CRL	Nach dem Löschen sind alle anderen CRL-Indizes, die für diese Nachricht verwendet werden, nicht mehr gültig und müssen durch Aufrufen der CryptMsgGetParam-Funktion erneut erfasst werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null, und die GetLastError-Funktion gibt einen ASN.1-Codierungsfehler ( Abstract Syntax Notation One ) zurück. Informationen zu diesen Fehlern finden Sie unter ASN.1-Rückgabewerte für Codierung/Decodierung.

Wenn eine gestreamte, umhüllte Nachricht decodiert wird, treten Fehler in der anwendungsdefinierten Rückruffunktion auf, die vom pStreamInfo-Parameter des
Die CryptMsgOpenToDecode-Funktion kann an die CryptMsgControl-Funktion weitergegeben werden. In diesem Fall wird die SetLastError-Funktion nicht von der CryptMsgControl-Funktion aufgerufen, nachdem die Rückruffunktion zurückgegeben wurde. Dadurch bleiben alle Fehler erhalten, die unter der Kontrolle der Anwendung auftreten. Es liegt in der Verantwortung der Rückruffunktion (oder einer der APIs, die sie aufruft), die SetLastError-Funktion aufzurufen, wenn ein Fehler auftritt, während die Anwendung die gestreamten Daten verarbeitet.

Bei den folgenden Funktionen können verteilte Fehler auftreten:

• CryptCreateHash
• CryptDecrypt
• CryptGetHashParam
• CryptGetUserKey
• CryptHashData
• CryptImportKey
• CryptSignHash
• CryptVerifySignature

Die folgenden Fehlercodes werden am häufigsten zurückgegeben.

Rückgabecode	Beschreibung
CRYPT_E_ALREADY_DECRYPTED	Der Nachrichteninhalt wurde bereits entschlüsselt. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_DECRYPT festgelegt ist.
CRYPT_E_AUTH_ATTR_MISSING	Die Nachricht enthält kein erwartetes authentifizierte Attribut. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist.
CRYPT_E_BAD_ENCODE	Fehler beim Codieren oder Decodieren. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist.
CRYPT_E_CONTROL_TYPE	Der Steuerelementtyp ist ungültig.
CRYPT_E_HASH_VALUE	Der Hashwert ist falsch.
CRYPT_E_INVALID_INDEX	Der Indexwert ist ungültig.
CRYPT_E_INVALID_MSG_TYPE	Ungültiger Nachrichtentyp.
CRYPT_E_OID_FORMAT	Der Objektbezeichner ist falsch formatiert. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_ADD_SIGNER festgelegt ist.
CRYPT_E_RECIPIENT_NOT_FOUND	Die umhüllte Datennachricht enthält nicht den angegebenen Empfänger. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_DECRYPT festgelegt ist.
CRYPT_E_SIGNER_NOT_FOUND	Der angegebene Signierer für die Nachricht wurde nicht gefunden. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist.
CRYPT_E_UNKNOWN_ALGO	Der kryptografische Algorithmus ist unbekannt.
CRYPT_E_UNEXPECTED_ENCODING	Die Nachricht ist nicht wie erwartet codiert. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist.
E_INVALIDARG	Mindestens ein Argument ist ungültig. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_DECRYPT festgelegt ist.
E_OUTOFMEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll

Weitere Informationen

Nachrichtenfunktionen auf niedriger Ebene

Vereinfachte Nachrichtenfunktionen