Can I Install an ISAPI Filter as an ISAPI Extension or Wildcard Application Mapping?

  • Article

Question:

My ISAPI filter written in MFC using Visual Studio .NET 2003, to replace character (I am replacing " ' " with " ` " in URL) works fine in my development machine having IIS 5.0, but fails in server having IIS 6.0. I am getting Internal Server Error (HTTP 500).

I have compiled the dll as "Use MFC in a Static Library" and "No use of ATL" and in "Release Mode".

I have added the ISAPI filter in the "Web Sites" Level in the server (IIS 6.0) and have also added the dll in the "Particular Virtual Folder-->Properties-->Directory--> Configuration-->Wildcard Application Maps" level.

The server has .NET Framework 1.1 (1.1.4322), same as development machine.

If you can help me out , that will be great.

Thanks,

Answer:

The problem here is that you misconfigured IIS to load an ISAPI Filter DLL as a Wildcard Application Mapping. If you remove the ISAPI Filter DLL at the "Wildcard Application Maps" level, you should stop getting the 500 error.

Details, Details...

The terms "ISAPI Extension" and "ISAPI Filter" commonly confuse users, so here are some factual ways to compare/contrast them:

  1. ISAPI Extension and ISAPI Filter are two completely different mechanisms to extend IIS functionality and are not interchangeable.
  2. ISAPI Extension and ISAPI Filter are both implemented as normal Win32 DLLs for IIS to call LoadLibrary() on.
  3. ISAPI Extension DLLs must export two function signatures, GetExtensionVersion and HttpExtensionProc, and optionally TerminateExtension.
  4. ISAPI Filter DLLs must export two function signatures, GetFilterVersion and HttpFilterProc, and optionally TerminateFilter.
  5. The only way you can configure one DLL as both ISAPI Extension and ISAPI Filter is if that DLL exports all of the necessary function signatures of both ISAPI Extension and ISAPI Filter (i.e. at minimum, GetExtensionVersion, GetFilterVersion, HttpExtensionProc, HttpFilterProc).
  6. ISAPI Filters are configured as "Filters" at either the Websites (aka "Global") or Website (aka "Site") level.
  7. ISAPI Extensions are configured either as "Application Mappings" or "Wildcard Application Mappings", or they are requested as-is on the URL request line (i.e. https://server/cgi-bin/myISAPI.dll?param=value)

What is happening in your situation is this:

  • You wrote an ISAPI Filter DLL that exports GetFilterVersion and HttpFilterProc function signatures.
  • You configured this DLL as an ISAPI Filter at the global level. This is perfectly fine.
  • You configured this DLL as an ISAPI Extension at the "Wildcard Application Maps" level. This is not fine because the DLL does not export GetExtensionVersion nor HttpExtensionProc.
  • And since IIS6 honors Wildcard Application Maps first amongst all script mappings (see this URL for an explanation), IIS fails to load your ISAPI Filter DLL as an ISAPI Extension, and this causes the 500 error.

This is why I recommend that you remove the incorrect Wildcard Application Mapping configuration.

If you still have problems with your ISAPI Filter, you may want to check out this URL on diagnosing ISAPI Filter Load Errors.

Why does this work on IIS5 but not on IIS6?

Regarding your question about why the same configuration succeeds on IIS5 but fails on IIS6... I can only say that LOTS of illegal things succeed or silently fail on IIS5. For example, a lot of security vulnerabilities work on IIS5 but not on IIS6. ISAPI Filters silently fail on IIS5 but not on IIS6. Etc.

In general, IIS6 is far more secure and far less forgiving than IIS5 when it comes to invalid server configuration or invalid usage of API calls. This is a good thing from a security perspective. So, the fact that something accidentally worked on IIS5 is no indication that it works on IIS6. You may have required a relaxed security model or vulnerability in order to function, and IIS6 or Windows Server 2003 no longer allow that for security reasons. Sorry... security is only as good as the weakest link, so there is no way that we can close security threats from the bad guys without taking away the same functionality from you. I can only recommend that you heed the warning from IIS6 and perform a security analysis of your own code to determine if it truly needs the elevated privileges to function or if you want things to "just work" and darn the security vulnerabilities... but please do take responsibility for your own actions since IIS/Windows did warn you...

//David