IIS Native Module Development
IIS7 Native Module
IIS native modules are a very powerful way to customize your web server. A module can pretty much achieve anything if designed correctly.
Native modules are of two main types: CGlobalModule and CHttpModule. CHttpModule exposes notification entry points in the context of a request execution. e.g., Begin, Authenticate, Execute, Log, End.
CGlobalModule exposes notification entry points when something happens on the server: e.g: Configuration Change, Trace Event, Cache Lookup etc.
The only exception is, CGlobalModule exposes a per-request notification called GL_PRE_BEGIN_REQUEST, which gives the global module a chance to do something before pretty much anything happens on the server.
For all entry points invoked by the CGlobalModule, the return code is either GL_NOTIFICATION_HANDLED or GL_NOTIFICATION_CONTINUE.
If a module returns GL_NOTIFICATION_HANDLED, it means that the module has taken the right action, and IIS should not call into any other modules for that notification. What is not obvious from the statement is that, in the context of a GL_PRE_BEGIN_REEQUEST, the module has to either process or continue, which implies that it cannot do any input-output operations in an asynchronous way.
So, in general, it is not recommended to do Read/Write operations on the request on GL_PRE_BEGIN_REQUEST, even though it is entirely possible.
For all entry points invoked by the CHttpModule, the return code is one of the following:
RQ_NOTIFICATION_FINISHED
RQ_NOTIFICATION_CONTINUE
RQ_NOTIFICATION_PENDING
CONTINUE and FINISHED are similar to the global notification return status. However PENDING is interesting. In order to use the asynchronous model efficiently, understanding the implications of RQ_NOTIFICATION_PENDING is crucial.
When do you return pending?
- You want to do an IO to the client (Read or Write) In this case, the recommended way is to use the asynchronous API calls. The nature of async overloads for the IO functions are as follows.
hr = ReadEntityBody(..., TRUE, .. &fCompletionExpected)
if (FAILED(hr))
{
// handle error
}
if (fCompletionExpected)
{
// the IO is not complete, IIS will invoke OnAsyncCompletion
// when the IO finishes.
// return pending.
return RQ_NOTIFICATION_PENDING;
}
else
{
// IO completed inline, process.
}
Note about the optional BOOL * fCompletionExpected flag: If this argument is passed as NULL, there will always be a call to OnAsyncCompletion() invoked by IIS when the IO completes, on a IIS thread pool thread. Passing a valid BOOL * gives the app a performance boost opportunity by allowing the code to do processing right away without a context switch.*
- You queue up work in your own threadpool, and want to return IIS’s threadpool back to its pool. You would want to notify IIS later that it is ok to continue the request processing:
In this case, you will return RQ_NOTIFICATION_PENDING after queueing up the work to your threadpool. Once your threadpool finishes its work, you will need to tell IIS to continue. To do so, you can use the IHttpContext->IndicateCompletion() or IHttpContext->PostCompletion(). This pattern is commonly used by webengine.dll which is the native module handing ASP.NET application.
This call results in the OnAsyncCompletion entry point to be invoked, at which point, you can either return any of the REQUEST_NOTIFICATION_STATUS, depending on what your internal state looks like for the request.
This pattern is also used when you are doing an outbound network IO (say call to SQL database, or externel REST API) in the context of a request. A good implementation will make these calls asynchronously, and this way, you can return IIS’s thread back to the pool while the asynchronous operation is pending.
Difference between IndicateCompletion and PostCompletion methods of IHttpContext:
The calls behave the same in the sense, both calls will invoke the OnAsyncCompletion callbacks. However, PostCompletion ensures that the callback is invoked on an IIS Threadpool thread, while IndicateCompletion calls the OnAsyncCompletion callback in the same thread which called IndicateCompletion.
Can a module be implemented as both a CGlobalModule and CHttpModule?
Yes.
Importance of doing asynchronous IO.
If the module is intended to run in a server environment, then doing IO in a synchronous fashion is asking for trouble. The main thing folks tend to overlook is that, a client can completely control the rate at which the IO is done from its side. For e.g., if the module is written to read the entity body of a HTTP request(e.g., POST Form Data), then a simple implementation would just call IHttpRequest::ReadEntityBody() with fAsync set to FALSE.
This means that a malicious client can send a POST request, but not send the entity body associated with this. On the server end, we have one thread waiting on incoming data on this connection. If more requests arrive this way, IIS will eventually run out of threads, and the server will be unable to process any more incoming requests, causing a DoS attack.
If the implementation incorporated an asynchronous pattern, by passing the fAsync=TRUE, then there is no thread waiting on the IO data. When any data arrives, IIS will automatically notify the module through the OnAsyncCompletion() method, and the module can then take appropriate action.
In this scenario, all a malicious client can do is make IIS maintain state for many such requests, but at this point, the system has an higher barrier to failure, since the server health is directly correlated to the amount of virtual memory in the machine. Also, this scenario can be easily mitigated by a module like Dynamic IP restriction, which has the capability to track requests from each client.
How to do asynchronous IO?
e.g. This example demonstrates the NegotiateClientCertificate API which on an SSL connection triggers a certificate request on the client side for client certificate based auth. This same pattern can be used for IHttpRequest->ReadEntityBody and IHttpResponse->WriteEntityChunks
REQUEST_NOTIFICATION_STATUS
IIS_MODULE::OnPostBeginRequest(
IHttpContext *pHttpContext,
IHttpEventProvider *pProvider
)
{
HRESULT hr = pHttpContext->GetRequest()->NegotiateClientCertificate(
TRUE,
&fCompletionExpected);
if (FAILED(hr))
{
pHttpContext->GetResponse()->SetStatus(500,
"Internal Server Error",
0,
hr);
pHttpContext->GetResponse()->SetNeedDisconnect();
return RQ_NOTIFICATION_FINISH_REQUEST;
}
if (fCompletionExpected)
{
//
// The call will complete asynchronously, return pending to IIS
// right away.
//
return RQ_NOTIFICATION_PENDING;
}
else
{
return RQ_NOTIFICATION_CONTINUE;
}
}
REQUEST_NOTIFICATION_STATUS
IIS_MODULE::OnAsyncCompletion(
IHttpContext * pHttpContext,
DWORD dwNotification,
BOOL fPostNotification,
IHttpEventProvider * pProvider,
IHttpCompletionInfo * pCompletionInfo
)
{
if (FAILED(pCompletionInfo->GetCompletionStatus()))
{
pHttpContext->GetResponse()->SetStatus(500,
"Internal Server Error",
0,
pCompletionInfo->GetCompletionStatus());
pHttpContext->GetResponse()->SetNeedDisconnect();
return RQ_NOTIFICATION_FINISH_REQUEST;
}
return RQ_NOTIFICATION_CONTINUE;
}
Knowing the difference between a parent request and a child request
Any module in IIS pipeline can create a child request. A child request executes from the beginning, ensuring that all checks are done on this new requst before IIS processes it.
A child request is typically created when a URL is rewritten, since the permissions and settings for the new URL can be different from the original one. Classic examples of when this is used are 1. IIS Default Document module. When a request to “/” is rewritten to say “/index.html”. 1.. UrlRewrite module on inbound rule execution.
If a request is a root request, then IHttpContext()->GetParentContext() returns NULL. If a request is a child request, then this API will return the parent context of the request.
When does the parent/child request relationship matter?
Your module keeps track of requests originating from a client. Child request and parent requests are bound to the same TCP connection. From a client perspective, it is still a single request. So if a module is doing any kind of accounting of requests count/concurrent requests, it is important to count only parent requests, otherwise the number is not going to match what is expected.
An action needs to be taken only once per request:
Quick start template for IIS native module development
class IIS_HTTP_MODULE : public CHttpModule
{
public:
IIS_HTTP_MODULE()
{}
void
Dispose()
/*++
Called on every request completion by IIS.
Since the implementation of GetHttpModule within the
module factory returns a pointer to a singleton which
is used to process all requests, we need to make sure
dispose() doesn't try to delete the object.
--*/
{
}
REQUEST_NOTIFICATION_STATUS
OnBeginRequest(
IHttpContext* pHttpContext,
IHttpEventProvider* pProvider
);
~IIS_HTTP_MODULE()
{}
};
class IIS_HTTP_MODULE_FACTORY : public IHttpModuleFactory
{
public:
HRESULT
GetHttpModule(
CHttpModule** ppModule,
IModuleAllocator* pAllocator
)
{
*ppModule = &_module;
return S_OK;
}
VOID
Terminate()
{
delete this;
}
private:
~IIS_HTTP_MODULE_FACTORY()
{
}
IIS_HTTP_MODULE _module;
};
IHttpServer * g_pServer = NULL;
HRESULT
WINAPI
RegisterModule(
DWORD dwServerVersion,
IHttpModuleRegistrationInfo* pModuleInfo,
IHttpServer* pGlobalInfo
)
/*++
Register Module:
Entry point called by IIS, after a global module (system.webServer/globalModules)
is loaded into memory.
The module should declare the notifications it's interested in
listening on, using a ModuleFactory class.
Make sure that this function is in the export table for the module.
i.e., it should either be defined in the definitions file for the dll, or marked as exportable.
Return HRESULT.
--*/
{
HRESULT hr = S_OK;
//
// Remember the pointer to pGlobalInfo for future use.
// This can be used to get a pointer to the readable instance
// of IIS Configuration system.
//
g_pServer = pGlobalInfo;
//
// Create the Module Factory. The module factory controls the
// creation of the actual module object, to which the request
// notifications are dispatched by the IIS core.
//
IIS_HTTP_MODULE_FACTORY *pFactory = new IIS_HTTP_MODULE_FACTORY();
if ( pFactory == NULL )
{
hr = E_OUTOFMEMORY;
goto Finished;
}
//
// Set the notifications we are interested in listening.
//
hr = pModuleInfo->SetRequestNotifications(pFactory,
RQ_BEGIN_REQUEST,
0 ); // dwPostNotifications
if ( FAILED ( hr ) )
{
goto Finished;
}
pFactory = NULL;
Finished:
if ( pFactory != NULL )
{
pFactory->Terminate();
pFactory = NULL;
}
return hr;
}
REQUEST_NOTIFICATION_STATUS
IIS_HTTP_MODULE::OnBeginRequest(
IHttpContext* pHttpContext,
IHttpEventProvider* pProvider
)
/*++
Routine Description:
Called on IIS on RQ_BEGIN_REQUEST
Return:
REQUEST_NOTIFICATION_STATUS
--*/
{
OutputDebugStringA("IIS_HTTP_MODULE::OnBeginRequest\n");
return RQ_NOTIFICATION_CONTINUE;
}