Funzione BCryptDecapsulate

Annotazioni

Alcune informazioni riguardano un prodotto in versione preliminare che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non fornisce alcuna garanzia, espressa o implicita, in relazione alle informazioni fornite qui. La funzionalità descritta in questo argomento è disponibile nelle versioni non definitive del Windows Insider Preview.

La funzione BCryptDecapsulate esegue l'operazione di decapsulation di un meccanismo di incapsulamento chiave (KEM). Accetta un testo crittografato KEM e decrittografa con la chiave privata fornita, restituendo la chiave privata condivisa.

Se il testo crittografato è formattato correttamente ma non corrisponde alla chiave di decapsulation, questa API avrà esito positivo, ma verrà generata una chiave privata condivisa casuale.

Sintassi

NTSTATUS BCryptDecapsulate(
  _In_  BCRYPT_KEY_HANDLE hKey,
  _In_reads_bytes_(cbCipherText)
        PUCHAR            pbCipherText,
  _In_  ULONG             cbCipherText,
  _Out_writes_bytes_to_opt_(cbSecretKey, *pcbSecretKey)
        PUCHAR            pbSecretKey,
  _In_  ULONG             cbSecretKey,
  _Out_ ULONG             *pcbSecretKey,
  _In_  ULONG             dwFlags
);

Parametri

hKey[in]

Handle della chiave da usare per decapsulare il testo crittografato KEM. Deve essere la chiave privata (decapsulation) che corrisponde alla chiave pubblica (incapsulamento) usata per produrre il testo crittografato KEM. L'handle di chiave viene ottenuto da una delle funzioni di creazione della coppia di chiavi, ad esempio BCryptGenerateKeyPair o BCryptImportKeyPair.

pbCipherText[in]

Puntatore a un buffer contenente il testo crittografato KEM. La funzione BCryptEncapsulate può essere usata per creare un testo crittografato KEM.

cbCipherText[in]

Dimensioni, in byte, del buffer pbCipherText .

pbSecretKey[out]

Puntatore a un buffer che riceve la chiave privata condivisa. Per altre informazioni, vedere le osservazioni .

cbSecretKey[in]

Dimensione, in byte, del buffer pbSecretKey .

pcbSecretKey[out]

Puntatore a una variabile ULONG che riceve il numero di byte scritti nel buffer pbSecretKey .

Se pbSecretKey è NULL, riceve le dimensioni, in byte, necessarie per la chiave privata condivisa. Per altre informazioni, vedere le osservazioni .

dwFlags[in]

Riservato, deve essere zero.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non solo, quanto segue.

Codice di ritorno	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_INVALID_PARAMETER	Uno o più parametri obbligatori (hKey, pcbSecretKey, pbCipherText) è NULLo uno dei parametri ha un valore non valido.
STATUS_INVALID_BUFFER_SIZE	Una dimensione del buffer (cbSecretKey, cbCipherText) non corrisponde alle dimensioni previste per i parametri KEM associati alla chiave di decapsulation.
STATUS_BUFFER_TOO_SMALL	Una dimensione del buffer di output (cbSecretKey) è troppo piccola per l'operazione di decapsulation dei risultati per i parametri KEM associati alla chiave di decapsulation. pcbSecretKey riceve il numero di byte necessari per pbSecretKey.

Osservazioni:

Per eseguire una query sulle dimensioni necessarie del buffer pbSecretKey necessario per la chiave privata condivisa KEM, chiamare BCryptDecapsulate con pbSecretKeyNULL. Le dimensioni richieste verranno restituite in pcbSecretKey. Questa query è efficiente e restituisce le dimensioni senza eseguire il decapsulation. In modo equivalente, usare BCryptGetProperty per eseguire una query sulla proprietà BCRYPT_KEM_SHARED_SECRET_LENGTH dell'algoritmo o dell'handle di chiave. Per gli algoritmi KEM attualmente supportati (ML-KEM), la lunghezza del segreto condiviso è una dimensione costante per un determinato algoritmo.

Osservazioni aggiuntive

Dato un testo crittografato non valido, ma con dimensioni corrette, l'operazione di decapsulation ML-KEM rifiuterà in modo implicito il testo crittografato restituendo esito positivo in tempo uguale a un'operazione di decapsulation valida, con output di chiave privata condivisa pseudo-casuale. In questo modo i protocolli di livello superiore non vengono eseguiti in un secondo momento quando le chiavi simmetriche dei peer non corrispondono. Di conseguenza, il decapsulato avrà esito negativo solo se sono presenti errori di programmazione (ad esempio dimensioni non corrette, uso di hKey non inizializzati) o qualcosa di fondamentalmente va storto con l'ambiente (ovvero l'allocazione della memoria interna non riesce o il test di coerenza interna rileva un errore hardware).

Requisiti

Requisito	Valore
Client minimo supportato	Windows Insiders Preview [solo app desktop]
Server minimo supportato	Windows Insiders Preview [solo app desktop]
Biblioteca	Bcrypt.lib
DLL	Bcrypt.dll

Vedere anche

BCryptEncapsulate

BCryptGetProperty