peter-gergely-horvath / windpapi4j

Windows DPAPI JNA Wrapper

WinDPAPI4J: A Windows DPAPI Wrapper for Java

Introduction

Starting from Microsoft(R) Windows(R) 2000, 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.

Note:

• Since this library exposes a Windows feature, it will only work, when called from a Java application running on Windows
• 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.

The JavaDoc is part of the Maven Central installation and can be viewed online via javadoc.io

Passing special flags to Windows DPAPI

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 WinDPAPI#newInstance(CryptProtectFlag...) after which the WinDPAPI instance returned will pass them to the target native Windows DPAPI method.

Mapping of methods

Methods for encryption

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

Methods for decryption

WinDPAPI library methods	Windows CryptoAPI method
WinDPAPI#unprotectData(byte[])	CryptUnprotectData
WinDPAPI#unprotectData(byte[], byte[])	CryptUnprotectData

Sample Code

package sample;
  
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) ) {
                // should not happen
                throw new IllegalStateException(message + " != " + decryptedMessage); 
            }

            System.out.println(decryptedMessage);

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

Availability

This library has been made available in Maven Central Repository.

windpapi4j's Issues

Application built using Launch4j and WinDPAPI4j may have an issue with DLL hijacking.

This is a bit of a weird one, but I at least wanted to make you aware of something I'm currently discussing with the Launch4j maintainer that might be addressable by your library as well. You can find the Launch4j conversation here: https://sourceforge.net/p/launch4j/discussion/332683/thread/17833e817b/?limit=25

Issue:
An application using WinDPAPI4j that is wrapped using Launch4j (Gui, with splash screen) may be vulnerable to DLL hijacking by placing a dummy/malicious cryptbase.dll file alongside the executable.

Prerequisites:

• Java application encrypts/decrypts string via WinDPAPI4j on startup.
• Java application is wrapped into Windows EXE using Launch4j with the gui and options configured.
• Sample code is available, though I have not put it online yet given it might expose a potential security risk.

Steps to reproduce:

1. Confirm that the EXE runs normally. (Sample code available would display a JavaFX dialog with String, DPAPI encrypted string, DPAPI decrypted string.)
2. Create a 0-byte "cryptbase.dll" file in the same folder as the EXE file.
3. Attempt to run the EXE again.

Expected Result:

• Application ignores the dummy file and runs normally.

Actual result:

• For a 0-byte file named cryptbase.dll: Application generates a windows error: "/cryptbase.dll is either not designed to run on Windows or it contains an error. Try installing the program again using the original installation media or contact your system administrator or the software vendor for support. Error status 0xc0000020."
• For a built DLL file renamed cryptbase.dll: Application crashes silently.

Further details / thoughts:

• The problem only occurs if Launch4j is configured with headerType:gui and a splash screen. By removing the element from the Launch4J configuration, the dummy file is not picked up by the executable. Similarly, the problem is not reproducible using headerType:console.
• Crypt32.dll appears to possibly have a dependency on cryptbase.dll via DPAPI.dll, though I'm not well versed enough on using the dependencies tool or windows programming in general to know how cryptbase might be brought in.
• Windows provides the means of specifying a search path for DLLs when loaded, and it appears JNA might also support these flags.
• One of the flags is LOAD_LIBRARY_SEARCH_SYSTEM32, which might help keep the DLL search constrained to the only location it should be pulling these libraries from: windows' system directory. (Constraining the DLL search path either by default or by option is what I think WinDPAPI4j might be able to do to address this issue)

Do you think there is something here that you can look into, or would you need some further details from the launch4j investigation first? I do have sample source code that can reliably reproduce this issue that I can provide.

Thank you!

Update to use the latest version of JNA

It would be nice to update this to use the latest version of JNA (5.5.0). This should eliminate the need to install the Visual Studio 2010 Redistributable in order for this to work.

blog post on windpapi4j

Hi Peter,

thanks for the great DPAPI wrapper! I just wanted to let you know that I wrote a blog post about it: https://labs.consol.de/development/2017/03/27/protecting-passwords-in-java-properties-files.html

Fabian

Failed to initialize a WinDPAPI instance on Windows Server 2019 Standard edition

We have created a standalone java utility to encrypt/decrypt the text using WinDP APIs. We are using this library to do the same.

The utility is failed to encrypt or decrypt with the below error. Looks like it was failed at the below statement.

Error: Initialization failed.

Failing statement:

• WinDPAPI winDPAPI = WinDPAPI.newInstance(CryptProtectFlag.CRYPTPROTECT_LOCAL_MACHINE);

This utility is failed on one VM having Windows Server 2019 Standard edition OS. But it is working fine on other VM having the same OS. This utility is also working fine on other OS like Windows Server 2012 R2, Server 2016, etc.

Can someone help to resolve this error? Does it require some pre-req before executing this library?

Kindly help as soon as possible.

We are getting the following errors.