Fonction CryptProtectData (dpapi.h)
La fonction CryptProtectData effectue le chiffrement sur les données dans une structure DATA_BLOB . En règle générale, seul un utilisateur disposant des mêmes informations d’identification d’ouverture de session que l’utilisateur qui a chiffré les données peut déchiffrer les données. En outre, le chiffrement et le déchiffrement doivent généralement être effectués sur le même ordinateur. Pour plus d’informations sur les exceptions, consultez Remarques.
Syntaxe
DPAPI_IMP BOOL CryptProtectData(
[in] DATA_BLOB *pDataIn,
[in, optional] LPCWSTR szDataDescr,
[in, optional] DATA_BLOB *pOptionalEntropy,
[in] PVOID pvReserved,
[in, optional] CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
[in] DWORD dwFlags,
[out] DATA_BLOB *pDataOut
);
Paramètres
[in] pDataIn
Pointeur vers une structure DATA_BLOB qui contient le texte en clair à chiffrer.
[in, optional] szDataDescr
Chaîne avec une description lisible des données à chiffrer. Cette chaîne de description est incluse avec les données chiffrées. Ce paramètre est facultatif et peut être défini sur NULL.
[in, optional] pOptionalEntropy
Pointeur vers une structure de DATA_BLOB qui contient un mot de passe ou une autre entropie supplémentaire utilisée pour chiffrer les données. La structure DATA_BLOB utilisée dans la phase de chiffrement doit également être utilisée dans la phase de déchiffrement. Ce paramètre peut être défini sur NULL pour aucune entropie supplémentaire. Pour plus d’informations sur la protection des mots de passe, consultez Gestion des mots de passe.
[in] pvReserved
Réservé pour une utilisation ultérieure et doit être défini sur NULL.
[in, optional] pPromptStruct
Pointeur vers une structure de CRYPTPROTECT_PROMPTSTRUCT qui fournit des informations sur l’emplacement et le moment où les invites doivent être affichées, ainsi que sur le contenu de ces invites. Ce paramètre peut être défini sur NULL dans les phases de chiffrement et de déchiffrement.
[in] dwFlags
Ce paramètre peut être l’un des indicateurs suivants.
| Valeur | Signification |
|---|---|
|
Lorsque cet indicateur est défini, il associe les données chiffrées à l’ordinateur actuel plutôt qu’à un utilisateur individuel. Tout utilisateur sur l’ordinateur sur lequel CryptProtectData est appelé peut utiliser CryptUnprotectData pour déchiffrer les données. |
|
Cet indicateur est utilisé pour les situations distantes où la présentation d’une interface utilisateur n’est pas une option. Lorsque cet indicateur est défini et qu’une interface utilisateur est spécifiée pour l’opération protéger ou annuler la protection, l’opération échoue et GetLastError retourne le code ERROR_PASSWORD_RESTRICTION. |
|
Cet indicateur génère un audit sur les opérations de protection et de non-protection. Les entrées du journal d’audit sont enregistrées uniquement si szDataDescr n’a pas la valeur NULL et n’est pas vide. |
[out] pDataOut
Pointeur vers une structure DATA_BLOB qui reçoit les données chiffrées. Lorsque vous avez terminé d’utiliser la structure DATA_BLOB , libérez son membre pbData en appelant la fonction LocalFree .
Valeur retournée
Si la fonction réussit, la fonction retourne TRUE.
Si la fonction échoue, elle retourne FALSE. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Notes
En règle générale, seul un utilisateur disposant d’informations d’identification d’ouverture de session qui correspondent à celles de l’utilisateur qui a chiffré les données peut déchiffrer les données. En outre, le déchiffrement ne peut généralement être effectué que sur l’ordinateur où les données ont été chiffrées. Toutefois, un utilisateur disposant d’un profil itinérant peut déchiffrer les données d’un autre ordinateur sur le réseau.
Si l’indicateur CRYPTPROTECT_LOCAL_MACHINE est défini lorsque les données sont chiffrées, tout utilisateur sur l’ordinateur sur lequel le chiffrement a été effectué peut déchiffrer les données.
La fonction crée une clé de session pour effectuer le chiffrement. La clé de session est dérivée à nouveau lorsque les données doivent être déchiffrées.
La fonction ajoute également un code d’authentification de message (MAC) (case activée d’intégrité à clé) aux données chiffrées pour vous protéger contre la falsification des données.
Pour chiffrer la mémoire pour une utilisation temporaire dans le même processus ou entre les processus, appelez la fonction CryptProtectMemory .
Exemples
L’exemple suivant montre le chiffrement des données dans une structure DATA_BLOB . La fonction CryptProtectData effectue le chiffrement à l’aide d’une clé de session créée par la fonction à l’aide des informations d’identification d’ouverture de session de l’utilisateur. Pour obtenir un autre exemple qui utilise cette fonction, consultez Exemple de programme C : utilisation de CryptProtectData.
// Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.
//--------------------------------------------------------------------
// Declare and initialize variables.
DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;
//--------------------------------------------------------------------
// Initialize the DataIn structure.
DataIn.pbData = pbDataInput;
DataIn.cbData = cbDataInput;
//--------------------------------------------------------------------
// Begin protect phase. Note that the encryption key is created
// by the function and is not passed.
if(CryptProtectData(
&DataIn,
L"This is the description string.", // A description string
// to be included with the
// encrypted data.
NULL, // Optional entropy not used.
NULL, // Reserved.
NULL, // Pass NULL for the
// prompt structure.
0,
&DataOut))
{
printf("The encryption phase worked.\n");
LocalFree(DataOut.pbData);
}
else
{
printf("Encryption error using CryptProtectData.\n");
exit(1);
}
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | dpapi.h |
| Bibliothèque | Crypt32.lib |
| DLL | Crypt32.dll |