Konfigurace koncových bodů pro webový server ASP.NET Core Kestrel

Článek
11/06/2024

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Kestrel koncové body poskytují infrastrukturu pro naslouchání příchozím požadavkům a jejich směrování do příslušného middlewaru. Kombinace adresy a protokolu definuje koncový bod.

Adresa určuje síťové rozhraní, na které server naslouchá příchozím požadavkům, jako je port TCP.
Protokol určuje komunikaci mezi klientem a serverem, například HTTP/1.1, HTTP/2 nebo HTTP/3.
Koncový bod je možné zabezpečit pomocí schématu https adresy URL nebo UseHttps metody.

Koncové body je možné nakonfigurovat pomocí adres URL, JSON v appsettings.jsona kódu. Tento článek popisuje použití jednotlivých možností ke konfiguraci koncového bodu:

Konfigurace koncových bodů
Konfigurace HTTPS
Konfigurace protokolů HTTP

Výchozí koncový bod

Nové projekty ASP.NET Core jsou nakonfigurované tak, aby se svážely s náhodným portem HTTP mezi 5000–5300 a náhodným portem HTTPS mezi 7000–7300. Vybrané porty se ukládají do vygenerovaného Properties/launchSettings.json souboru a můžou je upravit vývojáři. Soubor launchSetting.json se používá pouze v místním vývoji.

Pokud neexistuje žádná konfigurace koncového bodu, vytvoří Kestrel vazbu na http://localhost:5000.

Konfigurace koncových bodů

Kestrel koncové body naslouchají příchozím připojením. Když se koncový bod vytvoří, musí být nakonfigurovaný s adresou, kterou bude naslouchat. Obvykle se jedná o adresu TCP a číslo portu.

Pro konfiguraci koncových bodů existuje několik možností:

Konfigurace koncových bodů pomocí adres URL
Zadat pouze porty
Konfigurace koncových bodů v appsettings.json
Konfigurace koncových bodů v kódu

Konfigurace koncových bodů pomocí adres URL

V následujících částech se dozvíte, jak nakonfigurovat koncové body pomocí následujících možností:

ASPNETCORE_URLS proměnná prostředí.
--urls argument příkazového řádku.
urls konfigurační klíč hostitele.
UseUrls rozšiřující metoda.
WebApplication.Urls vlastnost.

Formáty adres URL

Adresy URL označují IP nebo hostitelské adresy s porty a protokoly, na které by měl server naslouchat. Port je možné vynechat, pokud se jedná o výchozí hodnotu protokolu (obvykle 80 a 443). Adresy URL můžou být v libovolném z následujících formátů.

Adresa IPv4 s číslem portu
```
http://65.55.39.10:80/
```
0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.
Adresa IPv6 s číslem portu
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.
Hostitel se zástupnými čísly portů
```
http://contoso.com:80/
http://*:80/
```
Cokoli, co se nerozpoznalo jako platná IP adresa nebo localhost se považuje za zástupný znak, který je vázán na všechny adresy IPv4 a IPv6. Někteří lidé rádi používají * nebo + jsou explicitnější. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server.

Příklady reverzního proxy serveru zahrnují IIS, YARP, Nginx a Apache.
Název localhost hostitele s číslem portu nebo IP adresou zpětné smyčky s číslem portu
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

Pomocí oddělovače středníku (;) je možné zadat více předpon adres URL:

http://*:5000;http://localhost:5001;https://hostname:5002

Další informace naleznete v tématu Přepsání konfigurace.

Předpony adresy URL HTTPS

Předpony adresy URL HTTPS je možné použít k definování koncových bodů pouze v případě, že je v konfiguraci koncového bodu HTTPS zadaný výchozí certifikát. Použijte KestrelServerOptions například konfiguraci nebo konfigurační soubor, jak je znázorněno dále v tomto článku.

Další informace najdete v tématu Konfigurace HTTPS.

Zadat pouze porty

Aplikace a kontejnery mají často jenom port pro naslouchání, jako je port 80, bez dalších omezení, jako je hostitel nebo cesta. HTTP_PORTS a HTTPS_PORTS jsou konfigurační klíče, které určují porty naslouchání pro Kestrel servery a servery HTTP.sys. Tyto klíče mohou být zadány jako proměnné prostředí definované s DOTNET_ předponami nebo ASPNETCORE_ zadané přímo prostřednictvím jakéhokoli jiného vstupu konfigurace, například appsettings.json. Každý z nich je seznam hodnot portů oddělený středníkem, jak je znázorněno v následujícím příkladu:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Předchozí příklad je zkratka pro následující konfiguraci, která určuje schéma (HTTP nebo HTTPS) a libovolného hostitele nebo IP adresy.

ASPNETCORE_URLS=http://*:80/;http://*:8080/;https://*:443/;https://*:8081/

Konfigurační klíče HTTP_PORTS a HTTPS_PORTS mají nižší prioritu a jsou přepsány adresami URL nebo hodnotami zadanými přímo v kódu. Certifikáty je stále potřeba nakonfigurovat samostatně prostřednictvím mechaniky specifické pro server pro PROTOKOL HTTPS.

Konfigurace koncových bodů v appsettings.json

Kestrel může načíst koncové body z IConfiguration instance. Ve výchozím nastavení Kestrel se konfigurace načte z oddílu Kestrel a koncové body se konfigurují v Kestrel:Endpoints:

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpEndpoint": {
        "Url": "http://localhost:8080"
      }
    }
  }
}

Předchozí příklad:

Používá appsettings.json se jako zdroj konfigurace. Lze však použít jakýkoli IConfiguration zdroj.
Přidá koncový bod s názvem MyHttpEndpoint na portu 8080.

Další informace o konfiguraci koncových bodů pomocí formátu JSON najdete v dalších částech tohoto článku, které diskutují o konfiguraci protokolu HTTPS a konfiguraci protokolů HTTP v appsettings.json.

Opětovné načtení koncových bodů z konfigurace

Opětovné načtení konfigurace koncového bodu, když je ve výchozím nastavení povolená změna zdroje konfigurace. Lze ho zakázat pomocí KestrelServerOptions.Configure(IConfiguration, Boolean).

Pokud je změna signalována, provede se následující kroky:

Nová konfigurace se porovná se starou konfigurací a žádný koncový bod bez změn konfigurace se nezmění.
Odebrané nebo upravené koncové body mají 5 sekund k dokončení požadavků na zpracování a vypnutí.
Spustí se nové nebo upravené koncové body.

Klienti, kteří se připojují k upravenému koncovému bodu, můžou být při restartování koncového bodu odpojeni nebo odmítnuti.

ConfigurationLoader

KestrelServerOptions.Configure vrátí hodnotu KestrelConfigurationLoader. Metoda zavaděče Endpoint(String, Action<EndpointConfiguration>) , která se dá použít k doplnění nakonfigurovaného nastavení koncového bodu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader lze získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který WebApplicationBuilder.WebHostposkytuje .

Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
KestrelServerOptions.Configure(IConfiguration) lze volat vícekrát, ale pouze poslední konfigurace je použita, pokud Load není explicitně volána u předchozích instancí. Výchozí hostitel nevolá Load , aby se jeho výchozí konfigurační oddíl mohl nahradit.
KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptions Endpoint přetížení, takže koncové body kódu a konfigurace je možné nakonfigurovat na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Konfigurace koncových bodů v kódu

KestrelServerOptions poskytuje metody konfigurace koncových bodů v kódu:

Listen Když se současně použijí rozhraní API useUrls i UseUrls, Listen přepíší UseUrls koncové body koncové body.

Vytvoření vazby k soketu TCP

Metody Listena , ListenLocalhostkteré ListenAnyIP jsou svázané se soketem TCP:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Předchozí příklad:

Konfiguruje koncové body, které naslouchají na portu 5000 a 5001.
Nakonfiguruje HTTPS pro koncový bod pomocí UseHttps metody rozšíření .ListenOptions Další informace najdete v tématu Konfigurace HTTPS v kódu.

Ve Windows je možné vytvořit certifikáty podepsané svým držitelem pomocí rutiny PowerShellu.New-SelfSignedCertificate Nepodporovaný příklad najdete v tématu UpdateIISExpressSSLForChrome.ps1.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Vytvoření vazby k soketu Unix

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

V konfiguračním souboru Nginx nastavte server>proxy_pass>locationpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Konfigurace výchozích hodnot koncového bodu

ConfigureEndpointDefaults(Action<ListenOptions>) určuje konfiguraci, která se spouští pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults několikrát nahrazuje předchozí konfiguraci.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

Dynamická vazba portu

Pokud je zadáno číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel vázaný za běhu:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Dynamická vazba portu není v některých situacích dostupná:

KestrelServerOptions.ListenLocalhost
Vazby PROTOKOLU HTTP/1.1 nebo HTTP/2 založené na protokolu TCP a vzájemně založené na QUIC HTTP/3.

Konfigurace HTTPS

Kestrel podporuje zabezpečení koncových bodů pomocí protokolu HTTPS. Data odesílaná přes PROTOKOL HTTPS se šifrují pomocí protokolu TLS (Transport Layer Security), aby se zvýšilo zabezpečení dat přenášených mezi klientem a serverem.

HTTPS vyžaduje certifikát TLS. Certifikát TLS je uložený na serveru a Kestrel je nakonfigurovaný tak, aby ho používal. Aplikace může používat vývojový certifikát ASP.NET Core HTTPS v místním vývojovém prostředí. Vývojový certifikát není nainstalovaný v prostředích, která nejsou součástí vývoje. V produkčním prostředí musí být certifikát TLS explicitně nakonfigurovaný. Musí se zadat minimálně výchozí certifikát.

Způsob konfigurace protokolu HTTPS a certifikátu TLS závisí na konfiguraci koncových bodů:

Pokud se k definování koncových bodů používají jenom předpony adres URL nebo zadání portů, můžete https použít jenom v případě, že je v konfiguraci koncového bodu HTTPS zadaný výchozí certifikát. Výchozí certifikát lze nakonfigurovat s jednou z následujících možností:
Konfigurace HTTPS v appsettings.json
Konfigurace HTTPS v kódu

Konfigurace HTTPS v appsettings.json

Pro nastavení aplikace HTTPS je k dispozici Kestrelvýchozí schéma konfigurace nastavení aplikace HTTPS . Nakonfigurujte několik koncových bodů, včetně adres URL a certifikátů, které se mají použít, a to buď ze souboru na disku, nebo z úložiště certifikátů.

Jakýkoli koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v rámci Certificates:Default nebo vývojovém certifikátu.

Následující příklad je pro appsettings.json, ale jakýkoli zdroj konfigurace lze použít:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

V předchozím příkladu je heslo certifikátu uloženo ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Poznámky ke schématu

Názvy koncových bodů nerozlišují malá a velká písmena. Například HTTPS a Https jsou ekvivalentní.
Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu. Viz formáty adres URL dříve v tomto článku.
Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls , a ne jejich přidávání. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
Oddíl Certificate je nepovinný. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v Certificates:Default oddílu. Pokud nejsou k dispozici žádné výchozí hodnoty, použije se vývojový certifikát. Pokud neexistují žádné výchozí hodnoty a není k dispozici vývojový certifikát, server vyvolá výjimku a nespustí se.
Tato Certificate část podporuje více zdrojů certifikátů.
Libovolný počet koncových bodů může být definován v Configurationpřípadě, že nezpůsobují konflikty portů.

Zdroje certifikátů

Uzly certifikátů je možné nakonfigurovat tak, aby načítá certifikáty z řady zdrojů:

Path a Password načíst soubory .pfx .
PathKeyPath a Password pro načtení souborů .pem.crt/ a .key.
Subject a Store načíst z úložiště certifikátů.

Certificates:Default Například certifikát lze zadat takto:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

Konfigurace klientských certifikátů v appsettings.json

ClientCertificateMode slouží ke konfiguraci chování klientského certifikátu.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Výchozí hodnota je ClientCertificateMode.NoCertificate, kde Kestrel nevyžaduje nebo nevyžaduje certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Konfigurace protokolů SSL/TLS v appsettings.json

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Výchozí hodnota , SslProtocols.Nonezpůsobí Kestrel použití výchozího operačního systému zvolit nejlepší protokol. Pokud nemáte konkrétní důvod k výběru protokolu, použijte výchozí nastavení.

Konfigurace HTTPS v kódu

Při použití Listen rozhraní API UseHttps je k dispozici metoda ListenOptions rozšíření pro konfiguraci HTTPS.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

ListenOptions.UseHttps parametry:

filename je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
password je heslo potřebné pro přístup k datům certifikátu X.509.
configureOptions je konfigurace Action HttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
subject je název subjektu certifikátu.
allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
location je umístění úložiště, ze které se má certifikát načíst.
serverCertificate je certifikát X.509.

Úplný seznam UseHttps přetížení naleznete v tématu UseHttps.

Konfigurace klientských certifikátů v kódu

ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

Výchozí hodnota je NoCertificate, kde Kestrel nevyžaduje nebo nevyžaduje certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Konfigurace výchozích hodnot HTTPS v kódu

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) určuje konfiguraci Action , která se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults několikrát nahradí předchozí Action instance poslední Action zadanou instancí.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

Konfigurace protokolů SSL/TLS v kódu

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

Konfigurace filtru šifrovacích sad TLS v kódu

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě připojení:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Konfigurace indikace názvu serveru

Indikaci názvu serveru (SNI) lze použít k hostování více domén na stejné IP adrese a portu. SNI lze použít k zachování prostředků obsluhou více lokalit z jednoho serveru.

Aby rozhraní SNI fungovalo, klient odešle název hostitele pro zabezpečenou relaci na server během metody handshake protokolu TLS, aby server mohl poskytnout správný certifikát. Klient používá zařízený certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje za metodou handshake protokolu TLS.

Všechny weby musí běžet ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

SNI je možné nakonfigurovat dvěma způsoby:

Nakonfigurujte mapování mezi názvy hostitelů a možnostmi HTTPS v konfiguraci. Například JSON v appsettings.json souboru.
Vytvořte koncový bod v kódu a vyberte certifikát pomocí názvu hostitele se zpětným voláním ServerCertificateSelector .

Konfigurace SNI v appsettings.json

Kestrel podporuje SNI definované v konfiguraci. Koncový bod lze nakonfigurovat s objektem Sni , který obsahuje mapování mezi názvy hostitelů a možnostmi HTTPS. Název hostitele připojení se shoduje s možnostmi a používá se pro toto připojení.

Následující konfigurace přidá koncový bod s názvem MySniEndpoint SNI k výběru možností HTTPS na základě názvu hostitele:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Možnosti HTTPS, které je možné přepsat pomocí SNI:

Certificate nakonfiguruje zdroj certifikátu.
Protocols nakonfiguruje povolené protokoly HTTP.
SslProtocols nakonfiguruje povolené protokoly SSL.
ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání zástupných znaků:

Přesná shoda. Například a.example.org odpovídá a.example.org.
Předpona zástupných znaků. Pokud existuje více zástupných znaků, vybere se nejdelší vzor. Například *.example.org shody b.example.org a c.example.org.
Plný zástupný znak. * odpovídá všemu jinému, včetně klientů, kteří nepoužívají SNI a neposílají název hostitele.

Odpovídající konfigurace SNI se použije na koncový bod pro připojení a přepisuje hodnoty koncového bodu. Pokud se připojení neshoduje s nakonfigurovaným názvem hostitele SNI, připojení se odmítne.

Konfigurace SNI pomocí kódu

Kestrel podporuje SNI s několika rozhraními API zpětného volání:

ServerCertificateSelector
ServerOptionsSelectionCallback
TlsHandshakeCallbackOptions

SNI s `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI s `ServerOptionsSelectionCallback`

Kestrel podporuje další dynamickou konfiguraci protokolu TLS prostřednictvím zpětného ServerOptionsSelectionCallback volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat odpovídající certifikát a konfiguraci protokolu TLS. Výchozí certifikáty a ConfigureHttpsDefaults nepoužívají se s tímto zpětným voláním.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI s `TlsHandshakeCallbackOptions`

Kestrel podporuje další dynamickou konfiguraci protokolu TLS prostřednictvím zpětného TlsHandshakeCallbackOptions.OnConnection volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát, konfiguraci protokolu TLS a další možnosti serveru. Výchozí certifikáty a ConfigureHttpsDefaults nepoužívají se s tímto zpětným voláním.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

Konfigurace protokolů HTTP

Kestrel podporuje všechny běžně používané verze HTTP. Koncové body je možné nakonfigurovat tak, aby podporovaly různé verze HTTP pomocí výčtu HttpProtocols , který určuje dostupné možnosti verze PROTOKOLU HTTP.

Pro podporu více než jedné verze PROTOKOLU HTTP se vyžaduje protokol TLS. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů.

`HttpProtocols` hodnota	Povolený protokol připojení
`Http1`	Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
`Http2`	Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
`Http3`	Pouze HTTP/3. Vyžaduje protokol TLS. Klient možná bude muset být nakonfigurovaný tak, aby používal pouze HTTP/3.
`Http1AndHttp2`	HTTP/1.1 a HTTP/2. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 a HTTP/3. První požadavek klienta obvykle používá http/1.1 nebo HTTP/2 a `alt-svc` hlavička odpovědi vyzve klienta k upgradu na HTTP/3. PROTOKOL HTTP/2 a HTTP/3 vyžaduje protokol TLS; jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí hodnota protokolu pro koncový bod je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

TLS verze 1.2 nebo novější
Opětovné vyjednávání zakázáno
Komprese je zakázaná
Minimální dočasné velikosti výměny klíčů:
- Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
- Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Konfigurace protokolů HTTP v appsettings.json

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

V oddílu Kestrel:EndpointDefaults je možné nakonfigurovat výchozí protokol. Následující appsettings.json příklad vytvoří http/1.1 jako výchozí připojovací protokol pro všechny koncové body:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Protokoly zadané v hodnotách přepsání kódu nastavených konfigurací.

Konfigurace protokolů HTTP v kódu

ListenOptions.Protocols slouží k určení protokolů pomocí výčtu HttpProtocols .

Následující příklad nakonfiguruje koncový bod pro připojení HTTP/1.1, HTTP/2 a HTTP/3 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Viz také

ASP.NET základní projekty jsou nakonfigurované tak, aby se svážely s náhodným portem HTTP mezi 5000–5300 a náhodným portem HTTPS mezi 7000–7300. Tato výchozí konfigurace je určena vygenerovaném Properties/launchSettings.json souboru a lze ji přepsat. Pokud nejsou zadány žádné porty, Kestrel vytvoří vazby na http://localhost:5000.

Zadejte adresy URL pomocí:

ASPNETCORE_URLS proměnná prostředí.
--urls argument příkazového řádku.
urls konfigurační klíč hostitele.
UseUrls rozšiřující metoda.

Hodnota zadaná pomocí těchto přístupů může být jeden nebo více koncových bodů HTTP a HTTPS (pokud je k dispozici výchozí certifikát). Nakonfigurujte hodnotu jako seznam oddělený středníkem (například "Urls": "http://localhost:8000;http://localhost:8001").

Další informace o těchtopřístupch

Vytvoří se vývojový certifikát:

Při instalaci sady .NET SDK.
Nástroj dev-certs slouží k vytvoření certifikátu.

Vývojový certifikát je k dispozici pouze pro uživatele, který certifikát vygeneruje. Některé prohlížeče vyžadují udělení explicitního oprávnění k důvěryhodnosti místního vývojového certifikátu.

Šablony projektů konfigurují aplikace pro spouštění na HTTPS ve výchozím nastavení a zahrnují podporu přesměrování HTTPS a HSTS.

Volání Listen nebo ListenUnixSocket metody KestrelServerOptions konfigurace předpon adres URL a portů pro Kestrel.

UseUrls--urls, argument příkazového řádku, urls konfigurační klíč hostitele a ASPNETCORE_URLS proměnná prostředí také fungují, ale mají omezení, která jsou uvedena dále v této části (pro konfiguraci koncového bodu HTTPS musí být dostupný výchozí certifikát).

KestrelServerOptions konfigurace:

KonfiguraceDefaultsEndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>) určuje konfiguraci Action , která se má spustit pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults několikrát nahradí předchozí Actions posledním Action zadaným kódem:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

Configure(IConfiguration)

Kestrel Umožňuje načíst koncové body z objektu IConfiguration. Konfigurace musí být vymezena na oddíl konfigurace pro Kestrel. Přetížení Configure(IConfiguration, bool) lze použít k povolení opětovného načtení koncových bodů při změně zdroje konfigurace.

Ve výchozím nastavení Kestrel se konfigurace načte z oddílu Kestrel a změny se znovu načtou:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Pokud je povolená konfigurace opětovného načítání a je signalována změna, je třeba provést následující kroky:

Nová konfigurace se porovná se starou konfigurací, žádný koncový bod bez změn konfigurace se nezmění.
Odebrané nebo upravené koncové body mají 5 sekund k dokončení požadavků na zpracování a vypnutí.
Spustí se nové nebo upravené koncové body.

Klienti, kteří se připojují k upravenému koncovému bodu, můžou být při restartování koncového bodu odpojeni nebo odmítnuti.

KonfiguraceHttpsDefaults

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

ListenOptions.UseHttps

Nakonfigurujte Kestrel použití PROTOKOLU HTTPS.

ListenOptions.UseHttps rozšíření:

UseHttps: Nakonfigurujte Kestrel použití protokolu HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurovaný žádný výchozí certifikát.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps parametry:

filename je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
password je heslo potřebné pro přístup k datům certifikátu X.509.
configureOptions je konfigurace Action HttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
subject je název subjektu certifikátu.
allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
location je umístění úložiště, ze které se má certifikát načíst.
serverCertificate je certifikát X.509.

V produkčním prostředí musí být https explicitně nakonfigurované. Musí se zadat minimálně výchozí certifikát.

Pokud se certifikáty čtou z disku, na rozdíl od úložiště certifikátů systému Windows, musí mít adresář obsahující příslušná oprávnění, aby se zabránilo neoprávněnému přístupu.

Podporované konfigurace popsané dále:

Bez konfigurace
Nahrazení výchozího certifikátu z konfigurace
Změna výchozích hodnot v kódu

Bez konfigurace

Kestrel naslouchá na http://localhost:5000.

Nahrazení výchozího certifikátu z konfigurace

V následujícím appsettings.json příkladu:

Nastavte AllowInvalid na true povolení použití neplatných certifikátů (například certifikátů podepsaných svým držitelem).
Jakýkoli koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v rámci Certificates:Default nebo vývojovém certifikátu.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

V předchozím příkladu jsou hesla certifikátů uložena ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo každého certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Poznámky ke schématu:

Názvy koncových bodů nerozlišují malá a velká písmena. Například HTTPS a Https jsou ekvivalentní.
Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu.
Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls , a ne přidají do nich. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
Oddíl Certificate je nepovinný. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v Certificates:Default oddílu. Pokud nejsou k dispozici žádné výchozí hodnoty, použije se vývojový certifikát. Pokud neexistují žádné výchozí hodnoty a není k dispozici vývojový certifikát, server vyvolá výjimku a nespustí se.
Tato Certificate část podporuje více zdrojů certifikátů.
Libovolný počet koncových bodů může být definován v konfiguraci , pokud nezpůsobí konflikty portů.

Zdroje certifikátů

Uzly certifikátů je možné nakonfigurovat tak, aby načítá certifikáty z řady zdrojů:

Path a Password načíst soubory .pfx .
PathKeyPath a Password pro načtení souborů .pem.crt/ a .key.
Subject a Store načíst z úložiště certifikátů.

Certificates:Default Například certifikát lze zadat takto:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

Configure(IConfiguration)KestrelConfigurationLoader vrátí metoduEndpoint(String, Action<EndpointConfiguration>), která se dá použít k doplnění nakonfigurovaného nastavení koncového bodu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader lze získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který WebApplicationBuilder.WebHostposkytuje .

Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
Více konfigurací může být načteno opětovným voláním Configure(IConfiguration) s jinou částí. Použije se pouze poslední konfigurace, pokud Load není explicitně volána u předchozích instancí. Metabalíc nevolá Load , aby se mohl nahradit výchozí konfigurační oddíl.
KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptions Endpoint přetížení, takže je možné nakonfigurovat koncové body kódu a konfigurace na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Změna výchozích hodnot v kódu

ConfigureEndpointDefaultsa ConfigureHttpsDefaults lze ho použít ke změně výchozího nastavení a HttpsConnectionAdapterOptionsListenOptions , včetně přepsání výchozího certifikátu zadaného v předchozím scénáři. ConfigureEndpointDefaults a ConfigureHttpsDefaults měly by se volat před konfigurací všech koncových bodů.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Konfigurace koncových bodů pomocí indikací názvu serveru

Indikaci názvu serveru (SNI) lze použít k hostování více domén na stejné IP adrese a portu. Aby rozhraní SNI fungovalo, klient odešle název hostitele pro zabezpečenou relaci na server během metody handshake protokolu TLS, aby server mohl poskytnout správný certifikát. Klient používá zařízený certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje za metodou handshake protokolu TLS.

SNI je možné nakonfigurovat dvěma způsoby:

Vytvořte koncový bod v kódu a vyberte certifikát pomocí názvu hostitele se zpětným voláním ServerCertificateSelector .
Nakonfigurujte mapování mezi názvy hostitelů a možnostmi HTTPS v konfiguraci. Například JSON v appsettings.json souboru.

SNI s `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI s `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI s `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI v konfiguraci

Následující konfigurace přidá koncový bod s názvem MySniEndpoint SNI k výběru možností HTTPS na základě názvu hostitele:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Možnosti HTTPS, které je možné přepsat pomocí SNI:

Certificate nakonfiguruje zdroj certifikátu.
Protocols nakonfiguruje povolené protokoly HTTP.
SslProtocols nakonfiguruje povolené protokoly SSL.
ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání zástupných znaků:

Přesná shoda. Například a.example.org odpovídá a.example.org.
Předpona zástupných znaků. Pokud existuje více zástupných znaků, vybere se nejdelší vzor. Například *.example.org shody b.example.org a c.example.org.
Plný zástupný znak. * odpovídá všemu jinému, včetně klientů, kteří nepoužívají SNI a neposílají název hostitele.

Požadavky na SNI

Všechny weby musí běžet ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

Protokoly SSL/TLS

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Klientské certifikáty

ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Výchozí hodnota je ClientCertificateMode.NoCertificate místo, kde Kestrel nebude požadovat nebo vyžadovat certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Protokolování připojení

Volání UseConnectionLogging pro generování protokolů na úrovni ladění pro komunikaci na úrovni bajtů v připojení. Protokolování připojení je užitečné při řešení problémů při komunikaci nízké úrovně, například při šifrování TLS a za proxy servery. Pokud UseConnectionLogging je před umístěním UseHttps, zašifrovaný provoz se zaprotokoluje. Pokud UseConnectionLogging je umístěn po UseHttps, dešifrovaný provoz se zaprotokoluje. Toto je integrovaný middleware připojení.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Vytvoření vazby k soketu TCP

Metoda Listen vytvoří vazbu na soket TCP a možnost lambda umožňuje konfiguraci certifikátu X.509:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Příklad nakonfiguruje HTTPS pro koncový bod s ListenOptions. Ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body použijte stejné rozhraní API.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Vytvoření vazby k soketu Unix

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

V konfiguračním souboru Nginx nastavte server>proxy_pass>locationpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Port 0

Pokud je zadané číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel vázaný za běhu:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Dynamická vazba portu není v některých situacích dostupná:

ListenLocalhost
Vazby PROTOKOLU HTTP/1.1 nebo HTTP/2 založené na protokolu TCP a vzájemně založené na QUIC HTTP/3.

Omezení

Nakonfigurujte koncové body pomocí následujících přístupů:

UseUrls
--urls Argument příkazového řádku
urls konfigurační klíč hostitele
ASPNETCORE_URLS proměnná prostředí

Tyto metody jsou užitečné pro práci s kódem s jinými servery než Kestrel. Mějte však na paměti následující omezení:

Https se s těmito přístupy nedá použít, pokud není v konfiguraci koncového bodu HTTPS k dispozici výchozí certifikát (například použití KestrelServerOptions konfigurace nebo konfiguračního souboru, jak je znázorněno výše v tomto článku).
Listen UseUrls Když se současně používají oba přístupy, Listen koncové body přepíší UseUrls koncové body.

Konfigurace koncového bodu služby IIS

Při použití služby IIS jsou vazby adresy URL pro vazby přepsání služby IIS nastaveny buď Listen nebo UseUrls. Další informace najdete v tématu ASP.NET Core Module.

ListenOptions.Protocols

Vlastnost Protocols vytvoří protokoly HTTP (HttpProtocols) povolené v koncovém bodu připojení nebo pro server. Přiřaďte hodnotu vlastnosti Protocols z výčtu HttpProtocols .

`HttpProtocols` enum value	Povolený protokol připojení
`Http1`	Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
`Http2`	Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
`Http3`	Pouze HTTP/3. Vyžaduje protokol TLS. Klient možná bude muset být nakonfigurovaný tak, aby používal pouze HTTP/3.
`Http1AndHttp2`	HTTP/1.1 a HTTP/2. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 a HTTP/3. První požadavek klienta obvykle používá http/1.1 nebo HTTP/2 a `alt-svc` hlavička odpovědi vyzve klienta k upgradu na HTTP/3. PROTOKOL HTTP/2 a HTTP/3 vyžaduje protokol TLS; jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota každého koncového bodu je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

TLS verze 1.2 nebo novější
Opětovné vyjednávání zakázáno
Komprese je zakázaná
Minimální dočasné velikosti výměny klíčů:
- Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
- Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Následující příklad umožňuje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě připojení:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware připojení

Middleware vlastního připojení může v případě potřeby filtrovat metody handshake protokolu TLS na základě připojení pro konkrétní šifry.

Následující příklad vyvolá NotSupportedException jakýkoli algoritmus šifry, který aplikace nepodporuje. Případně definujte a porovnejte ITlsHandshakeFeature.CipherAlgorithm seznam přijatelných šifrovacích sad.

U šifrovacího CipherAlgorithmType.Null algoritmu se nepoužívá žádné šifrování.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Nastavení protokolu HTTP z konfigurace

Ve výchozím nastavení Kestrel se konfigurace načte z oddílu Kestrel . Následující appsettings.json příklad vytvoří http/1.1 jako výchozí připojovací protokol pro všechny koncové body:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokoly zadané v hodnotách přepsání kódu nastavených konfigurací.

Předpony adres URL

Při použití UseUrlsargumentu --urls příkazového řádku, urls konfiguračního klíče hostitele nebo ASPNETCORE_URLS proměnné prostředí můžou být předpony adresy URL v libovolném z následujících formátů.

Platné jsou pouze předpony adresy URL HTTP. Kestrel nepodporuje HTTPS při konfiguraci vazeb adres URL pomocí UseUrls.

Adresa IPv4 s číslem portu
```
http://65.55.39.10:80/
```
0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.
Adresa IPv6 s číslem portu
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.
Název hostitele s číslem portu
```
http://contoso.com:80/
http://*:80/
```
Názvy hostitelů a *+, nejsou zvláštní. Nic se nerozpoznalo jako platná IP adresa nebo localhost vazba na všechny IP adresy IPv4 a IPv6. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server. Příklady reverzního proxy serveru zahrnují službu IIS, Nginx nebo Apache.

Upozorňující

Hostování v konfiguraci reverzního proxy serveru vyžaduje filtrování hostitele.
Název hostitele localhost s číslem portu nebo IP adresou zpětné smyčky s číslem portu
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

http://localhost:5000
https://localhost:5001 (pokud je k dispozici místní vývojový certifikát)

Zadejte adresy URL pomocí:

ASPNETCORE_URLS proměnná prostředí.
--urls argument příkazového řádku.
urls konfigurační klíč hostitele.
UseUrls rozšiřující metoda.

Další informace o těchtopřístupch

Vytvoří se vývojový certifikát:

Při instalaci sady .NET SDK.
Nástroj dev-certs slouží k vytvoření certifikátu.

Šablony projektů konfigurují aplikace pro spouštění na HTTPS ve výchozím nastavení a zahrnují podporu přesměrování HTTPS a HSTS.

Volání Listen nebo ListenUnixSocket metody KestrelServerOptions konfigurace předpon adres URL a portů pro Kestrel.

KestrelServerOptions konfigurace:

KonfiguraceDefaultsEndpointDefaults

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

Configure(IConfiguration)

Ve výchozím nastavení Kestrel se konfigurace načte z oddílu Kestrel a změny se znovu načtou:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Pokud je povolená konfigurace opětovného načítání a je signalována změna, je třeba provést následující kroky:

Nová konfigurace se porovná se starou konfigurací, žádný koncový bod bez změn konfigurace se nezmění.
Odebrané nebo upravené koncové body mají 5 sekund k dokončení požadavků na zpracování a vypnutí.
Spustí se nové nebo upravené koncové body.

Klienti, kteří se připojují k upravenému koncovému bodu, můžou být při restartování koncového bodu odpojeni nebo odmítnuti.

KonfiguraceHttpsDefaults

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

ListenOptions.UseHttps

Nakonfigurujte Kestrel použití PROTOKOLU HTTPS.

ListenOptions.UseHttps rozšíření:

UseHttps: Nakonfigurujte Kestrel použití protokolu HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurovaný žádný výchozí certifikát.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps parametry:

filename je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
password je heslo potřebné pro přístup k datům certifikátu X.509.
configureOptions je konfigurace Action HttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
subject je název subjektu certifikátu.
allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
location je umístění úložiště, ze které se má certifikát načíst.
serverCertificate je certifikát X.509.

V produkčním prostředí musí být https explicitně nakonfigurované. Musí se zadat minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

Bez konfigurace
Nahrazení výchozího certifikátu z konfigurace
Změna výchozích hodnot v kódu

Bez konfigurace

Kestrel naslouchá a http://localhost:5000 https://localhost:5001 (pokud je k dispozici výchozí certifikát).

Nahrazení výchozího certifikátu z konfigurace

V následujícím appsettings.json příkladu:

Nastavte AllowInvalid na true povolení použití neplatných certifikátů (například certifikátů podepsaných svým držitelem).
Jakýkoli koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v rámci Certificates:Default nebo vývojovém certifikátu.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Poznámky ke schématu:

Názvy koncových bodů nerozlišují malá a velká písmena. Například HTTPS a Https jsou ekvivalentní.
Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu.
Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls , a ne přidají do nich. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
Oddíl Certificate je nepovinný. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v Certificates:Default oddílu. Pokud nejsou k dispozici žádné výchozí hodnoty, použije se vývojový certifikát. Pokud neexistují žádné výchozí hodnoty a není k dispozici vývojový certifikát, server vyvolá výjimku a nespustí se.
Tato Certificate část podporuje více zdrojů certifikátů.
Libovolný počet koncových bodů může být definován v konfiguraci , pokud nezpůsobí konflikty portů.

Zdroje certifikátů

Uzly certifikátů je možné nakonfigurovat tak, aby načítá certifikáty z řady zdrojů:

Path a Password načíst soubory .pfx .
PathKeyPath a Password pro načtení souborů .pem.crt/ a .key.
Subject a Store načíst z úložiště certifikátů.

Certificates:Default Například certifikát lze zadat takto:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

Configure(IConfiguration)KestrelConfigurationLoader vrátí metoduEndpoint(String, Action<EndpointConfiguration>), která se dá použít k doplnění nakonfigurovaného nastavení koncového bodu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader lze získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který WebApplicationBuilder.WebHostposkytuje .

Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
Více konfigurací může být načteno opětovným voláním Configure(IConfiguration) s jinou částí. Použije se pouze poslední konfigurace, pokud Load není explicitně volána u předchozích instancí. Metabalíc nevolá Load , aby se mohl nahradit výchozí konfigurační oddíl.
KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptions Endpoint přetížení, takže je možné nakonfigurovat koncové body kódu a konfigurace na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Změna výchozích hodnot v kódu

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Konfigurace koncových bodů pomocí indikací názvu serveru

SNI je možné nakonfigurovat dvěma způsoby:

Vytvořte koncový bod v kódu a vyberte certifikát pomocí názvu hostitele se zpětným voláním ServerCertificateSelector .
Nakonfigurujte mapování mezi názvy hostitelů a možnostmi HTTPS v konfiguraci. Například JSON v appsettings.json souboru.

SNI s `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI s `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI s `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI v konfiguraci

Následující konfigurace přidá koncový bod s názvem MySniEndpoint SNI k výběru možností HTTPS na základě názvu hostitele:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Možnosti HTTPS, které je možné přepsat pomocí SNI:

Certificate nakonfiguruje zdroj certifikátu.
Protocols nakonfiguruje povolené protokoly HTTP.
SslProtocols nakonfiguruje povolené protokoly SSL.
ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání zástupných znaků:

Přesná shoda. Například a.example.org odpovídá a.example.org.
Předpona zástupných znaků. Pokud existuje více zástupných znaků, vybere se nejdelší vzor. Například *.example.org shody b.example.org a c.example.org.
Plný zástupný znak. * odpovídá všemu jinému, včetně klientů, kteří nepoužívají SNI a neposílají název hostitele.

Požadavky na SNI

Všechny weby musí běžet ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

Protokoly SSL/TLS

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Klientské certifikáty

ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Výchozí hodnota je ClientCertificateMode.NoCertificate místo, kde Kestrel nebude požadovat nebo vyžadovat certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Protokolování připojení

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Vytvoření vazby k soketu TCP

Metoda Listen vytvoří vazbu na soket TCP a možnost lambda umožňuje konfiguraci certifikátu X.509:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Příklad nakonfiguruje HTTPS pro koncový bod s ListenOptions. Ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body použijte stejné rozhraní API.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Vytvoření vazby k soketu Unix

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

V konfiguračním souboru Nginx nastavte server>proxy_pass>locationpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Port 0

Pokud je zadané číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel vázaný za běhu:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Omezení

Nakonfigurujte koncové body pomocí následujících přístupů:

UseUrls
--urls Argument příkazového řádku
urls konfigurační klíč hostitele
ASPNETCORE_URLS proměnná prostředí

Tyto metody jsou užitečné pro práci s kódem s jinými servery než Kestrel. Mějte však na paměti následující omezení:

Https se s těmito přístupy nedá použít, pokud není v konfiguraci koncového bodu HTTPS k dispozici výchozí certifikát (například použití KestrelServerOptions konfigurace nebo konfiguračního souboru, jak je znázorněno výše v tomto článku).
Listen UseUrls Když se současně používají oba přístupy, Listen koncové body přepíší UseUrls koncové body.

Konfigurace koncového bodu služby IIS

Při použití služby IIS jsou vazby adresy URL pro vazby přepsání služby IIS nastaveny buď Listen nebo UseUrls. Další informace najdete v tématu ASP.NET Core Module.

ListenOptions.Protocols

Vlastnost Protocols vytvoří protokoly HTTP (HttpProtocols) povolené v koncovém bodu připojení nebo pro server. Přiřaďte hodnotu vlastnosti Protocols z výčtu HttpProtocols .

`HttpProtocols` enum value	Povolený protokol připojení
`Http1`	Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
`Http2`	Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
`Http1AndHttp2`	HTTP/1.1 a HTTP/2. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota každého koncového bodu je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

TLS verze 1.2 nebo novější
Opětovné vyjednávání zakázáno
Komprese je zakázaná
Minimální dočasné velikosti výměny klíčů:
- Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
- Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Následující příklad umožňuje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě připojení:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware připojení

Middleware vlastního připojení může v případě potřeby filtrovat metody handshake protokolu TLS na základě připojení pro konkrétní šifry.

U šifrovacího CipherAlgorithmType.Null algoritmu se nepoužívá žádné šifrování.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Nastavení protokolu HTTP z konfigurace

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokoly zadané v hodnotách přepsání kódu nastavených konfigurací.

Předpony adres URL

Platné jsou pouze předpony adresy URL HTTP. Kestrel nepodporuje HTTPS při konfiguraci vazeb adres URL pomocí UseUrls.

Adresa IPv4 s číslem portu
```
http://65.55.39.10:80/
```
0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.
Adresa IPv6 s číslem portu
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.
Název hostitele s číslem portu
```
http://contoso.com:80/
http://*:80/
```
Názvy hostitelů a *+, nejsou zvláštní. Nic se nerozpoznalo jako platná IP adresa nebo localhost vazba na všechny IP adresy IPv4 a IPv6. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server. Příklady reverzního proxy serveru zahrnují službu IIS, Nginx nebo Apache.

Upozorňující

Hostování v konfiguraci reverzního proxy serveru vyžaduje filtrování hostitele.
Název hostitele localhost s číslem portu nebo IP adresou zpětné smyčky s číslem portu
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

Ve výchozím nastavení ASP.NET Core vytvoří vazbu na:

http://localhost:5000
https://localhost:5001 (pokud je k dispozici místní vývojový certifikát)

Zadejte adresy URL pomocí:

ASPNETCORE_URLS proměnná prostředí.
--urls argument příkazového řádku.
urls konfigurační klíč hostitele.
UseUrls rozšiřující metoda.

Další informace o těchtopřístupch

Vytvoří se vývojový certifikát:

Při instalaci sady .NET SDK.
Nástroj dev-certs slouží k vytvoření certifikátu.

Některé prohlížeče vyžadují udělení explicitního oprávnění k důvěryhodnosti místního vývojového certifikátu.

Šablony projektů konfigurují aplikace pro spouštění na HTTPS ve výchozím nastavení a zahrnují podporu přesměrování HTTPS a HSTS.

Volání Listen nebo ListenUnixSocket metody KestrelServerOptions konfigurace předpon adres URL a portů pro Kestrel.

KestrelServerOptions konfigurace:

KonfiguraceDefaultsEndpointDefaults

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

Configure(IConfiguration)

Kestrel Umožňuje načíst koncové body z objektu IConfiguration. Konfigurace musí být vymezena na oddíl konfigurace pro Kestrel.

Přetížení Configure(IConfiguration, bool) lze použít k povolení opětovného načtení koncových bodů při změně zdroje konfigurace.

IHostBuilder.ConfigureWebHostDefaults volání Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) ve výchozím nastavení pro načtení Kestrel konfigurace a povolení opětovného načtení.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Pokud je povolená konfigurace opětovného načítání a je signalována změna, je třeba provést následující kroky:

Nová konfigurace se porovná se starou konfigurací, žádný koncový bod bez změn konfigurace se nezmění.
Odebrané nebo upravené koncové body mají 5 sekund k dokončení požadavků na zpracování a vypnutí.
Spustí se nové nebo upravené koncové body.

Klienti, kteří se připojují k upravenému koncovému bodu, můžou být při restartování koncového bodu odpojeni nebo odmítnuti.

KonfiguraceHttpsDefaults

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

Poznámka:

Koncové body vytvořené voláním Listen před voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

ListenOptions.UseHttps

Nakonfigurujte Kestrel použití PROTOKOLU HTTPS.

ListenOptions.UseHttps rozšíření:

UseHttps: Nakonfigurujte Kestrel použití protokolu HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurovaný žádný výchozí certifikát.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps parametry:

filename je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
password je heslo potřebné pro přístup k datům certifikátu X.509.
configureOptions je konfigurace Action HttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
subject je název subjektu certifikátu.
allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
location je umístění úložiště, ze které se má certifikát načíst.
serverCertificate je certifikát X.509.

V produkčním prostředí musí být https explicitně nakonfigurované. Musí se zadat minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

Bez konfigurace
Nahrazení výchozího certifikátu z konfigurace
Změna výchozích hodnot v kódu

Bez konfigurace

Kestrel naslouchá a http://localhost:5000 https://localhost:5001 (pokud je k dispozici výchozí certifikát).

Nahrazení výchozího certifikátu z konfigurace

V následujícím appsettings.json příkladu:

Nastavte AllowInvalid na true povolení použití neplatných certifikátů (například certifikátů podepsaných svým držitelem).
Jakýkoli koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v rámci Certificates:Default nebo vývojovém certifikátu.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Poznámky ke schématu:

Názvy koncových bodů nerozlišují malá a velká písmena. Například HTTPS a Https jsou ekvivalentní.
Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu.
Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls , a ne přidají do nich. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
Oddíl Certificate je nepovinný. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v Certificates:Default oddílu. Pokud nejsou k dispozici žádné výchozí hodnoty, použije se vývojový certifikát. Pokud neexistují žádné výchozí hodnoty a není k dispozici vývojový certifikát, server vyvolá výjimku a nespustí se.
Tato Certificate část podporuje více zdrojů certifikátů.
Libovolný počet koncových bodů může být definován v konfiguraci , pokud nezpůsobí konflikty portů.

Zdroje certifikátů

Uzly certifikátů je možné nakonfigurovat tak, aby načítá certifikáty z řady zdrojů:

Path a Password načíst soubory .pfx .
PathKeyPath a Password pro načtení souborů .pem.crt/ a .key.
Subject a Store načíst z úložiště certifikátů.

Certificates:Default Například certifikát lze zadat takto:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

options.Configure(context.Configuration.GetSection("{SECTION}"))KestrelConfigurationLoader vrátí metodu.Endpoint(string name, listenOptions => { }), která se dá použít k doplnění nakonfigurovaného nastavení koncového bodu:

webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader lze získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který CreateDefaultBuilderposkytuje .

Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
Více konfigurací může být načteno opětovným voláním options.Configure(context.Configuration.GetSection("{SECTION}")) s jinou částí. Použije se pouze poslední konfigurace, pokud Load není explicitně volána u předchozích instancí. Metabalíc nevolá Load , aby se mohl nahradit výchozí konfigurační oddíl.
KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptions Endpoint přetížení, takže je možné nakonfigurovat koncové body kódu a konfigurace na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Změna výchozích hodnot v kódu

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Konfigurace koncových bodů pomocí indikací názvu serveru

SNI je možné nakonfigurovat dvěma způsoby:

Vytvořte koncový bod v kódu a vyberte certifikát pomocí názvu hostitele se zpětným voláním ServerCertificateSelector .
Nakonfigurujte mapování mezi názvy hostitelů a možnostmi HTTPS v konfiguraci. Například JSON v appsettings.json souboru.

SNI s `ServerCertificateSelector`

Kestrel podporuje SNI prostřednictvím zpětného ServerCertificateSelector volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát. Následující kód zpětného volání lze použít ve ConfigureWebHostDefaults volání metody souboru projektu Program.cs :

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(StringComparer.OrdinalIgnoreCase)
            {
                { "localhost", localhostCert },
                { "example.com", exampleCert },
                { "sub.example.com", subExampleCert },
            };            

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI s `ServerOptionsSelectionCallback`

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost", StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                    {
                        ServerCertificate = localhostCert,
                        // Different TLS requirements for this host
                        ClientCertificateRequired = true,
                    });
                }

                return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                {
                    ServerCertificate = exampleCert,
                });
            }, state: null);
        });
    });
});

SNI v konfiguraci

Následující konfigurace přidá koncový bod s názvem MySniEndpoint SNI k výběru možností HTTPS na základě názvu hostitele:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Upozorňující

Možnosti HTTPS, které je možné přepsat pomocí SNI:

Certificate nakonfiguruje zdroj certifikátu.
Protocols nakonfiguruje povolené protokoly HTTP.
SslProtocols nakonfiguruje povolené protokoly SSL.
ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání zástupných znaků:

Přesná shoda. Například a.example.org odpovídá a.example.org.
Předpona zástupných znaků. Pokud existuje více zástupných znaků, vybere se nejdelší vzor. Například *.example.org shody b.example.org a c.example.org.
Plný zástupný znak. * odpovídá všemu jinému, včetně klientů, kteří nepoužívají SNI a neposílají název hostitele.

Požadavky na SNI

Běží v cílovém rozhraní netcoreapp2.1 nebo novějším. Při net461 nebo novějším je vyvoláno zpětné volání, ale name je vždy null. To name platí také null v případě, že klient nezadá parametr názvu hostitele v metodě handshake protokolu TLS.
Všechny weby běží ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

Protokoly SSL/TLS

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Klientské certifikáty

ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Upozorňující

Výchozí hodnota je ClientCertificateMode.NoCertificate místo, kde Kestrel nebude požadovat nebo vyžadovat certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Protokolování připojení

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Vytvoření vazby k soketu TCP

Metoda Listen vytvoří vazbu na soket TCP a možnost lambda umožňuje konfiguraci certifikátu X.509:

public static void Main(string[] args)
{
    CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

Příklad nakonfiguruje HTTPS pro koncový bod s ListenOptions. Ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body použijte stejné rozhraní API.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Vytvoření vazby k soketu Unix

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})

V konfiguračním souboru Nginx nastavte server>proxy_pass>locationpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Port 0

Pokud je zadané číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel vázaný za běhu:

public void Configure(IApplicationBuilder app)
{
    var serverAddressesFeature =
        app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync("<p>Request URL: " +
            $"{context.Request.GetDisplayUrl()}<p>");
    });
}

Když je aplikace spuštěná, výstup okna konzoly označuje dynamický port, na kterém je možné aplikaci dosáhnout:

Listening on the following addresses: http://127.0.0.1:48508

Omezení

Nakonfigurujte koncové body pomocí následujících přístupů:

UseUrls
--urls Argument příkazového řádku
urls konfigurační klíč hostitele
ASPNETCORE_URLS proměnná prostředí

Tyto metody jsou užitečné pro práci s kódem s jinými servery než Kestrel. Mějte však na paměti následující omezení:

Https se s těmito přístupy nedá použít, pokud není v konfiguraci koncového bodu HTTPS k dispozici výchozí certifikát (například použití KestrelServerOptions konfigurace nebo konfiguračního souboru, jak je znázorněno výše v tomto článku).
Listen UseUrls Když se současně používají oba přístupy, Listen koncové body přepíší UseUrls koncové body.

Konfigurace koncového bodu služby IIS

Při použití služby IIS jsou vazby adresy URL pro vazby přepsání služby IIS nastaveny buď Listen nebo UseUrls. Další informace najdete v tématu ASP.NET Core Module.

ListenOptions.Protocols

Vlastnost Protocols vytvoří protokoly HTTP (HttpProtocols) povolené v koncovém bodu připojení nebo pro server. Přiřaďte hodnotu vlastnosti Protocols z výčtu HttpProtocols .

`HttpProtocols` enum value	Povolený protokol připojení
`Http1`	Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
`Http2`	Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
`Http1AndHttp2`	HTTP/1.1 a HTTP/2. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota každého koncového bodu je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

TLS verze 1.2 nebo novější
Opětovné vyjednávání zakázáno
Komprese je zakázaná
Minimální dočasné velikosti výměny klíčů:
- Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
- Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Následující příklad umožňuje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě připojení:

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware připojení

Middleware vlastního připojení může v případě potřeby filtrovat metody handshake protokolu TLS na základě připojení pro konkrétní šifry.

Následující příklad vyvolá NotSupportedException jakýkoli algoritmus šifry, který aplikace nepodporuje. Případně můžete definovat a porovnat ITlsHandshakeFeature.CipherAlgorithm se seznamem přijatelných šifrovacích sad.

U šifrovacího algoritmu CipherAlgorithmType.Null se nepoužívá žádné šifrování.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});

using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

Filtrování připojení je také možné nakonfigurovat prostřednictvím IConnectionBuilder lambda:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Nastavení protokolu HTTP z konfigurace

CreateDefaultBuilder ve výchozím nastavení volá serverOptions.Configure(context.Configuration.GetSection("Kestrel")) konfiguraci načtení Kestrel .

Následující appsettings.json příklad vytvoří http/1.1 jako výchozí připojovací protokol pro všechny koncové body:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokoly zadané v hodnotách přepsání kódu nastavených konfigurací.

Předpony adres URL

Platné jsou pouze předpony adresy URL HTTP. Kestrel nepodporuje HTTPS při konfiguraci vazeb adres URL pomocí UseUrls.

Adresa IPv4 s číslem portu
```
http://65.55.39.10:80/
```
0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.
Adresa IPv6 s číslem portu
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.
Název hostitele s číslem portu
```
http://contoso.com:80/
http://*:80/
```
Názvy hostitelů a *+, nejsou zvláštní. Nic se nerozpoznalo jako platná IP adresa nebo localhost vazba na všechny IP adresy IPv4 a IPv6. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server. Příklady reverzního proxy serveru zahrnují službu IIS, Nginx nebo Apache.

Upozorňující

Hostování v konfiguraci reverzního proxy serveru vyžaduje filtrování hostitele.
Název hostitele localhost s číslem portu nebo IP adresou zpětné smyčky s číslem portu
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

Sdílet prostřednictvím

Konfigurace koncových bodů pro webový server ASP.NET Core Kestrel

Výchozí koncový bod

Konfigurace koncových bodů

Konfigurace koncových bodů pomocí adres URL

Formáty adres URL

Předpony adresy URL HTTPS

Zadat pouze porty

Konfigurace koncových bodů v appsettings.json

Opětovné načtení koncových bodů z konfigurace

ConfigurationLoader

Konfigurace koncových bodů v kódu

Vytvoření vazby k soketu TCP

Vytvoření vazby k soketu Unix

Konfigurace výchozích hodnot koncového bodu

Dynamická vazba portu

Konfigurace HTTPS

Konfigurace HTTPS v appsettings.json

Poznámky ke schématu

Zdroje certifikátů

Konfigurace klientských certifikátů v appsettings.json

Konfigurace protokolů SSL/TLS v appsettings.json

Konfigurace HTTPS v kódu

Konfigurace klientských certifikátů v kódu

Konfigurace výchozích hodnot HTTPS v kódu

Konfigurace protokolů SSL/TLS v kódu

Konfigurace filtru šifrovacích sad TLS v kódu

Konfigurace indikace názvu serveru

Konfigurace SNI v appsettings.json

Konfigurace SNI pomocí kódu

SNI s ServerCertificateSelector

SNI s ServerOptionsSelectionCallback

SNI s TlsHandshakeCallbackOptions

Konfigurace protokolů HTTP

Konfigurace protokolů HTTP v appsettings.json

Konfigurace protokolů HTTP v kódu

Viz také

KonfiguraceDefaultsEndpointDefaults

Configure(IConfiguration)

KonfiguraceHttpsDefaults

ListenOptions.UseHttps

Bez konfigurace

Nahrazení výchozího certifikátu z konfigurace

Zdroje certifikátů

ConfigurationLoader

Změna výchozích hodnot v kódu

Konfigurace koncových bodů pomocí indikací názvu serveru

SNI s ServerCertificateSelector

SNI s ServerOptionsSelectionCallback

SNI s TlsHandshakeCallbackOptions

SNI v konfiguraci

Požadavky na SNI

Protokoly SSL/TLS

Klientské certifikáty

Protokolování připojení

Vytvoření vazby k soketu TCP

Vytvoření vazby k soketu Unix

Port 0

Omezení

Konfigurace koncového bodu služby IIS

ListenOptions.Protocols

Middleware připojení

Nastavení protokolu HTTP z konfigurace

Předpony adres URL

KonfiguraceDefaultsEndpointDefaults

Configure(IConfiguration)

KonfiguraceHttpsDefaults

ListenOptions.UseHttps

Bez konfigurace

Nahrazení výchozího certifikátu z konfigurace

Zdroje certifikátů

ConfigurationLoader

Změna výchozích hodnot v kódu

Konfigurace koncových bodů pomocí indikací názvu serveru

SNI s ServerCertificateSelector

SNI s ServerOptionsSelectionCallback

SNI s TlsHandshakeCallbackOptions

SNI v konfiguraci

Požadavky na SNI

Protokoly SSL/TLS

SNI s `ServerCertificateSelector`

SNI s `ServerOptionsSelectionCallback`

SNI s `TlsHandshakeCallbackOptions`

SNI s `ServerCertificateSelector`

SNI s `ServerOptionsSelectionCallback`

SNI s `TlsHandshakeCallbackOptions`

SNI s `ServerCertificateSelector`

SNI s `ServerOptionsSelectionCallback`

SNI s `TlsHandshakeCallbackOptions`

SNI s `ServerCertificateSelector`

SNI s `ServerOptionsSelectionCallback`