структура BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO (bcrypt.h)

Статья
08/22/2023

Структура BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO используется с функциями BCryptEncrypt и BCryptDecrypt для хранения дополнительных сведений, связанных с режимами шифров, прошедших проверку подлинности.

Синтаксис

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;

Члены

cbSize

Размер данной структуры (в байтах). Не устанавливайте это поле напрямую. Вместо этого используйте макрос BCRYPT_INIT_AUTH_MODE_INFO .

dwInfoVersion

Номер версии структуры. Единственное поддерживаемое значение — BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION. Не устанавливайте это поле напрямую. Вместо этого используйте макрос BCRYPT_INIT_AUTH_MODE_INFO .

pbNonce

Указатель на буфер, содержащий nonce. Поставщики алгоритмов Майкрософт для расширенного стандарта шифрования (AES) требуют nonce для счетчика с режимами цепочки CBC-MAC (CCM) и галуа/счетчика (GCM) и возвращают ошибку, если они отсутствуют. Если nonce не используется, этому элементу необходимо задать значение NULL.

cbNonce

Размер (в байтах) буфера, на который указывает член pbNonce . Если nonce не используется, этому элементу необходимо задать нулевое значение.

pbAuthData

Указатель на буфер, содержащий данные, прошедшие проверку подлинности. Это данные, которые будут включены в код проверки подлинности сообщения (MAC), но не зашифрованы. Если данные, прошедшие проверку подлинности, отсутствуют, этому элементу необходимо задать значение NULL.

cbAuthData

Размер (в байтах) буфера, на который указывает элемент pbAuthData . Если данные, прошедшие проверку подлинности, отсутствуют, этому элементу необходимо задать нулевое значение.

pbTag

Указатель на буфер.

Использование этого элемента зависит от функции, которой передается структура.

Функция	Описание
BCryptEncrypt	Буфер получит тег проверки подлинности.
BCryptDecrypt	Буфер содержит тег проверки подлинности для проверки подлинности.

Если тег отсутствует, для этого элемента необходимо задать значение NULL.

cbTag

Размер буфера pbTag (в байтах). Буфер должен быть достаточно длинным, чтобы включить весь тег проверки подлинности. Некоторые режимы проверки подлинности, такие как CCM и GCM, поддерживают проверку тега с несколькими длинами. Чтобы получить допустимые длины тегов проверки подлинности, используйте BCryptGetProperty для запроса свойства BCRYPT_AUTH_TAG_LENGTH . Если тег отсутствует, этот элемент должен быть равен нулю.

pbMacContext

Указатель на буфер, в котором хранится частично вычисляемый MAC-адрес между вызовами BCryptEncrypt и BCryptDecrypt при шифровании или расшифровке цепочки.

Если входные данные для шифрования или расшифровки распределены по нескольким буферам, необходимо связать вызовы функций BCryptEncrypt и BCryptDecrypt . Для цепочки можно задать флаг BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG в элементе dwFlags .

Этот буфер должен быть предоставлен вызывающим объектом и должен быть не меньше, чем максимальная длина тега проверки подлинности для используемого шифра. Чтобы получить допустимую длину тега проверки подлинности, используйте BCryptGetProperty для запроса свойства BCRYPT_AUTH_TAG_LENGTH .

Если вызовы BCryptEncrypt и BCryptDecrypt не связаны в цепочку, для этого элемента необходимо задать значение NULL.

cbMacContext

Размер (в байтах) буфера, на который указывает элемент pbMacContext . Если вызовы BCryptEncrypt и BCryptDecrypt не связаны в цепочку, этот член должен иметь нулевое значение.

cbAAD

Длина (в байтах) дополнительных данных, прошедших проверку подлинности (AAD), которые будут использоваться функциями BCryptEncrypt и BCryptDecrypt . Этот член используется только при связывании вызовов.

Этот элемент используется, только если установлен флаг BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG в элементе dwFlags .

При первом вызове BCryptEncrypt или BCryptDecrypt необходимо задать для этого поля нулевое значение.

Примечание Во время последовательности цепочки этот элемент поддерживается внутри организации и не должен изменяться, иначе значение вычисляемого MAC-адреса будет повреждено.

cbData

Длина (в байтах) полезных данных, которые были зашифрованы или расшифрованы. Этот член используется только при связывании вызовов.

Этот элемент используется, только если установлен флаг BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG в элементе dwFlags .

При первом вызове BCryptEncrypt или BCryptDecrypt необходимо задать для этого поля нулевое значение либо напрямую, либо путем вызова макроса BCRYPT_INIT_AUTH_INFO

dwFlags

Этот флаг используется при связывании вызовов функций BCryptEncrypt или BCryptDecrypt . Если вызовы не связаны в цепочку, для этого элемента необходимо задать нулевое значение.

Значение	Значение
0x00000000	Для BCryptEncrypt вычислите тег проверки подлинности и поместите его в буфер, на который указывает элемент pbTag . Для BCryptDecrypt вычислите тег проверки подлинности и сравните его с тегом, переданным в буфер, на который указывает элемент pbTag . При связывании нескольких вызовов bCryptEncrypt или BCryptDecrypt это значение указывает на конец цепочки.
BCRYPT_AUTH_MODE_CHAIN_CALLS_FLAG 0x00000001	Указывает, что вызовы функций BCryptEncrypt и BCryptDecrypt связаны в цепочку и что значение MAC не будет вычисляться. При последнем вызове в цепочке очистите это значение, чтобы вычислить значение MAC для всей цепочки.
BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG 0x00000002	Указывает, что эта BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO структура используется в последовательности связанных вызовов функций BCryptEncrypt или BCryptDecrypt . Этот флаг устанавливается и поддерживается внутри системы. Примечание Во время последовательности цепочки это значение флага сохраняется внутри системы и не должно изменяться, иначе значение вычисляемого MAC-адреса будет повреждено.

Размер этой структуры отличается для 64-разрядных и 32-разрядных операционных систем. В 64-разрядных операционных системах размер зависит от 64-разрядных и 32-разрядных процессов. Экземпляры этой структуры не должны совместно использоваться в потоках или передаваться между процессами.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista с пакетом обновления 1 (SP1) [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Верхняя часть	bcrypt.h

Поделиться через

структура BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO (bcrypt.h)

Синтаксис

Члены

Комментарии

Требования

Обратная связь

Дополнительные ресурсы