CryptProtectData 関数 (dpapi.h)

  • [アーティクル]

CryptProtectData 関数は、DATA_BLOB構造内のデータに対して暗号化を実行します。 通常、データを暗号化したユーザーと同じログオン資格情報を持つユーザーのみがデータの暗号化を解除できます。 さらに、暗号化と暗号化解除は通常、同じコンピューターで行う必要があります。 例外の詳細については、「備考」を参照してください。

構文

DPAPI_IMP BOOL CryptProtectData(
  [in]           DATA_BLOB                 *pDataIn,
  [in, optional] LPCWSTR                   szDataDescr,
  [in, optional] DATA_BLOB                 *pOptionalEntropy,
  [in]           PVOID                     pvReserved,
  [in, optional] CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  [in]           DWORD                     dwFlags,
  [out]          DATA_BLOB                 *pDataOut
);

パラメーター

[in] pDataIn

暗号化するプレーンテキストを含むDATA_BLOB構造体へのポインター。

[in, optional] szDataDescr

暗号化するデータの読み取り可能な説明を含む文字列。 この説明文字列は、暗号化されたデータに含まれています。 このパラメーターは省略可能であり、 NULL に設定できます。

[in, optional] pOptionalEntropy

データ の暗号化 に使用されるパスワードまたはその他の追加エントロピを含むDATA_BLOB構造体へのポインター。 暗号化フェーズで使用される DATA_BLOB 構造は、暗号化解除フェーズでも使用する必要があります。 追加のエントロピがない場合は、このパラメーターを NULL に設定できます。 パスワードの保護については、「パスワードの 処理」を参照してください。

[in] pvReserved

将来使用するために予約されており、 NULL に設定する必要があります。

[in, optional] pPromptStruct

プロンプトを表示する場所とタイミング、およびプロンプトの内容に関する情報を提供する、 CRYPTPROTECT_PROMPTSTRUCT 構造体へのポインター。 このパラメーターは、暗号化フェーズと復号化フェーズの両方で NULL に設定できます。

[in] dwFlags

このパラメーターには、次のいずれかのフラグを指定できます。

値 意味
CRYPTPROTECT_LOCAL_MACHINE
 このフラグを設定すると、暗号化されたデータが個々のユーザーではなく、現在のコンピューターに関連付けられます。 CryptProtectData が呼び出されるコンピューター上のすべてのユーザーは、CryptUnprotectData を使用してデータの暗号化を解除できます。
CRYPTPROTECT_UI_FORBIDDEN
 このフラグは、ユーザー インターフェイス (UI) の表示がオプションではないリモートの状況で使用されます。 このフラグを設定し、保護または保護解除のいずれかの操作に UI を指定すると、操作は失敗し、 GetLastError は ERROR_PASSWORD_RESTRICTIONコードを返します。
CRYPTPROTECT_AUDIT
 このフラグは、保護操作と保護解除操作に関する監査を生成します。 監査ログ エントリは、szDataDescr が NULL ではなく空でない場合にのみ記録されます。

[out] pDataOut

暗号化されたデータを受信する DATA_BLOB 構造体へのポインター。 DATA_BLOB構造体の使用が完了したら、LocalFree 関数を呼び出して pbData メンバーを解放します。

戻り値

関数が成功した場合、関数は TRUE を返します。

関数が失敗すると、 FALSE が返されます。 拡張エラー情報については、 GetLastError を呼び出します。

解説

通常、データを暗号化したユーザーの 資格情報 と一致するログオン資格情報を持つユーザーのみがデータの暗号化を解除できます。 さらに、暗号化解除は通常、データが暗号化されたコンピューターでのみ実行できます。 ただし、ローミング プロファイルを持つユーザーは、ネットワーク上の別のコンピューターからデータを復号化できます。

データの暗号化時にCRYPTPROTECT_LOCAL_MACHINE フラグが設定されている場合、暗号化が行われたコンピューター上のユーザーは、データの暗号化を解除できます。

関数は、暗号化を実行するセッション キーを作成します。 データの暗号化を解除するときに、セッション キーが再度派生します。

また、この関数は、データ改ざんを防ぐために、暗号化されたデータにメッセージ認証コード (MAC) (キー付き整合性チェック) を追加します。

同じプロセスまたはプロセス間で一時的に使用するためにメモリを暗号化するには、 CryptProtectMemory 関数を呼び出します。

例

次の例は、 DATA_BLOB 構造内のデータの暗号化を示しています。 CryptProtectData 関数は、ユーザーのログオン資格情報を使用して関数が作成するセッション キーを使用して暗号化を行います。 この関数を使用する別の例については、「 サンプル C プログラム: CryptProtectData の使用」を参照してください。

// Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.

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

DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;

//--------------------------------------------------------------------
// Initialize the DataIn structure.

DataIn.pbData = pbDataInput;    
DataIn.cbData = cbDataInput;

//--------------------------------------------------------------------
//  Begin protect phase. Note that the encryption key is created
//  by the function and is not passed.

if(CryptProtectData(
     &DataIn,
     L"This is the description string.", // A description string
                                         // to be included with the
                                         // encrypted data. 
     NULL,                               // Optional entropy not used.
     NULL,                               // Reserved.
     NULL,                               // Pass NULL for the 
                                         // prompt structure.
     0,
     &DataOut))
{
     printf("The encryption phase worked.\n");
     LocalFree(DataOut.pbData);
}
else
{
    printf("Encryption error using CryptProtectData.\n");
    exit(1); 
}

要件

   
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー dpapi.h
Library Crypt32.lib
[DLL] Crypt32.dll

関連項目

CryptProtectMemory

CryptUnprotectData

データ暗号化と復号化関数

LocalFree