Freigeben über


CryptEncodeObjectEx-Funktion (wincrypt.h)

Die CryptEncodeObjectEx-Funktion codiert eine Struktur des Typs, die durch den Wert des lpszStructType-Parameters angegeben wird. Diese Funktion bietet eine erhebliche Leistungsverbesserung gegenüber CryptEncodeObject , da die Speicherzuordnung mit dem CRYPT_ENCODE_ALLOC_FLAG-Wert unterstützt wird.

Syntax

BOOL CryptEncodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const void         *pvStructInfo,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_ENCODE_PARA pEncodePara,
  [out]     void               *pvEncoded,
  [in, out] DWORD              *pcbEncoded
);

Parameter

[in] dwCertEncodingType

Der Zertifikatcodierungstyp und nachrichtencodierungstyp , der zum Codieren des Objekts verwendet werden soll. Dieser Parameter kann eine Kombination aus mindestens einem der folgenden Werte sein.

Wert Bedeutung
PKCS_7_ASN_ENCODING
65536 (0x10000)
Gibt die PKCS 7-Nachrichtencodierung an.
X509_ASN_ENCODING
1 (0x1)
Gibt die X.509-Zertifikatcodierung an.

[in] lpszStructType

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

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 sein, der von lpszStructType angegeben wird.

[in] dwFlags

Gibt Optionen für die Codierung an. Dieser Parameter kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.

Wert Bedeutung
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
Die aufgerufene Codierungsfunktion weist Arbeitsspeicher für die codierten Bytes zu. Ein Zeiger auf die zugeordneten Bytes wird in pvEncoded zurückgegeben.
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
Dieses Flag gilt für die Aktivierung der Punycode-Codierung 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_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG
1073741824 (0x40000000)
Dieses Flag gilt beim Codieren X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE oder X509_UNICODE_ANY_STRING. Wenn dieses Flag festgelegt ist, werden die Zeichen nicht überprüft, um zu bestimmen, ob sie für den angegebenen Werttyp gültig sind.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG
2147483648 (0x80000000)
Dieses Flag gilt, wenn die Codierung X509_UNICODE_NAME. Wenn dieses Flag festgelegt ist und alle Unicode-Zeichen = 0xFF sind <, wird anstelle des CERT_RDN_UNICODE_STRING die CERT_RDN_T61_STRING ausgewählt.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG
536870912 (0x20000000)
Dieses Flag gilt beim Codieren eines X509_UNICODE_NAME. Wenn festgelegt, wird CERT_RDN_UTF8_STRING anstelle von CERT_RDN_UNICODE_STRING ausgewählt.
CRYPT_UNICODE_NAME_ENCODE_FORCE_UTF8_UNICODE_FLAG
268435456 (0x10000000)
Dieses Flag gilt beim Codieren eines X509_UNICODE_NAME. Wenn festgelegt, wird CERT_RDN_UTF8_STRING anstelle von CERT_RDN_PRINTABLE_STRING für Verzeichniszeichenfolgentypen ausgewählt. Außerdem ermöglicht dieses Flag CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG.

[in] pEncodePara

Ein Zeiger auf eine CRYPT_ENCODE_PARA Struktur, die Codierungsinformationen enthält. Dieser Parameter kann NULL sein.

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

Wenn sowohl pEncodePara als auch das pfnAlloc-Element von pEncodePara nicht NULL sind, wird die Funktion aufgerufen, auf die das pfnAlloc-Element der CRYPT_ENCODE_PARA Struktur verweist, auf die pEncodePara verweist, für die Zuordnung aufgerufen. Die Funktion, auf die der pfnFree-Member von pEncodePara verweist, muss aufgerufen werden, um den Arbeitsspeicher freizugeben.

[out] pvEncoded

Ein Zeiger auf einen Puffer, um die codierte Struktur zu empfangen. Die Größe dieses Puffers wird im parameter pcbEncoded angegeben. 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 des Puffers für Speicherbelegungszwecke abzurufen. Weitere Informationen finden Sie unter Abrufen von Daten unbekannter Länge.

Wenn dwFlags das flag CRYPT_ENCODE_ALLOC_FLAG enthält, ist pvEncoded kein Zeiger auf einen Puffer, sondern die Adresse eines Zeigers auf den Puffer. Da arbeitsspeicher in der Funktion zugeordnet ist und der Zeiger in pvEncoded gespeichert ist, kann pvEncoded nicht NULL sein.

[in, out] pcbEncoded

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

Wenn dwFlags das CRYPT_ENCODE_ALLOC_FLAG-Flag enthält, ist pcbEncoded die Adresse eines Zeigers auf den aktualisierten DWORD-Wert .

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

Gibt nonzero zurück, wenn der Vorgang erfolgreich war oder andernfalls null.

Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Die folgende Tabelle enthält einige mögliche Fehlercodes, die von GetLastError zurückgegeben werden können, wenn CryptEncodeObjectEx fehlschlägt.

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 vom parameter pvEncoded 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.

CryptEncodeObjectEx sucht zunächst nach einer installierbaren erweiterten Codierungsfunktion. Wenn keine erweiterte Codierungsfunktion gefunden wird, befindet sich die alte, nonextended, installierbare Funktion.

Wenn eine direkte IA5String-Codierung des Objekts nicht möglich ist, können Sie punycode-Codierung angeben, indem Sie den dwFlag-Parameter auf den CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG-Wert festlegen. Das Festlegen des CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG-Flags hat unterschiedliche Auswirkungen basierend auf dem Strukturtyp, der codiert wird, wie durch den Wert des lpszStructType-Parameters angegeben.

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
  • szOID_NAME_CONSTRAINTS
  • X509_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
Das CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG-Flag bestimmt in Verbindung mit dem Wert des dwAltNameChoice-Members der CERT_ALT_NAME_ENTRY-Struktur die Art und Weise, wie Zeichenfolgen codiert werden.
dwAltNameChoice Wirkung
CERT_ALT_NAME_DNS_NAME Wenn der Hostname Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält, wird der Hostname zuerst in Punycode codiert und dann als IA5String-Zeichenfolge codiert.
CERT_ALT_NAME_RFC822_NAME Wenn der Hostnamenteil der E-Mail-Adresse Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält, wird der Hostnamenteil der E-Mail-Adresse in Punycode codiert. Die resultierende E-Mail-Adresse wird dann als IA5String-Zeichenfolge codiert.
CERT_ALT_NAME_URL Wenn der Serverhostname des URI Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält, wird der Hostnamenteil des URI in Punycode codiert. Dann wird der resultierende URI als Escapezeichen gesetzt, und die URL wird dann als IA5String-Zeichenfolge codiert.
 

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_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
Wenn der Serverhostname des URI beim Codieren des CERT_HASHED_URL Strukturwerts Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält und der CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG festgelegt ist, wird der Hostnamenteil des URI in Punycode codiert. Dann wird der resultierende URI als Escapezeichen gesetzt, und die URL wird dann als IA5String-Zeichenfolge codiert.

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 Wertelement Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält, wird der Hostnamenteil der E-Mail-Adresse in Punycode codiert. Anschließend wird die resultierende E-Mail-Adresse als IA5String-Zeichenfolge codiert.

In allen Fällen erfolgt die Punycode-Codierung des Hostnamens auf Label-by-Label-Basis.

Beispiele

Das folgende Beispiel zeigt das Initialisieren und Codieren einer X509_NAME-Struktur mithilfe von CryptEncodeObjectEx. Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel C-Programm: ASN.1-Codierung und -Decodierung.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")


#define MY_TYPE (X509_ASN_ENCODING)

void main()
{

//#define moved

//--------------------------------------------------------------------
//   Declare and initialize local variables.

char *Cert_Sub_Name ="Test User Name";

//--------------------------------------------------------------------
// Initialize a single RDN structure.

CERT_RDN_ATTR rgNameAttr = 
{
   "2.5.4.3",                      // The OID
   CERT_RDN_PRINTABLE_STRING,      // Type of string
   (DWORD)strlen(Cert_Sub_Name)+1, // String length including
                                   //  the terminating null character
   (BYTE *)Cert_Sub_Name           // Pointer to the string 
};
//--------------------------------------------------------------------
// Declare and initialize a structure to include
// the array of RDN structures.

CERT_RDN rgRDN[] = 
{
   1,               // The number of elements in the array
   &rgNameAttr      // Pointer to the array
};

//--------------------------------------------------------------------
//  Declare and initialize a CERT_NAME_INFO 
//  structure that includes a CERT_RND.

CERT_NAME_INFO CertName = 
{
    1,          // The number of elements in the CERT_RND's array
    rgRDN
};

//--------------------------------------------------------------------
//  Declare additional variables.

DWORD cbEncoded;              // Variable to hold the
                              //  length of the encoded string
BYTE *pbEncoded;              // Variable to hold a pointer to the 
                              //  encoded buffer
//--------------------------------------------------------------------
// Call CrypteEncodeObjectEx to get 
// length to allocate for pbEncoded.

if( CryptEncodeObjectEx(
     MY_TYPE,        // The encoding/decoding type
     X509_NAME,    
     &CertName,
     0,                 
     NULL, 
     NULL,
     &cbEncoded))    // Fill in the length needed for
                     // the encoded buffer.
{
     printf("The number of bytes needed is %d \n",cbEncoded);
}
else
{
     printf("The first call to the function failed.\n");
     exit(1);
}

if( pbEncoded = (BYTE*)malloc(cbEncoded))
{
     printf("Memory for pvEncoded has been allocated.\n");
}
else
{
    printf("Memory allocation failed.\n");
    exit(1);
}

if(CryptEncodeObjectEx(
     MY_TYPE,
     X509_NAME,
     &CertName,
     0,
     NULL, 
     pbEncoded,
     &cbEncoded))
{
     printf("The structure has been encoded.\n");
}
else
{
     printf("Encoding failed.");
     exit(1);
}
// Free allocated memory when done.
// ...
if(pbEncoded)
{
    free(pbEncoded);
}


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

Weitere Informationen

CryptDecodeObject

CryptDecodeObjectEx

CryptEncodeObject

Objektcodierungs- und Decodierungsfunktionen