Konfigurowanie punktów końcowych dla serwera ASP.NET Core Kestrel sieci Web

ASP.NET Core są skonfigurowane do powiązania z losowym portem HTTP z zakresie 5000–5300 i losowym portem HTTPS z zakresie 7000–7300. Ta domyślna konfiguracja jest określona w wygenerowanym pliku Properties/launchSettings.json i można ją przesłonić. Jeśli nie określono żadnych portów, zostanie Kestrel on powiązyny z:

  • http://localhost:5000
  • https://localhost:5001 (jeśli jest obecny lokalny certyfikat dewelopera)

Określ adresy URL przy użyciu:

  • ASPNETCORE_URLS zmienna środowiskowa.
  • --urls argument wiersza polecenia.
  • urls klucz konfiguracji hosta.
  • UseUrls metoda rozszerzenia.

Wartością zapewnianą przy użyciu tych metod może być co najmniej jeden punkt końcowy HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001").

Aby uzyskać więcej informacji na temat tych metod, zobacz Server URLs and Override configuration ( Adresy URL serwera i konfiguracja przesłonięcia).

Zostanie utworzony certyfikat dewelopera:

Certyfikat dewelopera jest dostępny tylko dla użytkownika, który generuje certyfikat. Niektóre przeglądarki wymagają udzielenia jawnego uprawnienia do zaufania lokalnemu certyfikatowi dewelopera.

Project konfigurują aplikacje do domyślnego uruchamiania przy użyciu protokołu HTTPS i obejmują obsługę przekierowania HTTPS i usług HSTS.

Wywołaj Listen wywołanie metody lub ListenUnixSocket , KestrelServerOptions aby skonfigurować prefiksy adresów URL i porty dla elementu Kestrel.

UseUrls, argument --urls wiersza polecenia, urls klucz konfiguracji hosta i zmienna środowiskowa również działają, ASPNETCORE_URLS ale mają ograniczenia zanotowe w dalszej części tej sekcji (domyślny certyfikat musi być dostępny dla konfiguracji punktu końcowego HTTPS).

KestrelServerOptions Konfiguracji:

ConfigureEndpointDefaults(ActionListenOptions<>)

Określa konfigurację do Action uruchomienia dla każdego określonego punktu końcowego. Wielokrotne ConfigureEndpointDefaults wywołanie zastępuje poprzednie wartości Actionostatnimi określonymi Action wartościami:

var builder = WebApplication.CreateBuilder(args);

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

Uwaga

Punkty końcowe utworzone przez wywołanie Listenprzed wywołaniemConfigureEndpointDefaults nie będą mieć zastosowanych wartości domyślnych.

Configure(IConfiguration)

Umożliwia Kestrel ładowanie punktów końcowych z .IConfiguration Konfiguracja musi być w zakresie sekcji konfiguracji dla programu Kestrel. Przeciążenie Configure(IConfiguration, bool) może służyć do włączania ponownego ładowania punktów końcowych po zmianie źródła konfiguracji.

Domyślnie konfiguracja jest Kestrel ładowana z sekcji Kestrel i jest włączone ponowne ładowanie zmian:

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

Jeśli włączono konfigurację ponownego ładowania i zasygnalizowana jest zmiana, zostaną wykonane następujące kroki:

  • Nowa konfiguracja jest porównywana ze starą, a żaden punkt końcowy bez zmian konfiguracji nie jest modyfikowany.
  • Usunięte lub zmodyfikowane punkty końcowe mają 5 sekund na ukończenie przetwarzania żądań i zamknięcie.
  • Zostaną uruchomione nowe lub zmodyfikowane punkty końcowe.

Klienci łączący się ze zmodyfikowanym punktem końcowym mogą zostać rozłączeni lub odmówieni podczas ponownego uruchamiania punktu końcowego.

ConfigureHttpsDefaults(ActionHttpsConnectionAdapterOptions<>)

Określa konfigurację do Action uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wielokrotnie zastępuje poprzednie z Actionostatniej Action określonej.

var builder = WebApplication.CreateBuilder(args);

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

Uwaga

Punkty końcowe utworzone przez wywołanie Listenprzed wywołaniemConfigureHttpsDefaults nie będą mieć zastosowanych wartości domyślnych.

ListenOptions.UseHttps

Skonfiguruj do Kestrel używania protokołu HTTPS.

ListenOptions.UseHttps Rozszerzenia:

  • UseHttps: skonfiguruj do Kestrel używania protokołu HTTPS z certyfikatem domyślnym. Zgłasza wyjątek, jeśli nie skonfigurowano certyfikatu domyślnego.
  • 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 to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
  • configureOptionsto element Action do konfigurowania .HttpsConnectionAdapterOptions Zwraca wartość ListenOptions.
  • storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
  • subject to nazwa podmiotu certyfikatu.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
  • location to lokalizacja magazynu, z których ma być ładowany certyfikat.
  • serverCertificate to certyfikat X.509.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS. Należy podać co najmniej certyfikat domyślny.

Obsługiwane konfiguracje opisane poniżej:

  • Brak konfiguracji
  • Zastępowanie domyślnego certyfikatu z konfiguracji
  • Zmienianie wartości domyślnych w kodzie

Brak konfiguracji

Kestrel Nasłuchuje http://localhost:5000 na i https://localhost:5001 (jeśli jest dostępny domyślny certyfikat).

Zastępowanie domyślnego certyfikatu z konfiguracji

Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel. Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

W poniższym przykładzie appsettings.json :

  • Ustaw AllowInvalid wartość , true aby zezwolić na używanie nieprawidłowych certyfikatów (na przykład certyfikatów z podpisem własnym).
  • Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie), Certificates:Default powraca do certyfikatu zdefiniowanego w obszarze lub certyfikatu dewelopera.
{
  "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$"
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasła certyfikatów są przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła każdego certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w środowisku dewelopera. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault konfiguracji. Wpisów tajnych procesów deweloperskich nie należy używać w środowisku produkcyjnym ani testowym.

Uwagi dotyczące schematu:

  • W nazwach punktów końcowych nie jest uwzględniania ich litera. Na przykład elementy HTTPS i Https są równoważne.
  • Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr Urls konfiguracji najwyższego poziomu, z tą różnicą, że jest ograniczony do pojedynczej wartości.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls , a nie dodając do nich. Punkty końcowe zdefiniowane w kodzie za pośrednictwem Listen programu kumulują się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
  • Sekcja Certificate jest opcjonalna. Jeśli sekcja Certificate nie zostanie określona, zostaną użyte wartości domyślne zdefiniowane w Certificates:Default sekcji . Jeśli nie są dostępne żadne wartości domyślne, używany jest certyfikat dewelopera. Jeśli nie ma żadnych wartości domyślnych, a certyfikat dewelopera nie istnieje, serwer zgłasza wyjątek i nie można go uruchomić.
  • Sekcja Certificate obsługuje wiele źródeł certyfikatów.
  • Dowolną liczbę punktów końcowych można zdefiniować w konfiguracji, o ile nie powodują konfliktów portów.

Źródła certyfikatów

Węzły certyfikatów można skonfigurować do ładowania certyfikatów z wielu źródeł:

  • Path i Password w celu załadowania plików pfx .
  • Path, KeyPath i Password w celu załadowania plików pem.crt/i .key.
  • Subject i Store do załadowania z magazynu certyfikatów.

Na przykład certyfikat Certificates:Default można określić jako:

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

ConfigurationLoader

Configure(IConfiguration) Zwraca metodę KestrelConfigurationLoader z metodą Endpoint(String, Action<EndpointConfiguration>) , która może służyć do uzupełnienia skonfigurowanych ustawień punktu końcowego:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoaderMożna uzyskać bezpośredni dostęp, aby kontynuować iterowanie istniejącego modułu ładującego, takiego jak ten dostarczony przez .WebApplicationBuilder.WebHost

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach Endpoint metody , aby można było odczytać ustawienia niestandardowe.
  • Wiele konfiguracji może zostać załadowanych przez wywołanie ponownie Configure(IConfiguration) z inną sekcją. Używana jest tylko ostatnia konfiguracja, chyba że jest Load jawnie wywoływana w poprzednich wystąpieniach. Metapakiet nie jest wywołany, Load aby można było zastąpić jego domyślną sekcję konfiguracji.
  • KestrelConfigurationLoader odzwierciedla rodzinę Listen interfejsów API KestrelServerOptions z programu jako Endpoint przeciążenia, więc punkty końcowe kodu i konfiguracji mogą być skonfigurowane w tym samym miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Zmienianie wartości domyślnych w kodzie

ConfigureEndpointDefaults i ConfigureHttpsDefaults mogą służyć do zmiany ustawień domyślnych dla ListenOptions i HttpsConnectionAdapterOptions, w tym zastępowania certyfikatu domyślnego określonego w wcześniejszym scenariuszu. ConfigureEndpointDefaults i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem jakichkolwiek punktów końcowych.

var builder = WebApplication.CreateBuilder(args);

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

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

Konfigurowanie punktów końcowych przy użyciu Oznaczanie nazwy serwera

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i tym samym porcie. Aby funkcja SNI działała, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uściśniania TLS, dzięki czemu serwer może podać prawidłowy certyfikat. Klient używa zabezpieczonego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po ugodzie TLS.

SNI można skonfigurować na dwa sposoby:

  • Utwórz punkt końcowy w kodzie i wybierz certyfikat przy użyciu nazwy hosta z wywołaniem ServerCertificateSelector zwrotowym.
  • Skonfiguruj mapowanie między nazwami hostów i opcjami protokołu HTTPS w konfiguracji. Na przykład JSON w appsettings.json pliku .

SNI z ServerCertificateSelector

Kestrel Obsługuje SNI za pośrednictwem wywołania ServerCertificateSelector zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu:

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 z ServerOptionsSelectionCallback

Kestrel obsługuje dodatkową dynamiczną konfigurację TLS za pośrednictwem wywołania ServerOptionsSelectionCallback zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzanie nazwy hosta i wybranie odpowiedniego certyfikatu i konfiguracji TLS. Certyfikaty domyślne i nie ConfigureHttpsDefaults są używane z tym wywołaniem zwrotym.

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 z TlsHandshakeCallbackOptions

Kestrel obsługuje dodatkową dynamiczną konfigurację TLS za pośrednictwem wywołania TlsHandshakeCallbackOptions.OnConnection zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzanie nazwy hosta i wybranie odpowiedniego certyfikatu, konfiguracji TLS i innych opcji serwera. Certyfikaty domyślne i nie ConfigureHttpsDefaults są używane z tym wywołaniem zwrotym.

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 w konfiguracji

Kestrel obsługuje funkcję SNI zdefiniowaną w konfiguracji. Punkt końcowy można skonfigurować za pomocą obiektu Sni , który zawiera mapowanie między nazwami hostów i opcjami protokołu HTTPS. Nazwa hosta połączenia jest do dopasowana do opcji i są one używane dla tego połączenia.

W poniższej konfiguracji dodano punkt końcowy o nazwie MySniEndpoint , który używa SNI do wybierania opcji protokołu HTTPS na podstawie nazwy hosta:

{
  "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$"
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasła certyfikatów są przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła każdego certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w programie. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault configuration provider (Dostawca konfiguracji usługi Azure Key Vault). Wpisów tajnych procesów programistskich nie należy używać w środowisku produkcyjnym ani testowym.

Opcje protokołu HTTPS, które mogą zostać zastąpione przez SNI:

Nazwa hosta obsługuje dopasowywanie symboli wieloznacznych:

  • Dokładne dopasowanie. Na przykład dopasowuje a.example.org .a.example.org
  • Prefiks symbolu wieloznacznego. Jeśli istnieje wiele dopasowania symboli wieloznacznych, wybierany jest najdłuższy wzorzec. Na przykład dopasowuje *.example.org i b.example.orgc.example.org.
  • Pełny symbol wieloznaczny. * dopasowuje wszystkie inne dane, w tym klientów, którzy nie korzystali z funkcji SNI i nie wysyłają nazwy hosta.

Dopasowana konfiguracja SNI jest stosowana do punktu końcowego dla połączenia, zastępując wartości w punkcie końcowym. Jeśli połączenie nie jest zgodne ze skonfigurowaną nazwą hosta SNI, połączenie zostanie odrzucone.

Wymagania dotyczące SNI

Wszystkie witryny internetowe muszą działać w tym samym wystąpieniu Kestrel . Kestrel Nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera proxy.

Protokoły SSL/TLS

Protokoły SSL to protokoły używane do szyfrowania i odszyfrowywania ruchu między dwoma elementami równorzędnych, tradycyjnie klientem i serwerem.

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$"
        }
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w programie. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault configuration provider (Dostawca konfiguracji usługi Azure Key Vault). Wpisów tajnych procesów programistskich nie należy używać w środowisku produkcyjnym ani testowym.

Wartość domyślna, SslProtocols.None, powoduje Kestrel , że do wyboru najlepszego protokołu jest używany domyślny system operacyjny. Jeśli nie ma konkretnego powodu, aby wybrać protokół, użyj wartości domyślnej.

Certyfikaty klienta

ClientCertificateMode Konfiguruje wymagania dotyczące certyfikatu klienta.

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$"
        }
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w programie. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault configuration provider (Dostawca konfiguracji usługi Azure Key Vault).

Wartość domyślna to ClientCertificateMode.NoCertificate where Kestrel nie będzie żądać ani wymagać certyfikatu od klienta.

Aby uzyskać więcej informacji, zobacz Konfigurowanie uwierzytelniania certyfikatów w ASP.NET Core.

Rejestrowanie połączeń

Wywołaj UseConnectionLogging polecenie , aby emitować dzienniki poziomu debugowania dla komunikacji na poziomie bajtu w połączeniu. Rejestrowanie połączeń jest przydatne w przypadku rozwiązywania problemów z komunikacją niskiego poziomu, takich jak szyfrowanie TLS i za proxy. Jeśli zostanie UseConnectionLogging umieszczony przed UseHttps, szyfrowany ruch jest rejestrowany. Jeśli zostanie UseConnectionLogging umieszczony po UseHttps, odszyfrowany ruch jest rejestrowany. Jest to wbudowane oprogramowanie pośredniczące połączeń.

var builder = WebApplication.CreateBuilder(args);

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

Wiązanie z gniazdem TCP

Metoda Listen wiąże się z gniazdem TCP, a lambda opcji zezwala na konfigurację certyfikatu 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");
    });
});

W przykładzie skonfigurowano protokół HTTPS dla punktu końcowego za pomocą parametru ListenOptions. Użyj tego samego interfejsu API, aby skonfigurować inne Kestrel ustawienia dla określonych punktów końcowych.

Na Windows certyfikatów z podpisem własnym można tworzyć przy użyciu polecenia New-SelfSignedCertificate cmdlet programu PowerShell. Aby uzyskać nieobsługiwany przykład, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows można tworzyć certyfikaty przy użyciu programu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwać na gnieździe ListenUnixSocket systemu Unix za pomocą polecenia w celu poprawy wydajności przy użyciu systemu Nginx, jak pokazano w tym przykładzie:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
  • W pliku konfiguracji serwera Nginx ustaw wpis server>proxy_pass>locationna .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} to nazwa gniazda dostarczonego dla ListenUnixSocket (na przykład w kestrel-test.sock poprzednim przykładzie).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład chmod go+w /tmp/kestrel-test.sock).

Port 0

Po podano numer 0 portu, Kestrel dynamicznie wiąże się z dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port jest Kestrel powiązany w czasie wykonywania:

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

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

        // ...
    }
});

Ograniczenia

Skonfiguruj punkty końcowe przy użyciu następujących metod:

  • UseUrls
  • --urls argument wiersza polecenia
  • urls klucz konfiguracji hosta
  • ASPNETCORE_URLS zmienna środowiskowa

Te metody są przydatne do pracy kodu z serwerami innymi niż Kestrel. Należy jednak pamiętać o następujących ograniczeniach:

  • Przy użyciu tych metod nie można używać protokołu HTTPS, chyba że w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat ( KestrelServerOptions na przykład przy użyciu konfiguracji lub pliku konfiguracji, jak pokazano wcześniej w tym artykule).
  • Gdy oba podejścia Listen i UseUrls są używane jednocześnie, punkty Listen końcowe przesłaniają UseUrls punkty końcowe.

Konfiguracja punktu końcowego usług IIS

W przypadku korzystania z usług IIS powiązania adresów URL dla powiązań przesłonięcia usług IIS są ustawiane przez wartość Listen lub UseUrls. Aby uzyskać więcej informacji, zobacz ASP.NET Core Module.

ListenOptions.Protocols

Właściwość Protocols ustanawia protokoły HTTP () włączoneHttpProtocols w punkcie końcowym połączenia lub na serwerze. Przypisz wartość do właściwości Protocols z wyli HttpProtocols roku.

HttpProtocols wartość wyli Dozwolony protokół połączenia
Http1 Tylko PROTOKÓŁ HTTP/1.1. Może być używany z lub bez użycia TLS.
Http2 Tylko HTTP/2. Może być używany bez użycia TLS tylko wtedy, gdy klient obsługuje tryb wcześniejszej wiedzy.
Http1AndHttp2 HTTP/1.1 i HTTP/2. Protokół HTTP/2 wymaga od klienta wybrania protokołu HTTP/2 podczas negocjacji protokołu TLS Application-Layer Protocol (ALPN ); W przeciwnym razie połączenie domyślnie ma wartość HTTP/1.1.

Wartość domyślna ListenOptions.Protocols dla dowolnego punktu końcowego to HttpProtocols.Http1AndHttp2.

Ograniczenia protokołu TLS dla protokołu HTTP/2:

  • TLS w wersji 1.2 lub nowszej
  • Renegocjacja jest wyłączona
  • Kompresja wyłączona
  • Minimalne rozmiary efemeralnych wymiany kluczy:
    • Krzywa wielokropka Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bity
    • Wartości pól skończonych Diffie-Hellman (DHE) [TLS12]: minimum 2048 bitów
  • Zestaw szyfrowania nie jest zabroniony.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] z krzywą wielokropka P-256 [FIPS186] jest obsługiwana domyślnie.

Poniższy przykład umożliwia połączenia HTTP/1.1 i HTTP/2 na porcie 8000. Połączenia są zabezpieczone przez zabezpieczenia TLS przy użyciu dostarczonego certyfikatu:

var builder = WebApplication.CreateBuilder(args);

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

W systemie Linux CipherSuitesPolicy można użyć do filtrowania uściślień TLS dla per-connection basis:

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,
                    // ...
                });
        };
    });
});

Oprogramowanie pośredniczące połączeń

Niestandardowe oprogramowanie pośredniczące połączeń może w razie potrzeby filtrować uściślniania TLS dla poszczególnych połączeń.

Poniższy przykład zgłasza wyjątek NotSupportedException dla dowolnego algorytmu szyfrowania, który nie jest przez aplikację obsługi. Alternatywnie zdefiniuj i porównaj ITlsHandshakeFeature.CipherAlgorithm z listą akceptowalnych mechanizmów szyfrowania.

Szyfrowanie nie jest używane z algorytmem CipherAlgorithmType.Null szyfrowania.

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();
        });
    });
});

Ustawianie protokołu HTTP z konfiguracji

Domyślnie konfiguracja Kestrel jest ładowana z Kestrel sekcji . W poniższym appsettings.json przykładzie protokół HTTP/1.1 jest ustanawiany jako domyślny protokół połączenia dla wszystkich punktów końcowych:

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

W poniższym appsettings.json przykładzie ustanawiany jest protokół połączenia HTTP/1.1 dla określonego punktu końcowego:

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

Protokoły określone w kodzie zastępują wartości ustawione przez konfigurację.

Prefiksy adresów URL

W przypadku UseUrlskorzystania z argumentu --urls wiersza polecenia, urls klucza ASPNETCORE_URLS konfiguracji hosta lub zmiennej środowiskowej prefiksy adresów URL mogą być w dowolnym z następujących formatów.

Prawidłowe są tylko prefiksy adresów URL HTTP. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy użyciu usługi UseUrls.

  • Adres IPv4 z numerem portu

    http://65.55.39.10:80/
    

    0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

  • Adres IPv6 z numerem portu

    http://[0:0:0:0:0:ffff:4137:270a]:80/
    

    [::] jest odpowiednikiem protokołu IPv6 protokołu IPv4 0.0.0.0.

  • Nazwa hosta z numerem portu

    http://contoso.com:80/
    http://*:80/
    

    Nazwy hostów *, , i +, nie są specjalne. Wszystkie wartości, które nie są rozpoznawane jako prawidłowy adres localhost IP lub są powiązywane ze wszystkimi adresami IP IPv4 i IPv6. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core na tym samym porcie, użyj HTTP.sys lub odwrotnego serwera proxy. Przykłady odwrotnego serwera proxy to usługi IIS, Nginx lub Apache.

    Ostrzeżenie

    Hosting w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.

  • Nazwa localhost hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

    http://localhost:5000/
    http://127.0.0.1:5000/
    http://[::1]:5000/
    

    Gdy localhost jest określony, Kestrel próbuje powiązać z interfejsami sprzężenia zwrotnego IPv4 i IPv6. Jeśli żądany port jest w użyciu przez inną usługę w obu interfejsach sprzężenia zwrotnego, Kestrel uruchomienie nie powiedzie się. Jeśli którykolwiek z interfejsów sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej z powodu tego, że protokół IPv6 nie jest obsługiwany), Kestrel program rejestruje ostrzeżenie.

Domyślnie program ASP.NET Core z:

  • http://localhost:5000
  • https://localhost:5001 (jeśli jest obecny lokalny certyfikat dewelopera)

Określ adresy URL przy użyciu:

  • ASPNETCORE_URLS zmienna środowiskowa.
  • --urls argument wiersza polecenia.
  • urls klucz konfiguracji hosta.
  • UseUrls metoda rozszerzenia.

Wartością zapewnianą przy użyciu tych metod może być co najmniej jeden punkt końcowy HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001").

Aby uzyskać więcej informacji na temat tych metod, zobacz Server URLs and Override configuration ( Adresy URL serwera i konfiguracja przesłonięcia).

Zostanie utworzony certyfikat dewelopera:

Niektóre przeglądarki wymagają udzielenia jawnego uprawnienia do zaufania lokalnemu certyfikatowi dewelopera.

Project konfigurują aplikacje do domyślnego uruchamiania przy użyciu protokołu HTTPS i obejmują obsługę przekierowania HTTPS i usług HSTS.

Wywołaj Listen wywołanie metody lub ListenUnixSocket , KestrelServerOptions aby skonfigurować prefiksy adresów URL i porty dla elementu Kestrel.

UseUrls, argument --urls wiersza polecenia, urls klucz konfiguracji hosta i zmienna środowiskowa również działają, ASPNETCORE_URLS ale mają ograniczenia zanotowe w dalszej części tej sekcji (domyślny certyfikat musi być dostępny dla konfiguracji punktu końcowego HTTPS).

KestrelServerOptions Konfiguracji:

ConfigureEndpointDefaults(ActionListenOptions<>)

Określa konfigurację do Action uruchomienia dla każdego określonego punktu końcowego. Wywołanie ConfigureEndpointDefaults wielokrotnie zastępuje poprzednie z Actionostatniej Action określonej.

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

Uwaga

Punkty końcowe utworzone przez wywołanie Listenprzed wywołaniemConfigureEndpointDefaults nie będą mieć zastosowanych wartości domyślnych.

Configure(IConfiguration)

Umożliwia Kestrel ładowanie punktów końcowych z .IConfiguration Konfiguracja musi być w zakresie sekcji konfiguracji dla programu Kestrel.

Przeciążenie Configure(IConfiguration, bool) może służyć do włączania ponownego ładowania punktów końcowych po zmianie źródła konfiguracji.

IHostBuilder.ConfigureWebHostDefaults Domyślnie Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) program wywołuje usługę , aby załadować Kestrel konfigurację i włączyć ponowne ładowanie.

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

Jeśli włączono konfigurację ponownego ładowania i zasygnalizowana jest zmiana, zostaną wykonane następujące kroki:

  • Nowa konfiguracja jest porównywana ze starą, a żaden punkt końcowy bez zmian konfiguracji nie jest modyfikowany.
  • Usunięte lub zmodyfikowane punkty końcowe mają 5 sekund na ukończenie przetwarzania żądań i zamknięcie.
  • Zostaną uruchomione nowe lub zmodyfikowane punkty końcowe.

Klienci łączący się ze zmodyfikowanym punktem końcowym mogą zostać rozłączeni lub odmówieni podczas ponownego uruchamiania punktu końcowego.

ConfigureHttpsDefaults(ActionHttpsConnectionAdapterOptions<>)

Określa konfigurację do Action uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wielokrotnie zastępuje poprzednie z Actionostatniej Action określonej.

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

Uwaga

Punkty końcowe utworzone przez wywołanie funkcji ListenprzedConfigureHttpsDefaults wywołaniem nie będą mieć zastosowanych wartości domyślnych.

ListenOptions.UseHttps

Skonfiguruj do Kestrel używania protokołu HTTPS.

ListenOptions.UseHttps Rozszerzenia:

  • UseHttps: skonfiguruj do Kestrel używania protokołu HTTPS z certyfikatem domyślnym. Zgłasza wyjątek, jeśli nie skonfigurowano certyfikatu domyślnego.
  • 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 to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
  • configureOptionsto element Action do konfigurowania .HttpsConnectionAdapterOptions Zwraca wartość ListenOptions.
  • storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
  • subject to nazwa podmiotu certyfikatu.
  • allowInvalid Wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
  • location to lokalizacja magazynu, z których ma być ładowany certyfikat.
  • serverCertificate to certyfikat X.509.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS. Należy podać co najmniej domyślny certyfikat.

Obsługiwane konfiguracje opisane w następnej konfiguracji:

  • Brak konfiguracji
  • Zastępowanie domyślnego certyfikatu z konfiguracji
  • Zmienianie wartości domyślnych w kodzie

Brak konfiguracji

Kestrel Nasłuchuje http://localhost:5000 na i https://localhost:5001 (jeśli jest dostępny domyślny certyfikat).

Zastępowanie domyślnego certyfikatu z konfiguracji

Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel. Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

W poniższym przykładzie appsettings.json :

  • Ustaw AllowInvalid wartość true , aby zezwolić na używanie nieprawidłowych certyfikatów (na przykład certyfikatów z podpisem własnym).
  • Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie), Certificates:Default powraca do certyfikatu zdefiniowanego w programie lub certyfikatu dewelopera.
{
  "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$"
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasła certyfikatów są przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła każdego certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w programie. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault configuration provider (Dostawca konfiguracji usługi Azure Key Vault). Wpisów tajnych procesów programistskich nie należy używać w środowisku produkcyjnym ani testowym.

Uwagi dotyczące schematu:

  • W nazwach punktów końcowych nie jest uwzględniania ich litera. Na przykład elementy HTTPS i Https są równoważne.
  • Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr Urls konfiguracji najwyższego poziomu z tą różnicą, że jest ograniczony do pojedynczej wartości.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls , zamiast dodawać do nich. Punkty końcowe zdefiniowane w kodzie za pośrednictwem programu Listen kumulują się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
  • Sekcja Certificate jest opcjonalna. Jeśli sekcja Certificate nie zostanie określona, zostaną użyte wartości domyślne zdefiniowane w Certificates:Default pliku . Jeśli nie są dostępne żadne wartości domyślne, używany jest certyfikat dewelopera. Jeśli nie ma żadnych wartości domyślnych i nie ma certyfikatu dewelopera, serwer zgłasza wyjątek i nie można go uruchomić.
  • Sekcja Certificate obsługuje wiele źródeł certyfikatów.
  • Dowolną liczbę punktów końcowych można zdefiniować w konfiguracji, o ile nie powodują konfliktów portów.

Źródła certyfikatów

Węzły certyfikatów można skonfigurować do ładowania certyfikatów z wielu źródeł:

  • Path i Password w celu załadowania plików pfx .
  • Path, KeyPath i Password w celu załadowania plików pem.crt/i .key.
  • Subject i Store do załadowania z magazynu certyfikatów.

Na przykład certyfikat Certificates:Default można określić jako:

"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}")) Metoda zwraca KestrelConfigurationLoader metodę , .Endpoint(string name, listenOptions => { }) która może służyć do uzupełnienia skonfigurowanych ustawień punktu końcowego:

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

KestrelServerOptions.ConfigurationLoaderMożna uzyskać bezpośredni dostęp, aby kontynuować iterowanie istniejącego modułu ładującego, takiego jak ten dostarczony przez .CreateDefaultBuilder

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach Endpoint metody , aby można było odczytać ustawienia niestandardowe.
  • Wiele konfiguracji może zostać załadowanych przez wywołanie ponownie options.Configure(context.Configuration.GetSection("{SECTION}")) z inną sekcją. Używana jest tylko ostatnia konfiguracja, chyba że jest Load jawnie wywoływana w poprzednich wystąpieniach. Metapakiet nie jest wywołany, Load aby można było zastąpić jego domyślną sekcję konfiguracji.
  • KestrelConfigurationLoader odzwierciedla rodzinę Listen interfejsów API KestrelServerOptions z programu jako Endpoint przeciążenia, więc punkty końcowe kodu i konfiguracji mogą być skonfigurowane w tym samym miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Zmienianie wartości domyślnych w kodzie

ConfigureEndpointDefaults i ConfigureHttpsDefaults mogą służyć do zmiany ustawień domyślnych dla ListenOptions i HttpsConnectionAdapterOptions, w tym zastępowania certyfikatu domyślnego określonego w wcześniejszym scenariuszu. ConfigureEndpointDefaults i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem jakichkolwiek punktów końcowych.

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

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

Konfigurowanie punktów końcowych przy użyciu Oznaczanie nazwy serwera

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i tym samym porcie. Aby funkcja SNI działała, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uściśniania TLS, dzięki czemu serwer może podać prawidłowy certyfikat. Klient używa zabezpieczonego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po ugodzie TLS.

SNI można skonfigurować na dwa sposoby:

  • Utwórz punkt końcowy w kodzie i wybierz certyfikat przy użyciu nazwy hosta z wywołaniem ServerCertificateSelector zwrotowym.
  • Skonfiguruj mapowanie między nazwami hostów i opcjami protokołu HTTPS w konfiguracji. Na przykład JSON w appsettings.json pliku .

SNI z ServerCertificateSelector

Kestrel Obsługuje SNI za pośrednictwem wywołania ServerCertificateSelector zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu. W wywołaniu ConfigureWebHostDefaults metody pliku projektu można użyć następującego kodu wywołania zwrotnego 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 z ServerOptionsSelectionCallback

Kestrel obsługuje dodatkową dynamiczną konfigurację TLS za pośrednictwem wywołania ServerOptionsSelectionCallback zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzanie nazwy hosta i wybranie odpowiedniego certyfikatu i konfiguracji TLS. Certyfikaty domyślne i nie ConfigureHttpsDefaults są używane z tym wywołaniem zwrotym.

// 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 w konfiguracji

Kestrel obsługuje funkcję SNI zdefiniowaną w konfiguracji. Punkt końcowy można skonfigurować za pomocą obiektu Sni , który zawiera mapowanie między nazwami hostów i opcjami protokołu HTTPS. Nazwa hosta połączenia jest do dopasowana do opcji i są one używane dla tego połączenia.

W poniższej konfiguracji dodano punkt końcowy o nazwie MySniEndpoint , który używa SNI do wybierania opcji protokołu HTTPS na podstawie nazwy hosta:

{
  "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$"
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasła certyfikatów są przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła każdego certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w programie. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault configuration provider (Dostawca konfiguracji usługi Azure Key Vault). Wpisów tajnych procesów programistskich nie należy używać w środowisku produkcyjnym ani testowym.

Opcje protokołu HTTPS, które mogą zostać zastąpione przez SNI:

Nazwa hosta obsługuje dopasowywanie symboli wieloznacznych:

  • Dokładne dopasowanie. Na przykład dopasowuje a.example.org .a.example.org
  • Prefiks symbolu wieloznacznego. Jeśli istnieje wiele dopasowania symboli wieloznacznych, wybierany jest najdłuższy wzorzec. Na przykład dopasowuje *.example.org i b.example.orgc.example.org.
  • Pełny symbol wieloznaczny. * pasuje do wszystkich innych, w tym klientów, którzy nie korzystali z SNI i nie wysyłają nazwy hosta.

Dopasowana konfiguracja SNI jest stosowana do punktu końcowego dla połączenia, zastępując wartości w punkcie końcowym. Jeśli połączenie nie jest zgodne ze skonfigurowaną nazwą hosta SNI, połączenie zostanie odrzucone.

Wymagania dotyczące SNI

  • Uruchamianie na platformie docelowej netcoreapp2.1 lub nowszej. W net461 dniu lub później wywołanie zwrotne jest wywoływane, ale zawsze jest name .null Parametr name jest również null wtedy, gdy klient nie poda parametru nazwy hosta w uściślce TLS.
  • Wszystkie witryny internetowe działają w tym samym wystąpieniu Kestrel . Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera proxy.

Protokoły SSL/TLS

Protokoły SSL to protokoły używane do szyfrowania i odszyfrowywania ruchu między dwoma elementami równorzędnych, tradycyjnie klientem i serwerem.

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$"
        }
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w środowisku dewelopera. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault konfiguracji. Wpisów tajnych procesów deweloperskich nie należy używać w środowisku produkcyjnym ani testowym.

Wartość domyślna, SslProtocols.None, powoduje Kestrel , że system operacyjny domyślnie wybiera najlepszy protokół. Jeśli nie masz określonego powodu, aby wybrać protokół, użyj wartości domyślnej.

Certyfikaty klienta

ClientCertificateMode konfiguruje wymagania dotyczące certyfikatu klienta.

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$"
        }
      }
    }
  }
}

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w programie appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych w środowisku dewelopera. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Azure Key Vault konfiguracji. Wpisów tajnych procesów deweloperskich nie należy używać w środowisku produkcyjnym ani testowym.

Wartość domyślna to where ClientCertificateMode.NoCertificateKestrel will not request or require a certificate from the client.

Aby uzyskać więcej informacji, zobacz Konfigurowanie uwierzytelniania certyfikatów w ASP.NET Core.

Rejestrowanie połączeń

Wywołanie w UseConnectionLogging celu emitowania dzienników poziomu debugowania dla komunikacji na poziomie bajtu w połączeniu. Rejestrowanie połączeń jest przydatne w przypadku rozwiązywania problemów z komunikacją niskiego poziomu, takich jak szyfrowanie TLS i za proxy. Jeśli UseConnectionLogging zostanie umieszczony przed UseHttps, szyfrowany ruch jest rejestrowany. Jeśli UseConnectionLogging zostanie umieszczony po UseHttps, odszyfrowany ruch jest rejestrowany. Jest to wbudowane oprogramowanie pośredniczące połączeń.

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

Wiązanie z gniazdem TCP

Metoda Listen wiąże się z gniazdem TCP, a lambda opcji zezwala na konfigurację certyfikatu 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>();
        });

W przykładzie skonfigurowano protokół HTTPS dla punktu końcowego za pomocą .ListenOptions Użyj tego samego interfejsu API, aby skonfigurować inne Kestrel ustawienia dla określonych punktów końcowych.

Na Windows można tworzyć certyfikaty z podpisem własnym za pomocą polecenia New-SelfSignedCertificate cmdlet programu PowerShell. Aby uzyskać nieobsługiwany przykład, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows można tworzyć certyfikaty przy użyciu programu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwać na gnieździe ListenUnixSocket systemu Unix za pomocą polecenia w celu poprawy wydajności przy użyciu systemu Nginx, jak pokazano w poniższym przykładzie:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • W pliku konfiguracji serwera Nginx ustaw wpis server>proxy_pass>locationna wartość .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} to nazwa gniazda dostarczonego dla ListenUnixSocket (na przykład kestrel-test.sock w poprzednim przykładzie).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład chmod go+w /tmp/kestrel-test.sock).

Port 0

Po podano numer 0 portu, Kestrel dynamicznie wiąże się z dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port jest Kestrel powiązany w czasie wykonywania:

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>");
    });
}

Po uruchomieniu aplikacji dane wyjściowe okna konsoli wskazują port dynamiczny, na którym można uzyskać do aplikacji:

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

Ograniczenia

Skonfiguruj punkty końcowe przy użyciu następujących metod:

  • UseUrls
  • --urls argument wiersza polecenia
  • urls klucz konfiguracji hosta
  • ASPNETCORE_URLS zmienna środowiskowa

Te metody są przydatne do pracy kodu z serwerami innymi niż Kestrel. Należy jednak pamiętać o następujących ograniczeniach:

  • Przy użyciu tych metod nie można używać protokołu HTTPS, chyba że w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat ( KestrelServerOptions na przykład przy użyciu konfiguracji lub pliku konfiguracji, jak pokazano wcześniej w tym artykule).
  • Gdy oba podejścia Listen i UseUrls są używane jednocześnie, punkty Listen końcowe przesłaniają UseUrls punkty końcowe.

Konfiguracja punktu końcowego usług IIS

W przypadku korzystania z usług IIS powiązania adresów URL dla powiązań przesłonięcia usług IIS są ustawiane przez wartość Listen lub UseUrls. Aby uzyskać więcej informacji, zobacz ASP.NET Core Module.

ListenOptions.Protocols

Właściwość Protocols ustanawia protokoły HTTP () włączoneHttpProtocols w punkcie końcowym połączenia lub na serwerze. Przypisz wartość do właściwości Protocols z wyli HttpProtocols roku.

HttpProtocols wartość wyli Dozwolony protokół połączenia
Http1 Tylko PROTOKÓŁ HTTP/1.1. Może być używany z lub bez użycia TLS.
Http2 Tylko HTTP/2. Może być używany bez użycia TLS tylko wtedy, gdy klient obsługuje tryb wcześniejszej wiedzy.
Http1AndHttp2 HTTP/1.1 i HTTP/2. Protokół HTTP/2 wymaga od klienta wybrania protokołu HTTP/2 podczas negocjacji protokołu TLS Application-Layer Protocol (ALPN ); W przeciwnym razie połączenie domyślnie ma wartość HTTP/1.1.

Wartość domyślna ListenOptions.Protocols dla dowolnego punktu końcowego to HttpProtocols.Http1AndHttp2.

Ograniczenia protokołu TLS dla protokołu HTTP/2:

  • TLS w wersji 1.2 lub nowszej
  • Renegocjacja jest wyłączona
  • Kompresja wyłączona
  • Minimalne rozmiary efemeralnych wymiany kluczy:
    • Krzywa wielokropka Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bity
    • Wartości pól skończonych Diffie-Hellman (DHE) [TLS12]: minimum 2048 bitów
  • Zestaw szyfrowania nie jest zabroniony.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] z krzywą wielokropka P-256 [FIPS186] jest obsługiwana domyślnie.

Poniższy przykład umożliwia połączenia HTTP/1.1 i HTTP/2 na porcie 8000. Połączenia są zabezpieczone przez zabezpieczenia TLS przy użyciu dostarczonego certyfikatu:

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

W systemie Linux CipherSuitesPolicy można użyć do filtrowania uściślień TLS dla per-connection basis:

// 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,
                    // ...
                });
        };
    });
});

Oprogramowanie pośredniczące połączeń

Niestandardowe oprogramowanie pośredniczące połączeń może w razie potrzeby filtrować uściślniania TLS dla poszczególnych połączeń.

Poniższy przykład zgłasza wyjątek NotSupportedException dla dowolnego algorytmu szyfrowania, który nie jest przez aplikację obsługi. Alternatywnie zdefiniuj i porównaj ITlsHandshakeFeature.CipherAlgorithm z listą akceptowalnych mechanizmów szyfrowania.

Szyfrowanie nie jest używane z algorytmem szyfrowania CipherAlgorithmType.Null .

// 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();
            });
        }
    }
}

Filtrowanie połączeń można również skonfigurować za pomocą wyrażenia 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();
        });
    });
});

Ustawianie protokołu HTTP z konfiguracji

CreateDefaultBuilder Domyślnie serverOptions.Configure(context.Configuration.GetSection("Kestrel")) program wywołuje usługę , aby załadować Kestrel konfigurację.

W poniższym appsettings.json przykładzie protokół HTTP/1.1 jest ustanawiany jako domyślny protokół połączenia dla wszystkich punktów końcowych:

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

W poniższym appsettings.json przykładzie ustanawiany jest protokół połączenia HTTP/1.1 dla określonego punktu końcowego:

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

Protokoły określone w kodzie zastępują wartości ustawione przez konfigurację.

Prefiksy adresów URL

W przypadku UseUrlskorzystania z argumentu --urls wiersza polecenia , urls klucza ASPNETCORE_URLS konfiguracji hosta lub zmiennej środowiskowej prefiksy adresów URL mogą być w dowolnym z następujących formatów.

Prawidłowe są tylko prefiksy adresów URL PROTOKOŁU HTTP. Kestrelnie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy użyciu .UseUrls

  • Adres IPv4 z numerem portu

    http://65.55.39.10:80/
    

    0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

  • Adres IPv6 z numerem portu

    http://[0:0:0:0:0:ffff:4137:270a]:80/
    

    [::] jest odpowiednikiem protokołu IPv6 protokołu IPv4 0.0.0.0.

  • Nazwa hosta z numerem portu

    http://contoso.com:80/
    http://*:80/
    

    Nazwy hostów, *, i +, nie są specjalne. Wszystko, co nie jest rozpoznawane jako prawidłowy adres IP lub wiąże localhost się ze wszystkimi adresami IP IPv4 i IPv6. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core na tym samym porcie, użyj HTTP.syslub odwrotnego serwera proxy. Przykłady zwrotnego serwera proxy to usługi IIS, Nginx lub Apache.

    Ostrzeżenie

    Hosting w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.

  • Nazwa hosta localhost z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

    http://localhost:5000/
    http://127.0.0.1:5000/
    http://[::1]:5000/
    

    Gdy localhost jest określony, Kestrel próbuje powiązać z interfejsami sprzężenia zwrotnego IPv4 i IPv6. Jeśli żądany port jest w użyciu przez inną usługę w obu interfejsach sprzężenia zwrotnego, Kestrel uruchomienie nie powiedzie się. Jeśli którykolwiek z interfejsów sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej nie jest obsługiwany protokół IPv6), program Kestrel rejestruje ostrzeżenie.