com.github.windpapi4j

Class WinDPAPI

java.lang.Object

com.github.windpapi4j.WinDPAPI

public final class WinDPAPI
extends Object

Starting from Microsoft(R) Windows(R) XP, Windows operating systems provide a built-in cryptographic feature called "Windows Data Protection API" (DPAPI), which allows any application to securely encrypt confidential user data using the user's credentials in a way that it can only be decrypted by the same user.

This Java library exposes Windows Data Protection encryption and decryption features as an easy to use Java API. Behind the scenes, JNA (Java Native Access) library is used to invoke the native Windows CryptoAPI CryptProtectData and CryptUnprotectData functions. Only an essential subset of Windows Data Protection API (DPAPI) is supported by this library: advanced cases involving showing prompts to the user etc. are not implemented.

As described in Microsoft Development Network Documentation on Cryptography Functions , both CryptProtectData and CryptUnprotectData functions accept optional flag values, which control their behaviour. These optional flag values are defined in WinDPAPI.CryptProtectFlag as enum constants and can be passed to the static factory method newInstance(CryptProtectFlag...)} after which the WinDPAPI instance returned will pass them to the target native Windows DPAPI method.

The methods provided by this class call the corresponding Windows Data Protection API native methods according to the following:

WinDPAPI library methods	Windows CryptoAPI method
protectData(byte[]) protectData(byte[], byte[]) protectData(byte[], byte[], java.lang.String)	CryptProtectData
unprotectData(byte[]) unprotectData(byte[], byte[])	CryptUnprotectData

Sample Code

 package test;

 import com.github.windpapi4j.WinDPAPI;
 import com.github.windpapi4j.WinDPAPI.CryptProtectFlag;

 public class Sample {

      public static void main(String[] args) throws Exception {

          if(WinDPAPI.isPlatformSupported()) {
               WinDPAPI winDPAPI = WinDPAPI.newInstance(CryptProtectFlag.CRYPTPROTECT_UI_FORBIDDEN);

               String message = "Hello World!";
               String charsetName = "UTF-8";

               byte[] clearTextBytes = message.getBytes(charsetName);

               byte[] cipherTextBytes = winDPAPI.protectData(clearTextBytes);

               byte[] decryptedBytes = winDPAPI.unprotectData(cipherTextBytes);

               String decryptedMessage = new String(decryptedBytes, charsetName);

               if(! message.equals(decryptedMessage) ) {
                    throw new IllegalStateException(message + " != " + decryptedMessage); // should not happen
               }

               System.out.println(decryptedMessage);

          } else {
               System.err.println("ERROR: platform not supported");
          }
      }
 }
 

Author:

Peter G. Horvath

See Also:

isPlatformSupported(), newInstance(CryptProtectFlag...), protectData(byte[]), protectData(byte[], byte[]), protectData(byte[], byte[], String), unprotectData(byte[]), unprotectData(byte[], byte[])

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WinDPAPI.CryptProtectFlag Possible flag values that can be passed to Windows Data Protection API CryptProtectData and CryptUnprotectData methods.

Method Summary

Modifier and Type	Method and Description
static boolean	isPlatformSupported() Returns an indication whether the current platform supports Windows Data Protection API and this library can be used or not.
static WinDPAPI	newInstance(WinDPAPI.CryptProtectFlag... cryptProtectFlags) Create a new instance of the WinDPAPI class.
byte[]	protectData(byte[] data) Encrypts the provided data using Windows Data Protection API CryptProtectData method.
byte[]	protectData(byte[] data, byte[] entropy) Encrypts the provided data using Windows Data Protection API CryptProtectData method.
byte[]	protectData(byte[] data, byte[] entropy, String description) Encrypts the provided data using Windows Data Protection API CryptProtectData method.
byte[]	unprotectData(byte[] data) Decrypts the provided encrypted data and performs an integrity check using Windows Data Protection API CryptUnprotectData method.
byte[]	unprotectData(byte[] data, byte[] entropy) Decrypts the provided encrypted data and performs an integrity check using Windows Data Protection API CryptUnprotectData method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newInstance

public static WinDPAPI newInstance(WinDPAPI.CryptProtectFlag... cryptProtectFlags)
                            throws InitializationFailedException

Create a new instance of the WinDPAPI class.

This static method creates a new WinDPAPI instance. If there are WinDPAPI.CryptProtectFlags specified as arguments, the returned WinDPAPI instance will pass the flag value to Windows Data Protection API CryptProtectData and CryptUnprotectData functions for both the encryption (protectData(byte[])), protectData(byte[], byte[]), protectData(byte[], byte[], String) and decryption unprotectData(byte[]), unprotectData(byte[], byte[])) methods are called.

NOTE:

• Passing any flag value to this method is optional and in most of the cases unnecessary.
• Some of the available flag values control behaviour or features not exposed in this library.

Parameters:

cryptProtectFlags - the (optional) flags to apply when Windows Data Protection API methods CryptProtectData and CryptUnprotectData are called

Returns:

a WinDPAPI instance, which (if there is any) applies the passed flags to Windows Data Protection API CryptProtectData and CryptUnprotectData method calls.

Throws:

InitializationFailedException - in case the WinDPAPI could not be initialized. (for example if it is called on a non-Windows platform or the loading of the JNA dispatcher fails)

See Also:

WinDPAPI.CryptProtectFlag

isPlatformSupported

public static boolean isPlatformSupported()

Returns an indication whether the current platform supports Windows Data Protection API and this library can be used or not.

NOTE: end-of-life Windows platforms are not considered: as a result, this method practically checks only if the current platform is Windows or not.

Returns:

true if the system is supported and this class can be used, false otherwise

protectData

public byte[] protectData(byte[] data)
                   throws WinAPICallFailedException

Encrypts the provided data using Windows Data Protection API CryptProtectData method.

If any flags were specified in newInstance(CryptProtectFlag...), then they are passed to the underlying CryptProtectData method call.

Parameters:

data - the data to encrypt (cannot be null)

Returns:

the encrypted data

Throws:

NullPointerException - if argument data is null

WinAPICallFailedException - in case the invocation of Windows DPAPI CryptProtectData fails

See Also:

unprotectData(byte[])

protectData

public byte[] protectData(byte[] data,
                          byte[] entropy)
                   throws WinAPICallFailedException

Encrypts the provided data using Windows Data Protection API CryptProtectData method. The (optional) entropy parameter allows an additional secret to be specified, which will be required to decrypt the data.

If any flags were specified in newInstance(CryptProtectFlag...), then they are passed to the underlying CryptProtectData method call.

Parameters:

data - the data to encrypt (cannot be null)

entropy - password or other additional entropy used to encrypt the data (might be null)

Returns:

the encrypted data

Throws:

WinAPICallFailedException - in case the invocation of Windows DPAPI CryptProtectData fails

NullPointerException - if argument data is null

See Also:

unprotectData(byte[], byte[])

protectData

public byte[] protectData(byte[] data,
                          byte[] entropy,
                          String description)
                   throws WinAPICallFailedException

Encrypts the provided data using Windows Data Protection API CryptProtectData method. The (optional) entropy parameter allows an additional secret to be specified, which will be required to decrypt the data.

If any flags were specified in newInstance(CryptProtectFlag...), then they are passed to the underlying CryptProtectData method call.

Parameters:

data - the data to encrypt (cannot be null)

entropy - password or other additional entropy used to encrypt the data (might be null)

description - a human readable description of data to be encrypted, which will be included with the encrypted data (might be null)

Returns:

the encrypted data

Throws:

WinAPICallFailedException - in case the invocation of Windows DPAPI CryptProtectData fails

NullPointerException - if argument data is null

See Also:

unprotectData(byte[], byte[])

unprotectData

public byte[] unprotectData(byte[] data)
                     throws WinAPICallFailedException

Decrypts the provided encrypted data and performs an integrity check using Windows Data Protection API CryptUnprotectData method.

If any flags were specified in newInstance(CryptProtectFlag...), then they are passed to the underlying CryptUnprotectData method call.

Parameters:

data - the data to decrypt (cannot be null)

Returns:

the decrypted data

Throws:

WinAPICallFailedException - in case the invocation of Windows DPAPI CryptUnprotectData fails

NullPointerException - if argument data is null

See Also:

protectData(byte[])

unprotectData

public byte[] unprotectData(byte[] data,
                            byte[] entropy)
                     throws WinAPICallFailedException

Decrypts the provided encrypted data and performs an integrity check using Windows Data Protection API CryptUnprotectData method. The (optional) entropy parameter is required if the data was encrypted using an additional secret.

If any flags were specified in newInstance(CryptProtectFlag...), then they are passed to the underlying CryptUnprotectData method call.

Parameters:

data - the data to decrypt (cannot be null)

entropy - password or other additional entropy that was used to encrypt the data (might be null)

Returns:

the decrypted data

Throws:

WinAPICallFailedException - in case the invocation of Windows DPAPI CryptUnprotectData fails

NullPointerException - if argument data is null

See Also:

protectData(byte[], byte[])