HTTP API Page ============= By `Lex Li`_ This page shows you how to use Jexus Manager HTTP API page to review IIS/IIS Express HTTPS bindings. Background ---------- You probably wonder how IIS is able to serve HTTPS bindings for web sites, especially when the site bindings map to the same IP:port combination. For example, I have a server with a single IP address (``192.168.1.2``), and it hosts two sites, ``https://lextudio.com`` and ``https://sharpsnmp.com``. The relevant part in ``applicationHost.config`` file looks like below, .. code-block:: xml Where are the certificates? And how does Windows pick up the right certificate? When modern web browsers create an HTTPS connection to a web server like IIS, the initial SSL/TLS handshake packet contains the host name (matching the Host header in future HTTPS requests). This is the so called Server Name Indication (SNI). When Windows receives such a handshake packet, it relies on a few mappings in HTTP API to determine which server certificate to present in handshake response, * Check SNI based mappings first. If any mapping matches the host name in the request, return the certificate in that mapping. * If there is no SNI mapping matched, check IP based mappings. If the destination IP and port number of the request matches a mapping, return the certificate of that mapping. * If no mapping matches at all, this HTTPS connection cannot be created. .. note:: If a web browser does not support SNI, then only IP based mappings is scanned. Examples: All browsers on Windows XP. .. note:: If your Windows/IIS is too old to support SNI, then only IP based mappings is scanned. Examples: Windows Vista/Windows 7/Windows Server 2008/ Windows Server 2008 R2. .. note:: Each SNI site bindings should have a corresponding SNI mapping in HTTP API. Otherwise, there is something wrong. The same does not apply to non-SNI site bindings, as they share the same IP based mapping in HTTP API. So in IIS Manager/Jexus Manager if you changed the certificate bind to such a site binding, remember you in fact changed a mapping that affects multiple site bindings (more than the one you changed). So if you notice a wrong certificate is displayed in web browser when you navigate to a page, time to review the mappings. The quickest way to check the mappings is to use Jexus Manager (more details below). Jexus Manager uses such mappings to display the correct certificate in binding dialog, .. image:: _static/https_binding.png .. important:: All can be done via equivalent ``netsh`` commands if you prefer not to download and use such a visual tool. Ask Google to learn the commands then. IP Based Bindings ----------------- If "Require Server Name Indication" is not checked, then this binding is not SNI enabled. It also means for this binding, the certificate is registered to the IP address + port number (in this example, ``0.0.0.0:44300``). Windows stores the certificate information in a private storage for http.sys to read, which can be queried via ``netsh http show sslcert``. Jexus Manager features a new page to show the list, .. image:: _static/http_api.png It is very clear that the certificate mappings are here. .. image:: _static/https_ip_based.png .. note:: IIS Express creates mappings for ``0.0.0.0:44300``–``0.0.0.0:44399`` during installation, so that non administrators can bind HTTPS sites to such mappings. That's also why Visual Studio uses a default port between 44300 and 44399 for new ASP.NET or ASP.NET Core projects on IIS Express. Due to the limitation of such mappings, we know for a single IP end point, only a single certificate can be registered. That’s why when we attempt to host multiple HTTPS sites on a single IP end point we could only use a wildcard certificate or a UC certificate. .. important:: Equivalent command line is ``netsh http show sslcert``. SNI Based Bindings ------------------ Starting from Windows 8/IIS 8 and above, we can create SNI based in addition to IP based bindings. This allows multiple certificates to be bind to a single IP end point. .. image:: _static/https_sni.png SNI based mapping for certificates is displayed under SNI tab. They are bind to host name + port number instead of IP end point + port number. Such SNI based mappings are automatically created by Jexus Manager when you add SNI based bindings to web sites. They are also removed automatically when such bindings are removed from sites. .. important:: Equivalent command line is ``netsh http show sslcert``. Reserved URLs ------------- Reserved URLs are displayed under Reserved URL tab. .. image:: _static/reserved_urls.png .. note:: Microsoft has more information about reserved URLs `here `_ . Many applications would register their own URL reservations. Typical applications include Microsoft SQL Server Reporting Services. Reservations can conflict with each other, and that can lead to problems like IIS/IIS Express cannot start to monitor certain site bindings. .. note:: When troubleshooting conflicts, reserved URLs only provide partial information. A process running as administrator can hook to Windows HTTP API without any reservation (like a Windows service). .. important:: Equivalent command line is ``netsh http show urlacl``. Related Resources ----------------- - :doc:`/getting-started/install` - :doc:`/getting-started/features` - :doc:`/tutorials/self-signed` - :doc:`/tutorials/inplace-elevation` - :doc:`/tutorials/ssl-diagnostics` - :doc:`/tutorials/binding-diagnostics`