BCryptDecrypt, fonction (bcrypt.h)

La fonction BCryptDecrypt déchiffre un bloc de données.

Syntaxe

NTSTATUS BCryptDecrypt(
  [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 déchiffrer les données. Ce handle est obtenu à partir de l’une des fonctions de création de clés, telles que BCryptGenerateSymmetricKey, BCryptGenerateKeyPair ou BCryptImportKey.

[in] pbInput

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

[in] cbInput

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

[in, optional] pPaddingInfo

Pointeur vers une structure qui contient des informations de remplissage. Ce paramètre est utilisé uniquement avec des clés asymétriques et des 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 pointe ce paramètre 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 dé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 avoir la valeur NULL si aucun paramètre IV n’est utilisé.

La taille requise de l’IV 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’IV.

[in] cbIV

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

[out, optional] pbOutput

Adresse d’une mémoire tampon pour recevoir le texte en clair 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 BCryptDecrypt calcule la taille requise pour le texte en clair des données chiffrées transmises 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.

Si les valeurs des paramètres pbOutput et pbInput sont NULL, une erreur est retournée, sauf si un algorithme de chiffrement authentifié est en cours d’utilisation. 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, transmise dans le paramètre pPaddingInfo , est vérifiée.

[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 pour recevoir le nombre d’octets copiés dans la mémoire tampon pbOutput . Si pbOutput a la valeur NULL, il reçoit la taille, en octets, requise pour le texte en clair.

[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.

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

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.

Remarques

Les paramètres pbInput et pbOutput peuvent être égaux. Dans ce cas, cette fonction effectue le déchiffrement sur place. Si pbInput et pbOutput ne sont pas égaux, les deux mémoires tampons peuvent ne pas se chevaucher.

Selon les modes de processeur pris en charge par un fournisseur, BCryptDecrypt peut être appelé en mode utilisateur ou en 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 BCryptDecrypt 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 pilote (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.

Configuration requise

Voir aussi

BCryptEncrypt