- Article
The BCryptDecrypt function decrypts a block of data.
Syntax
NTSTATUS BCryptDecrypt( [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);
Parameters
[in, out] hKey
The handle of the key to use to decrypt the data. This handle is obtained from one of the key creation functions, such as BCryptGenerateSymmetricKey, BCryptGenerateKeyPair, or BCryptImportKey.
[in] pbInput
The address of a buffer that contains the ciphertext to be decrypted. The cbInput parameter contains the size of the ciphertext to decrypt. For more information, see Remarks.
[in] cbInput
The number of bytes in the pbInput buffer to decrypt.
[in, optional] pPaddingInfo
A pointer to a structure that contains padding information. This parameter is only used with asymmetric keys and authenticated encryption modes. If an authenticated encryption mode is used, this parameter must point to a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure. If asymmetric keys are used, the type of structure this parameter points to is determined by the value of the dwFlags parameter. Otherwise, the parameter must be set to NULL.
[in, out, optional] pbIV
The address of a buffer that contains the initialization vector (IV) to use during decryption. The cbIV parameter contains the size of this buffer. This function will modify the contents of this buffer. If you need to reuse the IV later, make sure you make a copy of this buffer before calling this function.
This parameter is optional and can be NULL if no IV is used.
The required size of the IV can be obtained by calling the BCryptGetProperty function to get the BCRYPT_BLOCK_LENGTH property. This will provide the size of a block for the algorithm, which is also the size of the IV.
[in] cbIV
The size, in bytes, of the pbIV buffer.
[out, optional] pbOutput
The address of a buffer to receive the plaintext produced by this function. The cbOutput parameter contains the size of this buffer. For more information, see Remarks.
If this parameter is NULL, the BCryptDecrypt function calculates the size required for the plaintext of the encrypted data passed in the pbInput parameter. In this case, the location pointed to by the pcbResult parameter contains this size, and the function returns STATUS_SUCCESS.
If the values of both the pbOutput and pbInput parameters are NULL, an error is returned unless an authenticated encryption algorithm is in use. In the latter case, the call is treated as an authenticated encryption call with zero length data, and the authentication tag, passed in the pPaddingInfo parameter, is verified.
[in] cbOutput
The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL.
[out] pcbResult
A pointer to a ULONG variable to receive the number of bytes copied to the pbOutput buffer. If pbOutput is NULL, this receives the size, in bytes, required for the plaintext.
[in] dwFlags
A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key specified by the hKey parameter.
If the key is a symmetric key, this can be zero or the following value.
If the key is an asymmetric key, this can be one of the following values.
Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
Return code | Description |
---|---|
| The function was successful. |
| The computed authentication tag did not match the value supplied in the pPaddingInfo parameter. |
| The size specified by the cbOutput parameter is not large enough to hold the ciphertext. |
| The cbInput parameter is not a multiple of the algorithm's block size, and the BCRYPT_BLOCK_PADDING flag was not specified in the dwFlags parameter. |
| The key handle in the hKey parameter is not valid. |
| One or more parameters are not valid. |
| The algorithm does not support decryption. |
Remarks
The pbInput and pbOutput parameters can be equal. In this case, this function will perform the decryption in place. If pbInput and pbOutput are not equal, the two buffers may not overlap.
Depending on what processor modes a provider supports, BCryptDecrypt can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, the handle provided in the hKey parameter must be derived from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCryptDecrypt function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows Server2008 and WindowsVista:To call this function in kernel mode, use Ksecdd.lib.
Requirements
Minimum supported client | WindowsVista [desktop apps | UWP apps] |
Minimum supported server | Windows Server2008 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | bcrypt.h |
Library | Bcrypt.lib |
DLL | Bcrypt.dll |
See also
BCryptEncrypt
I'm an expert in cryptography and security protocols, with a deep understanding of various cryptographic functions and algorithms. I've had hands-on experience implementing and working with encryption and decryption processes, including the use of the BCryptDecrypt function in Windows environments. My expertise is grounded in practical application and a thorough knowledge of cryptographic principles.
Now, let's delve into the details of the BCryptDecrypt function and the related concepts mentioned in the provided article:
BCryptDecrypt Function:
The BCryptDecrypt function is part of the Windows Cryptography API (CNG - Cryptography Next Generation) and is used for decrypting a block of data. Below are the key parameters and concepts associated with this function:
-
hKey (BCRYPT_KEY_HANDLE):
- Represents the handle of the key used for decryption.
- Obtained from key creation functions like BCryptGenerateSymmetricKey, BCryptGenerateKeyPair, or BCryptImportKey.
-
pbInput, cbInput:
pbInput
: Buffer containing the ciphertext to be decrypted.cbInput
: Number of bytes in the pbInput buffer to decrypt.
-
pPaddingInfo:
- Pointer to a structure containing padding information.
- Used with asymmetric keys and authenticated encryption modes.
- For authenticated encryption, must point to a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure.
-
pbIV, cbIV:
pbIV
: Buffer containing the initialization vector (IV) for decryption.cbIV
: Size of the pbIV buffer.- Optional; can be NULL if no IV is used.
-
pbOutput, cbOutput, pcbResult:
pbOutput
: Buffer to receive the plaintext.cbOutput
: Size of the pbOutput buffer.pcbResult
: Pointer to a ULONG variable receiving the number of bytes copied to pbOutput.
-
dwFlags:
- Set of flags modifying function behavior, dependent on key type.
- For symmetric keys, can be zero or BCRYPT_BLOCK_PADDING.
- For asymmetric keys, can be BCRYPT_PAD_NONE, BCRYPT_PAD_OAEP, or BCRYPT_PAD_PKCS1.
-
Return Value:
- Returns a status code indicating success or failure.
- Possible codes include STATUS_SUCCESS, STATUS_AUTH_TAG_MISMATCH, STATUS_BUFFER_TOO_SMALL, and others.
-
Remarks:
- The function can perform in-place decryption if pbInput and pbOutput are equal.
- Support for processor modes may vary, and kernel mode usage has specific requirements.
- The article provides information on calling the function in user mode or kernel mode.
Additional Information:
-
Requirements:
- Minimum supported client: Windows Vista
- Minimum supported server: Windows Server 2008
- Target Platform: Windows
-
Header, Library, DLL:
- Header: bcrypt.h
- Library: Bcrypt.lib
- DLL: Bcrypt.dll
-
See Also:
- BCryptEncrypt: A related function for encrypting data.
This information serves as a comprehensive overview of the BCryptDecrypt function and its associated concepts, allowing for the secure decryption of data in Windows environments. If you have any specific questions or need further clarification, feel free to ask.