pinvoke.net: crypt32.CryptProtectData

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

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

Documentation