BCryptEncrypt, fonction (bcrypt.h)
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 |
|---|---|
|
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 |
|---|---|
|
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. |
|
Utilisez le schéma OAEP (Optimal Asymmetric Encryption Padding). Le paramètre pPaddingInfo est un pointeur vers une structure BCRYPT_OAEP_PADDING_INFO . |
|
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 |
|---|---|
|
La fonction a réussi. |
|
La taille spécifiée par le paramètre cbOutput n’est pas assez grande pour contenir le texte chiffré. |
|
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 . |
|
Le handle de clé dans le paramètre hKey n’est pas valide. |
|
Un ou plusieurs paramètres ne sont pas valides. |
|
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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour