Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

CryptProtectData (crypt32)
 
.
Summary
The CryptProtectData function performs encryption on the data in a DATA_BLOB structure. Typically, only a user with the same logon credential as the encrypter can decrypt the data. In addition, the encryption and decryption usually must be done on the same computer.

C# Signature:

[
DllImport("Crypt32.dll",
SetLastError=true,
CharSet=System.Runtime.InteropServices.CharSet.Auto)
]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool CryptProtectData(
    ref DATA_BLOB pDataIn,
    String szDataDescr,
    ref DATA_BLOB pOptionalEntropy,
    IntPtr pvReserved,
    ref CRYPTPROTECT_PROMPTSTRUCT pPromptStruct,
    CryptProtectFlags dwFlags,
    ref DATA_BLOB pDataOut
);

VB .NET Signature:

<DllImport("Crypt32.dll", SetLastError:=True, CharSet:=System.Runtime.InteropServices.CharSet.Auto)> _
Private Shared Function CryptProtectData ( _
    ByRef pDataIn As DATA_BLOB, _
    ByVal szDataDescr As String, _
    ByRef pOptionalEntropy As DATA_BLOB, _
    ByVal pvReseved As IntPtr, _
    ByRef pPromptStruct As CRYPTPROTECT_PROMPTSTRUCT, _
    ByVal dwFlags As Integer, _
    ByRef pDataOut As DATA_BLOB _
) As Boolean
End Function

See also:

DATA_BLOB

CRYPTPROTECT_PROMPTSTRUCT

CryptProtectFlags

CryptUnprotectData

Notes:

Only a user with logon credentials matching those of the encrypter can decrypt the data. In addition, decryption usually can only be done on the computer where the data was encrypted.

Warning If the logon credentials are lost or forgotten, the data is usually unrecoverable. However, if the dwFlags parameter in the CryptProtectData function is set to CRYPTPROTECT_LOCAL_MACHINE with or without additional entropy specified in the pOptionalEntropy parameter, any user on the same computer where the data was encrypted can recover the data.

The function creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted.

The function also adds a message authentication code (MAC), which is a keyed integrity check, to the encrypted data to guard against data tampering.

Under some circumstances, Microsoft cryptographic service providers (CSPs) may not allow encryption when used in France, in which case this function fails with the error code NTE_PERM.

You can store the encryption or master keys used by CryptProtectData in a file in the Windows folder or in the system registry so that certain persistent registry implementations will retain the encryption keys after losing and regaining power. See Master Key Storage for more information.

Tips & Tricks:

Please add some!

Change the DATA_BLOB and CRYPTPROTECT_PROMPTSTRUT from structures to classes. This way you don't have to pass the value types by ref. Both the pOptionalEntropy and the pPromptStruct can be null. If you use structs you have to new empty structs instead of just passing null if you use classes.

Sample Code:

How To Create a DPAPI Library: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secmod/html/secmod21.asp

Alternative Managed API:

In .NET v2.0, the System.Cryptography.ProtectedData class provides the same functionality:

http://msdn2.microsoft.com/en-us/library/system.security.cryptography.protecteddata.aspx

In the upcoming .NET v2.0, the ProtectData class will provide the same functionality.

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions