CryptUnprotectData 함수(dpapi.h)

아티클
02/29/2024

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 구조체에 대한 포인터입니다. DATA_BLOB 구조체의 cbData 멤버는 암호화할 텍스트가 포함된 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 값입니다. 이 매개 변수는 0일 수 있으며 이 경우 옵션이 설정되지 않거나 다음 플래그가 될 수 있습니다.

값	의미
CRYPTPROTECT_UI_FORBIDDEN	이 플래그는 UI(사용자 인터페이스)가 옵션이 아닌 원격 상황에 사용됩니다. 이 플래그가 설정되고 보호 또는 보호 해제 작업에 대해 UI가 지정되면 작업이 실패하고 GetLastError 가 ERROR_PASSWORD_RESTRICTION 코드를 반환합니다.
CRYPTPROTECT_VERIFY_PROTECTION	이 플래그는 보호된 BLOB의 보호를 확인합니다. 호스트에 구성된 기본 보호 수준이 BLOB의 현재 보호 수준보다 높은 경우 함수는 CRYPT_I_NEW_PROTECTION_REQUIRED 반환하여 호출자에게 BLOB에 포함된 일반 텍스트를 다시 보호하도록 권고합니다.

[out] pDataOut

함수가 암호 해독된 데이터를 저장하는 DATA_BLOB 구조체에 대한 포인터입니다. DATA_BLOB 구조체 사용을 마치면 LocalFree 함수를 호출하여 pbData 멤버를 해제합니다.

반환 값

함수가 성공하면 함수는 TRUE를 반환합니다.

함수가 실패하면 FALSE를 반환합니다.

설명

CryptProtectData 함수는 데이터가 암호화될 때 세션 키를 만듭니다. 해당 키는 다시 파생되고 데이터 BLOB의 암호를 해독하는 데 사용됩니다.

암호화된 데이터에 추가된 MAC( 메시지 인증 코드 ) 해시 를 사용하여 암호화된 데이터가 어떤 방식으로 변경되었는지 여부를 확인할 수 있습니다. 변조하면 ERROR_INVALID_DATA 코드가 반환됩니다.

DATA_BLOB 구조체 사용을 마치면 LocalFree 함수를 호출하여 pbData 멤버를 해제합니다. NULL이 아닌 ppszDataDescr도 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
헤더	dpapi.h
라이브러리	Crypt32.lib
DLL	Crypt32.dll