Funzione CryptEncodeObjectEx (wincrypt.h)
La funzione CryptEncodeObjectEx codifica una struttura del tipo indicato dal valore del parametro lpszStructType . Questa funzione offre un miglioramento significativo delle prestazioni rispetto a CryptEncodeObject supportando l'allocazione di memoria con il valore CRYPT_ENCODE_ALLOC_FLAG .
Sintassi
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
);
Parametri
[in] dwCertEncodingType
Tipo di codifica del certificato e tipo di codifica dei messaggi da utilizzare per codificare l'oggetto. Questo parametro può essere una combinazione di uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
Specifica la codifica dei messaggi PKCS 7. |
|
Specifica la codifica del certificato X.509. |
[in] lpszStructType
Puntatore a un identificatore di oggetto (OID) che definisce il tipo di struttura. Se la parola di ordine elevato del parametro lpszStructType è zero, la parola con ordine basso specifica un identificatore integer per il tipo della struttura specificata. In caso contrario, questo parametro è un puntatore a una stringa con terminazione Null che contiene la rappresentazione di stringa dell'OID.
Per altre informazioni sulle stringhe di identificatore di oggetto, sulle costanti predefinite e sulle strutture corrispondenti, vedere Costanti per CryptEncodeObject e CryptDecodeObject.
[in] pvStructInfo
Puntatore alla struttura da codificare. La struttura deve essere del tipo specificato da lpszStructType.
[in] dwFlags
Specifica le opzioni per la codifica. Questo parametro può essere zero o una combinazione di uno o più dei valori seguenti.
[in] pEncodePara
Puntatore a una struttura CRYPT_ENCODE_PARA che contiene informazioni di codifica. Questo parametro può essere NULL.
Se pEncodePara o il membro pfnAlloc di pEncodePara è NULL, viene usato LocalAlloc per l'allocazione e LocalFree deve essere chiamato per liberare la memoria.
Se sia pEncodePara che il membro pfnAlloc di pEncodePara non sono NULL, la funzione a cui punta il membro pfnAlloc della struttura CRYPT_ENCODE_PARA a cui punta pEncodePara viene chiamata per l'allocazione. La funzione a cui punta il membro pfnFree di pEncodePara deve essere chiamata per liberare la memoria.
[out] pvEncoded
Puntatore a un buffer per ricevere la struttura codificata. La dimensione di questo buffer viene specificata nel parametro pcbEncoded . Quando il buffer specificato non è sufficientemente grande da ricevere la struttura decodificata, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile a cui punta pcbEncoded.
Questo parametro può essere NULL per recuperare le dimensioni del buffer a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.
Se dwFlags contiene il flag CRYPT_ENCODE_ALLOC_FLAG , pvEncoded non è un puntatore a un buffer, ma è l'indirizzo di un puntatore al buffer. Poiché la memoria viene allocata all'interno della funzione e il puntatore viene archiviato in pvEncoded, pvEncoded non può essere NULL.
[in, out] pcbEncoded
Puntatore a una variabile DWORD contenente le dimensioni, in byte, del buffer a cui punta il parametro pvEncoded . Quando la funzione viene restituita, la variabile a cui punta il parametro pcbEncoded contiene il numero di byte allocati e codificati archiviati nel buffer.
Quando dwFlags contiene il flag CRYPT_ENCODE_ALLOC_FLAG , pcbEncoded è l'indirizzo di un puntatore al valore DWORD aggiornato.
Valore restituito
Restituisce un valore diverso da zero se ha esito positivo o zero in caso contrario.
Per informazioni sugli errori estesi, chiamare GetLastError. La tabella seguente mostra alcuni possibili codici di errore che possono essere restituiti da GetLastError quando CryptEncodeObjectEx ha esito negativo.
| Codice restituito | Descrizione |
|---|---|
|
Errore durante la codifica. |
|
Impossibile trovare una funzione di codifica per l'oggetto dwCertEncodingType e lpszStructType specificato. |
|
Se il buffer specificato dal parametro pvEncoded non è sufficientemente grande da contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile a cui punta pcbEncoded. |
Se la funzione ha esito negativo, GetLastError può restituire un errore di codifica/decodifica ASN.1 ( Abstract Syntax Notation One ). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.
Commenti
Quando si codifica un oggetto di crittografia usando la funzione CryptEncodeObjectEx preferita, viene incluso il carattere NULL di terminazione. Durante la decodifica, usando la funzione CryptDecodeObjectEx preferita, il carattere NULL di terminazione non viene mantenuto.
CryptEncodeObjectEx cerca innanzitutto una funzione di codifica estesa installabile. Se non viene trovata alcuna funzione di codifica estesa, si trova la funzione precedente, non automatica, installabile.
Quando la codifica IA5String diretta dell'oggetto non è possibile, è possibile specificare la codifica Punycode impostando il parametro dwFlag sul valore CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG . L'impostazione del flag CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG ha effetti diversi in base al tipo di struttura codificato come specificato dal valore del parametro lpszStructType .
Ogni costante nell'elenco seguente ha un tipo di struttura associato a cui punta il parametro pvStructInfo . La struttura a cui punta, direttamente o indirettamente, ha un riferimento a una struttura CERT_ALT_NAME_ENTRY .
- 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 | Effetto |
|---|---|
| CERT_ALT_NAME_DNS_NAME | Se il nome host contiene caratteri Unicode all'esterno del set di caratteri ASCII, il nome host viene prima codificato in Punycode e quindi codificato come stringa IA5String . |
| CERT_ALT_NAME_RFC822_NAME | Se la parte del nome host dell'indirizzo di posta elettronica contiene caratteri Unicode all'esterno del set di caratteri ASCII, la parte del nome host dell'indirizzo di posta elettronica viene codificata in Punycode. L'indirizzo di posta elettronica risultante viene quindi codificato come stringa IA5String . |
| CERT_ALT_NAME_URL | Se il nome host del server dell'URI contiene caratteri Unicode all'esterno del set di caratteri ASCII, la parte del nome host dell'URI viene codificata in Punycode. Viene quindi eseguito l'escape dell'URI risultante e l'URL viene quindi codificato come stringa IA5String . |
Ogni costante nell'elenco seguente ha un tipo di struttura associato a cui punta il parametro pvStructInfo . La struttura a cui punta, direttamente o indirettamente, ha un riferimento a una struttura CERT_HASHED_URL .
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
- szOID_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
Ogni costante X509_UNICODE_NAME nell'elenco seguente ha un tipo di struttura associato a cui punta il parametro pvStructInfo .
- X509_UNICODE_NAME
In tutti i casi, la codifica Punycode del nome host viene eseguita in base all'etichetta.
Esempio
L'esempio seguente illustra l'inizializzazione e la codifica di una struttura X509_NAME usando CryptEncodeObjectEx. Per un esempio che include il contesto completo per questo esempio, vedere Esempio di programma C: codifica ASN.1 e decodifica.
#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);
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |