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 |
|---|---|
|
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 |
|---|---|
|
Ein BLOB , das die codierten Bytes des Attributzertifikats enthält. |
|
Eine CRYPT_INTEGER_BLOB-Struktur , die die codierten Bytes des Zertifikats enthält, das der Nachricht hinzugefügt werden soll. |
|
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. |
|
Ein BLOB, das die codierten Bytes der CRL enthält, die der Nachricht hinzugefügt werden soll. |
|
Eine CMSG_SIGNER_ENCODE_INFO-Struktur , die die Signiererinformationen enthält, die der Nachricht hinzugefügt werden sollen. |
|
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. |
|
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. |
|
Der Index des zu entfernenden Attributzertifikats. |
|
Der Index des Zertifikats, das aus der Nachricht gelöscht werden soll. |
|
Der Index der Zertifikatsperrliste, die aus der Nachricht gelöscht werden soll. |
|
Der Index des zu löschenden Signierers. |
|
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. |
|
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:
|
|
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. |
|
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. |
|
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. |
|
Dieser Wert wird nicht verwendet. |
|
Eine CERT_INFO-Struktur , die den Signierer der Nachricht identifiziert, deren Signatur überprüft werden soll. |
|
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 |
|---|---|
|
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 .
|
|
Der aus dem Inhalt der Nachricht berechnete Hash wird mit dem in der Nachricht enthaltenen Hash verglichen. |
|
pvCtrlPara verweist auf eine CMSG_SIGNER_ENCODE_INFO-Struktur , die die Signiererinformationen enthält, die der Nachricht hinzugefügt werden sollen. |
|
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. |
|
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. |
|
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. |
|
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 |
|---|---|
|
Der Nachrichteninhalt wurde bereits entschlüsselt. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_DECRYPT festgelegt ist. |
|
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. |
|
Fehler beim Codieren oder Decodieren. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist. |
|
Der Steuerelementtyp ist ungültig. |
|
Der Hashwert ist falsch. |
|
Der Indexwert ist ungültig. |
|
Ungültiger Nachrichtentyp. |
|
Der Objektbezeichner ist falsch formatiert. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_ADD_SIGNER festgelegt ist. |
|
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. |
|
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. |
|
Der kryptografische Algorithmus ist unbekannt. |
|
Die Nachricht ist nicht wie erwartet codiert. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_VERIFY_SIGNATURE festgelegt ist. |
|
Mindestens ein Argument ist ungültig. Dieser Fehler kann zurückgegeben werden, wenn der dwCtrlType-Parameter auf CMSG_CTRL_DECRYPT festgelegt ist. |
|
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 |