Freigeben über


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:

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