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 |
|---|---|
|
Gibt die PKCS 7-Nachrichtencodierung an. |
|
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.
[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 .
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 |
|---|---|
|
Beim Codieren ist ein Fehler aufgetreten. |
|
Für die angegebenen dwCertEncodingType und lpszStructType konnte keine Codierungsfunktion gefunden werden. |
|
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
| 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
Jede X509_UNICODE_NAME Konstante in der folgenden Liste verfügt über einen zugeordneten Strukturtyp, auf den der parameter pvStructInfo verweist.
- X509_UNICODE_NAME
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 |