Overview

On Windows, a security vulnerability called "DLL hijacking" can occur when an application loads a malicious DLL instead of the intended one. This risk arises when the system searches for application-dependent DLLs in directories that are writable or controlled by unauthorized users, allowing a legitimate DLL to be replaced with a malicious one of the same name.

To mitigate this risk for your Java application, the Wrapper allows you to configure where the system will look for DLLs that are loaded by native libraries. Restricting the search to trusted directories helps prevent untrusted libraries from being loaded.

The following properties can be used to configure search paths for DLLs:

NOTE

The scope of these settings is limited to the Java application's process, meaning the configured search paths are not inherited by child processes.

Additionally, these settings only affect libraries loaded by native code, not those explicitly loaded by Java using methods like system.LoadLibrary(). To specify where the JVM should look for native libraries, use the wrapper.java.library.path.<n> properties instead.

wrapper.java.windows.dll.search.mode Property
Compatibility :3.6.3
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/Linux (Not Supported)

This property makes it possible to configure two modes: one leaving DLL searching to the system's default behavior, and the other one restricting the search to only the paths specified by the wrapper.java.windows.dll.search.path.<n> properties.

The two modes are represented by the following tokens:

  • LEGACY: system's default behavior (Safe DLL Search Mode on recent versions of Windows)

  • RESTRICTED: To restrict the directories where DLL are searched.

The default value is LEGACY.

Example: 
wrapper.java.windows.dll.search.mode=RESTRICTED

NOTE

When using LEGACY mode, the Wrapper allows the system to use its default mechanism for loading DLLs.

Starting with Windows XP Service Pack 2, Windows follows a more secure DLL search order that excludes the application's working directory. This change helps reduce the risk of loading malicious DLLs from insecure locations. However, it's important to note that the search order still includes directories specified in the PATH environment variable. Since PATH is often shared system-wide, it may include directories that are not safe for the application to load libraries from.

Specific directories can be added to the beginning of the PATH by using the wrapper.system.library.path.<n> properties.


In contrast, when using RESTRICTED mode, the system does not search for DLLs in the directories listed in the PATH environment variable. Although the PATH is always populated with values from wrapper.java.windows.dll.search.path.<n>, the directories specified through these properties are not used by the system when searching for DLLs. RESTRICTED mode is therefore limited to the system32 path, the directory containing the Java command, and the paths specified with wrapper.java.windows.dll.search.path.<n>.

WARNING

When using the RESTRICTED mode, be cautious as overly restrictive settings that disallow directories expected by the JVM or the application may result in DLL loading failures and runtime errors.

wrapper.java.windows.dll.search.path.<n> Properties
Compatibility :3.6.3
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/Linux (Not Supported)

This property set allows you to configure the paths to search when DLLs are loaded from native libraries. These properties only apply when wrapper.java.windows.dll.search.mode is set to RESTRICTED and are ignored when LEGACY is used.

<n> component:
Each element has a property name which starts with "wrapper.java.windows.dll.search.path." and the "<n>" component of the property name is an integer number counting up from "1". By default the numbering should be in sequence without gaps". The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

Example: 
wrapper.java.windows.dll.search.path.1=../syslib

Reference: Library
  • wrapper.java.library.path.<n> (2.2.9)

    Specify a list of directories containing any native libraries used by the Wrapper or the Java application.

  • wrapper.java.library.path.append_system_path (3.1.0)

    Appends the content of the system PATH to the Java library path.

  • wrapper.native_library (3.1.0)

    Sets the base name of the Wrapper native library.

  • wrapper.java.windows.dll.search.mode (3.6.3) ( Std/Pro )

    Specifies how the system searches for DLLs loaded from native code within the Java process.

  • wrapper.java.windows.dll.search.path.<n> (3.6.3) ( Std/Pro )

    Sets the directories to search for DLLs loaded from native code within the Java process.

  • wrapper.system.library.path.<n> (3.6.0)

    Specify a list of directories containing native libraries that are loaded using the operating system's default mechanism.

  • wrapper.working.dir (3.1.0)

    Sets the path to the working directory.