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 構造体へのポインター。 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
Library	Crypt32.lib
[DLL]	Crypt32.dll