Fonction CryptUnprotectData (dpapi.h)

La fonction CryptUnprotectData déchiffre et effectue un contrôle d’intégrité des données dans une structure DATA_BLOB . En règle générale, le seul utilisateur qui peut déchiffrer les données est un utilisateur disposant des 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 Notes 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 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 par 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 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é pour une utilisation ultérieure et doit être défini sur NULL.

[in, optional] pPromptStruct

Pointeur vers une structure CRYPTPROTECT_PROMPTSTRUCT qui fournit des informations sur l’emplacement et le moment où les invites doivent être affichées et 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 égal à zéro, auquel cas aucune option n’est définie ou l’indicateur suivant.

[out] pDataOut

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

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 le blob de données.

Le hachageMAC (Message Authentication Code) ajouté aux données chiffrées est utilisé pour détecter si les données chiffrées ont été modifiées de quelque manière que ce soit. Toutefois, le code d’erreur spécifique retourné lors de la falsification peut varier en fonction de la nature de l’altération. La fonction peut retourner ERROR_INVALID_DATA, ERROR_INVALID_PARAMETER ou, dans certains cas, réussir avec une sortie endommagée. Les applications ne doivent pas s’appuyer sur un code d’erreur spécifique pour détecter la falsification des données. Pour une détection de falsification robuste, envisagez d’implémenter des vérifications d’intégrité supplémentaires au niveau de l’application.

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

Lorsque vous avez fini d’utiliser des informations sensibles, effacez-la de la mémoire en appelant la fonction SecureZeroMemory .

Examples

L’exemple suivant montre le déchiffrement des données chiffrées dans une structure DATA_BLOB . Cette fonction effectue le déchiffrement à l’aide d’une clé de session que la fonction crée à l’aide des informations d’identification d’ouverture de session de l’utilisateur. Pour obtenir un autre exemple qui utilise cette fonction, consultez l’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!");
}

Spécifications

Voir aussi

CryptProtectData

CryptUnprotectMemory

Fonctions de chiffrement et de déchiffrement des données

LocalFree

Fournisseur de chiffrement de base Microsoft