Funzione CryptDecrypt (wincrypt.h)

Articolo
07/16/2024

Importante Questa API è deprecata. Il software nuovo ed esistente deve iniziare a usare API Di nuova generazione di crittografia. Microsoft potrebbe rimuovere questa API nelle versioni future.

La funzione CryptDecrypt decrittografa i dati precedentemente crittografati usando la funzione CryptEncrypt.

Sono state apportate modifiche importanti per supportare l'interoperabilità della posta elettronica sicura/multiuso (S/MIME) a CryptoAPI che influiscono sulla gestione dei messaggi in busta. Per altre informazioni, vedere la sezione Osservazioni di CryptMsgOpenToEncode.

Sintassi

BOOL CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

Parametri

[in] hKey

Handle per la chiave da usare per la decrittografia. Un'applicazione ottiene questo handle usando la funzione CryptGenKey o CryptImportKey.

Questa chiave specifica l'algoritmo di decrittografia da utilizzare.

[in] hHash

Handle per un oggetto hash . Se i dati devono essere decrittografati e contemporaneamente con hash, viene passato un handle a un oggetto hash in questo parametro. Il valore hash viene aggiornato con l'testo non crittografato decrittografato. Questa opzione è utile quando si decrittografa e si verifica contemporaneamente una firma.

Prima di chiamare CryptDecrypt, l'applicazione deve ottenere un handle per l'oggetto hash chiamando la funzione CryptCreateHash. Al termine della decrittografia, il valore hash può essere ottenuto usando la funzione CryptGetHashParam, può anche essere firmato usando la funzione CryptSignHash oppure può essere usata per verificare una firma digitale usando la funzione CryptVerifySignature.

Se non è necessario eseguire alcun hash, questo parametro deve essere zero.

[in] Final

Valore booleano che specifica se si tratta dell'ultima sezione di una serie da decrittografare. Questo valore è TRUE se si tratta dell'ultimo blocco o solo. Se non si tratta dell'ultimo blocco, questo valore è FALSE. Per altre informazioni, vedere Osservazioni.

[in] dwFlags

Vengono definiti i valori di flag seguenti.

Valore	Significato
CRYPT_OAEP 0x00000040	Usare il riempimento OAEP (Optimal Asymmetric Encryption Padding) (PKCS #1 versione 2). Questo flag è supportato solo dal provider di crittografia avanzato Microsoft con crittografia/decrittografia RSA. Questo flag non può essere combinato con il flag CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	Eseguire la decrittografia sul BLOB senza controllare la spaziatura interna. Questo flag è supportato solo dal provider di crittografia avanzato Microsoft con crittografia/decrittografia RSA. Questo flag non può essere combinato con il flag CRYPT_OAEP.

[in, out] pbData

Puntatore a un buffer che contiene i dati da decrittografare. Dopo l'esecuzione della decrittografia, il testo non crittografato viene inserito nuovamente nello stesso buffer.

Il numero di byte crittografati in questo buffer viene specificato da pdwDataLen.

[in, out] pdwDataLen

Puntatore a un valore DWORD che indica la lunghezza del buffer pbData . Prima di chiamare questa funzione, l'applicazione chiamante imposta il valore DWORD sul numero di byte da decrittografare. Al termine, il valore DWORD contiene il numero di byte del testo non crittografato decrittografato.

Quando si usa un di crittografia a blocchi , questa lunghezza dei dati deve essere un multiplo delle dimensioni del blocco, a meno che non si tratta della sezione finale dei dati da decrittografare e il parametro finale sia TRUE.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero (TRUE).

Se la funzione ha esito negativo, restituisce zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError.

I codici di errore preceduti dall'NTE vengono generati dal CSP specifico usato. Di seguito sono riportati alcuni possibili codici di errore.

Valore	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore non valido.
NTE_BAD_ALGID	L'chiave di sessione hKey specifica un algoritmo non supportato da questo provider di servizi di configurazione.
NTE_BAD_DATA	I dati da decrittografare non sono validi. Ad esempio, quando viene usata una crittografia a blocchi e il flag finale è FALSE, il valore specificato da pdwDataLen deve essere un multiplo delle dimensioni del blocco. Questo errore può essere restituito anche quando il di riempimento non è valido.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_HASH	Il parametro hHash contiene un handle non valido.
NTE_BAD_KEY	Il parametro hKey non contiene un handle valido per una chiave.
NTE_BAD_LEN	La dimensione del buffer di output è troppo piccola per contenere il testo non crittografato generato.
NTE_BAD_UID	Impossibile trovare il contesto CSP specificato al momento della creazione della chiave.
NTE_DOUBLE_ENCRYPT	L'applicazione ha tentato di decrittografare due volte gli stessi dati.
NTE_FAIL	La funzione non è riuscita in modo imprevisto.

Osservazioni

Se una grande quantità di dati deve essere decrittografata, può essere eseguita in sezioni chiamando CryptDecrypt ripetutamente. Il parametro Final deve essere impostato su TRUE solo sull'ultima chiamata a CryptDecrypt, in modo che il motore di decrittografia possa completare correttamente il processo di decrittografia. Le azioni aggiuntive seguenti vengono eseguite quando finale viene TRUE:

Se la chiave è una chiave di crittografia a blocchi, i dati vengono riempiti in un multiplo delle dimensioni del blocco della crittografia. Per trovare le dimensioni del blocco di una crittografia, usare CryptGetKeyParam per ottenere il valore KP_BLOCKLEN della chiave.
Se la crittografia funziona in modalità di concatenamento , la successiva operazione di CryptDecrypt reimposta il registro dei commenti e suggerimenti della crittografia sul valore KP_IV della chiave.
Se la crittografia è una crittografia flusso, la successiva chiamata CryptDecrypt reimposta lo stato iniziale .

Non è possibile impostare il registro dei commenti e suggerimenti della crittografia sul valore KP_IV della chiave senza impostare il parametro Final su TRUE. Se ciò è necessario, come nel caso in cui non si voglia aggiungere un blocco di riempimento aggiuntivo o modificare le dimensioni di ogni blocco, è possibile simularlo creando un duplicato della chiave originale usando la funzione CryptDuplicateKey e passando la chiave duplicata alla funzione CryptDecrypt. In questo modo la KP_IV della chiave originale viene inserita nella chiave duplicata. Dopo aver creato o importato la chiave originale, non è possibile usare la chiave originale per la crittografia perché il registro dei commenti e suggerimenti della chiave verrà modificato. Lo pseudocodice seguente mostra come eseguire questa operazione.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Il provider di crittografia avanzato Microsoft supporta la crittografia diretta con RSAchiavi pubbliche e decrittografia con chiavi private RSA . La crittografia usa PKCS #1 riempimento. In caso di decrittografia, questa spaziatura interna viene verificata. La lunghezza di testo crittografato dati da decrittografare deve essere la stessa lunghezza del modulo della chiave RSA usata per decrittografare i dati. Se il testo crittografato ha zeri nei byte più significativi, questi byte devono essere inclusi nel buffer di dati di input e nella lunghezza del buffer di input. Il testo crittografato deve essere in formato little-endian.

Esempi

Per un esempio che usa questa funzione, vedere Programma C di esempio: Decrittografia di un file.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	wincrypt.h
libreria	Advapi32.lib
dll	Advapi32.dll