CryptDecrypt, fonction (wincrypt.h)

Article
07/16/2024

important cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.

La fonction CryptDecrypt déchiffre les données précédemment chiffrées à l’aide de la fonction CryptEncrypt.

Des modifications importantes pour prendre en charge l’interopérabilité des e-mails (S/MIME) sécurisées/multi-usage ont été apportées à CryptoAPI qui affectent la gestion des messages enveloppes. Pour plus d’informations, consultez la section Notes de CryptMsgOpenToEncode.

Syntaxe

BOOL CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

Paramètres

[in] hKey

Handle vers la clé à utiliser pour le déchiffrement. Une application obtient ce handle à l’aide de la fonction CryptGenKey ou CryptImportKey.

Cette clé spécifie l’algorithme de déchiffrement à utiliser.

[in] hHash

Handle d’un objet de hachage . Si les données doivent être déchiffrées et hachées simultanément, un handle vers un objet de hachage est transmis dans ce paramètre. La valeur de hachage est mise à jour avec le en texte clair déchiffré. Cette option est utile lorsque vous déchiffrez et vérifiez simultanément une signature.

Avant d’appeler CryptDecrypt, l’application doit obtenir un handle pour l’objet de hachage en appelant la fonction CryptCreateHash. Une fois le déchiffrement terminé, la valeur de hachage peut être obtenue à l’aide de la fonction CryptGetHashParam, elle peut également être signée à l’aide de la fonction CryptSignHash, ou elle peut être utilisée pour vérifier une signature numérique à l’aide de la fonction CryptVerifySignature.

Si aucun hachage n’est à faire, ce paramètre doit être égal à zéro.

[in] Final

Valeur booléenne qui spécifie s’il s’agit de la dernière section d’une série déchiffrée. Cette valeur est TRUE si c’est le dernier ou seul bloc. Si ce n’est pas le dernier bloc, cette valeur est FALSE. Pour plus d’informations, consultez Remarques.

[in] dwFlags

Les valeurs d’indicateur suivantes sont définies.

Valeur	Signification
CRYPT_OAEP 0x00000040	Utilisez le remplissage optimal du chiffrement asymétrique (OAEP) (PKCS #1 version 2). Cet indicateur est pris en charge uniquement par le Fournisseur de chiffrement Microsoft Amélioré avec chiffrement/déchiffrement RSA. Cet indicateur ne peut pas être combiné avec l’indicateur CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	Effectuez le déchiffrement sur le BLOB sans vérifier le remplissage. Cet indicateur est pris en charge uniquement par le Fournisseur de chiffrement Microsoft Amélioré avec chiffrement/déchiffrement RSA. Cet indicateur ne peut pas être combiné avec l’indicateur CRYPT_OAEP.

[in, out] pbData

Pointeur vers une mémoire tampon qui contient les données à déchiffrer. Une fois le déchiffrement effectué, le texte en clair est placé dans cette même mémoire tampon.

Le nombre d’octets chiffrés dans cette mémoire tampon est spécifié par pdwDataLen.

[in, out] pdwDataLen

Pointeur vers une valeur DWORD qui indique la longueur de la mémoire tampon pbData . Avant d’appeler cette fonction, l’application appelante définit la valeur DWORD sur le nombre d’octets à déchiffrer. Lors du retour, la valeur DWORD contient le nombre d’octets du texte en clair déchiffré.

Lorsqu’un de chiffrement de bloc est utilisé, cette longueur de données doit être un multiple de la taille du bloc, sauf s’il s’agit de la dernière section des données à déchiffrer et que le paramètre Final est TRUE.

Valeur de retour

Si la fonction réussit, la fonction retourne une valeur différente de zéro (TRUE).

Si la fonction échoue, elle retourne zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur précédés par NTE sont générés par le fournisseur de solutions Cloud en cours d’utilisation. Certains codes d’erreur possibles suivent.

Valeur	Description
ERROR_INVALID_HANDLE	L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER	L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_ALGID	La clé de session hKey spécifie un algorithme que ce fournisseur de solutions Cloud ne prend pas en charge.
NTE_BAD_DATA	Les données à déchiffrer ne sont pas valides. Par exemple, lorsqu’un chiffrement de bloc est utilisé et que l’indicateur Final est FALSE, la valeur spécifiée par pdwDataLen doit être un multiple de la taille de bloc. Cette erreur peut également être retournée lorsque le remplissage est introuvable.
NTE_BAD_FLAGS	Le paramètre dwFlags n’est pas zéro.
NTE_BAD_HASH	Le paramètre hHash contient un handle qui n’est pas valide.
NTE_BAD_KEY	Le paramètre hKey ne contient pas de handle valide à une clé.
NTE_BAD_LEN	La taille de la mémoire tampon de sortie est trop petite pour contenir le texte en clair généré.
NTE_BAD_UID	Le contexte CSP spécifié lors de la création de la clé est introuvable.
NTE_DOUBLE_ENCRYPT	L’application a tenté de déchiffrer les mêmes données deux fois.
NTE_FAIL	La fonction a échoué de manière inattendue.

Remarques

Si une grande quantité de données doit être déchiffrée, elle peut être effectuée dans les sections en appelant CryptDecrypt à plusieurs reprises. Le paramètre final doit être défini sur TRUE uniquement lors du dernier appel à CryptDecrypt, afin que le moteur de déchiffrement puisse terminer correctement le processus de déchiffrement. Les actions supplémentaires suivantes sont effectuées lorsque final est TRUE:

Si la clé est une clé de chiffrement de bloc, les données sont rembourrées à un multiple de la taille de bloc du chiffrement. Pour rechercher la taille de bloc d’un chiffrement, utilisez CryptGetKeyParam pour obtenir la valeur KP_BLOCKLEN de la clé.
Si le chiffrement fonctionne en mode chaînage , l’opération CryptDecrypt suivante réinitialise l’inscription des commentaires du chiffrement à la valeur KP_IV de la clé.
Si le chiffrement est un de chiffrement de flux de données, l’appel CryptDecrypt suivant réinitialise le chiffrement à son état de initial.

Il n’existe aucun moyen de définir l’inscription des commentaires du chiffrement à la valeur KP_IV de la clé sans définir le paramètre Final sur TRUE. Si cela est nécessaire, comme dans le cas où vous ne souhaitez pas ajouter un bloc de remplissage supplémentaire ou modifier la taille de chaque bloc, vous pouvez le simuler en créant un doublon de la clé d’origine à l’aide de la fonction CryptDuplicateKey et en passant la clé dupliquée à la fonction CryptDecrypt. Cela entraîne l’KP_IV de la clé d’origine à placer dans la clé dupliquée. Après avoir créé ou importé la clé d’origine, vous ne pouvez pas utiliser la clé d’origine pour le chiffrement, car le registre de commentaires de la clé sera modifié. Le pseudocode suivant montre comment procéder.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Le fournisseur de chiffrement Microsoft Amélioré prend en charge le chiffrement direct avec rsa clés publiques et le déchiffrement avec des clés privées RSA . Le chiffrement utilise le remplissage PKCS #1 . Lors du déchiffrement, ce remplissage est vérifié. La longueur de texte chiffré données à déchiffrer doit être de la même longueur que le module de la clé RSA utilisée pour déchiffrer les données. Si le texte chiffré a des zéros dans les octets les plus significatifs, ces octets doivent être inclus dans la mémoire tampon de données d’entrée et dans la longueur de la mémoire tampon d’entrée. Le texte chiffré doit être au format little-endian.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : déchiffrement d’un fichier.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wincrypt.h
bibliothèque	Advapi32.lib
DLL	Advapi32.dll