Funzione NCryptEncrypt (ncrypt.h)

Articolo
03/15/2023

La funzione NCryptEncrypt crittografa un blocco di dati.

Sintassi

SECURITY_STATUS NCryptEncrypt(
  [in]           NCRYPT_KEY_HANDLE hKey,
  [in]           PBYTE             pbInput,
  [in]           DWORD             cbInput,
  [in, optional] VOID              *pPaddingInfo,
  [out]          PBYTE             pbOutput,
  [in]           DWORD             cbOutput,
  [out]          DWORD             *pcbResult,
  [in]           DWORD             dwFlags
);

Parametri

[in] hKey

Handle della chiave da usare per crittografare i dati.

[in] pbInput

Indirizzo di un buffer che contiene i dati da crittografare. Il parametro cbInput contiene le dimensioni dei dati 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. Il tipo effettivo di struttura a cui punta questo parametro dipende dal valore del parametro dwFlags . Questo parametro viene usato solo con chiavi asimmetriche e deve essere NULL in caso contrario.

[out] pbOutput

Indirizzo di un buffer che riceverà i dati crittografati generati da questa funzione. Il parametro cbOutput contiene le dimensioni di questo buffer. Per altre informazioni, vedere la sezione Osservazioni.

Se questo parametro è NULL, questa funzione calcola le dimensioni necessarie per i dati crittografati e restituisce le dimensioni nella posizione a cui punta il parametro pcbResult .

[in] cbOutput

Dimensioni, in byte, del buffer pbOutput . Questo parametro viene ignorato se il parametro pbOutput è NULL.

[out] pcbResult

Puntatore a una variabile DWORD 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

Contrassegni che modificano il comportamento della funzione. Il set consentito di flag dipende dal tipo di chiave specificato dal parametro hKey .

Se la chiave è una chiave asimmetrica, questo può essere uno dei valori seguenti.

Valore	Significato
NCRYPT_NO_PADDING_FLAG	Non usare spaziatura interna. Il parametro pPaddingInfo non viene usato. Se si specifica la NCRYPT_NO_PADDING_FLAG, la funzione NCryptEncrypt crittografa solo i primi bit N, dove N è la lunghezza della chiave passata come parametro hKey . Tutti i bit dopo i primi bit N vengono ignorati.
NCRYPT_PAD_OAEP_FLAG	Usare lo schema OAEP (Optimal Asymmetric Encryption Padding). Il parametro pPaddingInfo è un puntatore a una struttura BCRYPT_OAEP_PADDING_INFO .
NCRYPT_PAD_PKCS1_FLAG	I dati verranno riempiti con un numero casuale per arrotondare le dimensioni del blocco. Il parametro pPaddingInfo non viene usato.
NCRYPT_SILENT_FLAG	Richiede che il provider di servizi chiave (KSP) non visualizzi alcuna interfaccia utente. Se il provider deve visualizzare l'interfaccia utente da operare, la chiamata ha esito negativo e il KSP deve impostare il codice di errore NTE_SILENT_CONTEXT come ultimo errore.

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
ERROR_SUCCESS	La funzione ha avuto esito positivo.
NTE_BAD_FLAGS	Il parametro dwFlags contiene un valore non valido.
NTE_BAD_KEY_STATE	La chiave identificata dal parametro hKey non è stata completata o è incompleta.
NTE_BUFFER_TOO_SMALL	Le dimensioni specificate dal parametro cbOutput non sono sufficienti per contenere i dati crittografati.
NTE_INVALID_HANDLE	Il parametro hKey non è valido.
NTE_INVALID_PARAMETER	Uno o più parametri non sono validi.

Commenti

I parametri pbInput e pbOutput possono puntare allo stesso buffer. 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.

Un servizio non deve chiamare questa funzione dalla funzione StartService. Se un servizio chiama questa funzione dalla funzione StartService, può verificarsi un deadlock e il servizio potrebbe interrompere la risposta.

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	ncrypt.h
Libreria	Ncrypt.lib
DLL	Ncrypt.dll

Condividi tramite