HTTP Hosting Endpoint SNI Configuration
Configure Server Name Indication (SNI) for an HTTP endpoint to support multiple hostnames with different certificates and settings on a single endpoint.
SNI allows you to configure host-specific TLS certificates, protocols, and client certificate requirements based on the hostname requested by the client.
Configuration Path
Section titled “Configuration Path”HAKOM:TSM:Http:Hosting:Endpoints:{EndpointName}:SniConfiguration Structure
Section titled “Configuration Structure”Sni└─ {HostName} ├─ Protocols ├─ SslProtocols ├─ Certificate │ ├─ Path │ ├─ Password │ ├─ Location │ ├─ Store │ ├─ Subject │ └─ AllowInvalid └─ ClientCertificateModeConfiguration Elements
Section titled “Configuration Elements”Each {HostName} element under Sni can specify:
| Element | Type | Default | Required | Description |
|---|---|---|---|---|
{HostName} |
object |
— | ✓ | The fully qualified domain name (FQDN) for which these settings apply (e.g., api.example.com). This becomes the element name. |
Protocols |
enum |
— | HTTP protocols supported for this hostname (see Protocols below). | |
SslProtocols |
enum |
— | TLS/SSL protocols allowed for this hostname (see SSL Protocols below). | |
Certificate |
object |
— | ✓ | The certificate to use for this hostname. See HTTP Hosting Endpoint Certificate Configuration. |
ClientCertificateMode |
enum |
NoCertificate |
Client certificate requirements for this hostname (see Client Certificate Mode below). |
Protocols
Section titled “Protocols”Specify which HTTP protocols this hostname supports.
| Value | Description |
|---|---|
Http1 |
HTTP/1.1 only. |
Http2 |
HTTP/2 only. |
Http3 |
HTTP/3 only (requires HTTPS). |
Http1AndHttp2 |
Both HTTP/1.1 and HTTP/2 (default for HTTPS endpoints). |
Http1AndHttp2AndHttp3 |
HTTP/1.1, HTTP/2, and HTTP/3. |
SSL Protocols
Section titled “SSL Protocols”Specify which TLS/SSL protocol versions are allowed for this hostname.
| Value | Description |
|---|---|
Tls |
TLS 1.0 (not recommended). |
Tls11 |
TLS 1.1 (not recommended). |
Tls12 |
TLS 1.2. |
Tls13 |
TLS 1.3. |
Multiple protocols can be combined using the pipe (|) symbol.
Client Certificate Mode
Section titled “Client Certificate Mode”Configure how this hostname handles client certificates for mutual TLS (mTLS) authentication.
| Value | Description |
|---|---|
NoCertificate |
Client certificates are not used (default). |
AllowCertificate |
Client certificates are accepted but not required. |
RequireCertificate |
Client certificates are required for all connections. |
DelayCertificate |
Client certificate validation is deferred until after the TLS handshake. |
What Is SNI?
Section titled “What Is SNI?”Server Name Indication (SNI) is a TLS extension that allows a server to present different SSL certificates based on the hostname the client is requesting. This enables hosting multiple HTTPS sites on a single IP address and port.
When a client connects, it includes the hostname in the TLS handshake, allowing the server to select the appropriate certificate and configuration for that specific hostname.
Understanding SNI Behavior
Section titled “Understanding SNI Behavior”Hostname Matching
Section titled “Hostname Matching”- SNI hostname matching is case-insensitive
- The hostname must match exactly (wildcards are not supported in the
{HostName}element) - If a client requests a hostname not configured in SNI, the connection will fail
Fallback Behavior
Section titled “Fallback Behavior”If you configure both a default Certificate on the endpoint and SNI-specific certificates:
<EndpointWithFallback> <Url>https://*:443</Url> <Certificate> <!-- Default certificate used when hostname doesn't match any SNI entry --> <Path>C:\certificates\default.pfx</Path> </Certificate> <Sni> <specific.example.com> <Certificate> <Path>C:\certificates\specific.pfx</Path> </Certificate> </specific.example.com> </Sni></EndpointWithFallback>- Clients requesting
specific.example.comuse the SNI-configured certificate - Clients requesting any other hostname use the default certificate
Protocol and SSL Protocol Inheritance
Section titled “Protocol and SSL Protocol Inheritance”If Protocols or SslProtocols are not specified for an SNI hostname, they inherit from the parent endpoint configuration.
Examples
Section titled “Examples”Basic SNI configuration with two hostnames
Section titled “ Basic SNI configuration with two hostnames”Configure an endpoint with different certificates for two domains:
<MultiDomainEndpoint> <Url>https://*:443</Url> <Sni> <api.example.com> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>api.example.com</Subject> </Certificate> </api.example.com> <portal.example.com> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>portal.example.com</Subject> </Certificate> </portal.example.com> </Sni></MultiDomainEndpoint>SNI with different protocol support
Section titled “ SNI with different protocol support”Configure different HTTP protocol support for each hostname:
<VersionedEndpoint> <Url>https://*:443</Url> <Sni> <modern.example.com> <Protocols>Http1AndHttp2AndHttp3</Protocols> <SslProtocols>Tls13</SslProtocols> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>modern.example.com</Subject> </Certificate> </modern.example.com> <legacy.example.com> <Protocols>Http1</Protocols> <SslProtocols>Tls12</SslProtocols> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>legacy.example.com</Subject> </Certificate> </legacy.example.com> </Sni></VersionedEndpoint>SNI with client certificate requirements
Section titled “ SNI with client certificate requirements”Configure different client certificate requirements for different hostnames:
<SecureEndpoint> <Url>https://*:443</Url> <Sni> <api.example.com> <Protocols>Http1AndHttp2</Protocols> <SslProtocols>Tls12|Tls13</SslProtocols> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>api.example.com</Subject> </Certificate> </api.example.com> <admin.example.com> <Protocols>Http1AndHttp2</Protocols> <SslProtocols>Tls13</SslProtocols> <ClientCertificateMode>RequireCertificate</ClientCertificateMode> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>admin.example.com</Subject> </Certificate> </admin.example.com> </Sni></SecureEndpoint>This configuration:
- Allows access to
api.example.comwithout client certificates - Requires client certificates for
admin.example.com - Uses TLS 1.3 only for the admin hostname
- Uses TLS 1.2 or 1.3 for the API hostname
SNI with file-based certificates
Section titled “ SNI with file-based certificates”Configure SNI using certificate files instead of the certificate store:
<FileBasedEndpoint> <Url>https://*:443</Url> <Sni> <dev.example.com> <Protocols>Http1AndHttp2</Protocols> <Certificate> <Path>C:\certificates\dev.example.com.pfx</Path> <Password>dev_password</Password> </Certificate> </dev.example.com> <test.example.com> <Protocols>Http1AndHttp2</Protocols> <Certificate> <Path>C:\certificates\test.example.com.pfx</Path> <Password>test_password</Password> </Certificate> </test.example.com> </Sni></FileBasedEndpoint>Mixed SNI configuration
Section titled “ Mixed SNI configuration”Combine different certificate sources and security settings:
<ComplexEndpoint> <Url>https://*:443</Url> <Sni> <public.example.com> <Protocols>Http1AndHttp2AndHttp3</Protocols> <SslProtocols>Tls12|Tls13</SslProtocols> <Certificate> <Location>LocalMachine</Location> <Store>My</Store> <Subject>public.example.com</Subject> </Certificate> </public.example.com> <internal.example.com> <Protocols>Http1AndHttp2</Protocols> <SslProtocols>Tls13</SslProtocols> <ClientCertificateMode>RequireCertificate</ClientCertificateMode> <Certificate> <Path>C:\certificates\internal.pfx</Path> <Password>internal_password</Password> </Certificate> </internal.example.com> <localhost> <Protocols>Http1AndHttp2</Protocols> <Certificate> <Location>CurrentUser</Location> <Store>My</Store> <Subject>localhost</Subject> <AllowInvalid>true</AllowInvalid> </Certificate> </localhost> </Sni></ComplexEndpoint>This configuration demonstrates:
- Public hostname with HTTP/3 support and certificate store
- Internal hostname requiring client certificates with file-based certificate
- Development localhost with self-signed certificate