Fonction CryptEncrypt (wincrypt.h)
Des modifications importantes pour prendre en charge l’interopérabilité des e-mails S/MIME ( Secure/Multipurpose Internet Mail Extensions ) ont été apportées à CryptoAPI qui affectent la gestion des messages enveloppés. Pour plus d’informations, consultez la section Notes de CryptMsgOpenToEncode.
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 de la fonction CryptGenKey ou CryptImportKey .
La clé spécifie l’algorithme de chiffrement utilisé.
[in] hHash
Handle pour un objet de hachage. Si les données doivent être hachées et chiffrées simultanément, un handle à un objet de hachage peut être passé 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 pour 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 ne doit être effectué, ce paramètre doit avoir la valeur NULL.
[in] Final
Valeur booléenne qui spécifie s’il s’agit de la dernière section d’une série en cours de chiffrement. Final est défini sur TRUE pour le dernier ou le seul bloc et sur FALSE s’il y a d’autres blocs à chiffrer. Pour plus d'informations, consultez la section Notes.
[in] dwFlags
La valeur dwFlags suivante est définie, mais réservée pour une utilisation ultérieure.
| Valeur | Signification |
|---|---|
|
Utilisez optimal asymmetric encryption padding (OAEP) (PKCS #1 version 2). Cet indicateur est uniquement pris en charge 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 dans 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 la place 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, ce 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 assez 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 a la valeur 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 de mémoire tampon correcte.
Lorsqu’un chiffrement par bloc est utilisé, cette longueur de données doit être un multiple de la taille du bloc, sauf s’il s’agit de la section finale des données à chiffrer et que le paramètre Final a la valeur TRUE.
[in] dwBufLen
Spécifie la taille totale, en octets, de la mémoire tampon pbData d’entrée.
Notez que, selon l’algorithme utilisé, le texte chiffré peut être plus grand que le 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 chiffrement de flux est utilisé, le texte chiffré a la même taille que le texte en clair. Si un chiffrement par bloc est utilisé, le texte chiffré est jusqu’à une longueur de bloc supérieure au texte en clair.
Valeur retournée
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éfacés par NTE sont générés par le fournisseur de solutions Cloud particulier utilisé. Certains codes d’erreur possibles suivent.
| Valeur | Description |
|---|---|
|
L’un des paramètres spécifie un handle qui n’est pas valide. |
|
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. |
|
La clé de sessionhKey spécifie un algorithme que ce fournisseur de solutions Cloud ne prend pas en charge. |
|
Les données à chiffrer ne sont pas valides. Par exemple, lorsqu’un chiffrement par bloc est utilisé et que l’indicateur Final a la valeur FALSE, la valeur spécifiée par pdwDataLen doit être un multiple de la taille de bloc. |
|
Le paramètre dwFlags est différent de zéro. |
|
Le paramètre hHash contient un handle qui n’est pas valide. |
|
Une tentative a été effectuée pour ajouter des données à un objet de hachage qui est déjà marqué « terminé ». |
|
Le paramètre hKey ne contient pas de handle valide pour une clé. |
|
La taille de la mémoire tampon de sortie est trop petite pour contenir le texte chiffré généré. |
|
Le contexte CSP qui a été spécifié lors de la création de la clé est introuvable. |
|
L’application a tenté de chiffrer les mêmes données deux fois. |
|
La fonction a échoué d’une manière inattendue. |
|
Le fournisseur de solutions Cloud a manqué de mémoire pendant l’opération. |
Remarques
Si une grande quantité de données doit être chiffrée, vous pouvez le faire en 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 a la valeur TRUE :
- Si la clé est une clé de chiffrement de bloc, les données sont complétées en 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 le registre de commentaires du chiffrement à la valeur KP_IV de la clé.
- Si le chiffrement est un chiffrement de flux, le CryptEncrypt suivant réinitialise le chiffrement à son état initial.
Il n’existe aucun moyen de définir le registre de commentaires du chiffrement sur la valeur KP_IV de la clé sans affecter au paramètre Final la valeur TRUE. Si cela est nécessaire, comme dans le cas où vous ne souhaitez pas ajouter de bloc de remplissage supplémentaire ou modifier la taille de chaque bloc, vous pouvez simuler cela en créant un doublon de la clé d’origine à l’aide de la fonction CryptDuplicateKey et en passant la clé en double à la fonction CryptEncrypt . Cela entraîne le KP_IV de la clé d’origine à placer dans la clé en double. 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 pseudo-code 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 des clés publiquesRSA 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 de texte clair qui peuvent être chiffrées avec un appel à CryptEncrypt avec une clé RSA est la longueur du module 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | wincrypt.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.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