Funzione BCryptDecrypt (bcrypt.h)

Articolo
03/14/2023

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
BCRYPT_BLOCK_PADDING	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
BCRYPT_PAD_NONE	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.
BCRYPT_PAD_OAEP	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 .
BCRYPT_PAD_PKCS1	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
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_AUTH_TAG_MISMATCH	Il tag di autenticazione calcolata non corrisponde al valore specificato nel parametro pPaddingInfo .
STATUS_BUFFER_TOO_SMALL	Le dimensioni specificate dal parametro cbOutput non sono sufficienti per contenere il testo di crittografia.
STATUS_INVALID_BUFFER_SIZE	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 .
STATUS_INVALID_HANDLE	L'handle della chiave nel parametro hKey non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.
STATUS_NOT_SUPPORTED	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

Vedi anche

BCryptEncrypt

Condividi tramite