David Wang : IIS7

HOWTO: PreCondition an ISAPI Extension DLL

David.Wang — Fri, 31 Oct 2008 08:00:00 GMT

Question:

Hello

We have a legacy x64 ISAPI extension that runs without problems in Win 2003 64bit - IIS 6.0.

But in Win2008 EBS Security Manager setup, IIS 7.0 Default Application Pool's WOW64 / Enable32BitApp property is enabled by default, and this makes x64 ISAPI extension DLL to fail loading.

By setting the Enable32BitApp option as false in application pool settings, the problem gets resolved.

However we want to speicify ISAPI extension explicitly to be loaded as x64 module using "precondition='bitness64' " settings like ISAPI filters, so that ISAPI extension works no matter what application pool is configured for (x64 only, or both x64 and x86)

Could anyone please suggest how we can do this or the app cmd that would allow us to do it.

Answer:

Technically, preConditions only apply on a per-GlobalModule, per-Module, per-Handler, or per-ISAPI Filter basis. This is because globalModules, modules, handlers, and ISAPI Filters have to be explicitly configured within IIS to function. ISAPI Extensions simply need to be dropped into a web-accessible folder and then "allowed to execute" via Executable execution permission and IsapiCgiRestriction. There is no per-ISAPI Extension configuration to stick preConditions.

However, as I will illustrate shortly, it is STILL possible to apply preConditions on a per-ISAPI Extension basis in a fairly clean and clear manner.

Some people would propose that it would be nice to stick preCondition onto IsapiCgiRestriction since it is a sort of per-ISAPI Extension configuration, but IsapiCgiRestriction is really a security configuration which we hardly want to preCondition. Besides, what happens if notListedIsapisAllowed="true" and we still want to preCondition an ISAPI Extension - now we have to add a bogus entry for preCondition? Anyways, this is getting complicated very quickly, a sure sign that the proposed design has some fundamental logical flaw.

Common Misconceptions about Bitness and preConditions

Now, before I get into how to setup per-ISAPI Extension preCondition, I want to clarify some of the misconceptions in your question about Bitness and preCondition. Using preCondition="bitness64" does NOT:

Explicitly load an ISAPI Extension as x64 module
Make an ISAPI work no matter what the application pool is configured for
Allow "both x64 and x86" of ANYTHING

A preCondition is a simple filtering mechanism on the affected IIS configuration. What preCondition="bitness64" means is that the affected configuration is ONLY applicable in a 64bit Application Pool. A 64bit Application Pool will only see globalModule, module, handler, and isapiFilter with either bitness64 or no bitness preCondition. It will not see any globalModule, module, handler, and isapiFilter configuration with the bitness32 preCondition.

Thus, a preCondition does NOT cause an ISAPI to be explicitly loaded as any bitness. LoadLibrary() will just load the resolved DLL name into the process's address space, and if the bitness do not match, fail. Likewise, it cannot make the ISAPI work no matter what, because if the bitness does not match, it fails. Finally, Windows does not allow both 32bit and 64bit code to co-exist in the same process, and IIS does not allow an Application Pool to be both 32bit and 64bit.

What is a correct way to use the bitness preConditions? Check out the various pre-defined "-64" handlers when ASP.Net Feature support is installed. For example, the svc-ISAPI-2.0 and svc-ISAPI-2.0-64 handlers. Notice that the bitness32 preCondition applies to a 32bit ISAPI, and bitness64 preCondition applies to a separate 64bit ISAPI. This dual configuration allows the same feature to work with both 32bit and 64bit Application Pools with no additional configurations changes in-between. Remember how you had to run aspnet_regiis.exe from the correct Framework bitness directory every time you changed Application Pool bitness with .Net Framework 2.0 on IIS6 in 64bit Windows, or else you would see 503 Service Unavailable failure? No longer necessary with preConditions on IIS7 and things just work!

PreConditioning an ISAPI Extension DLL

As I mentioned earlier, per-ISAPI Extension preCondition can be accomplished by leveraging preCondition support of handlers. The following configuration shows how to request an ISAPI Extension name "MyISAPI.dll" and have it work no matter the bitness of the Application Pool. It requires a 32bit version and 64bit version of the same DLL, named MyISAPI32.dll and MyISAPI64.dll, respectively.

<handlers>
  ...
  <add name="MyISAPI-64" path="MyISAPI.dll" verb="*" modules="IsapiModule" scriptProcessor="C:\inetpub\wwwroot\bin\MyISAPI64.dll" resourceType="File" requireAccess="Execute" preCondition="bitness64" />
  <add name="MyISAPI-32" path="MyISAPI.dll" verb="*" modules="IsapiModule" scriptProcessor="C:\inetpub\wwwroot\bin\MyISAPI32.dll" resourceType="File" requireAccess="Execute" preCondition="bitness32" />
  ...
</handlers>

Looking at the key configuration details:

Having two handlers, one with bitness32 preCondition on the 32bit MyISAPI32.dll, the other with bitness64 preCondition on the 64bit MyISAPI64.dll, assures that only one of these handlers with the correct bitness apply to any given Application Pool
path="MyISAPI.dll" means that end consumers only request /MyISAPI.dll while the dynamic 32/64bit wiring happens underneath the covers via the bitness preCondition
requireAccess="Execute" makes Execute permissions necessary to execute an ISAPI Extension DLL in a given URL namespace

The combination of preConditions, path-remapping, and requireAccess gives the illusion of a single named ISAPI DLL which transparently works with similar requirements as ISAPI Extension regardless of Application Pool bitness. Yes, don't forget to set IsapiCgiRestriction on both MyISAPI64.dll and MyISAPI32.dll as well as enable "Execute" permission on your virtual directory... :-)

Cheers.

//David

Managed Modules and ISAPI Filters

David.Wang — Tue, 09 Sep 2008 07:36:00 GMT

Question:

Hello,

I have an isapi filter and a managed module. I need to put both in the same website and I need that the manage module run before the isapi filter. The sequence are: Module--->ISAPI filter. How can I do this?

Answer:

The answer really depends on the filter events that the ISAPI Filter subscribes to.

Unfortunately, no built-in IIS UI or tool displays this information since it is rarely of interest to the user.

However, you can use my tool from here to view the events that an ISAPI Filter subscribes for. To the astute reader - this filter status information is only available AFTER IIS successfully loads an ISAPI Filter (i.e. IIS successfully LoadLibrary(), GetProcAddress() the Filter DLL's GetFilterVersion() exported function, executes it for registered events, and the function returns TRUE to IIS), and depending on IIS version/mode and the type of ISAPI Filter, IIS ends up loading an ISAPI Filter at different times. The history and rationale behind the differences is an entire blog entry all to itself, but the following table is a sufficient summary for now:

IIS Version (Mode)	Global Filter Loads...	Site Filter Loads...
IIS4 / IIS5 / IIS5.1	On Server Startup	When Configured for a Website
IIS6 (IIS5 Compatibility Mode)	On Server Startup	When Configured, on first request to that Website
IIS6 (Worker Process Isolation Mode)	On w3wp.exe Startup	When Configured, on first request to that Website
IIS7 (Classic and Integrated Modes)	Same as IIS6 Worker Process Isolation Mode	Same as IIS6 Worker Process Isolation Mode

It's all about Timing

Now, you may wonder WHY knowing the subscribed filter events affect the answer. As in life and most things in our four dimensional world, it's all about timing, and this situation is no exception.

ISAPI Filter triggers on various events fired by IIS throughout a request's processing, while Managed Modules trigger after only one of those events (and in IIS7 in Integrated Pipeline Mode, Managed Modules trigger on ALMOST all of the events). Thus, if you want the Managed Module to run before the ISAPI Filter, the ISAPI Filter's subscribed events must be limited to those that happen AFTER the Module triggers.

Since Modules trigger pretty late in the request processing, right before response generation and logging, and ISAPI Filters typically trigger early in the request process, to perform either custom authentication, URL rewriting, etc, it is highly likely that what you want to do is impossible on any IIS version - without knowing the exact filter events involved, I cannot be definitive.

The following is a condensed outline of how ISAPI Filter and Managed Modules triggering are ordered:

On IIS4, IIS5, IIS5.1, and IIS6, Managed Modules trigger between the SF_NOTIFY_AUTH_COMPLETE and SF_NOTIFY_SEND_RESPONSE filter events.
On IIS7 in Classic Pipeline Mode, things behave as in IIS6.
On IIS7 in Integrated Pipeline Mode, Managed Modules trigger in-line with all ISAPI Filter events in all Pipeline Modes (Classic and Integrated) because ISAPI Filters are actually just DLLs loaded by the "ISAPI Filter" Module, which acts as a shim to trigger appropriate ISAPI Filter events for the corresponding Module events of the Integrated Pipeline. For example, the "ISAPI Filter Module" subscribes for the OnPreBeginRequest event, which when triggered by IIS will cause it to fire the SF_NOTIFY_PREPROC_HEADERS filter event to all applicable ISAPI Filters for that URL scope.

Conclusion

In general, if your ISAPI filter does NOT subscribe to events earlier than SF_NOTIFY_SEND_RESPONSE, it would be possible for a Managed Module to execute before the ISAPI filter triggers.

You should notice some direct correlations between the Module events of the IIS7 Integrated Pipeline and a merging of the ISAPI Filter events and classic ASP.Net HttpModule events. This is intentional - that is what we meant with the name "Integrated" Pipeline! :-)

The astute reader should note that Managed Modules on IIS7 do not have access to the OnPreBeginRequest module event. Since that event is used by the "ISAPI Filter" Module to trigger the SF_NOTIFY_PREPROC_HEADERS event, this means that even in Integrated Pipeline mode, where Managed Modules trigger in-line with any other module such as the "ISAPI Filter" Module shim, a Managed Module will NOT be able to execute before an ISAPI Filter that subscribes to the SF_NOTIFY_PREPROC_HEADERS event.

Yes, there is a huge story behind why OnPreBeginRequest even exists and why Managed Modules do not have access to that event (and other such global notification events). The blurbs on MSDN simply does not do it justice...

But at long last, here is the long-winded response to it all.

Cheers!

//David

IIS7 Handlers - accessPolicy and requireAccess

David.Wang — Sun, 01 Jun 2008 11:50:00 GMT

Question:

Hello:

In IIS 7.0, you can edit a handler mapping in the Handler Mappings applet (like for AspClassic), then click Request Restrictions button, Access tab, and select the "Write" permission. But even when the "Edit Feature Permission" in that site/folder is set to Read+Script+Execute, the handler with the "Write" permission is still disabled!

Why?

How do you both keep a handler enabled and also set its request restriction to "Write" at the same time? I've read through all the IIS help files, they're either silent or incorrect on this question.

Answer:

What you want to do is not achievable via the UI. You have to configure the .config file directly.

This looks like a bug in the UI because the "accessPolicy" and "requireAccess" attributes are not aligned.

Here's what the UI is attempting to do:

accessPolicy corresponds to the old "Execute Permissions" set of checkboxes
requireAccess is brand new in IIS7. After we opened up the handler definition in IIS7, it became necessary to add requireAccess so that one could express the concept of "this handler requires script access permissions to execute" so that one could then use accessPolicy to control whether "scripts" can run or not.

Before IIS7, the logical tie between handlers and requireAccess was hardcoded into IIS into statements like:

StaticFileHandler requires Read Permission
All Other Handlers require Script Permission
EXE and DLL require Execute Permission

Starting from IIS7, it is completely wide open. The astute reader should realize that it is possible in IIS7 to do something goofy like set ISAPI Handler to require "no" permissions (instead of Execute) and allow the ISAPI Handler to be executed by IIS Core all the time. However, the actual execution of an ISAPI DLL by the ISAPI Handler is still subject to ISAPI CGI Restriction. This is another example of defense in depth!

What the UI tries to display via the "State" view is: "if you allow only scripts, only these handlers are active". Of course, it is missing the "Write" permission as a filter. Even though the handler require access dialog just added "Write". Thus, when you selected "Write" request restriction for the handler, it makes it impossible for the UI to display as enabled because it does not have "Write" permission as a filter.

I would chalk this up as a bug introduced when WebDAV was added for Windows Server 2008 because that's the main module that needs it. However, if you think about what I just said, this is really easy to work around. Remember, IIS7 does not know what "Execute" permission is (or else the goofy ISAPI Handler configuration would not be possible), so IIS7 does not know what "Write" permission is, either.

Internally, the handler execution logic in IIS7 Core is:

accessPolicy contains "Text1, Text2, Text3".
handler's requireAccess contains "Text3".
requireAccess text is found inside of accessPolicy text. Allow handler execution.

//David

Choice of Development Platform for IIS Modules

David.Wang — Fri, 18 Apr 2008 11:40:00 GMT

Question:

I am starting a new project (ASP.NET 3.5) that will require at least one custom HTTP module. My two development computers are running 32-bit XP Pro/SP2, but I plan to reimage with Vista (already have it ready to be installed). My preference would be to NOT switch to Vista quite yet, but continue the project with my XP Pro systems.

Is it possible or reasonable to proceed with developing the custom HTTP module(s) with my XP Pro system (IIS 5.1) and expect that they will work just fine with IIS7 - and with no changes - when I upgrade to Vista? Or do I really need to switch to Vista before developing these custom HTTP modules?

One module will implement a custom authentication scheme. Another will load an assembly into a separate app domain, execute some code, marshal the results back, stick them into the ASP.NET application state, and then kill that separate app domain.

Answer:

I think the choice of development platform should depend on the features you want to provide and the platforms you plan to support. Personal preference and upgrade schedule should not decide the development platform unless you also want them to decide your potential user/customer base.

Personally, I believe you should develop on Vista, and here is why.

First, IIS7 is finally the release where the development experience on the client OS matches the corresponding server OS. No more hassling over XP Pro and Windows Server 2003 differences in everything related to IIS, from security ACLs, security models, Application isolation between high/medium/low and Application Pools, Web Service Restrictions on CGI and ISAPI, configuration changes, TCP Connection limitations, etc... you get the picture. The same IIS7 server core is on Vista and Windows Server 2008, with the same security model, application isolation, configuration files, etc. Unity at last.

Now, for some more technical reasons. IIS7 has two "Pipeline modes", classic and integrated, that offer completely different behavior/abilities for certain events (authentication being one of them):

Classic mode is supposed to mirror ASP.Net behavior on IIS5x/6.0. With some minor tweaks while reconciling IIS and ASP.Net behavior.
Integrated mode is completely new and represents true managed code extensibility of IIS for the future that mostly matches the native code extensibility of IIS.

I must warn that Classic mode will NEVER match Integrated mode in terms of features and functionality - it exists only for legacy, compatibility reasons. Thus, by definition, the two modes are different.

So, yes, it should be relatively painless to author a Custom Authentication HttpModule in ASP.Net on IIS 5.1 and run it in Classic mode on IIS7. However, that module will likely fail when you switch to Integrated mode, especially for Authentication since it is one of those events whose ordering changes (intentionally, for the better) between Classic and Integrated mode.

In fact, the way you configure that module will be different in IIS7 between the two modes:

In Integrated mode, your simply add a new <module> using the type of your custom auth assembly in <modules>, and optionally add a preCondition to determine if the module should only run on requests involving managed code (i.e. only .aspx, .asmx, etc pages) or all requests (i.e. .html, .xml, .css, .asp, .php, pages).

This is exactly what people tried (in vain) to do with ASP.Net 2.0 on IIS6 but could not, and certainly not with the elegance and compactness of preConditions.

Instead, what one needs to do is the following set of kludges...
In Classic mode, you need configuration that emulates what it took on IIS6 to get similar (but not identical) behavior. This means:
1. *-scriptmap to aspnet_isapi.dll -- this is now a *-<handler> to isapi.dll with aspnet_isapi.dll as the scriptProcessor
2. <httpHandler> for * which derives from DefaultHttpHandler and tweaks some special settings on the HttpContext to cause it to call the HSE_REQ_EXEC_URL ISAPI ServerSupportFunction underneath the covers
3. Order the remaining <httpHandlers> correctly relative to #2 to get reasonable behavior

The astute reader will remind you that I just rushed through a WHOLE lot of details there, which many people have dedicated countless number of hours of pain/frustration/anguish and countless fragments of articles describing how to get an ASP.Net 2.0 Custom Authentication Module to [not] work on IIS 6. And what I just described does not even apply or work on the IIS 5.1 on XP Pro 32bit scenario you just described, unless you intend to only implement Custom Authentication module for ASP.Net pages and static files.

Now, we could have made it easier on the users (but much harder on us) in implementation, but we chose the clean implementation you currently see PRECISELY because it starkly shows how much more elegent Integrated mode is in comparison to classic mode at resolving the issue of managed code extensibility of IIS.

I hope this helps frame the discussion for your future development .

//David