BCryptEncrypt, fonction (bcrypt.h)

Article
02/23/2024

La fonction BCryptEncrypt chiffre un bloc de données.

Syntaxe

NTSTATUS BCryptEncrypt(
  [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
);

Paramètres

[in, out] hKey

Handle de la clé à utiliser pour chiffrer les données. Ce handle est obtenu à partir de l’une des fonctions de création de clé, telles que BCryptGenerateSymmetricKey, BCryptGenerateKeyPair ou BCryptImportKey.

[in] pbInput

Adresse d’une mémoire tampon qui contient le texte en clair à chiffrer. Le paramètre cbInput contient la taille du texte en clair à chiffrer. Pour plus d'informations, consultez la section Notes.

[in] cbInput

Nombre d’octets dans la mémoire tampon pbInput à chiffrer.

[in, optional] pPaddingInfo

Pointeur vers une structure qui contient des informations de remplissage. Ce paramètre est utilisé uniquement avec les clés asymétriques et les modes de chiffrement authentifiés. Si un mode de chiffrement authentifié est utilisé, ce paramètre doit pointer vers une structure BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO . Si des clés asymétriques sont utilisées, le type de structure vers lequel ce paramètre pointe est déterminé par la valeur du paramètre dwFlags . Sinon, le paramètre doit être défini sur NULL.

[in, out, optional] pbIV

Adresse d’une mémoire tampon qui contient le vecteur d’initialisation (IV) à utiliser pendant le chiffrement. Le paramètre cbIV contient la taille de cette mémoire tampon. Cette fonction modifie le contenu de cette mémoire tampon. Si vous devez réutiliser l’iv ultérieurement, veillez à effectuer une copie de cette mémoire tampon avant d’appeler cette fonction.

Ce paramètre est facultatif et peut être NULL si aucun iv n’est utilisé.

La taille requise de l’ivr peut être obtenue en appelant la fonction BCryptGetProperty pour obtenir la propriété BCRYPT_BLOCK_LENGTH . Cela fournit la taille d’un bloc pour l’algorithme, qui est également la taille de l’ivr.

[in] cbIV

Taille, en octets, de la mémoire tampon pbIV .

[out, optional] pbOutput

Adresse de la mémoire tampon qui reçoit le texte chiffré généré par cette fonction. Le paramètre cbOutput contient la taille de cette mémoire tampon. Pour plus d'informations, consultez la section Notes.

Si ce paramètre a la valeur NULL, la fonction BCryptEncrypt calcule la taille nécessaire pour le texte chiffré des données passées dans le paramètre pbInput . Dans ce cas, l’emplacement vers lequel pointe le paramètre pcbResult contient cette taille, et la fonction retourne STATUS_SUCCESS. Le paramètre pPaddingInfo n’est pas modifié.

Si les valeurs des paramètres pbOutput et pbInput sont NULL, une erreur est retournée, sauf si un algorithme de chiffrement authentifié est utilisé. Dans ce dernier cas, l’appel est traité comme un appel de chiffrement authentifié avec des données de longueur nulle, et la balise d’authentification est retournée dans le paramètre pPaddingInfo .

[in] cbOutput

Taille, en octets, de la mémoire tampon pbOutput . Ce paramètre est ignoré si le paramètre pbOutput a la valeur NULL.

[out] pcbResult

Pointeur vers une variable ULONG qui reçoit le nombre d’octets copiés dans la mémoire tampon pbOutput . Si pbOutput a la valeur NULL, cette opération reçoit la taille, en octets, requise pour le texte chiffré.

[in] dwFlags

Ensemble d’indicateurs qui modifient le comportement de cette fonction. Le jeu d’indicateurs autorisé dépend du type de clé spécifié par le paramètre hKey .

Si la clé est une clé symétrique, il peut s’agir de zéro ou de la valeur suivante.

Valeur	Signification
BCRYPT_BLOCK_PADDING	Permet à l’algorithme de chiffrement de faire passer les données à la taille de bloc suivante. Si cet indicateur n’est pas spécifié, la taille du texte en clair spécifié dans le paramètre cbInput doit être un multiple de la taille de bloc de l’algorithme. La taille de bloc peut être obtenue en appelant la fonction BCryptGetProperty pour obtenir la propriété BCRYPT_BLOCK_LENGTH de la clé. Cela fournit la taille d’un bloc pour l’algorithme. Cet indicateur ne doit pas être utilisé avec les modes de chiffrement authentifiés (AES-CCM et AES-GCM).

Valeur

Signification

BCRYPT_BLOCK_PADDING

Permet à l’algorithme de chiffrement de faire passer les données à la taille de bloc suivante. Si cet indicateur n’est pas spécifié, la taille du texte en clair spécifié dans le paramètre cbInput doit être un multiple de la taille de bloc de l’algorithme.

La taille de bloc peut être obtenue en appelant la fonction BCryptGetProperty pour obtenir la propriété BCRYPT_BLOCK_LENGTH de la clé. Cela fournit la taille d’un bloc pour l’algorithme.

Cet indicateur ne doit pas être utilisé avec les modes de chiffrement authentifiés (AES-CCM et AES-GCM).

Si la clé est une clé asymétrique, il peut s’agir de l’une des valeurs suivantes.

Valeur	Signification
BCRYPT_PAD_NONE	N’utilisez aucun remplissage. Le paramètre pPaddingInfo n’est pas utilisé. La taille du texte en clair spécifié dans le paramètre cbInput doit être un multiple de la taille de bloc de l’algorithme.
BCRYPT_PAD_OAEP	Utilisez le schéma OAEP (Optimal Asymmetric Encryption Padding). Le paramètre pPaddingInfo est un pointeur vers une structure BCRYPT_OAEP_PADDING_INFO .
BCRYPT_PAD_PKCS1	Les données seront complétées avec un nombre aléatoire pour compléter la taille du bloc. Le paramètre pPaddingInfo n’est pas utilisé.

Valeur retournée

Retourne un code status qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code de retour	Description
STATUS_SUCCESS	La fonction a réussi.
STATUS_BUFFER_TOO_SMALL	La taille spécifiée par le paramètre cbOutput n’est pas assez grande pour contenir le texte chiffré.
STATUS_INVALID_BUFFER_SIZE	Le paramètre cbInput n’est pas un multiple de la taille de bloc de l’algorithme et l’indicateur BCRYPT_BLOCK_PADDING ou BCRYPT_PAD_NONE n’a pas été spécifié dans le paramètre dwFlags .
STATUS_INVALID_HANDLE	Le handle de clé dans le paramètre hKey n’est pas valide.
STATUS_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
STATUS_NOT_SUPPORTED	L’algorithme ne prend pas en charge le chiffrement.

Remarques

Les paramètres pbInput et pbOutput peuvent être égaux. Dans ce cas, cette fonction effectue le chiffrement en place. Il est possible que la taille des données chiffrées soit supérieure à la taille des données non chiffrées, de sorte que la mémoire tampon doit être suffisamment grande pour contenir les données chiffrées. Si pbInput et pbOutput ne sont pas égaux, les deux tampons peuvent ne pas se chevaucher.

Selon les modes processeur pris en charge par un fournisseur, BCryptEncrypt peut être appelé à partir du mode utilisateur ou du mode noyau. Les appelants en mode noyau peuvent s’exécuter à PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Si le niveau IRQL actuel est DISPATCH_LEVEL, le handle fourni dans le paramètre hKey doit être dérivé d’un handle d’algorithme retourné par un fournisseur qui a été ouvert avec l’indicateur BCRYPT_PROV_DISPATCH , et tous les pointeurs passés à la fonction BCryptEncrypt doivent faire référence à la mémoire non paginée (ou verrouillée).

Pour appeler cette fonction en mode noyau, utilisez Cng.lib, qui fait partie du Kit de développement de pilotes (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	bcrypt.h
Bibliothèque	Bcrypt.lib
DLL	Bcrypt.dll

Voir aussi

BCryptDecrypt

Partager via