CryptDecodeObject-Funktion (wincrypt.h)

  • Artikel

Die CryptDecodeObject-Funktion decodiert eine Struktur des Typs, der durch den lpszStructType-Parameter angegeben wird. Die Verwendung von CryptDecodeObjectEx wird als API empfohlen, die dieselbe Funktion mit erheblichen Leistungsverbesserungen ausführt.

Syntax

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

Parameter

[in] dwCertEncodingType

Verwendeter 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 ein Nachrichtencodierungstyp erforderlich. X509_ASN_ENCODING ist die Standardeinstellung. Wenn dieser Typ angegeben ist, wird er verwendet. Wenn andernfalls der PKCS7_ASN_ENCODING Typ angegeben wird, wird er verwendet.
 

[in] lpszStructType

Ein Zeiger auf eine OID, die den Strukturtyp definiert. Wenn das Wort mit hoher Ordnung des lpszStructType-Parameters null ist, gibt das Wort mit niedriger Ordnung den ganzzahligen Bezeichner für den Typ der angegebenen Struktur an. Andernfalls ist dieser Parameter ein langer Zeiger auf eine Zeichenfolge mit NULL-Beendigung.

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

[in] pbEncoded

Ein Zeiger auf die codierte Struktur, die decodiert werden soll.

[in] cbEncoded

Anzahl der Bytes, auf die pbEncoded verweist.

[in] dwFlags

Die folgenden Flags sind definiert. Sie können mit einer bitweisen OR-Operation kombiniert werden.

Wert Bedeutung
CRYPT_DECODE_NOCOPY_FLAG
 Dieses Flag kann festgelegt werden, um anzugeben, dass die Optimierung "Keine Kopie" aktiviert ist. Diese Optimierung aktualisiert ggf. den parameter pvStructInfo so, dass er auf Inhalte verweist, die sich in pbEncoded befinden, anstatt eine Kopie des Inhalts zu erstellen und an pvStructInfo anzufügen. In entsprechenden Fällen muss weniger Arbeitsspeicher von der aufrufenden Anwendung zugewiesen werden, und die Ausführung erfolgt schneller, da keine Kopie erstellt wird. Beachten Sie, dass beim Ausführen einer "No Copy"-Decodierung der Nachteil besteht, dass pbEncoded 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 anfänglich als UTF8 decodiert. Wenn die UTF8-Decodierung fehlschlägt, wird der Wert als Acht-Bit-Zeichen decodiert. Wenn dieses Flag festgelegt ist, überspringt es den anfänglichen Versuch, den Wert als UTF8 zu decodieren, und decodiert den Wert als Acht-Bit-Zeichen.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 Standardmäßig enthielt 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.

[out] pvStructInfo

Ein Zeiger auf einen Puffer zum Empfangen der decodierten Struktur. 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 die Speicherbelegung abzurufen. Weitere Informationen finden Sie unter Abrufen von Daten mit unbekannter Länge.

[in, out] pcbStructInfo

Ein Zeiger auf einen DWORD-Wert , der die Größe des Puffers in Bytes angibt, auf den der parameter pvStructInfo verweist. Wenn die Funktion zurückgibt, enthält dieser DWORD-Wert die Größe der decodierten Daten, die in pvStructInfo kopiert wurden. Die in der Variable enthaltene Größe, 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 andere Strukturen enthalten kann. Diese Größe ist die Summe der Größe, die von der decodierten Struktur und anderen Strukturen benötigt wird, auf die verwiesen wird.

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 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.
 

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. Einige mögliche Fehlercodes sind in der folgenden Tabelle aufgeführt.

Rückgabecode Beschreibung
CRYPT_E_BAD_ENCODE
 Fehler beim Decodieren.
ERROR_FILE_NOT_FOUND
 Für den angegebenen dwCertEncodingType und lpszStructType wurde keine Decodierungsfunktion gefunden.
ERROR_MORE_DATA
 Wenn der vom pvStructInfo-Parameter angegebene Puffer nicht groß genug ist, um die zurückgegebenen Daten zu speichern, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Byte 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-Rückgabewerte für Codierung/Decodierung.

Hinweise

Beim Codieren eines kryptografischen Objekts mit der bevorzugten CryptEncodeObjectEx-Funktion wird das abschließende NULL-Zeichen eingeschlossen. Beim Decodieren mit der bevorzugten CryptDecodeObjectEx-Funktion wird das abschließende NULL-Zeichen nicht beibehalten.

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

CryptDecodeObjectEx

CryptEncodeObject

Objektcodierungs- und Decodierungsfunktionen