CryptEncodeObject-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CryptEncodeObject-Funktion codiert eine Struktur des Typs, die durch den Wert des lpszStructType-Parameters angegeben wird. Die Verwendung von CryptEncodeObjectEx wird als API empfohlen, die dieselbe Funktion mit erheblichen Leistungsverbesserungen ausführt.

Syntax

BOOL CryptEncodeObject(
  [in]      DWORD      dwCertEncodingType,
  [in]      LPCSTR     lpszStructType,
  [in]      const void *pvStructInfo,
  [out]     BYTE       *pbEncoded,
  [in, out] DWORD      *pcbEncoded
);

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 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 eine OID, die 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, ihren vordefinierten Konstanten und entsprechenden Strukturen finden Sie unter Konstanten für CryptEncodeObject und CryptDecodeObject.

[in] pvStructInfo

Ein Zeiger auf die zu codierende Struktur. Die Struktur muss vom Typ "lpszStructType" angegeben sein.

[out] pbEncoded

Ein Zeiger auf einen Puffer, um die codierte Struktur zu empfangen. 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 pcbEncoded 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] pcbEncoded

Ein Zeiger auf eine DWORD-Variable , die die Größe des Puffers in Bytes enthält, auf den der pbEncoded-Parameter verweist. Wenn die Funktion zurückgibt, enthält der DWORD-Wert die Anzahl der zugeordneten codierten Bytes, die im Puffer gespeichert sind.

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, ist der Rückgabewert nonzero (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	Beim Codieren ist ein Fehler aufgetreten.
ERROR_FILE_NOT_FOUND	Für die angegebenen dwCertEncodingType und lpszStructType konnte keine Codierungsfunktion gefunden werden.
ERROR_MORE_DATA	Wenn der durch den pbEncoded-Parameter 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 pcbEncoded 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.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Erstellen einer Zertifikatanforderung und 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

CryptEncodeObjectEx

Objektcodierungs- und Decodierungsfunktionen

Freigeben über