Fonction CryptEncrypt (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 CryptEncrypt chiffre les données. L’algorithme utilisé pour chiffrer les données est désigné par la clé détenue par le module CSP et référencé par le paramètre hKey.

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.

important La fonction CryptEncrypt n’est pas garantie d’être thread-safe et peut retourner des résultats incorrects s’ils sont appelés simultanément par plusieurs appelants.

Syntaxe

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

Paramètres

[in] hKey

Handle de la clé de chiffrement. Une application obtient ce handle à l’aide du CryptGenKey ou de la fonction CryptImportKey.

La clé spécifie l’algorithme de chiffrement utilisé.

[in] hHash

Handle d’un objet de hachage . Si les données doivent être hachées et chiffrées simultanément, un handle vers un objet de hachage peut être transmis dans le paramètre hHash. La valeur de hachage est mise à jour avec le texte en clair transmis. Cette option est utile lors de la génération de texte signé et chiffré.

Avant d’appeler CryptEncrypt, l’application doit obtenir un handle à l’objet de hachage en appelant la fonction CryptCreateHash. Une fois le chiffrement terminé, la valeur de hachage peut être obtenue à l’aide de la fonction CryptGetHashParam, ou le hachage peut être signé à l’aide de la fonction CryptSignHash.

Si aucun hachage n’est à effectuer, ce paramètre doit être null.

[in] Final

Valeur booléenne qui spécifie s’il s’agit de la dernière section d’une série chiffrée. dernière est définie sur TRUE pour le dernier ou seul bloc et FALSE s’il y a plus de blocs à chiffrer. Pour plus d’informations, consultez Remarques.

[in] dwFlags

La valeur dwFlags suivante est définie, mais réservée pour une utilisation ultérieure.

Valeur	Signification
CRYPT_OAEP	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.

[in, out] pbData

Pointeur vers une mémoire tampon qui contient le texte en clair à chiffrer. Le texte en clair de cette mémoire tampon est remplacé par le texte chiffré créé par cette fonction.

Le paramètre pdwDataLen pointe vers une variable qui contient la longueur, en octets, du texte en clair. Le paramètre dwBufLen contient la taille totale, en octets, de cette mémoire tampon.

Si ce paramètre contient NULL, cette fonction calcule la taille requise pour le texte chiffré et place celle-ci dans la valeur pointée par le paramètre pdwDataLen.

[in, out] pdwDataLen

Pointeur vers une valeur DWORD qui, lors de l’entrée, contient la longueur, en octets, du texte en clair dans la mémoire tampon pbData. À la sortie, cette DWORD contient la longueur, en octets, du texte chiffré écrit dans la mémoire tampon pbData.

Si la mémoire tampon allouée pour pbData n’est pas suffisamment grande pour contenir les données chiffrées, GetLastError retourne ERROR_MORE_DATA et stocke la taille de mémoire tampon requise, en octets, dans la valeur DWORD pointée par pdwDataLen.

Si pbData est NULL, aucune erreur n’est retournée et la fonction stocke la taille des données chiffrées, en octets, dans la valeur DWORD pointée par pdwDataLen. Cela permet à une application de déterminer la taille correcte de la mémoire tampon.

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

[in] dwBufLen

Spécifie la taille totale, en octets, de la mémoire tampon d’entrée pbData.

Notez que, selon l’algorithme utilisé, le texte chiffré peut être supérieur au texte en clair d’origine. Dans ce cas, la mémoire tampon pbData doit être suffisamment grande pour contenir le texte chiffré et tout remplissage.

En règle générale, si un de chiffrement de flux est utilisé, le texte chiffré est de la même taille que le texte en clair. Si un de chiffrement de bloc est utilisé, le texte chiffré est jusqu’à une longueur de bloc supérieure au texte en clair.

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 à 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.
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_HASH_STATE	Une tentative a été effectuée pour ajouter des données à un objet de hachage qui est déjà marqué « terminé ».
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 chiffré 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 chiffrer les mêmes données deux fois.
NTE_FAIL	La fonction a échoué de manière inattendue.
NTE_NO_MEMORY	Le fournisseur de solutions Cloud n’a plus de mémoire pendant l’opération.

Remarques

Si une grande quantité de données doit être chiffrée, elle peut être effectuée dans les sections en appelant CryptEncrypt à plusieurs reprises. Le paramètre final doit être défini sur TRUE lors du dernier appel à CryptEncrypt, afin que le moteur de chiffrement puisse terminer correctement le processus de 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. Si la longueur des données est égale à la taille de bloc du chiffrement, un bloc supplémentaire de remplissage est ajouté aux données. 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 CryptEncrypt suivante réinitialise l’enregistrement des commentaires du chiffrement à la valeur KP_IV de la clé.
Si le chiffrement est unde chiffrement de flux de , le suivant CryptEncrypt 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 CryptEncrypt. 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)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(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 des données en texte clair qui peuvent être chiffrées avec un appel à CryptEncrypt avec une clé RSA est la longueur du modulus de clé moins onze octets. Les onze octets sont le minimum choisi pour le remplissage PKCS #1. Le texte chiffré est retourné au format little-endian.

Exemples

Pour obtenir des exemples qui utilisent cette fonction, consultez Exemple de programme C : chiffrement d’un fichier et 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