Fonction CryptUnprotectData (dpapi.h)

Article
02/26/2024

La fonction CryptUnprotectData déchiffre et effectue une case activée d’intégrité des données dans une structure de DATA_BLOB. En règle générale, le seul utilisateur qui peut déchiffrer les données est un utilisateur avec les mêmes informations d’identification d’ouverture de session que l’utilisateur qui a chiffré les données. En outre, le chiffrement et le déchiffrement doivent être effectués sur le même ordinateur. Pour plus d’informations sur les exceptions, consultez la section Remarques de CryptProtectData.

Syntaxe

DPAPI_IMP BOOL CryptUnprotectData(
  [in]            DATA_BLOB                 *pDataIn,
  [out, optional] LPWSTR                    *ppszDataDescr,
  [in, optional]  DATA_BLOB                 *pOptionalEntropy,
                  PVOID                     pvReserved,
  [in, optional]  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  [in]            DWORD                     dwFlags,
  [out]           DATA_BLOB                 *pDataOut
);

Paramètres

[in] pDataIn

Pointeur vers une structure de DATA_BLOB qui contient les données chiffrées. Le membre cbData de la structure DATA_BLOB contient la longueur de la chaîne d’octets du membre pbData qui contient le texte à chiffrer.

[out, optional] ppszDataDescr

Pointeur vers une description lisible sous forme de chaîne des données chiffrées incluses avec les données chiffrées. Ce paramètre peut être défini sur NULL. Lorsque vous avez terminé d’utiliser ppszDataDescr, libérez-le en appelant la fonction LocalFree .

[in, optional] pOptionalEntropy

Pointeur vers une structure de DATA_BLOB qui contient un mot de passe ou une autre entropie supplémentaire utilisée lorsque les données ont été chiffrées. Ce paramètre peut être défini sur NULL ; toutefois, si une entropie facultative DATA_BLOB structure a été utilisée dans la phase de chiffrement, cette même structure DATA_BLOB doit être utilisée pour la phase de déchiffrement. Pour plus d’informations sur la protection des mots de passe, consultez Gestion des mots de passe.

pvReserved

Ce paramètre est réservé à une utilisation ultérieure et doit être défini sur NULL.

[in, optional] pPromptStruct

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

[in] dwFlags

Valeur DWORD qui spécifie les options de cette fonction. Ce paramètre peut être zéro, auquel cas aucune option n’est définie, ou l’indicateur suivant.

Valeur	Signification
CRYPTPROTECT_UI_FORBIDDEN	Cet indicateur est utilisé pour les situations distantes où l’interface utilisateur n’est pas une option. Lorsque cet indicateur est défini et que l’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.
CRYPTPROTECT_VERIFY_PROTECTION	Cet indicateur vérifie la protection d’un objet BLOB protégé. Si le niveau de protection par défaut configuré de l’hôte est supérieur au niveau de protection actuel pour l’objet BLOB, la fonction retourne CRYPT_I_NEW_PROTECTION_REQUIRED pour conseiller à l’appelant de protéger à nouveau le texte en clair contenu dans l’objet BLOB.

[out] pDataOut

Pointeur vers une structure DATA_BLOB où la fonction stocke les données déchiffrées. Une fois que 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.

Remarques

La fonction CryptProtectData crée une clé de session lorsque les données sont chiffrées. Cette clé est dérivée à nouveau et utilisée pour déchiffrer l’objet BLOB de données.

Le hachage MAC (Message Authentication Code) ajouté aux données chiffrées peut être utilisé pour déterminer si les données chiffrées ont été modifiées de quelque manière que ce soit. Toute falsification entraîne le retour du code ERROR_INVALID_DATA.

Une fois que vous avez terminé d’utiliser la structure DATA_BLOB , libérez son membre pbData en appelant la fonction LocalFree . Tout ppszDataDescr qui n’est pas NULL doit également être libéré à l’aide de LocalFree.

Une fois que vous avez terminé d’utiliser des informations sensibles, effacez-les de la mémoire en appelant la fonction SecureZeroMemory .

Exemples

L’exemple suivant montre le déchiffrement de données chiffrées dans une structure DATA_BLOB . Cette fonction effectue le dé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 un autre exemple qui utilise cette fonction, consultez Exemple de programme C : utilisation de CryptProtectData.

// Decrypt data from DATA_BLOB DataOut to DATA_BLOB DataVerify.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataOut;
DATA_BLOB DataVerify;
LPWSTR pDescrOut =  NULL;
//--------------------------------------------------------------------
// The buffer DataOut would be created using the CryptProtectData
// function. If may have been read in from a file.

//--------------------------------------------------------------------
//   Begin unprotect phase.

if (CryptUnprotectData(
        &DataOut,
        &pDescrOut,
        NULL,                 // Optional entropy
        NULL,                 // Reserved
        NULL,                 // Here, the optional 
                              // prompt structure is not
                              // used.
        0,
        &DataVerify))
{
     printf("The decrypted data is: %s\n", DataVerify.pbData);
     printf("The description of the data was: %s\n",pDescrOut);
     LocalFree(DataVerify.pbData);
     LocalFree(pDescrOut);
}
else
{
    printf("Decryption error!");
}

Configuration requise

Condition requise	Valeur
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