Funzione CryptDecodeObjectEx (wincrypt.h)
La funzione CryptDecodeObjectEx decodifica una struttura del tipo indicato dal parametro lpszStructType . CryptDecodeObjectEx offre un miglioramento significativo delle prestazioni su CryptDecodeObject supportando l'allocazione della memoria con il valore di CRYPT_DECODE_ALLOC_FLAG.
Sintassi
BOOL CryptDecodeObjectEx(
[in] DWORD dwCertEncodingType,
[in] LPCSTR lpszStructType,
[in] const BYTE *pbEncoded,
[in] DWORD cbEncoded,
[in] DWORD dwFlags,
[in] PCRYPT_DECODE_PARA pDecodePara,
[out] void *pvStructInfo,
[in, out] DWORD *pcbStructInfo
);
Parametri
[in] dwCertEncodingType
Tipo di codifica utilizzata. È sempre accettabile specificare sia i tipi di codifica del certificato che dei messaggi combinandoli con un'operazione bit per bit or , come illustrato nell'esempio seguente:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
I tipi di codifica attualmente definiti sono:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] lpszStructType
Puntatore a un identificatore di oggetto (OID) che definisce il tipo di struttura. Se la parola ad ordine elevato del parametro lpszStructType è zero, la parola a basso ordine specifica l'identificatore intero per il tipo della struttura specificata. In caso contrario, questo parametro è un puntatore lungo a una stringa con terminazione null.
Per altre informazioni sulle stringhe di identificatore di oggetto, sulle costanti predefinite e sulle strutture corrispondenti, vedere Costanti per CryptEncodeObject e CryptDecodeObject.
[in] pbEncoded
Puntatore ai dati da decodificare. La struttura deve essere del tipo specificato da lpszStructType.
[in] cbEncoded
Numero di byte a cui fa riferimento pbEncoded. Si tratta del numero di byte da decodificare.
[in] dwFlags
Questo parametro può essere uno o più dei flag seguenti. I flag possono essere combinati usando un'operazione BIT-OR bit.
| Valore | Significato |
|---|---|
|
La funzione denominata decodifica alloca memoria per la struttura decodificata. Viene restituito un puntatore alla struttura allocata in pvStructInfo.
Se pDecodePara o il membro pfnAlloc di pDecodePara è NULL, LocalAlloc viene chiamato per l'allocazione e LocalFree deve essere chiamato per liberare la memoria. Se pDecodePara e il membro pfnAlloc di pDecodePara non sono NULL, la funzione puntata da pfnAlloc viene chiamata per l'allocazione e la funzione puntata dal membro pfnFree di pDecodePara deve essere chiamata per liberare la memoria. |
|
Questo flag è applicabile per abilitare la decodifica di Punycode dei valori di stringa Unicode. Per altre informazioni, vedere la sezione Osservazioni.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo flag non è supportato. |
|
Questo flag può essere impostato per abilitare un'ottimizzazione "nessuna copia". Questa ottimizzazione aggiorna i membri pvStructInfo per puntare al contenuto che risiede all'interno di pbEncoded anziché creare una copia del contenuto e aggiungerlo a pvStructInfo. L'applicazione chiamante deve allocare meno memoria ed esecuzione è più veloce perché non viene eseguita una copia. Si noti che quando si esegue la decodifica "nessuna copia", pbEncoded non può essere liberato finché pvStructInfo non viene liberato. |
|
Questo flag è applicabile quando si decodifica X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE o X509_UNICODE_ANY_STRING. Per impostazione predefinita, CERT_RDN_T61_STRING i valori codificati vengono inizialmente decodificati come UTF8. Se la decodifica UTF8 ha esito negativo, il valore viene decodificato come caratteri a otto bit. Se questo flag è impostato, ignora il tentativo iniziale di decodificare il valore come UTF8 e decodifica il valore come caratteri a otto bit. |
|
Per impostazione predefinita, il contenuto del buffer a cui fa riferimento pbEncoded include il contenuto firmato e la firma. Se questo flag è impostato, il buffer include solo il contenuto "da firmare". Questo flag è applicabile agli oggetti X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED e X509_KEYGEN_REQUEST_TO_BE_SIGNED. |
|
Quando questo flag è impostato, le stringhe OID vengono allocate in Crypt32.dll e condivise anziché copiate nella struttura di dati restituita. Questo flag può essere impostato se Crypt32.dll non viene scaricato prima che il chiamante venga scaricato. |
|
Per impostazione predefinita, i byte di firma vengono invertito. Se questo flag è impostato, questa inversione di byte viene inibita. |
[in] pDecodePara
Puntatore a una struttura CRYPT_DECODE_PARA che contiene informazioni di paragrafo decodificate. Se pDecodePara è impostato su NULL, LocalAlloc e LocalFree vengono usati per allocare e liberare memoria. Se pDecodePara punta a una struttura di CRYPT_DECODE_PARA , tale struttura passa le funzioni di callback per allocare e liberare memoria. Queste funzioni di callback sostituiscono l'allocazione di memoria predefinita di LocalAlloc e LocalFree.
[out] pvStructInfo
Se la CRYPT_ENCODE_ALLOC_FLAG dwFlags è impostata, pvStructInfo 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 *pvStructInfo, pvStructInfo non deve mai essere NULL.
Se CRYPT_ENCODE_ALLOC_FLAG non è impostato, pvStructInfo è un puntatore a un buffer che riceve la struttura decodificata. Quando il buffer specificato non è sufficiente per 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 pcbStructInfo.
Questo parametro può essere NULL per recuperare le dimensioni di queste informazioni ai fini dell'allocazione della memoria. Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.
[in, out] pcbStructInfo
Puntatore a una variabile DWORD contenente le dimensioni, in byte, del buffer a cui punta il parametro pvStructInfo . Quando la funzione restituisce, il valore DWORD contiene il numero di byte archiviati nel buffer. Le dimensioni contenute nella variabile puntata da pcbStructInfo possono indicare una dimensione maggiore della struttura decodificata perché la struttura decodificata può includere puntatori ai dati ausiliari. Questa dimensione è la somma delle dimensioni necessarie dalla struttura decodificata e dai dati ausiliari.
Quando CRYPT_DECODE_ALLOC_FLAG è impostato, il valore iniziale di *pcbStructInfo non viene usato dalla funzione e in caso di restituzione, *pcbStructInfo contiene il numero di byte allocati per pvStructInfo.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce non zero (TRUE).
Se la funzione ha esito negativo, restituisce zero (FALSE). Per informazioni sull'errore estese, chiamare GetLastError. La tabella seguente mostra alcuni codici di errore possibili.
| Codice restituito | Descrizione |
|---|---|
|
Si è verificato un errore durante la decodifica. |
|
Impossibile trovare una funzione di decodifica per l'oggetto dwCertEncodingType specificato e lpszStructType. |
|
Se il buffer specificato dal parametro pvStructInfo non è sufficiente per contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile puntata da pcbStructInfo. |
Se la funzione ha esito negativo, GetLastError potrebbe restituire un errore di codifica astratta Notation One (ASN.1). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.
Commenti
Quando si codifica un oggetto crittografico usando la funzione CryptEncodeObjectEx preferita, è incluso il carattere NULL terminante. Quando si decodifica, usando la funzione CryptDecodeObjectEx preferita, il carattere NULL terminante non viene mantenuto.
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
- X509_NAME_CONSTRAINTS
- szOID_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 una stringa IA5String codificata punycode, viene convertita nell'equivalente Unicode. |
| CERT_ALT_NAME_RFC822_NAME | Se la parte del nome host dell'indirizzo di posta elettronica contiene una stringa IA5String codificata punycode, viene convertita nell'equivalente Unicode. |
| CERT_ALT_NAME_URL | L'URI viene decodificato. Se il nome host del server dell'URI contiene una stringa IA5String codificata punycode, la stringa del nome host viene decodificata nell'equivalente Unicode. |
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_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
Ogni costante X509_UNICODE_NAME nell'elenco seguente ha un tipo di struttura associato a cui punta il parametro pvStructInfo .
- X509_UNICODE_NAME
Esempio
Per un esempio che usa questa funzione, vedere Esempio di programma C: codifica e decodifica ASN.1.
Requisiti
| 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 |