BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO-Struktur (bcrypt.h)

Artikel
08/22/2023

Die BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO-Struktur wird mit den Funktionen BCryptEncrypt und BCryptDecrypt verwendet, um zusätzliche Informationen im Zusammenhang mit authentifizierten Verschlüsselungsmodi zu enthalten.

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;

Member

cbSize

Die Größe (in Bytes) dieser Struktur. Legen Sie dieses Feld nicht direkt fest. Verwenden Sie stattdessen das makro BCRYPT_INIT_AUTH_MODE_INFO .

dwInfoVersion

Die Versionsnummer der Struktur. Der einzige unterstützte Wert ist BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION. Legen Sie dieses Feld nicht direkt fest. Verwenden Sie stattdessen das makro BCRYPT_INIT_AUTH_MODE_INFO .

pbNonce

Ein Zeiger auf einen Puffer, der eine Nonce enthält. Die Microsoft-Algorithmusanbieter für Advanced Encryption Standard (AES) erfordern eine Nonce für den Leistungsindikator mit den Verkettungsmodi CBC-MAC (CCM) und Galois/Counter Mode (GCM) und geben einen Fehler zurück, wenn keine vorhanden ist. Wenn keine Nonce verwendet wird, muss dieser Member auf NULL festgelegt werden.

cbNonce

Die Größe des Puffers in Bytes, auf den das pbNonce-Element verweist. Wenn keine Nonce verwendet wird, muss dieses Element auf 0 festgelegt werden.

pbAuthData

Ein Zeiger auf einen Puffer, der die authentifizierten Daten enthält. Dies sind Daten, die im Nachrichtenauthentifizierungscode (MAC) enthalten, aber nicht verschlüsselt werden. Wenn keine authentifizierten Daten vorhanden sind, muss dieser Member auf NULL festgelegt werden.

cbAuthData

Die Größe des Puffers in Bytes, auf den das pbAuthData-Element verweist. Wenn keine authentifizierten Daten vorhanden sind, muss dieser Member auf Null festgelegt werden.

pbTag

Ein Zeiger auf einen Puffer.

Die Verwendung dieses Members hängt von der Funktion ab, an die die Struktur übergeben wird.

Funktion	BESCHREIBUNG
BCryptEncrypt	Der Puffer empfängt das Authentifizierungstag.
BCryptDecrypt	Der Puffer enthält das zu überprüfende Authentifizierungstag.

Wenn kein Tag vorhanden ist, muss dieses Element auf NULL festgelegt werden.

cbTag

Die Größe des pbTag-Puffers in Bytes. Der Puffer muss so lang sein, dass das gesamte Authentifizierungstag enthalten ist. Einige Authentifizierungsmodi, z. B. CCM und GCM, unterstützen die Überprüfung eines Tags mit mehreren Längen. Um die gültigen Authentifizierungstaglängen abzurufen, verwenden Sie BCryptGetProperty , um die BCRYPT_AUTH_TAG_LENGTH-Eigenschaft abzufragen. Wenn kein Tag vorhanden ist, muss dieses Element auf 0 festgelegt werden.

pbMacContext

Ein Zeiger auf einen Puffer, der den teilweise berechneten MAC zwischen Aufrufen von BCryptEncrypt und BCryptDecrypt beim Verketten von Verschlüsselung oder Entschlüsselung speichert.

Wenn die Eingabe für die Verschlüsselung oder Entschlüsselung auf mehrere Puffer verteilt ist, müssen Sie Aufrufe der Funktionen BCryptEncrypt und BCryptDecrypt verketten. Die Verkettung wird durch Festlegen des BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG-Flags im dwFlags-Element angegeben.

Dieser Puffer muss vom Aufrufer bereitgestellt werden und mindestens so groß sein wie die maximale Länge eines Authentifizierungstags für die von Ihnen verwendete Verschlüsselung. Um die gültigen Authentifizierungstaglängen abzurufen, verwenden Sie BCryptGetProperty , um die BCRYPT_AUTH_TAG_LENGTH-Eigenschaft abzufragen.

Wenn BCryptEncrypt - und BCryptDecrypt-Aufrufe nicht verkettet werden, muss dieser Member auf NULL festgelegt werden.

cbMacContext

Die Größe des Puffers in Bytes, auf den das pbMacContext-Element verweist. Wenn BCryptEncrypt - und BCryptDecrypt-Aufrufe nicht verkettet werden, muss dieses Element auf 0 festgelegt werden.

cbAAD

Die Länge zusätzlicher authentifizierter Daten (AAD) in Bytes, die von den Funktionen BCryptEncrypt und BCryptDecrypt verwendet werden sollen. Dieses Element wird nur beim Verketten von Aufrufen verwendet.

Dieses Element wird nur verwendet, wenn das BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG-Flag im dwFlags-Element festgelegt ist.

Beim ersten Aufruf von BCryptEncrypt oder BCryptDecrypt müssen Sie dieses Feld auf Null festlegen.

Hinweis Während der Verkettungssequenz wird dieser Member intern verwaltet und darf nicht geändert werden, da sonst der Wert des berechneten MAC beschädigt wird.

cbData

Die Länge der verschlüsselten oder entschlüsselten Nutzlastdaten in Bytes. Dieses Element wird nur beim Verketten von Aufrufen verwendet.

Dieses Element wird nur verwendet, wenn das BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG-Flag im dwFlags-Element festgelegt ist.

Beim ersten Aufruf von BCryptEncrypt oder BCryptDecrypt müssen Sie dieses Feld entweder direkt oder durch Aufrufen des BCRYPT_INIT_AUTH_INFO Makros auf Null festlegen.

Hinweis Während der Verkettungssequenz wird dieser Member intern verwaltet und darf nicht geändert werden, da sonst der Wert des berechneten MAC beschädigt wird.

dwFlags

Dieses Flag wird beim Verketten von BCryptEncrypt - oder BCryptDecrypt-Funktionsaufrufen verwendet. Wenn Aufrufe nicht verkettet werden, muss dieses Element auf 0 festgelegt werden.

Wert	Bedeutung
0x00000000	Berechnen Sie für BCryptEncrypt das Authentifizierungstag, und platzieren Sie es im Puffer, auf den das pbTag-Element verweist. Berechnen Sie für BCryptDecrypt das Authentifizierungstag, und vergleichen Sie es mit dem Tag, das an den Puffer übergeben wird, auf den das pbTag-Element verweist. Beim Verketten mehrerer Aufrufe an BCryptEncrypt oder BCryptDecrypt signalisiert dieser Wert das Ende der Kette.
BCRYPT_AUTH_MODE_CHAIN_CALLS_FLAG 0x00000001	Gibt an, dass BCryptEncrypt - und BCryptDecrypt-Funktionsaufrufe verkettet werden und dass der MAC-Wert nicht berechnet wird. Löschen Sie beim letzten Aufruf in der Kette diesen Wert, um den MAC-Wert für die gesamte Kette zu berechnen.
BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG 0x00000002	Gibt an, dass diese BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO-Struktur in einer Sequenz verketteter BCryptEncrypt - oder BCryptDecrypt-Funktionsaufrufe verwendet wird. Dieses Flag wird intern festgelegt und verwaltet. Hinweis Während der Verkettungssequenz wird dieser Flagwert intern beibehalten und darf nicht geändert werden, da sonst der Wert des berechneten MAC beschädigt wird.

Hinweise

Die Größe dieser Struktur unterscheidet sich zwischen 64-Bit- und 32-Bit-Betriebssystemen. Bei 64-Bit-Betriebssystemen unterscheidet sich die Größe zwischen 64-Bit- und 32-Bit-Prozessen. Instanzen dieser Struktur dürfen nicht über Threads hinweg freigegeben oder zwischen Prozessen übergeben werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista mit SP1 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Kopfzeile	bcrypt.h

Share via