Функция CryptUnprotectData (dpapi.h)

Статья
08/23/2023

Функция CryptUnprotectData расшифровывает и выполняет проверка целостности данных в DATA_BLOB структуре. Как правило, единственный пользователь, который может расшифровать данные, — это пользователь с теми же учетными данными для входа, что и пользователь, который зашифровал данные. Кроме того, шифрование и расшифровка должны выполняться на одном компьютере. Сведения об исключениях см. в разделе Примечания статьи CryptProtectData.

Синтаксис

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
);

Параметры

[in] pDataIn

Указатель на структуру DATA_BLOB , в которой хранятся зашифрованные данные. Член cbDataструктуры DATA_BLOB содержит длину строки байтов элемента pbData, содержащей текст, который требуется зашифровать.

[out, optional] ppszDataDescr

Указатель на доступное для чтения в строке описание зашифрованных данных, включенных в зашифрованные данные. Для этого параметра можно задать значение NULL. Завершив использование ppszDataDescr, освободите его, вызвав функцию LocalFree .

[in, optional] pOptionalEntropy

Указатель на структуру DATA_BLOB , содержащую пароль или другую дополнительную энтропию, используемую при шифровании данных. Для этого параметра можно задать значение NULL; Однако если на этапе шифрования использовалась дополнительная структура энтропии DATA_BLOB , то для этапа расшифровки необходимо использовать ту же структуру DATA_BLOB . Сведения о защите паролей см. в разделе Обработка паролей.

pvReserved

Этот параметр зарезервирован для использования в будущем и должен иметь значение NULL.

[in, optional] pPromptStruct

Указатель на структуру CRYPTPROTECT_PROMPTSTRUCT , которая предоставляет сведения о том, где и когда должны отображаться запросы, а также о том, каким должно быть содержимое этих запросов. Для этого параметра можно задать значение NULL.

[in] dwFlags

Значение DWORD , указывающее параметры для этой функции. Этот параметр может быть равен нулю, в этом случае не задан параметр или следующий флаг.

Значение	Значение
CRYPTPROTECT_UI_FORBIDDEN	Этот флаг используется в удаленных ситуациях, когда пользовательский интерфейс не является вариантом. Если этот флаг установлен и пользовательский интерфейс указан для операции защиты или отмены защиты, операция завершается сбоем и GetLastError возвращает код ERROR_PASSWORD_RESTRICTION.
CRYPTPROTECT_VERIFY_PROTECTION	Этот флаг проверяет защиту защищенного большого двоичного объекта. Если уровень защиты по умолчанию, настроенный для узла, выше текущего уровня защиты большого двоичного объекта, функция возвращает CRYPT_I_NEW_PROTECTION_REQUIRED , чтобы посоветовать вызывающей организации снова защитить открытый текст, содержащийся в BLOB.

Значение

CRYPTPROTECT_UI_FORBIDDEN

Этот флаг используется в удаленных ситуациях, когда пользовательский интерфейс не является вариантом. Если этот флаг установлен и пользовательский интерфейс указан для операции защиты или отмены защиты, операция завершается сбоем и GetLastError возвращает код ERROR_PASSWORD_RESTRICTION.

CRYPTPROTECT_VERIFY_PROTECTION

Этот флаг проверяет защиту защищенного большого двоичного объекта. Если уровень защиты по умолчанию, настроенный для узла, выше текущего уровня защиты большого двоичного объекта, функция возвращает CRYPT_I_NEW_PROTECTION_REQUIRED , чтобы посоветовать вызывающей организации снова защитить открытый текст, содержащийся в BLOB.

[out] pDataOut

Указатель на структуру DATA_BLOB , в которой функция хранит расшифрованные данные. Завершив использование структуры DATA_BLOB , освободите ее член pbData , вызвав функцию LocalFree .

Возвращаемое значение

Если функция выполнена успешно, функция возвращает значение TRUE.

Если функция завершается сбоем, она возвращает значение FALSE.

Хэш кода проверки подлинности сообщений (MAC), добавленный к зашифрованным данным, можно использовать для определения того, были ли зашифрованные данные каким-либо образом изменены. Любое незаконное изменение приводит к возвращению кода ERROR_INVALID_DATA.

Завершив использование структуры DATA_BLOB , освободите ее член pbData , вызвав функцию LocalFree . Все ppszDataDescr , не имеющие значения NULL , также должны быть освобождены с помощью LocalFree.

Завершив использование конфиденциальной информации, очистите ее из памяти, вызвав функцию SecureZeroMemory .

Примеры

В следующем примере показано расшифровка зашифрованных данных в DATA_BLOB структуре. Эта функция выполняет расшифровку с помощью ключа сеанса, создаваемого функцией с использованием учетных данных для входа пользователя. Еще один пример, в котором используется эта функция, см. в разделе Пример программы C: использование 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!");
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	dpapi.h
Библиотека	Crypt32.lib
DLL	Crypt32.dll