BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure (bcrypt.h)
The BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure is used with the BCryptEncrypt and BCryptDecrypt functions to contain additional information related to authenticated cipher modes.
Syntax
typedef struct _BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO {
ULONG cbSize;
ULONG dwInfoVersion;
PUCHAR pbNonce;
ULONG cbNonce;
PUCHAR pbAuthData;
ULONG cbAuthData;
PUCHAR pbTag;
ULONG cbTag;
PUCHAR pbMacContext;
ULONG cbMacContext;
ULONG cbAAD;
ULONGLONG cbData;
ULONG dwFlags;
} BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO, *PBCRYPT_AUTHENTICATED_CIPHER_MODE_INFO;
Members
cbSize
The size, in bytes, of this structure. Do not set this field directly. Use the BCRYPT_INIT_AUTH_MODE_INFO macro instead.
dwInfoVersion
The version number of the structure. The only supported value is BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION. Do not set this field directly. Use the BCRYPT_INIT_AUTH_MODE_INFO macro instead.
pbNonce
A pointer to a buffer that contains a nonce. The Microsoft algorithm providers for Advanced Encryption Standard (AES) require a nonce for the Counter with CBC-MAC (CCM) and Galois/Counter Mode (GCM) chaining modes, and will return an error if none is present. If a nonce is not used, this member must be set to NULL.
cbNonce
The size, in bytes, of the buffer pointed to by the pbNonce member. If a nonce is not used, this member must be set to zero.
pbAuthData
A pointer to a buffer that contains the authenticated data. This is data that will be included in the Message Authentication Code (MAC) but not encrypted. If there is no authenticated data, this member must be set to NULL.
cbAuthData
The size, in bytes, of the buffer pointed to by the pbAuthData member. If there is no authenticated data, this member must be set to zero.
pbTag
A pointer to a buffer.
The use of this member depends on the function to which the structure is passed.
| Function | Description |
|---|---|
| The buffer will receive the authentication tag. | |
| The buffer contains the authentication tag to be checked against. |
If there is no tag, this member must be set to NULL.
cbTag
The size, in bytes, of the pbTag buffer. The buffer must be long enough to include the whole authentication tag. Some authentication modes, such as CCM and GCM, support checking against a tag with multiple lengths. To obtain the valid authentication tag lengths use BCryptGetProperty to query the BCRYPT_AUTH_TAG_LENGTH property. If there is no tag, this member must be set to zero.
pbMacContext
A pointer to a buffer that stores the partially computed MAC between calls to BCryptEncrypt and BCryptDecrypt when chaining encryption or decryption.
If the input to encryption or decryption is scattered across multiple buffers, then you must chain calls to the BCryptEncrypt and BCryptDecrypt functions. Chaining is indicated by setting the BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG flag in the dwFlags member.
This buffer must be supplied by the caller and must be at least as large as the maximum length of an authentication tag for the cipher you are using. To get the valid authentication tag lengths, use BCryptGetProperty to query the BCRYPT_AUTH_TAG_LENGTH property.
If BCryptEncrypt and BCryptDecrypt calls are not being chained, this member must be set to NULL.
cbMacContext
The size, in bytes, of the buffer pointed to by the pbMacContext member. If BCryptEncrypt and BCryptDecrypt calls are not being chained, this member must be set to zero.
cbAAD
The length, in bytes, of additional authenticated data (AAD) to be used by the BCryptEncrypt and BCryptDecrypt functions. This member is used only when chaining calls.
This member is used only when the BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG flag in the dwFlags member is set.
On the first call to BCryptEncrypt or BCryptDecrypt you must set this field to zero.
cbData
The length, in bytes, of the payload data that was encrypted or decrypted. This member is used only when chaining calls.
This member is used only when the BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG flag in the dwFlags member is set.
On the first call to BCryptEncrypt or BCryptDecrypt you must set this field to zero, , either directly or by calling the BCRYPT_INIT_AUTH_INFO macro
dwFlags
This flag is used when chaining BCryptEncrypt or BCryptDecrypt function calls. If calls are not being chained, this member must be set to zero.
| Value | Meaning |
|---|---|
|
For BCryptEncrypt, calculate the authentication tag and place it in the buffer pointed to by the pbTag member.
For BCryptDecrypt, calculate the authentication tag and compare it against the tag passed in to the buffer pointed to by the pbTag member. When chaining multiple calls to BCryptEncrypt or BCryptDecrypt, this value signals the end of the chain. |
|
Indicates that BCryptEncrypt and BCryptDecrypt function calls are being chained and that the MAC value will not be computed. On the last call in the chain, clear this value to compute the MAC value for the entire chain. |
|
Indicates that this BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure is being used in a sequence of chained BCryptEncrypt or BCryptDecrypt function calls. This flag is set and maintained internally.
Note During the chaining sequence, this flag value is maintained internally and must not be changed or the value of the computed MAC will be corrupted.
|
Remarks
The size of this structure is different between 64-bit and 32-bit operating systems. On 64-bit operating systems, the size is different between 64-bit and 32-bit processes. Instances of this structure must not be shared across threads or passed between processes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista with SP1 [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Header | bcrypt.h |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for