BCryptEncrypt-Funktion (bcrypt.h)

  • Artikel

Die BCryptEncrypt-Funktion verschlüsselt einen Datenblock.

Syntax

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
);

Parameter

[in, out] hKey

Das Handle des Schlüssels, der zum Verschlüsseln der Daten verwendet werden soll. Dieses Handle wird von einer der Schlüsselerstellungsfunktionen abgerufen, z. B. BCryptGenerateSymmetricKey, BCryptGenerateKeyPair oder BCryptImportKey.

[in] pbInput

Die Adresse eines Puffers, der den zu verschlüsselnden Klartext enthält. Der cbInput-Parameter enthält die Größe des zu verschlüsselnden Klartexts. Weitere Informationen finden Sie in den Hinweisen.

[in] cbInput

Die Anzahl der zu verschlüsselnden Bytes im PbInput-Puffer .

[in, optional] pPaddingInfo

Ein Zeiger auf eine Struktur, die Auffüllungsinformationen enthält. Dieser Parameter wird nur mit asymmetrischen Schlüsseln und authentifizierten Verschlüsselungsmodi verwendet. Wenn ein authentifizierter Verschlüsselungsmodus verwendet wird, muss dieser Parameter auf eine BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO Struktur verweisen. Wenn asymmetrische Schlüssel verwendet werden, wird der Strukturtyp, auf den dieser Parameter verweist, durch den Wert des dwFlags-Parameters bestimmt. Andernfalls muss der Parameter auf NULL festgelegt werden.

[in, out, optional] pbIV

Die Adresse eines Puffers, der den Initialisierungsvektor (IV) enthält, der während der Verschlüsselung verwendet werden soll. Der cbIV-Parameter enthält die Größe dieses Puffers. Diese Funktion ändert den Inhalt dieses Puffers. Wenn Sie die IV später wiederverwenden müssen, stellen Sie sicher, dass Sie eine Kopie dieses Puffers erstellen, bevor Sie diese Funktion aufrufen.

Dieser Parameter ist optional und kann NULL sein, wenn kein IV verwendet wird.

Die erforderliche Größe des IV kann durch Aufrufen der BCryptGetProperty-Funktion abgerufen werden, um die BCRYPT_BLOCK_LENGTH-Eigenschaft abzurufen. Dadurch wird die Größe eines Blocks für den Algorithmus bereitgestellt, der auch die Größe des IV entspricht.

[in] cbIV

Die Größe des pbIV-Puffers in Bytes.

[out, optional] pbOutput

Die Adresse des Puffers, der den von dieser Funktion erzeugten Chiffretext empfängt. Der cbOutput-Parameter enthält die Größe dieses Puffers. Weitere Informationen finden Sie in den Hinweisen.

Wenn dieser Parameter NULL ist, berechnet die BCryptEncrypt-Funktion die größe, die für den Verschlüsselungstext der im pbInput-Parameter übergebenen Daten erforderlich ist. In diesem Fall enthält die Position, auf die der pcbResult-Parameter verweist, diese Größe, und die Funktion gibt STATUS_SUCCESS zurück. Der pPaddingInfo-Parameter wird nicht geändert.

Wenn die Werte der Parameter pbOutput und pbInputNULL sind, wird ein Fehler zurückgegeben, es sei denn, ein authentifizierter Verschlüsselungsalgorithmus wird verwendet. Im letzteren Fall wird der Aufruf als authentifizierter Verschlüsselungsaufruf mit Daten der Länge null behandelt, und das Authentifizierungstag wird im pPaddingInfo-Parameter zurückgegeben.

[in] cbOutput

Die Größe des pbOutput-Puffers in Bytes. Dieser Parameter wird ignoriert, wenn der pbOutput-ParameterNULL ist.

[out] pcbResult

Ein Zeiger auf eine ULONG-Variable , die die Anzahl der Bytes empfängt, die in den PbOutput-Puffer kopiert wurden. Wenn pbOutputNULL ist, empfängt dies die Größe in Bytes, die für den Verschlüsselungstext erforderlich ist.

[in] dwFlags

Eine Reihe von Flags, die das Verhalten dieser Funktion ändern. Der zulässige Satz von Flags hängt vom Typ des Schlüssels ab, der durch den hKey-Parameter angegeben wird.

Wenn es sich bei dem Schlüssel um einen symmetrischen Schlüssel handelt, kann dies null oder der folgende Wert sein.

Wert Bedeutung
BCRYPT_BLOCK_PADDING
 Ermöglicht dem Verschlüsselungsalgorithmus, die Daten auf die nächste Blockgröße zu binden. Wenn dieses Flag nicht angegeben ist, muss die im cbInput-Parameter angegebene Größe des Klartexts ein Vielfaches der Blockgröße des Algorithmus sein.

Die Blockgröße kann durch Aufrufen der BCryptGetProperty-Funktion abgerufen werden, um die BCRYPT_BLOCK_LENGTH-Eigenschaft für den Schlüssel abzurufen. Dadurch wird die Größe eines Blocks für den Algorithmus bereitgestellt.

Dieses Flag darf nicht mit den authentifizierten Verschlüsselungsmodi (AES-CCM und AES-GCM) verwendet werden.
 

Wenn es sich bei dem Schlüssel um einen asymmetrischen Schlüssel handelt, kann dies einer der folgenden Werte sein.

Wert Bedeutung
BCRYPT_PAD_NONE
 Verwenden Sie keine Auffüllung. Der pPaddingInfo-Parameter wird nicht verwendet. Die im cbInput-Parameter angegebene Größe des Klartexts muss ein Vielfaches der Blockgröße des Algorithmus sein.
BCRYPT_PAD_OAEP
 Verwenden Sie das OAEP-Schema (Optimal Asymmetric Encryption Padding). Der pPaddingInfo-Parameter ist ein Zeiger auf eine BCRYPT_OAEP_PADDING_INFO-Struktur .
BCRYPT_PAD_PKCS1
 Die Daten werden mit einer Zufallszahl aufgefüllt, um die Blockgröße abzurunden. Der pPaddingInfo-Parameter wird nicht verwendet.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes umfassen folgendes, sind aber nicht darauf beschränkt.

Rückgabecode Beschreibung
STATUS_SUCCESS
 Die Funktion war erfolgreich.
STATUS_BUFFER_TOO_SMALL
 Die vom cbOutput-Parameter angegebene Größe ist nicht groß genug, um den Verschlüsselungstext zu enthalten.
STATUS_INVALID_BUFFER_SIZE
 Der cbInput-Parameter ist kein Vielfaches der Blockgröße des Algorithmus, und das BCRYPT_BLOCK_PADDING oder das BCRYPT_PAD_NONE Flag wurde im dwFlags-Parameter nicht angegeben.
STATUS_INVALID_HANDLE
 Das Schlüsselhandle im hKey-Parameter ist ungültig.
STATUS_INVALID_PARAMETER
 Mindestens ein Parameter ist ungültig.
STATUS_NOT_SUPPORTED
 Der Algorithmus unterstützt keine Verschlüsselung.

Hinweise

Die Parameter pbInput und pbOutput können gleich sein. In diesem Fall führt diese Funktion die Verschlüsselung aus. Es ist möglich, dass die verschlüsselte Datengröße größer als die unverschlüsselte Datengröße ist, sodass der Puffer groß genug sein muss, um die verschlüsselten Daten aufzunehmen. Wenn pbInput und pbOutput nicht gleich sind, überlappen sich die beiden Puffer möglicherweise nicht.

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptEncrypt entweder im Benutzermodus oder im Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausführen. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss das im hKey-Parameter bereitgestellte Handle von einem Algorithmushandle abgeleitet werden, das von einem Anbieter zurückgegeben wird, der mit dem flag BCRYPT_PROV_DISPATCH geöffnet wurde, und alle Zeiger, die an die BCryptEncrypt-Funktion übergeben werden, müssen auf nicht ausgestellten (oder gesperrten) Arbeitsspeicher verweisen.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, die Teil des Driver Development Kit (DDK) ist. Windows Server 2008 und Windows Vista: Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Ksecdd.lib.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile bcrypt.h
Bibliothek Bcrypt.lib
DLL Bcrypt.dll

Weitere Informationen

BCryptDecrypt