Funzione CryptEncrypt (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 CryptEncrypt crittografa i dati. L'algoritmo usato per crittografare i dati viene designato dalla chiave contenuta nel modulo CSP e fa riferimento al parametro hKey .

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.

Importante La funzione CryptEncrypt non è garantita che sia thread-safe e potrebbe restituire risultati non corretti se richiamati simultaneamente da più chiamanti.

Sintassi

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

Parametri

[in] hKey

Handle per la chiave di crittografia. Un'applicazione ottiene questo handle usando la CryptGenKey o la funzione CryptImportKey.

La chiave specifica l'algoritmo di crittografia utilizzato.

[in] hHash

Handle per un oggetto hash . Se i dati devono essere contemporaneamente con hash e crittografati, è possibile passare un handle a un oggetto hash nel parametro hHash. Il valore hash viene aggiornato con il testo non crittografato passato. Questa opzione è utile quando si genera testo firmato e crittografato.

Prima di chiamare CryptEncrypt, l'applicazione deve ottenere un handle per l'oggetto hash chiamando la funzione CryptCreateHash. Al termine della crittografia, è possibile ottenere il valore hash usando la funzione CryptGetHashParam oppure l'hash può essere firmato usando la funzione CryptSignHash.

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

[in] Final

Valore booleano che specifica se si tratta dell'ultima sezione di una serie crittografata. finale è impostato su TRUE per l'ultimo blocco o solo e su false se sono presenti più blocchi da crittografare. Per altre informazioni, vedere Osservazioni.

[in] dwFlags

Il dwFlags seguente valore è definito ma riservato per un uso futuro.

Valore	Significato
CRYPT_OAEP	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.

[in, out] pbData

Puntatore a un buffer contenente il testo non crittografato da crittografare. Il testo non crittografato in questo buffer viene sovrascritto con il testo crittografato creato da questa funzione.

Il parametro pdwDataLen punta a una variabile contenente la lunghezza, in byte, del testo non crittografato. Il parametro dwBufLen contiene le dimensioni totali, in byte, di questo buffer.

Se questo parametro contiene NULL, questa funzione calcolerà le dimensioni necessarie per il testo crittografato e lo inserisce nel valore a cui punta il parametro pdwDataLen.

[in, out] pdwDataLen

Puntatore a un valore DWORD che , in ingresso, contiene la lunghezza, in byte, del testo non crittografato nel buffer pbData. All'uscita, questo DWORD contiene la lunghezza, in byte, del testo crittografato scritto nel buffer pbData.

Se il buffer allocato per pbData non è sufficientemente grande da contenere i dati crittografati, GetLastError restituisce ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nel valore DWORD a cui punta pdwDataLen.

Se pbData è NULL, non viene restituito alcun errore e la funzione archivia le dimensioni dei dati crittografati, in byte, nel valore DWORD a cui punta pdwDataLen. Ciò consente a un'applicazione di determinare le dimensioni corrette del buffer.

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 crittografare e il parametro finale sia TRUE.

[in] dwBufLen

Specifica le dimensioni totali, in byte, dell'input pbData buffer.

Si noti che, a seconda dell'algoritmo usato, il testo crittografato può essere maggiore del testo non crittografato originale. In questo caso, il buffer pbData deve essere sufficientemente grande da contenere il testo crittografato e qualsiasi spaziatura interna.

Come regola, se si usa un di crittografia del flusso, il testo crittografato corrisponde alla stessa dimensione del testo non crittografato. Se viene usata una di crittografia a blocchi , il testo crittografato è superiore a una lunghezza del blocco maggiore del testo non crittografato.

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 crittografare 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.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_HASH	Il parametro hHash contiene un handle non valido.
NTE_BAD_HASH_STATE	È stato effettuato un tentativo di aggiungere dati a un oggetto hash già contrassegnato come "completato".
NTE_BAD_KEY	Il parametro hKey non contiene un handle valido per una chiave.
NTE_BAD_LEN	Le dimensioni del buffer di output sono troppo piccole per contenere il testo 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 crittografare due volte gli stessi dati.
NTE_FAIL	La funzione non è riuscita in modo imprevisto.
NTE_NO_MEMORY	Il provider di servizi di configurazione ha esaurito la memoria durante l'operazione.

Osservazioni

Se una grande quantità di dati deve essere crittografata, può essere eseguita in sezioni chiamando CryptEncrypt ripetutamente. Il parametro Final deve essere impostato su TRUE sull'ultima chiamata a CryptEncrypt, in modo che il motore di crittografia possa completare correttamente il processo di crittografia. 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. Se la lunghezza dei dati è uguale alla dimensione del blocco della crittografia, viene aggiunto un blocco aggiuntivo di riempimento ai dati. 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 CryptEncrypt reimposta il registro dei commenti e suggerimenti della crittografia sul valore KP_IV della chiave.
Se la crittografia è una crittografia di flusso , il successivo CryptEncrypt reimposta la crittografia sullo 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 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 CryptEncrypt. 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)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(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 dei dati di testo non crittografato che è possibile crittografare con una chiamata a CryptEncrypt con una chiave RSA è la lunghezza del modulo di chiave meno undici byte. Gli undici byte sono il minimo scelto per la spaziatura interna PKCS #1. Il testo crittografato viene restituito in formato little-endian.

Esempi

Per esempi che usano questa funzione, vedere Programma C di esempio: Crittografia di un di file e 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