structure BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO (bcrypt.h)

Article
08/22/2023

La structure BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO est utilisée avec les fonctions BCryptEncrypt et BCryptDecrypt pour contenir des informations supplémentaires relatives aux modes de chiffrement authentifiés.

Syntaxe

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;

Membres

cbSize

Taille, en octets, de cette structure. Ne définissez pas ce champ directement. Utilisez plutôt la macro BCRYPT_INIT_AUTH_MODE_INFO .

dwInfoVersion

Numéro de version de la structure. La seule valeur prise en charge est BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION. Ne définissez pas ce champ directement. Utilisez plutôt la macro BCRYPT_INIT_AUTH_MODE_INFO .

pbNonce

Pointeur vers une mémoire tampon qui contient un nonce. Les fournisseurs d’algorithmes Microsoft pour advanced encryption Standard (AES) nécessitent un nonce pour le compteur avec les modes de chaînage CBC-MAC (CCM) et Galois/Counter Mode (GCM), et retournent une erreur si aucun n’est présent. Si un nonce n’est pas utilisé, ce membre doit être défini sur NULL.

cbNonce

Taille, en octets, de la mémoire tampon pointée vers le membre pbNonce . Si un nonce n’est pas utilisé, ce membre doit être défini sur zéro.

pbAuthData

Pointeur vers une mémoire tampon qui contient les données authentifiées. Il s’agit des données qui seront incluses dans le code d’authentification de message (MAC), mais qui ne seront pas chiffrées. S’il n’existe aucune donnée authentifiée, ce membre doit être défini sur NULL.

cbAuthData

Taille, en octets, de la mémoire tampon pointée par le membre pbAuthData . S’il n’existe aucune donnée authentifiée, ce membre doit être défini sur zéro.

pbTag

Pointeur vers une mémoire tampon.

L’utilisation de ce membre dépend de la fonction à laquelle la structure est passée.

Fonction	Description
BCryptEncrypt	La mémoire tampon recevra la balise d’authentification.
BCryptDecrypt	La mémoire tampon contient la balise d’authentification à vérifier.

S’il n’y a pas de balise, ce membre doit avoir la valeur NULL.

cbTag

Taille, en octets, de la mémoire tampon pbTag . La mémoire tampon doit être suffisamment longue pour inclure l’ensemble de la balise d’authentification. Certains modes d’authentification, tels que CCM et GCM, prennent en charge la vérification par rapport à une étiquette avec plusieurs longueurs. Pour obtenir les longueurs de balise d’authentification valides, utilisez BCryptGetProperty pour interroger la propriété BCRYPT_AUTH_TAG_LENGTH . S’il n’y a pas de balise, ce membre doit être défini sur zéro.

pbMacContext

Pointeur vers une mémoire tampon qui stocke le MAC partiellement calculé entre les appels à BCryptEncrypt et À BCryptDecrypt lors du chaînage du chiffrement ou du déchiffrement.

Si l’entrée pour le chiffrement ou le déchiffrement est dispersée dans plusieurs mémoires tampons, vous devez chaîner les appels aux fonctions BCryptEncrypt et BCryptDecrypt . Le chaînage est indiqué en définissant l’indicateur BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG dans le membre dwFlags .

Cette mémoire tampon doit être fournie par l’appelant et doit être au moins aussi grande que la longueur maximale d’une balise d’authentification pour le chiffrement que vous utilisez. Pour obtenir les longueurs de balise d’authentification valides, utilisez BCryptGetProperty pour interroger la propriété BCRYPT_AUTH_TAG_LENGTH .

Si les appels BCryptEncrypt et BCryptDecrypt ne sont pas chaînés, ce membre doit avoir la valeur NULL.

cbMacContext

Taille, en octets, de la mémoire tampon pointée vers le membre pbMacContext . Si les appels BCryptEncrypt et BCryptDecrypt ne sont pas chaînés, ce membre doit être défini sur zéro.

cbAAD

Longueur, en octets, des données authentifiées supplémentaires (AAD) à utiliser par les fonctions BCryptEncrypt et BCryptDecrypt . Ce membre est utilisé uniquement lors du chaînage des appels.

Ce membre est utilisé uniquement lorsque l’indicateur BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG dans le membre dwFlags est défini.

Lors du premier appel à BCryptEncrypt ou BCryptDecrypt , vous devez définir ce champ sur zéro.

Note Pendant la séquence de chaînage, ce membre est conservé en interne et ne doit pas être modifié, sinon la valeur du MAC calculé est endommagée.

cbData

Longueur, en octets, des données de charge utile chiffrées ou déchiffrées. Ce membre est utilisé uniquement lors du chaînage des appels.

Ce membre est utilisé uniquement lorsque l’indicateur BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG dans le membre dwFlags est défini.

Lors du premier appel à BCryptEncrypt ou BCryptDecrypt, vous devez définir ce champ sur zéro, , soit directement, soit en appelant la macro BCRYPT_INIT_AUTH_INFO

Note Pendant la séquence de chaînage, ce membre est conservé en interne et ne doit pas être modifié, sinon la valeur du MAC calculé est endommagée.

dwFlags

Cet indicateur est utilisé lors du chaînage des appels de fonction BCryptEncrypt ou BCryptDecrypt . Si les appels ne sont pas chaînés, ce membre doit être défini sur zéro.

Valeur	Signification
0x00000000	Pour BCryptEncrypt, calculez la balise d’authentification et placez-la dans la mémoire tampon pointée par le membre pbTag . Pour BCryptDecrypt, calculez la balise d’authentification et comparez-la à la balise transmise à la mémoire tampon pointée par le membre pbTag . Lors du chaînage de plusieurs appels à BCryptEncrypt ou BCryptDecrypt, cette valeur signale la fin de la chaîne.
BCRYPT_AUTH_MODE_CHAIN_CALLS_FLAG 0x00000001	Indique que les appels de fonction BCryptEncrypt et BCryptDecrypt sont en cours de chaînage et que la valeur MAC ne sera pas calculée. Lors du dernier appel de la chaîne, effacez cette valeur pour calculer la valeur MAC pour l’ensemble de la chaîne.
BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG 0x00000002	Indique que cette structure BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO est utilisée dans une séquence d’appels de fonction BCryptEncrypt ou BCryptDecrypt chaînés. Cet indicateur est défini et géré en interne. Note Pendant la séquence de chaînage, cette valeur d’indicateur est conservée en interne et ne doit pas être modifiée, sinon la valeur du MAC calculé est endommagée.

Remarques

La taille de cette structure diffère entre les systèmes d’exploitation 64 bits et 32 bits. Sur les systèmes d’exploitation 64 bits, la taille est différente entre les processus 64 bits et 32 bits. Les instances de cette structure ne doivent pas être partagées entre les threads ni passées entre les processus.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista avec SP1 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
En-tête	bcrypt.h

Share via