How this module works
This module is, in fact, very simple. The vast majority of the code is hoop jumping and related to the management GUI.
At it's core this module does two things:
- Upon initiation of the module for a site, if HSTS is enabled an event handler is attached to every response just before the headers are sent.
- This event, if attached, checks if the request is secure and, if so, injects the HSTS header as per the HSTS draft specification.
There are some optimisations which minimise the impact on performance. Specifically, the built HSTS header is cached in memory. This leverages the fact that the module is reloaded whenever the configuration is modified.
How to enable HSTS
How to enable HSTS using the web.config
Once the module is installed, if you do not use the IIS Manager, HSTS can be enabled on a per-website basis by adding this to the web.config:
<hsts max-age="31536000" includeSubDomains="true" enabled="true" />
What changes does the installer make? Or, how to manual install.
The HSTS-IIS-Module.dll is registered in the GAC.
The HSTS_schema.xml configuration schema is copied to the inetsvr\config\schema directory.
The module is registered in IIS. In inetsvr\config\applicationHost.config:
The configuration section is registered - in /configuration/configSections the sectionGroup named "system.webServer":
<section name="hsts" overrideModeDefault="Allow"/>
The DLL is registered - in /configuration/location/system.webServer/modules:
<add name="hsts" type="HSTS_IIS_Module.HSTS, HSTS-IIS-Module, Version=184.108.40.206, Culture=neutral, PublicKeyToken=eafe09d4eb48c4e0"/>
The management GUI is registered. In inetsvr\config\administration.config:
Register the manager module - in /configuration/location/modules:
Register the manager module provider dll - in /configuration/moduleProviders:
<add name="hsts" type="HSTS_IIS_Module.Manager.ConfigModuleProvider, HSTS-IIS-Module, Version=220.127.116.11, Culture=neutral, PublicKeyToken=eafe09d4eb48c4e0, processorArchitecture=MSIL"/>
Frequently Asked Questions:
Why build this module?
Whilst it is simple to add a custom header to an IIS site, there is no simple way to add the HSTS header in a way that is compliant with the draft specification (RFC 6797
). Specifically from
An HSTS Host MUST NOT include the STS header field in HTTP responses conveyed over non-secure transport.
An additional driver for such a module is the seriousness of attack vectors such as
. It is hoped that simplicity of installation and configuration will avoid any excuse for not implementing the most effective defence against such attacks.
Why not just use an IIS custom header?
Short answer, you pretty much can and, in fact, this is often the answer on forums and wikis all over the Internet.
However, strictly speaking, this solution does not follow the
HSTS draft specification
as the header will also be injected into non-secure responses. In reality, browsers ignore this header when sent over insecure channels, but this cannot be guaranteed. If a browser mistakenly accepts the header over an insecure
channel, it's effectiveness is undermined. This is probably unlikely, but what is the point of a spec if it isn't followed.
Additionaly, as explained in "Why build this module?", I wanted to make configuring HSTS as simple as possible to encourage it's adoption.
Given this module is installed at the server level, will it impact the performance of sites not using HSTS?
No. When the module is initialised an event handler is only attached to every site request on sites that have HSTS enabled in the configuration.
I have a criticism, an idea, an issue, a request, want to say hello.
Please feel free to contact me:
*Email: hstsiis <a in a circle> shaneargo.net
You should also be able to log issues in the tracker here on CodePlex.
I am running this module in production/test/x86/x64/Server 2K8/Server 2k12/giraffe/anything.
That's not a question. But please tell me. I'd love to hear about it, especially if you are running it on a giraffe.
General questions about HSTS
Couldn't a man in the middle (MITM) simply strip the Strict-Transport-Security header?
Yes, for the first request the browser makes. The purpose of HSTS is to greatly reduce the attack surface, but doesn't completely eliminate the risk. This is the reason that the max-age is recommended to be so long (a year or two).
When the browser first makes a request to a domain, which returns the Strict-Transport-Security header, the browser records the domain in the HSTS list and sets the expiry to the 'max-age' seconds from now. This means that for the next year or two,
that domain is protected from MITM attacks as the browser will refuse to communicate without SSL/TLS.
An example of this would be accessing your internet banking from home on your laptop. Your browser records your banks domain as secure. Now when you are out and about, accessing your internet banking from a coffee shop, you can rest assured that you are protected
from a MITM.
Clearing the browser cache, history etc. does not clear the HSTS list. The list can be managed manually using in-built tools in the browser.
What browsers support HSTS?
As this is an ever changing list, I will not provide a definitive list here. Generally speaking, most modern browsers support it, except Internet Explorer. For information check out the
OWASP wiki page
Here is a feature request to have
HSTS support added to IE