Funzione BCryptDecrypt (bcrypt.h)
La funzione BCryptDecrypt decrittografa un blocco di dati.
Sintassi
NTSTATUS BCryptDecrypt(
[in, out] BCRYPT_KEY_HANDLE hKey,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in, optional] VOID *pPaddingInfo,
[in, out, optional] PUCHAR pbIV,
[in] ULONG cbIV,
[out, optional] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);
Parametri
[in, out] hKey
Handle della chiave da usare per decrittografare i dati. Questo handle viene ottenuto da una delle funzioni di creazione chiave, ad esempio BCryptGenerateSymmetricKey, BCryptGenerateKeyPair o BCryptImportKey.
[in] pbInput
Indirizzo di un buffer contenente il testo di crittografia da decrittografare. Il parametro cbInput contiene le dimensioni del testo di crittografia da decrittografare. Per altre informazioni, vedere la sezione Osservazioni.
[in] cbInput
Numero di byte nel buffer pbInput da decrittografare.
[in, optional] pPaddingInfo
Puntatore a una struttura che contiene informazioni di riempimento. Questo parametro viene usato solo con chiavi asimmetriche e modalità di crittografia autenticate. Se viene usata una modalità di crittografia autenticata, questo parametro deve puntare a una struttura BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO . Se vengono usate chiavi asimmetriche, il tipo di struttura a cui punta questo parametro è determinato dal valore del parametro dwFlags . In caso contrario, il parametro deve essere impostato su NULL.
[in, out, optional] pbIV
Indirizzo di un buffer contenente il vettore di inizializzazione (IV) da usare durante la decrittografia. Il parametro cbIV contiene le dimensioni di questo buffer. Questa funzione modifica il contenuto del buffer. Se è necessario riutilizzare il IV in un secondo momento, assicurarsi di eseguire una copia di questo buffer prima di chiamare questa funzione.
Questo parametro è facoltativo e può essere NULL se non viene usato alcun iv.
Le dimensioni necessarie del IV possono essere ottenute chiamando la funzione BCryptGetProperty per ottenere la proprietà BCRYPT_BLOCK_LENGTH . In questo modo verranno fornite le dimensioni di un blocco per l'algoritmo, che è anche la dimensione del IV.
[in] cbIV
Dimensioni, in byte, del buffer pbIV .
[out, optional] pbOutput
Indirizzo di un buffer per ricevere il testo non crittografato prodotto da questa funzione. Il parametro cbOutput contiene le dimensioni di questo buffer. Per altre informazioni, vedere la sezione Osservazioni.
Se questo parametro è NULL, la funzione BCryptDecrypt calcola le dimensioni necessarie per il testo non crittografato dei dati crittografati passati nel parametro pbInput . In questo caso, la posizione a cui punta il parametro pcbResult contiene questa dimensione e la funzione restituisce STATUS_SUCCESS.
Se i valori dei parametri pbOutput e pbInput sono NULL, viene restituito un errore a meno che non sia in uso un algoritmo di crittografia autenticato. In quest'ultimo caso, la chiamata viene considerata come una chiamata di crittografia autenticata con dati di lunghezza zero e il tag di autenticazione, passato nel parametro pPaddingInfo , viene verificato.
[in] cbOutput
Dimensioni, in byte, del buffer pbOutput . Questo parametro viene ignorato se il parametro pbOutput è NULL.
[out] pcbResult
Puntatore a una variabile ULONG per ricevere il numero di byte copiati nel buffer pbOutput . Se pbOutput è NULL, questa riceve le dimensioni, in byte, necessarie per il testo non crittografato.
[in] dwFlags
Set di flag che modificano il comportamento di questa funzione. Il set consentito di flag dipende dal tipo di chiave specificato dal parametro hKey .
Se la chiave è una chiave simmetrica, questa può essere zero o il valore seguente.
| Valore | Significato |
|---|---|
|
I dati sono stati inseriti nella dimensione del blocco successiva quando è stata crittografata. Se questo flag è stato usato con la funzione BCryptEncrypt , deve essere specificato anche in questa funzione. Questo flag non deve essere usato con le modalità di crittografia autenticate (AES-CCM e AES-GCM). |
Se la chiave è una chiave asimmetrica, questo può essere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Non usare spaziatura interna. Il parametro pPaddingInfo non viene usato. Il parametro cbInput deve essere un multiplo delle dimensioni del blocco dell'algoritmo.
Le dimensioni del blocco possono essere ottenute chiamando la funzione BCryptGetProperty per ottenere la proprietà BCRYPT_BLOCK_LENGTH per la chiave. In questo modo verranno fornite le dimensioni di un blocco per l'algoritmo. |
|
Lo schema OAEP (Optimal Asymmetric Encryption Padding) è stato usato quando i dati sono stati crittografati. Il parametro pPaddingInfo è un puntatore a una struttura BCRYPT_OAEP_PADDING_INFO . |
|
I dati sono stati riempiti con un numero casuale quando i dati sono stati crittografati. Il parametro pPaddingInfo non viene usato. |
Valore restituito
Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.
I codici restituiti possibili includono, ma non sono limitati a, i seguenti.
| Codice restituito | Descrizione |
|---|---|
|
La funzione ha avuto esito positivo. |
|
Il tag di autenticazione calcolata non corrisponde al valore specificato nel parametro pPaddingInfo . |
|
Le dimensioni specificate dal parametro cbOutput non sono sufficienti per contenere il testo di crittografia. |
|
Il parametro cbInput non è un multiplo delle dimensioni del blocco dell'algoritmo e il flag di BCRYPT_BLOCK_PADDING non è stato specificato nel parametro dwFlags . |
|
L'handle della chiave nel parametro hKey non è valido. |
|
Uno o più parametri non sono validi. |
|
L'algoritmo non supporta la decrittografia. |
Commenti
I parametri pbInput e pbOutput possono essere uguali. In questo caso, questa funzione eseguirà la decrittografia sul posto. Se pbInput e pbOutput non sono uguali, i due buffer potrebbero non sovrapporsi.
A seconda delle modalità di processore supportate da un provider, È possibile chiamare BCryptDecrypt dalla modalità utente o dalla modalità kernel. I chiamanti in modalità kernel possono essere eseguiti in PASSIVE_LEVELIRQL o DISPATCH_LEVEL IRQL. Se il livello IRQL corrente è DISPATCH_LEVEL, l'handle fornito nel parametro hKey deve essere derivato da un handle di algoritmo restituito da un provider aperto con il flag BCRYPT_PROV_DISPATCH e tutti i puntatori passati alla funzione BCryptDecrypt devono fare riferimento a memoria non paginata (o bloccata).
Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte del Driver Development Kit (DDK). Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.
Requisiti
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | bcrypt.h |
| Libreria | Bcrypt.lib |
| DLL | Bcrypt.dll |