Windows Data Protection
DPAPI - Data Protection Application
Programming Interface; most probably the
smallest API available under Win32. It contains just two functions.
Beginning with Windows 2000, Microsoft introduced the DPAPI. It wasn't well known
or documented until Windows XP came out.
The DPAPI is a pretty well thought-out mechanism to allow any application to do
simple and yet powerful encryption for its data. It has good recovery methods
- in case the password gets lost, fully supports enterprise or home use
and is based on the Cryptographic Services available under Win32.
So, what does it actually do?? Simple - it encrypts or decrypts a block of data.
And it does it without asking much for settings, cryptographic keys, algorithms
and other hocus-pocus. Sounds like a ideal function for securing sensitive data?
Definitely. There are some options that you can set but it goes even without
Here are some highlights:
user bound encryption (using users credentials)
machine bound encryption (using the machines credentials)
application supplied pass phrase
optional user supplied password
transparent mode (no user-interface at all)
optional security auditing
operating on standards - PKCS#5v2, RFC-2404, RSA etc.
MSDN contains a very well written
article explaining the guts of DPAPI and is for sure worth reading if
you are into security.
While DPAPI isn't generally difficult to use it has some pitfalls which you can
avoid with the
The class makes all necessary conversions if needed (DPAPI takes only UNICODE
strings) and handles filling the data structures, allocating/freeing memory and
so on. But at the end its just a wrapper class.
It provides one function in many flavors to perform the encryption and another
one for decryption. Sanity checks on parameters are performed.
As you can see on the pictures, the
CryptoAPI provides some dialog boxes with
information and options to the user. It allows the user to modify encryption
strength, choose a custom password and view information about the data to be
Its important to remember when the user is allowed to choose a password, he
most probably will forget it. In this case there is no way to retrieve this
lost password and the data is not recoverable.
The main dialog when the UI is enabled.
The "Set security level..." dialog.
Changing to High Security mode enables the password. If you don't supply a
description, the user can enter a description on his own.
The "Details..." dialog.
How to use?
Create an instance of
CProtectedData, call its
member function, if needed set some options and finally call one of the
UnprotectData() functions. Both return a pointer to a
DATA_BLOB structure contains the size of the
resulting data and a pointer to the data. If the
cbData member is
0 the encryption/decryption failed and you can call
to retrieve the reason.
Be aware that this functions may fail when you enable the user interface because
the user can cancel the operation while normally the functions succeed.
const DATA_BLOB* pData = pd.ProtectData();
For convenience there are two derived classes
CMachineProtectedData. While the first is equal to the
class, the second class just sets the appropriate option to encrypt with
machine credentials. They are just provided for code cleanness.
The DPAPI uses optional entropy data which is supplied by the application. If
you supply entropy data, it will - simply expressed - be taken as a part of the
password and included in key generation. In other words, it increases
security. Data encrypted without entropy data can be decrypted by any other
One last thing is up to you in order to avoid memory leaks: when you retrieve
the description string from the encrypted data by supplying
with a pointer to a
LPTSTR variable it will place the description
into this variable and you must call
::LocalFree() when you don't
need it anymore.
The sample application shows how to use any and all of the available options and
performs multiple full cycles of encryption/decryption with and without user
intervention. Anyway, it does not save the encrypted data to disk.
All classes are fully MBCS/Unicode enabled. The sample contains all
configurations. Written, compiled and tested under VC7 but should also compile
with VC6 and below. The header file automatically add linking with crypt32.lib.
Remember that you need Windows 2000 or Windows XP to use DPAPI.