Funzione CryptDecodeObject (wincrypt.h)

  • Articolo

La funzione CryptDecodeObject decodifica una struttura del tipo indicato dal parametro lpszStructType . L'uso di CryptDecodeObjectEx è consigliato come API che esegue la stessa funzione con miglioramenti significativi delle prestazioni.

Sintassi

BOOL CryptDecodeObject(
  [in]      DWORD      dwCertEncodingType,
  [in]      LPCSTR     lpszStructType,
  [in]      const BYTE *pbEncoded,
  [in]      DWORD      cbEncoded,
  [in]      DWORD      dwFlags,
  [out]     void       *pvStructInfo,
  [in, out] DWORD      *pcbStructInfo
);

Parametri

[in] dwCertEncodingType

Tipo di codifica utilizzata. È sempre accettabile specificare sia il certificato che i tipi di codifica dei messaggi combinandoli con un'operazione OR bit per bit, 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 è l'impostazione predefinita. Se tale tipo è indicato, viene utilizzato. In caso contrario, se viene indicato il tipo di PKCS7_ASN_ENCODING, viene usato.
 

[in] lpszStructType

Puntatore a un OID che definisce il tipo di struttura. Se la parola di ordine elevato del parametro lpszStructType è zero, la parola di ordine basso specifica l'identificatore integer 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 alla struttura codificata da decodificare.

[in] cbEncoded

Numero di byte a cui punta pbEncoded.

[in] dwFlags

Vengono definiti i flag seguenti. Possono essere combinati con un'operazione OR bit per bit.

Valore Significato
CRYPT_DECODE_NOCOPY_FLAG
 Questo flag può essere impostato per indicare che l'ottimizzazione "nessuna copia" è abilitata. Questa ottimizzazione, se applicabile, aggiorna il parametro pvStructInfo in modo che punti al contenuto che si trova all'interno di pbEncoded anziché creare una copia del contenuto e accodarla a pvStructInfo. Per i casi applicabili, è necessario allocare meno memoria dall'applicazione chiamante e l'esecuzione è più veloce perché non viene eseguita una copia. Si noti che il compromesso quando si esegue una decodifica "nessuna copia" è che pbEncoded non può essere liberato finché pvStructInfo non viene liberato.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 Questo flag è applicabile quando si decodificano 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 punta pbEncoded includeva 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 invece di essere copiate nella struttura dei 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 della firma vengono invertiti. Se questo flag è impostato, questa inversione di byte viene inibita.

[out] pvStructInfo

Puntatore a un buffer per ricevere la struttura decodificata. 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 pcbStructInfo.

Questo parametro può essere NULL per recuperare le dimensioni di queste informazioni ai fini dell'allocazione della memoria. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.

[in, out] pcbStructInfo

Puntatore a un valore DWORD che specifica le dimensioni, in byte, del buffer a cui punta il parametro pvStructInfo . Al termine della funzione, questo valore DWORD contiene le dimensioni dei dati decodificati copiati in pvStructInfo. Le dimensioni contenute nella variabile a cui punta pcbStructInfo possono indicare una dimensione maggiore della struttura decodificata, in quanto la struttura decodificata può includere puntatori ad altre strutture. Questa dimensione è la somma delle dimensioni necessarie per la struttura decodificata e altre strutture a cui punta.

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 alle dimensioni del buffer specificato nell'input. In caso di input, le dimensioni del buffer vengono in genere specificate sufficientemente grandi per garantire che i dati di output più grandi possibili si adattino al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata in modo da riflettere le dimensioni effettive dei dati copiati nel buffer.
 

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError. Nella tabella seguente sono elencati alcuni codici di errore possibili.

Codice restituito Descrizione
CRYPT_E_BAD_ENCODE
 Errore durante la decodifica.
ERROR_FILE_NOT_FOUND
 Impossibile trovare una funzione di decodifica per l'oggetto dwCertEncodingType e lpszStructType specificato
ERROR_MORE_DATA
 Se il buffer specificato dal parametro pvStructInfo 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 pcbStructInfo.
 

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.

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

CryptDecodeObjectEx

CryptEncodeObject

Funzioni di codifica e decodifica degli oggetti