CryptMsgGetParam-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CryptMsgGetParam-Funktion ruft einen Nachrichtenparameter ab, nachdem eine kryptografische Nachricht codiert oder decodiert wurde. Diese Funktion wird nach dem letzten CryptMsgUpdate-Aufruf aufgerufen.

Syntax

BOOL CryptMsgGetParam(
  [in]      HCRYPTMSG hCryptMsg,
  [in]      DWORD     dwParamType,
  [in]      DWORD     dwIndex,
  [out]     void      *pvData,
  [in, out] DWORD     *pcbData
);

Parameter

[in] hCryptMsg

Handle einer kryptografischen Nachricht.

[in] dwParamType

Gibt die Abzurufenden Parametertypen an. Der Typ der abzurufenden Daten bestimmt den Typ der Struktur, die für pvData verwendet werden soll.

Für eine codierte Nachricht sind nur die CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM und CMSG_COMPUTED_HASH_PARAM dwParamTypes gültig.

Wert	Bedeutung
CMSG_ATTR_CERT_COUNT_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt die Anzahl der Attributzertifikate in einer SIGNIERTEN oder ENVELOPED-Nachricht zurück.
CMSG_ATTR_CERT_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Ruft ein Attributzertifikat ab. Um alle Attributzertifikate abzurufen, rufen Sie CryptMsgGetParam variiert dwIndex auf 0 die Anzahl der Attribute minus 1.
CMSG_BARE_CONTENT_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Ruft den codierten Inhalt einer codierten kryptografischen Nachricht ohne die äußere Schicht der CONTENT_INFO-Struktur ab. Das heißt, es wird nur die Codierung des pkCs #7 definierten Felds ContentInfo.content zurückgegeben.
CMSG_CERT_COUNT_PARAM	pvData-Datentyp : Zeiger auf DWORD Gibt die Anzahl der Zertifikate in einer empfangenen SIGNIERTEN oder ENVELOPED-Nachricht zurück.
CMSG_CERT_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt das Zertifikat eines Unterzeichners zurück. Um alle Zertifikate des Signierers abzurufen, rufen Sie CryptMsgGetParam auf, wobei dwIndex von 0 bis zur Anzahl der verfügbaren Zertifikate minus eins variiert.
CMSG_COMPUTED_HASH_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt den Hash zurück, der aus den Daten in der Nachricht berechnet wird. Dieser Typ gilt sowohl für die Codierung als auch für die Decodierung.
CMSG_CONTENT_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt die gesamte PKCS #7-Nachricht von einer Nachricht zurück, die zur Codierung geöffnet wurde. Ruft den inneren Inhalt einer Nachricht ab, die zur Decodierung geöffnet wurde. Wenn die Nachricht umhüllt ist, der innere Typ Daten sind und CryptMsgControl aufgerufen wurde, um die Nachricht zu entschlüsseln, wird der entschlüsselte Inhalt zurückgegeben. Wenn der innere Typ keine Daten ist, wird das codierte BLOB zurückgegeben, für das eine weitere Decodierung erforderlich ist. Wenn die Nachricht nicht umhüllt ist und der innere Inhalt DATA ist, sind die zurückgegebenen Daten die Oktette des inneren Inhalts. Dieser Typ gilt sowohl für die Codierung als auch für die Decodierung. Wenn der Typ für die Decodierung CMSG_DATA ist, werden die Oktette des Inhalts zurückgegeben. andernfalls wird der codierte innere Inhalt zurückgegeben.
CMSG_CRL_COUNT_PARAM	pvData-Datentyp : Zeiger auf DWORD Gibt die Anzahl der Zertifikatsperrlisten in einer empfangenen, SIGNIERTEN oder ENVELOPED-Nachricht zurück.
CMSG_CRL_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt eine Zertifikatsperrliste zurück. Um alle CRLs abzurufen, rufen Sie CryptMsgGetParam auf, wobei dwIndex von 0 bis zur Anzahl der verfügbaren CRLs minus 1 variiert.
CMSG_ENCODED_MESSAGE	pvData-Datentyp: Zeiger auf ein BYTE-Array Ändert den Inhalt einer bereits codierten Nachricht. Die Nachricht muss zuerst mit einem Aufruf von CryptMsgOpenToDecode decodiert werden. Anschließend erfolgt die Änderung der Nachricht durch einen Aufruf von CryptMsgControl, CryptMsgCountersign oder CryptMsgCountersignEncoded. Die Nachricht wird dann mit einem Aufruf von CryptMsgGetParam erneut codiert, wobei angegeben wird, CMSG_ENCODED_MESSAGE eine neue Codierung abzurufen, die die vorgenommenen Änderungen widerspiegelt. Dies kann für instance verwendet werden, um einer Nachricht ein Zeitstempel-Attribut hinzuzufügen.
CMSG_ENCODED_SIGNER	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt die codierten CMSG_SIGNER_INFO-Signaturgeberinformationen für einen Nachrichten signierer zurück.
CMSG_ENCRYPTED_DIGEST	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt den verschlüsselten Hash einer Signatur zurück. Wird in der Regel zum Durchführen von Zeitstempeln verwendet.
CMSG_ENCRYPT_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array für eine CRYPT_ALGORITHM_IDENTIFIER-Struktur . Gibt den Verschlüsselungsalgorithmus zurück, der zum Verschlüsseln der Nachricht verwendet wird.
CMSG_ENVELOPE_ALGORITHM_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array für eine CRYPT_ALGORITHM_IDENTIFIER-Struktur . Gibt den Verschlüsselungsalgorithmus zurück, der zum Verschlüsseln einer ENVELOPED-Nachricht verwendet wird.
CMSG_HASH_ALGORITHM_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array für eine CRYPT_ALGORITHM_IDENTIFIER-Struktur . Gibt den Hashalgorithmus zurück, der zum Hashen der Nachricht beim Erstellen verwendet wurde.
CMSG_HASH_DATA_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array Gibt den Hashwert zurück, der bei der Erstellung in der Nachricht gespeichert wurde.
CMSG_INNER_CONTENT_TYPE_PARAM	pvData-Datentyp: Zeiger auf ein BYTE-Array, um eine OID-Zeichenfolge (Null-Terminated Object Identifier) zu empfangen. Gibt den inneren Inhaltstyp einer empfangenen Nachricht zurück. Dieser Typ gilt nicht für Nachrichten vom Typ DATA.
CMSG_RECIPIENT_COUNT_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt die Anzahl der Schlüsseltransportempfänger einer empfangenen ENVELOPED-Nachricht zurück.
CMSG_CMS_RECIPIENT_COUNT_PARAM	pvData-Datentyp : Zeiger auf DWORD Gibt die Gesamtzahl aller Nachrichtenempfänger zurück, einschließlich Schlüsselvereinbarungs- und E-Mail-Listenempfängern.
CMSG_RECIPIENT_INDEX_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt den Index des Schlüsseltransportempfängers zurück, der zum Entschlüsseln einer ENVELOPED-Nachricht verwendet wird. Dieser Wert ist erst verfügbar, nachdem eine Nachricht entschlüsselt wurde.
CMSG_CMS_RECIPIENT_INDEX_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt den Index des Schlüsseltransports, der Schlüsselvereinbarung oder des E-Mail-Listenempfängers zurück, der zum Entschlüsseln einer ENVELOPED-Nachricht verwendet wird.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt den Index des verschlüsselten Schlüssels eines Schlüsselvereinbarungsempfängers zurück, der zum Entschlüsseln einer ENVELOPED-Nachricht verwendet wird.
CMSG_RECIPIENT_INFO_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CERT_INFO Struktur zu empfangen. Gibt Zertifikatinformationen über den Empfänger einer Schlüsseltransportnachricht zurück. Um Zertifikatinformationen zu allen Empfängern der Schlüsseltransportnachricht abzurufen, rufen Sie wiederholt CryptMsgGetParam auf, wobei dwIndex von 0 bis zur Anzahl der Empfänger minus 1 variiert. Nur die Member Issuer, SerialNumber und PublicKeyAlgorithm der zurückgegebenen CERT_INFO-Struktur sind verfügbar und gültig.
CMSG_CMS_RECIPIENT_INFO_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CMSG_CMS_RECIPIENT_INFO-Struktur zu empfangen. Gibt Informationen zu einem Schlüsseltransport, einer Schlüsselvereinbarung oder einem Empfänger einer E-Mail-Liste zurück. Dies ist nicht auf Schlüsseltransportnachrichtenempfänger beschränkt. Um Informationen zu allen Empfängern einer Nachricht zu erhalten, rufen Sie wiederholt CryptMsgGetParam auf, wobei dwIndex von 0 auf die Anzahl der Empfänger minus eins variiert.
CMSG_SIGNER_AUTH_ATTR_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CRYPT_ATTRIBUTES-Struktur zu empfangen. Gibt die authentifizierten Attribute eines Nachrichten signierers zurück. Um die authentifizierten Attribute für einen angegebenen Signierer abzurufen, rufen Sie CryptMsgGetParam mit dwIndex auf, der dem Index dieses Signierers entspricht.
CMSG_SIGNER_CERT_INFO_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um die CERT_INFO-Struktur zu empfangen. Gibt Informationen zu einem Nachrichten signierer zurück, der zum Identifizieren des Zertifikats des Signierers erforderlich ist. Der Aussteller und die Seriennummer eines Zertifikats können verwendet werden, um ein Zertifikat für den Abruf eindeutig zu identifizieren. Um Informationen für alle Signierer abzurufen, rufen Sie wiederholt CryptMsgGetParam auf, wobei dwIndex von 0 bis zur Anzahl der Signierer minus eins variiert. Nur die Felder Issuer und SerialNumber in der CERT_INFO zurückgegebenen Struktur enthalten verfügbare gültige Daten.
CMSG_SIGNER_CERT_ID_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CERT_ID-Struktur zu empfangen. Gibt Informationen zu einem Nachrichten signierer zurück, der zum Identifizieren des öffentlichen Schlüssels des Signierers erforderlich ist. Dies kann der Aussteller und die Seriennummer eines Zertifikats, eine KeyID oder eine HashId sein. Um Informationen für alle Signierer abzurufen, rufen Sie CryptMsgGetParam auf, die dwIndex von 0 bis zur Anzahl der Signierer minus 1 variiert.
CMSG_SIGNER_COUNT_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt die Anzahl der Unterzeichner einer empfangenen SIGNIERTen Nachricht zurück.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um die CRYPT_ALGORITHM_IDENTIFIER-Struktur zu empfangen. Gibt den Hashalgorithmus zurück, der von einem Signierer der Nachricht verwendet wird. Um den Hashalgorithmus für einen angegebenen Signierer abzurufen, rufen Sie CryptMsgGetParam mit dwIndex auf, der dem Index dieses Signierers entspricht.
CMSG_SIGNER_INFO_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CMSG_SIGNER_INFO-Struktur zu empfangen. Gibt Informationen zu einem Nachrichten signierer zurück. Dies umfasst den Aussteller und die Seriennummer des Zertifikats des Signierers sowie authentifizierte und nicht authentifizierte Attribute des Zertifikats des Signierers. Rufen Sie CryptMsgGetParam vom Typ dwIndex von 0 bis zur Anzahl der Signierer minus 1 auf, um Signiererinformationen für alle Signierer einer Nachricht abzurufen.
CMSG_CMS_SIGNER_INFO_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CMSG_CMS_SIGNER_INFO-Struktur zu empfangen. Gibt Informationen zu einem Nachrichten signierer zurück. Dies umfasst eine signerId sowie authentifizierte und nicht authentifizierte Attribute. Rufen Sie CryptMsgGetParam vom Typ dwIndex von 0 bis zur Anzahl der Signierer minus 1 auf, um Signiererinformationen für alle Signierer einer Nachricht abzurufen.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CRYPT_ATTRIBUTES-Struktur zu empfangen. Gibt die nicht authentifizierten Attribute eines Nachrichten signierers zurück. Um die nicht authentifizierten Attribute für einen angegebenen Signierer abzurufen, rufen Sie CryptMsgGetParam mit dwIndex auf, der dem Index dieses Signierers entspricht.
CMSG_TYPE_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt den Nachrichtentyp einer decodierten Nachricht des unbekannten Typs zurück. Der abgerufene Nachrichtentyp kann mit unterstützten Typen verglichen werden, um zu bestimmen, ob die Verarbeitung fortgesetzt werden kann. Unterstützte Nachrichtentypen finden Sie im dwMessageType-Parameter von CryptMsgOpenToDecode.
CMSG_UNPROTECTED_ATTR_PARAM	pvData-Datentyp : Zeiger auf ein BYTE-Array , um eine CMSG_ATTR-Struktur zu empfangen. Gibt die nicht geschützten Attribute in einer umhüllten Nachricht zurück.
CMSG_VERSION_PARAM	pvData-Datentyp : Zeiger auf ein DWORD Gibt die Version der decodierten Nachricht zurück. Weitere Informationen finden Sie in der Tabelle im Abschnitt „Hinweise“.

[in] dwIndex

Index für den abzurufenden Parameter, sofern zutreffend. Wenn ein Parameter nicht abgerufen wird, wird dieser Parameter ignoriert und auf 0 (null) festgelegt.

[out] pvData

Ein Zeiger auf einen Puffer, der die abgerufenen Daten empfängt. Die Form dieser Daten hängt vom Wert des dwParamType-Parameters ab.

Dieser Parameter kann NULL sein, um die Größe dieser Informationen für die Speicherbelegung festzulegen. Weitere Informationen finden Sie unter Abrufen von Daten mit unbekannter Länge.

Bei der Verarbeitung der in diesem Puffer zurückgegebenen Daten müssen Anwendungen die tatsächliche Größe der zurückgegebenen Daten verwenden. Die tatsächliche Größe kann etwas kleiner als die Größe des bei der Eingabe angegebenen Puffers sein. (Bei der Eingabe werden Puffergrößen in der Regel groß genug angegeben, um sicherzustellen, dass die größtmöglichen Ausgabedaten in den Puffer passen.) Bei der Ausgabe wird die Variable aktualisiert, auf die dieser Parameter verweist, um die tatsächliche Größe der in den Puffer kopierten Daten widerzuspiegeln.

[in, out] pcbData

Ein Zeiger auf eine Variable, die die Größe des Puffers in Bytes angibt, auf den der parameter pvData verweist. Wenn die Funktion zurückgibt, enthält die Variable, auf die der parameter pcbData verweist, die Anzahl der im Puffer gespeicherten Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). 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.

Rückgabecode	Beschreibung
CRYPT_E_ATTRIBUTES_MISSING	Die Nachricht enthält nicht die angeforderten Attribute.
CRYPT_E_INVALID_INDEX	Der Indexwert ist ungültig.
CRYPT_E_INVALID_MSG_TYPE	Ungültiger Nachrichtentyp.
CRYPT_E_NOT_DECRYPTED	Der Nachrichteninhalt wurde noch nicht entschlüsselt.
CRYPT_E_OID_FORMAT	Der Objektbezeichner ist falsch formatiert.
CRYPT_E_UNEXPECTED_ENCODING	Die Nachricht ist nicht wie erwartet codiert.
E_INVALIDARG	Mindestens ein Argument ist ungültig.
ERROR_MORE_DATA	Der angegebene Puffer ist nicht groß genug, um die zurückgegebenen Daten aufzunehmen.

Für dwParamType-CMSG_COMPUTED_HASH_PARAM kann ein Fehler von CryptGetHashParam weitergegeben werden.

Wenn die Funktion fehlschlägt, gibt GetLastError möglicherweise einen ASN.1-Codierungs-/Decodierungsfehler ( Abstract Syntax Notation One ) zurück. Informationen zu diesen Fehlern finden Sie unter ASN.1-Rückgabewerte für Codierung/Decodierung.

Hinweise

Die folgenden Versionsnummern werden durch Aufrufe von CryptMsgGetParam zurückgegeben, wobei dwParamType auf festgelegt ist, CMSG_VERSION_PARAM definiert sind:

CMSG_SIGNED_DATA_V1
CMSG_SIGNED_DATA_V3
CMSG_SIGNED_DATA_PKCS_1_5_VERSION
CMSG_SIGNED_DATA_CMS_VERSION
CMSG_SIGNER_INFO_V1
CMSG_SIGNER_INFO_V3
CMSG_SIGNER_INFO_PKCS_1_5_VERSION
CMSG_SIGNER_INFO_CMS_VERSION
CMSG_HASHED_DATA_V0
CMSG_HASHED_DATA_V2
CMSG_HASHED_DATA_PKCS_1_5_VERSION
CMSG_HASHED_DATA_CMS_VERSION
CMSG_ENVELOPED_DATA_V0
CMSG_ENVELOPED_DATA_V2
CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
CMSG_ENVELOPED_DATA_CMS_VERSION

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Signieren, Codieren, Decodieren und Überprüfen einer Nachricht, Alternativer Code zum Codieren einer umhüllten Nachricht, Beispiel C-Programm: Codieren einer umhüllten, signierten Nachricht und Beispiel C-Programm: Codieren und Decodieren einer Hashnachricht.

Anforderungen


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