Funzione BCryptEncrypt (bcrypt.h)
La funzione BCryptEncrypt crittografa un blocco di dati.
Sintassi
NTSTATUS BCryptEncrypt(
[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 crittografare 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 che contiene il testo non crittografato da crittografare. Il parametro cbInput contiene le dimensioni del testo non crittografato da crittografare. Per altre informazioni, vedere la sezione Osservazioni.
[in] cbInput
Numero di byte nel buffer pbInput da crittografare.
[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 crittografia. 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 del buffer che riceve il testo di crittografia 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 BCryptEncrypt calcola le dimensioni necessarie per il testo di crittografia dei dati passati nel parametro pbInput . In questo caso, la posizione a cui punta il parametro pcbResult contiene questa dimensione e la funzione restituisce STATUS_SUCCESS. Il parametro pPaddingInfo non viene modificato.
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 viene restituito nel parametro pPaddingInfo .
[in] cbOutput
Dimensioni, in byte, del buffer pbOutput . Questo parametro viene ignorato se il parametro pbOutput è NULL.
[out] pcbResult
Puntatore a una variabile ULONG che riceve il numero di byte copiati nel buffer pbOutput . Se pbOutput è NULL, questa riceve le dimensioni, in byte, necessarie per il testo di crittografia.
[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 |
|---|---|
|
Consente all'algoritmo di crittografia di eseguire il pad dei dati alla dimensione del blocco successiva. Se questo flag non è specificato, le dimensioni del testo non crittografato specificato nel parametro cbInput devono 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. 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. Le dimensioni del testo non crittografato specificato nel parametro cbInput devono essere un multiplo delle dimensioni del blocco dell'algoritmo. |
|
Usare lo schema OAEP (Optimal Asymmetric Encryption Padding). Il parametro pPaddingInfo è un puntatore a una struttura BCRYPT_OAEP_PADDING_INFO . |
|
I dati verranno riempiti con un numero casuale per arrotondare le dimensioni del blocco. 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. |
|
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 BCRYPT_BLOCK_PADDING o il flag di BCRYPT_PAD_NONE 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 crittografia. |
Commenti
I parametri pbInput e pbOutput possono essere uguali. In questo caso, questa funzione eseguirà la crittografia sul posto. È possibile che le dimensioni dei dati crittografate siano maggiori delle dimensioni dei dati non crittografate, pertanto il buffer deve essere abbastanza grande per contenere i dati crittografati. Se pbInput e pbOutput non sono uguali, i due buffer potrebbero non sovrapporsi.
A seconda delle modalità di processore supportate da un provider, BCryptEncrypt può essere chiamato 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 BCryptEncrypt 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
| Requisito | Valore |
|---|---|
| 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 |