CryptDecodeObjectEx-Funktion (wincrypt.h)

  • Artikel

Die CryptDecodeObjectEx-Funktion decodiert eine Struktur des Typs, die durch den lpszStructType-Parameter angegeben wird. CryptDecodeObjectEx bietet eine erhebliche Leistungsverbesserung gegenüber CryptDecodeObject , da die Speicherzuordnung mit dem CRYPT_DECODE_ALLOC_FLAG-Wert unterstützt wird.

Syntax

BOOL CryptDecodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const BYTE         *pbEncoded,
  [in]      DWORD              cbEncoded,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_DECODE_PARA pDecodePara,
  [out]     void               *pvStructInfo,
  [in, out] DWORD              *pcbStructInfo
);

Parameter

[in] dwCertEncodingType

Der verwendete Codierungstyp. 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
Hinweis Es ist entweder ein Zertifikat- oder Nachrichtencodierungstyp erforderlich. X509_ASN_ENCODING ist der Standardwert. Wenn dieser Typ angegeben ist, wird er verwendet. Andernfalls wird der PKCS7_ASN_ENCODING-Typ verwendet, wenn er angegeben wird.
 

[in] lpszStructType

Ein Zeiger auf einen Objektbezeichner (Object Identifier, OID), der den Strukturtyp definiert. Wenn das hochgeordnete Wort des lpszStructType-Parameters 0 ist, gibt das Wort mit niedriger Reihenfolge den ganzzahligen Bezeichner für den Typ der angegebenen Struktur an. Andernfalls ist dieser Parameter ein langer Zeiger auf eine NULL-Zeichenfolge.

Weitere Informationen zu Objektbezeichnerzeichenfolgen, deren vordefinierten Konstanten und entsprechenden Strukturen finden Sie unter Konstanten für CryptEncodeObject und CryptDecodeObject.

[in] pbEncoded

Ein Zeiger auf die zu decodierten Daten. Die Struktur muss vom typ sein, der von lpszStructType angegeben wird.

[in] cbEncoded

Die Anzahl von Bytes, auf die von pbEncoded verwiesen wird. Dies ist die Anzahl der Zu decodierenden Bytes.

[in] dwFlags

Dieser Parameter kann mindestens eins der folgenden Flags sein. Die Flags können mithilfe eines bitweisen OR-Vorgangs kombiniert werden.

Wert Bedeutung
CRYPT_DECODE_ALLOC_FLAG
 Die aufgerufene Decodierungsfunktion weist Arbeitsspeicher für die decodierte Struktur zu. Ein Zeiger auf die zugeordnete Struktur wird in pvStructInfo zurückgegeben.

Wenn pDecodePara oder das pfnAlloc-Element von pDecodeParaNULL ist, wird LocalAlloc für die Zuordnung aufgerufen, und LocalFree muss aufgerufen werden, um den Arbeitsspeicher freizugeben.

Wenn pDecodePara und das pfnAlloc-Element von pDecodePara nicht NULL sind, wird die Funktion, auf die von pfnAlloc verwiesen wird, für die Zuordnung aufgerufen, und die Funktion, auf die der pfnFree-Member von pDecodePara verweist, muss aufgerufen werden, um den Speicher freizugeben.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
 Dieses Flag gilt für die Aktivierung der Punycode-Decodierung von Unicode-Zeichenfolgenwerten. Weitere Informationen finden Sie in den Hinweisen.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieses Flag wird nicht unterstützt.
CRYPT_DECODE_NOCOPY_FLAG
 Dieses Flag kann festgelegt werden, um eine Optimierung ohne Kopie zu aktivieren. Diese Optimierung aktualisiert die pvStructInfo-Elemente so, dass sie auf Inhalte verweisen, die sich in pbEncoded befinden, anstatt eine Kopie des Inhalts zu erstellen und ihn an pvStructInfo anzufügen. Die aufrufende Anwendung muss weniger Arbeitsspeicher zuweisen, und die Ausführung ist schneller, da keine Kopie erstellt wird. Beachten Sie, dass pbEncoded bei der Decodierung ohne Kopie erst freigegeben werden kann, wenn pvStructInfo freigegeben wurde.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 Dieses Flag gilt beim Decodieren X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE oder X509_UNICODE_ANY_STRING. Standardmäßig werden CERT_RDN_T61_STRING codierten Werte zunächst als UTF8 decodiert. Wenn bei der UTF8-Decodierung ein Fehler auftritt, wird der Wert als Acht-Bit-Zeichen decodiert. Wenn dieses Flag festgelegt ist, überspringt es den ersten Versuch, den Wert als UTF8 zu decodieren, und decodiert den Wert als Acht-Bit-Zeichen.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 Standardmäßig enthält der Inhalt des Puffers, auf den pbEncoded verweist, den signierten Inhalt und die Signatur. Wenn dieses Flag festgelegt ist, enthält der Puffer nur den Zu signierten Inhalt. Dieses Flag gilt für X509_CERT_TO_BE_SIGNED-, X509_CERT_CRL_TO_BE_SIGNED-, X509_CRT_REQUEST_TO_BE_SIGNED- und X509_KEYGEN_REQUEST_TO_BE_SIGNED-Objekte.
CRYPT_DECODE_SHARE_OID_STRING_FLAG
 Wenn dieses Flag festgelegt ist, werden die OID-Zeichenfolgen in Crypt32.dll zugeordnet und freigegeben, anstatt in die zurückgegebene Datenstruktur kopiert zu werden. Dieses Flag kann festgelegt werden, wenn Crypt32.dll nicht entladen wird, bevor der Aufrufer entladen wird.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG
 Standardmäßig werden die Signaturbytes umgekehrt. Wenn dieses Flag festgelegt ist, wird diese Byteumkehr gehemmt.

[in] pDecodePara

Ein Zeiger auf eine CRYPT_DECODE_PARA-Struktur , die Decodierungsabsatzinformationen enthält. Wenn pDecodePara auf NULL festgelegt ist, werden LocalAlloc und LocalFree verwendet, um Arbeitsspeicher zuzuweisen und freizugeben. Wenn pDecodePara auf eine CRYPT_DECODE_PARA-Struktur verweist, übergibt diese Struktur Rückruffunktionen, um Arbeitsspeicher zuzuweisen und freizugeben. Diese Rückruffunktionen überschreiben die Standardspeicherbelegung von LocalAlloc und LocalFree.

[out] pvStructInfo

Wenn die dwFlags-CRYPT_ENCODE_ALLOC_FLAG festgelegt ist, ist pvStructInfo kein Zeiger auf einen Puffer, sondern die Adresse eines Zeigers auf den Puffer. Da arbeitsspeicher in der Funktion zugeordnet ist und der Zeiger in *pvStructInfo gespeichert wird, darf pvStructInfo niemals NULL sein.

Wenn CRYPT_ENCODE_ALLOC_FLAG nicht festgelegt ist, ist pvStructInfo ein Zeiger auf einen Puffer, der die decodierte Struktur empfängt. Wenn der angegebene Puffer nicht groß genug ist, um die decodierte Struktur zu empfangen, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Bytes in der Variablen, auf die von pcbStructInfo verwiesen wird.

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

[in, out] pcbStructInfo

Ein Zeiger auf eine DWORD-Variable , die die Größe des Puffers in Bytes enthält, auf den der parameter pvStructInfo verweist. Wenn die Funktion zurückgibt, enthält der DWORD-Wert die Anzahl der im Puffer gespeicherten Bytes. Die Größe in der Variablen, auf die von pcbStructInfo verwiesen wird, kann eine Größe angeben, die größer als die decodierte Struktur ist, da die decodierte Struktur Zeiger auf Hilfsdaten enthalten kann. Diese Größe ist die Summe der Größe, die von der decodierten Struktur und den Hilfsdaten benötigt wird.

Wenn CRYPT_DECODE_ALLOC_FLAG festgelegt ist, wird der Anfangswert von *pcbStructInfo nicht von der Funktion verwendet, und bei der Rückgabe enthält *pcbStructInfo die Anzahl der für pvStructInfo zugewiesenen Bytes.

Hinweis Bei der Verarbeitung der im 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 sein als die Größe des Puffers, der bei der Eingabe angegeben wird. (Bei der Eingabe werden Puffergrößen normalerweise 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.
 

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.

Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. In der folgenden Tabelle sind einige mögliche Fehlercodes aufgeführt.

Rückgabecode Beschreibung
CRYPT_E_BAD_ENCODE
 Beim Decodieren ist ein Fehler aufgetreten.
ERROR_FILE_NOT_FOUND
 Eine Decodierungsfunktion konnte für die angegebenen dwCertEncodingType und lpszStructType nicht gefunden werden.
ERROR_MORE_DATA
 Wenn der vom parameter pvStructInfo angegebene Puffer nicht groß genug ist, um die zurückgegebenen Daten aufzunehmen, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Bytes in der Variablen, auf die von pcbStructInfo verwiesen wird.
 

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 Encoding/Decoding Return Values.

Hinweise

Beim Codieren eines kryptografischen Objekts mit der bevorzugten CryptEncodeObjectEx-Funktion ist das beendende NULL-Zeichen enthalten. Beim Decodieren mit der bevorzugten CryptDecodeObjectEx-Funktion wird das beendende NULL-Zeichen nicht beibehalten.

Jede Konstante in der folgenden Liste verfügt über einen zugeordneten Strukturtyp, auf den der parameter pvStructInfo verweist. Die Struktur, auf die direkt oder indirekt verwiesen wird, weist einen Verweis auf eine CERT_ALT_NAME_ENTRY Struktur auf.

  • X509_ALTERNATE_NAME
  • szOID_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_KEY_ID2
  • szOID_AUTHORITY_KEY_IDENTIFIER2
  • szOID_CRL_DIST_POINTS
  • X509_CRL_DIST_POINTS
  • szOID_CROSS_CERT_DIST_POINTS
  • X509_CROSS_CERT_DIST_POINTS
  • szOID_ISSUER_ALT_NAME
  • szOID_ISSUER_ALT_NAME2
  • szOID_ISSUING_DIST_POINT
  • X509_ISSUING_DIST_POINT
  • X509_NAME_CONSTRAINTS
  • szOID_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
Das flag CRYPT_DECODE_ENABLE_PUNYCODE_FLAG in Verbindung mit dem Wert des dwAltNameChoice-Elements der CERT_ALT_NAME_ENTRY-Struktur bestimmt die Art und Weise, wie Zeichenfolgen codiert werden.
dwAltNameChoice Wirkung
CERT_ALT_NAME_DNS_NAME Wenn der Hostname eine Punycode-codierte IA5String-Zeichenfolge enthält, wird er in die Unicode-Entsprechung konvertiert.
CERT_ALT_NAME_RFC822_NAME Wenn der Hostnamenteil der E-Mail-Adresse eine Punycode-codierte IA5String-Zeichenfolge enthält, wird er in seine Unicode-Entsprechung konvertiert.
CERT_ALT_NAME_URL Der URI wird decodiert. Wenn der Serverhostname des URI eine Punycode-codierte IA5String-Zeichenfolge enthält, wird die Hostnamenzeichenfolge mit der Unicode-Entsprechung decodiert.
 

Jede Konstante in der folgenden Liste verfügt über einen zugeordneten Strukturtyp, auf den der parameter pvStructInfo verweist. Die Struktur, auf die direkt oder indirekt verwiesen wird, weist einen Verweis auf eine CERT_HASHED_URL-Struktur auf.

  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
Beim Decodieren des CERT_HASHED_URL Strukturwerts wird der URI decodiert. Wenn der Hostname einen Punycode-codierten Hostnamen enthält, wird er in die Unicode-Entsprechung konvertiert.

Jede X509_UNICODE_NAME Konstante in der folgenden Liste verfügt über einen zugeordneten Strukturtyp, auf den der parameter pvStructInfo verweist.

  • X509_UNICODE_NAME
Wenn das pszObjId-Element der CERT_RDN_ATTR-Struktur auf szOID_RSA_emailAddr festgelegt ist und die E-Mail-Adresse im Value-Element punycodecodierte Zeichenfolge enthält, wird sie in die Unicode-Entsprechung konvertiert.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: ASN.1-Codierung und -Decodierung.

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

Weitere Informationen

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

Objektcodierungs- und Decodierungsfunktionen