Funzione CryptDecodeObjectEx (wincrypt.h)

Articolo
08/27/2023

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

Nota È necessario un certificato o un tipo di codifica dei messaggi. X509_ASN_ENCODING è il valore predefinito. Se tale tipo è indicato, viene usato. In caso contrario, se il tipo di PKCS7_ASN_ENCODING è indicato, viene usato.

[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
CRYPT_DECODE_ALLOC_FLAG	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.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG 33554432 (0x2000000)	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.
CRYPT_DECODE_NOCOPY_FLAG	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.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG	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.
CRYPT_DECODE_TO_BE_SIGNED_FLAG	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.
CRYPT_DECODE_SHARE_OID_STRING_FLAG	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.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG	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.

Nota Quando si elaborano i dati restituiti nel buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori rispetto alle dimensioni del buffer specificato nell'input. In base all'input, le dimensioni del buffer vengono in genere specificate abbastanza grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata per riflettere le dimensioni effettive dei dati copiati nel buffer.

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
CRYPT_E_BAD_ENCODE	Si è verificato un errore durante la decodifica.
ERROR_FILE_NOT_FOUND	Impossibile trovare una funzione di decodifica per l'oggetto dwCertEncodingType specificato e lpszStructType.
ERROR_MORE_DATA	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

Il flag CRYPT_DECODE_ENABLE_PUNYCODE_FLAG , insieme al valore del membro dwAltNameChoice della struttura CERT_ALT_NAME_ENTRY , determina il modo in cui le stringhe vengono codificate.

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.

szOID_LOGOTYPE_EXT
X509_LOGOTYPE_EXT
szOID_BIOMETRIC_EXT
X509_BIOMETRIC_EXT

Quando si decodifica il valore della struttura CERT_HASHED_URL , l'URI viene decodificato. Se il nome host contiene un nome host codificato punycode, viene convertito nell'equivalente Unicode.

Ogni costante X509_UNICODE_NAME nell'elenco seguente ha un tipo di struttura associato a cui punta il parametro pvStructInfo .

X509_UNICODE_NAME

Se il membro pszObjId della struttura CERT_RDN_ATTR è impostato su szOID_RSA_emailAddr e l'indirizzo di posta elettronica nel membro Value contiene la stringa codificata Punycode, viene convertito nell'equivalente Unicode.

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

Vedi anche

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

Funzioni di codifica e decodifica degli oggetti