Merge pull request #2632 from corob-msft/cr-dependent-load-flag-update

PMEds28 · web-flow · commit 952cba411c20 · 2020-01-23T08:54:59.000Z
/DEPENDENTLOADFLAG revision per discussion
diff --git a/docs/build/reference/dependentloadflag.md b/docs/build/reference/dependentloadflag.md
@@ -1,13 +1,21 @@
 ---
 title: "/DEPENDENTLOADFLAG (Set default dependent load flags)"
-description: "The /DEPENDENTLOADFLAG option sets default flags for DLLs loaded using LoadLibrary"
-ms.date: "12/22/2018"
+description: "The /DEPENDENTLOADFLAG option sets default dependent load flags for DLLs loaded by this module."
+ms.date: "01/22/2020"
 f1_keywords: ["dependentloadflag"]
 helpviewer_keywords: ["LINK tool [C++], dependent load flags", "-DEPENDENTLOADFLAG linker option", "linker [C++], DEPENDENTLOADFLAG", "DEPENDENTLOADFLAG linker option", "/DEPENDENTLOADFLAG linker option"]
 ---
 # /DEPENDENTLOADFLAG (Set default dependent load flags)
 
-Sets the default load flags used when `LoadLibrary` is used to load DLLs.
+::: moniker range="vs-2015"
+
+The **/DEPENDENTLOADFLAG** option requires Visual Studio 2017 or later.
+
+::: moniker-end
+
+::: moniker range=">=vs-2017"
+
+Sets the default load flags used when the operating system resolves the statically linked imports of a module.
 
 ## Syntax
 
@@ -16,17 +24,23 @@ Sets the default load flags used when `LoadLibrary` is used to load DLLs.
 ### Arguments
 
 *load_flags*<br/>
-An optional "C"-style 16-bit integer value in decimal, octal with a leading zero, or hexadecimal with a leading `0x`, that specifies the dependent load flags to apply to all [LoadLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw) calls. The default value is 0.
+An optional integer value that specifies the load flags to apply when resolving statically linked import dependencies of the module. The default value is 0. For a list of supported flag values, see the `LOAD_LIBRARY_SEARCH_*` entries in [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw).
 
 ## Remarks
 
-This option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later versions. This option is ignored by other operating systems that run the app.
+When the operating system resolves the statically linked imports of a module, it uses the [default search order](/windows/win32/dlls/dynamic-link-library-search-order). Use the **/DEPENDENTLOADFLAG** option to specify a *load_flags* value that changes the search path used to resolve these imports. On supported operating systems, it changes the static import resolution search order, similar to what [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexa) does when using `LOAD_LIBRARY_SEARCH` parameters. For information on the search order set by *load_flags*, see [Search order using LOAD_LIBRARY_SEARCH flags](/windows/win32/dlls/dynamic-link-library-search-order#search-order-using-load_library_search-flags).
 
-On supported operating systems, this option has the effect of changing calls to `LoadLibrary("dependent.dll")` to the equivalent of `LoadLibraryEx("dependent.dll", 0, load_flags)`. Calls to [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw) are unaffected. This option doesn't apply recursively to DLLs loaded by your app.
+This flag can be used to make one [DLL planting attack](/windows/win32/dlls/dynamic-link-library-security) vector more difficult. For example, consider an app that has statically linked a DLL:
 
-This flag can be used to make [DLL planting attacks](/windows/win32/dlls/dynamic-link-library-security) more difficult. For example, if an app uses `LoadLibrary` to load a dependent DLL, an attacker could plant a DLL with the same name in the search path used by `LoadLibrary`, such as the current directory, which may be checked before system directories if safe DLL search mode is disabled. Safe DLL search mode places the user's current directory later in the search order, and is enabled by default on Windows XP SP2 and later versions. For more information, see [Dynamic-Link Library Search Order](/windows/win32/Dlls/dynamic-link-library-search-order).
+- An attacker could plant a DLL with the same name earlier in the import resolution search path, such as the application directory. Protected directories are more difficult - but not impossible - for an attacker to change.
 
-If you specify the link option `/DEPENDENTLOADFLAG:0xA00` (the value of the combined flags `LOAD_LIBRARY_SEARCH_APPLICATION_DIR | LOAD_LIBRARY_SEARCH_SYSTEM32`), then even if safe DLL search mode is disabled on the user's computer, the DLL search path is limited to the application directory, followed by the %windows%\system32 directory. An option of `/DEPENDENTLOADFLAG:0x800` is even more restrictive, limiting search to the %windows%\system32 directory. Protected directories are more difficult - but not impossible - for an attacker to change. For information on the flags available, and their symbolic and numeric values, see the *dwFlags* parameter description in [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw). For information on the search order used when various dependent load flags are used, see [Search order using LOAD_LIBRARY_SEARCH flags](/windows/win32/dlls/dynamic-link-library-search-order#search-order-using-load_library_search-flags).
+- If the DLL is missing from the application, %windows%\system32, and %windows% directories, import resolution falls through to the current directory. An attacker could plant a DLL there.
+
+In both cases, if you specify the link option `/DEPENDENTLOADFLAG:0x800` (the value of the flag `LOAD_LIBRARY_SEARCH_SYSTEM32`), then the module search path is limited to the %windows%\system32 directory. It offers some protection from planting attacks on the other directories. For more information, see [Dynamic-Link Library Security](/windows/win32/dlls/dynamic-link-library-security).
+
+To see the value set by the **/DEPENDENTLOADFLAG** option in any DLL, use the [DUMPBIN](dumpbin-reference.md) command with the [/LOADCONFIG](loadconfig.md) option.
+
+The **/DEPENDENTLOADFLAG** option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later versions. This option is ignored by other operating systems that run the app.
 
 ### To set the DEPENDENTLOADFLAG linker option in the Visual Studio development environment
 
@@ -43,8 +57,11 @@ If you specify the link option `/DEPENDENTLOADFLAG:0xA00` (the value of the comb
 ## See also
 
 - [MSVC linker reference](linking.md)
-- [MSVC Linker Options](linker-options.md)
-- [Link an executable to a DLL](../linking-an-executable-to-a-dll.md#linking-implicitly)
-- [Link an executable to a DLL](../linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use)
+- [MSVC linker options](linker-options.md)
+- [Link an executable to a DLL implicitly](../linking-an-executable-to-a-dll.md#linking-implicitly)
+- [Determine which linking method to use](../linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use)
 - [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw)
 - [Dynamic-Link Library Search Order](/windows/win32/Dlls/dynamic-link-library-search-order)
+- [Dynamic-Link Library Security](/windows/win32/dlls/dynamic-link-library-security)
+
+::: moniker-end
