Web sunucusu için ASP.NET Core Kestrel yapılandırma

Makale
09/24/2021
Okumak için 7 dakika

Varsayılan olarak, ASP.NET Core şu bağlantılara bağlanıyor:

http://localhost:5000
https://localhost:5001 (yerel bir geliştirme sertifikası mevcut olduğunda)

Şu url'leri kullanarak URL'leri belirtin:

ASPNETCORE_URLS ortam değişkeni.
--urls komut satırı bağımsız değişkeni.
urls konak yapılandırma anahtarı.
UseUrls extension yöntemi.

Bu yaklaşımlar kullanılarak sağlanan değer bir veya daha fazla HTTP ve HTTPS uç noktası (varsayılan sertifika varsa HTTPS) olabilir. Değeri noktalı virgülle ayrılmış liste (örneğin, ) olarak "Urls": "http://localhost:8000;http://localhost:8001" yapılandırma.

Bu yaklaşımlar hakkında daha fazla bilgi için bkz. Sunucu URL'leri ve Geçersiz Kılma yapılandırması.

Bir geliştirme sertifikası oluşturulur:

.NET SDK'sı yüklü olduğunda.
Bir sertifika oluşturmak için dev-certs aracı kullanılır.

Bazı tarayıcıların yerel geliştirme sertifikasına güvenmesi için açık izin verilmesi gerekir.

Project şablonları, uygulamaları varsayılan olarak HTTPS üzerinde çalıştıracak şekilde yapılandırarak HTTPS yeniden yönlendirme ve HSTS desteği içerir.

url Listen ön ListenUnixSocket eklerini ve bağlantı noktalarını yapılandırmak için çağrısı KestrelServerOptions veya Kestrel yöntemleri.

UseUrls, komut satırı bağımsız değişkeni, konak yapılandırma anahtarı ve ortam değişkeni de çalışır, ancak bu bölümün ilerleyen kısımlarında (HTTPS uç noktası yapılandırması için varsayılan sertifikanın kullanılabilir olması --urls urls ASPNETCORE_URLS gerekir) sınırlamalara sahiptir.

KestrelServerOptions Yapılandırma:

ConfigureEndpointDefaults(Eylem <ListenOptions> )

Belirtilen her uç nokta Action için çalıştıracak bir yapılandırma belirtir. Birden ConfigureEndpointDefaults çok kez çağrılarak Action öncekiler son belirtilenle Action değiştirilir.

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

Not

Çağrılmadan önce Listen çağrılarak oluşturulan ConfigureEndpointDefaults uç noktaların varsayılan değerleri uygulanmaz.

Configure(IConfiguration)

bir Kestrel 'den uç noktaların yüklenmeye olanak IConfiguration sağlar. Yapılandırmanın kapsamı için yapılandırma bölümü olarak Kestrel genişletildi.

Aşırı Configure(IConfiguration, bool) yükleme, yapılandırma kaynağı değişirken uç noktaların yeniden yüklenmesine olanak sağlamak için kullanılabilir.

IHostBuilder.ConfigureWebHostDefaults , Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) yapılandırmayı yüklemek ve Kestrel yeniden yüklemeyi etkinleştirmek için varsayılan olarak çağrır.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Yeniden yükleme yapılandırması etkinse ve bir değişiklik sinyali alınırsa aşağıdaki adımlar alınır:

Yeni yapılandırma eski yapılandırmayla karşılaştırıldı, yapılandırma değişikliği olmayan herhangi bir uç nokta değiştirilmez.
İşlem isteklerinin tamamlanması ve kapanması için kaldırılan veya değiştirilen uç noktalara 5 saniye verilir.
Yeni veya değiştirilmiş uç noktalar başlatıldı.

Değiştirilen uç noktasına bağlanan istemcilerin bağlantısı kesiliyor veya uç nokta yeniden başlatılırken reddediliyor olabilir.

ConfigureHttpsDefaults(Eylem <HttpsConnectionAdapterOptions> )

Her HTTPS uç noktası Action için çalıştıracak bir yapılandırma belirtir. Birden ConfigureHttpsDefaults çok kez çağrılarak Action öncekiler son belirtilenle Action değiştirilir.

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

Not

Çağrılmadan önce Listen çağrılarak oluşturulan ConfigureHttpsDefaults uç noktaların varsayılan değerleri uygulanmaz.

ListenOptions.UseHttps

KestrelHTTPS kullanmak için yapılandırma.

ListenOptions.UseHttps Uzantı -ları:

UseHttps: Varsayılan Kestrel sertifika ile HTTPS kullanmak üzere yapılandırma. Varsayılan sertifika yapılandırılmamışsa bir özel durum oluşturur.
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 Parametre:

filename , uygulamanın içerik dosyalarını içeren dizine göre bir sertifika dosyasının yolu ve dosya adıdır.
password , X.509 sertifika verilerine erişmek için gereken paroladır.
configureOptions, yapılandırmak Action için bir 'dır. HttpsConnectionAdapterOptions döndürür. ListenOptions
storeName , sertifikanın yükln olduğu sertifika deposu.
subject , sertifikanın konu adıdır.
allowInvalid , otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınmalıdır.
location , sertifikanın yükln olduğu depo konumu.
serverCertificate X.509 sertifikasıdır.

Üretimde HTTPS'nin açıkça yapılandırılması gerekir. En azından, varsayılan bir sertifika sağlanmalıdır.

Bundan sonra açıklanan desteklenen yapılandırmalar:

Yapılandırma yok
Yapılandırmadan varsayılan sertifikayı değiştirme
Kodda varsayılanları değiştirme

Yapılandırma yok

Kestrel ve http://localhost:5000 (varsayılan https://localhost:5001 bir sertifika varsa) dinler.

Yapılandırmadan varsayılan sertifikayı değiştirme

için varsayılan bir HTTPS uygulama ayarları yapılandırma şeması Kestrel mevcuttur. Disk veya sertifika depolama alanı üzerinde bulunan bir dosyadan, URL'ler ve kullanmak üzere sertifikalar dahil olmak üzere birden çok uç nokta yapılandırma.

Aşağıdaki appsettings.json örnekte:

geçersiz AllowInvalid true sertifikaların (örneğin, otomatik olarak imzalanan sertifikalar) kullanımına izin vermek için olarak ayarlayın.
Sertifika belirten https uç noktaları (aşağıdaki örnekte) veya geliştirme sertifikası altında tanımlanan HttpsDefaultCert Certificates:Default sertifikaya geri döner.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "<certificate password>"
        }
      },
      "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": "<certificate password>"
      }
    }
  }
}

Şema notları:

Uç nokta adları büyük/büyük/büyük harfe duyarlı değildir. Örneğin, HTTPS ve Https eşdeğerdir.
parametresi Url her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst Urls düzey yapılandırma parametresiyle aynıdır.
Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini almaktadır. aracılığıyla kodda tanımlanan uç Listen noktalar, yapılandırma bölümünde tanımlanan uç noktalarla biriktir.
bölümü Certificate isteğe bağlıdır. Bölümü Certificate belirtilmezse, içinde tanımlanan Certificates:Default varsayılanlar kullanılır. Varsayılan değer yoksa geliştirme sertifikası kullanılır. Varsayılan değer yoksa ve geliştirme sertifikası yoksa, sunucu bir özel durum oluşturur ve başlatamaz.
bölümü Certificate birden çok sertifika kaynağı destekler.
Bağlantı noktası çakışmaları neden olmayacaksa Yapılandırma'da herhangi bir sayıda uç nokta tanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, bir dizi kaynakta yer alan sertifikaları yüklemek için yalıtıldığında:

Path ve Password .pfx dosyalarını yüklemek için.
Path, KeyPath Password ve .pem / .crt ve .key dosyalarını yüklemek için.
Subject ve Store sertifika depolamadan yüklemek için.

Örneğin, Certificates:Default sertifika şu şekilde belirtilebilir:

"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 yapılandırılan .Endpoint(string name, listenOptions => { }) uç noktanın ayarlarını tamamlarken kullanılan bir yöntemi ile döndürür:

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

KestrelServerOptions.ConfigurationLoader tarafından sağlanan yükleyici gibi mevcut yükleyicide tekrar çalışmaya devam etmek için doğrudan CreateDefaultBuilder erişilebilir.

Her uç noktanın yapılandırma bölümü, özel ayarların Endpoint okunmalarını için yönteminde bulunan seçeneklerde kullanılabilir.
Başka bir bölümle yeniden çağrılarak options.Configure(context.Configuration.GetSection("{SECTION}")) birden çok yapılandırma yüklenebilir. Önceki örneklerde açıkça Load çağrılmadıkça yalnızca son yapılandırma kullanılır. Meta paketi, varsayılan yapılandırma Load bölümünün değiştirilene kadar çağrısız.
KestrelConfigurationLoader , API ailesini aşırı yüklemeler olarak yansıtarak kod ve yapılandırma uç Listen KestrelServerOptions Endpoint noktalarının aynı yerde yapılandırılamalarını sağlar. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Kodda varsayılanları değiştirme

ConfigureEndpointDefaults ve , önceki senaryoda belirtilen varsayılan sertifikayı geçersiz kılma da dahil olmak üzere ve ConfigureHttpsDefaults için varsayılan ayarları değiştirmek için ListenOptions HttpsConnectionAdapterOptions kullanılabilir. ConfigureEndpointDefaults ve ConfigureHttpsDefaults herhangi bir uç nokta yapılandırılmadan önce çağrılmış olmalıdır.

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

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

Uç noktaları Sunucu Adı Belirtme

Sunucu adı belirtme (SNı) , aynı IP adresi ve bağlantı noktası üzerinde birden fazla etki alanını barındırmak için kullanılabilir. SNı 'nin çalışması için, istemci, TLS el sıkışması sırasında güvenli oturum ana bilgisayar adını, sunucunun doğru sertifikayı sağlayabilmesi için gönderir. İstemci, TLS anlaşmasını izleyen güvenli oturum sırasında sunucuyla şifreli iletişim için bulunan sertifikayı kullanır.

SNı iki şekilde yapılandırılabilir:

Kodda bir uç nokta oluşturun ve geri çağırma ile ana bilgisayar adını kullanarak bir sertifika seçin ServerCertificateSelector .
Yapılandırmadaana bilgisayar adları ve https seçenekleri arasında bir eşleme yapılandırın. Örneğin, appsettings.json DOSYADAKI JSON.

SNı with `ServerCertificateSelector`

Kestrel geri çağırma aracılığıyla SNı 'yi destekler ServerCertificateSelector . Geri çağırma, uygulamanın ana bilgisayar adını incelemesine ve uygun sertifikayı seçmesini sağlamak için bağlantı başına bir kez çağrılır. Aşağıdaki geri çağırma kodu ConfigureWebHostDefaults bir projenin program. cs dosyasının Yöntem çağrısında kullanılabilir:

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

SNı with `ServerOptionsSelectionCallback`

Kestrel geri çağırma aracılığıyla ek dinamik TLS yapılandırması destekler ServerOptionsSelectionCallback . Geri çağırma, uygulamanın ana bilgisayar adını incelemesine izin vermek ve uygun sertifikayı ve TLS yapılandırmasını seçmek için bağlantı başına bir kez çağırılır. Varsayılan sertifikalar, ConfigureHttpsDefaults Bu geri çağırmada kullanılmaz.

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

SNı with `TlsHandshakeCallbackOptions`

Kestrel geri çağırma aracılığıyla ek dinamik TLS yapılandırmasını destekler TlsHandshakeCallbackOptions.OnConnection . Geri çağırma, uygulamanın ana bilgisayar adını incelemesine ve uygun sertifikayı, TLS yapılandırmasını ve diğer sunucu seçeneklerini seçmesini sağlamak için bağlantı başına bir kez çağrılır. Varsayılan sertifikalar, ConfigureHttpsDefaults Bu geri çağırmada kullanılmaz.

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

Yapılandırmada SNı

Kestrel yapılandırmada tanımlanan SNı destekler. Uç nokta, Sni ana bilgisayar adları ve https seçenekleri arasında eşleme içeren bir nesneyle yapılandırılabilir. Bağlantı ana bilgisayar adı seçeneklerle eşleştirilir ve bu bağlantı için kullanılır.

Aşağıdaki yapılandırma, MySniEndpoint ana bilgisayar adına göre https seçeneklerini seçmek için SNI kullanan adlı bir uç nokta ekler:

{
  "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": "<certificate password>"
            }
          },
          "*": {
            // 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": "<certificate password>"
      }
    }
  }
}

SNı tarafından geçersiz kılınabilen HTTPS seçenekleri:

Certificatesertifika kaynağınıyapılandırır.
Protocols izin verilen HTTP protokolleriniyapılandırır.
SslProtocols izin verilen SSL protokolleriniyapılandırır.
ClientCertificateModeistemci sertifikası gereksinimleriniyapılandırır.

Ana bilgisayar adı joker karakterle eşleştirmeyi destekler:

Tam eşleşme. Örneğin, a.example.org eşleşir a.example.org .
Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa, en uzun model seçilir. Örneğin, *.example.org ve ile b.example.org eşleşir c.example.org .
Tam joker karakter. * SNı kullanmayan ve ana bilgisayar adı göndermeyen istemciler dahil diğer her şeyi eşleştirir.

Eşleşen SNı yapılandırması, bağlantı için uç noktaya uygulanır ve uç noktada değerleri geçersiz kılar. Bir bağlantı yapılandırılmış SNı ana bilgisayar adıyla eşleşmiyorsa, bağlantı reddedilir.

SNı gereksinimleri

Hedef Framework netcoreapp2.1 veya sonraki sürümlerde çalışıyor. net461Veya sonraki sürümlerde, geri çağırma çağrılır, ancak name her zaman olur null . nameAyrıca, null ISTEMCI, TLS el sıkışmasının ana bilgisayar adı parametresini sağlamıyorsa de olur.
Tüm Web siteleri aynı örnek üzerinde çalışır Kestrel . Kestrel , bir IP adresinin ve bağlantı noktasının bir ters proxy olmadan birden çok örnek arasında paylaşılmasını desteklemez.

SSL/TLS protokolleri

SSL protokolleri iki eş arasındaki trafiği şifrelemek ve şifresini çözmek için kullanılan protokollerdir, geleneksel olarak bir istemci ve sunucu.

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": "<certificate password>"
        }
      }
    }
  }
}

Varsayılan değer, SslProtocols.None Kestrel en iyi Protokolü seçmek için işletim sistemi varsayılan değerlerini kullanılmasına neden olur. Bir protokol seçmek için özel bir nedeniniz yoksa, Varsayılanı kullanın.

İstemci Sertifikaları

ClientCertificateModeistemci sertifikası gereksinimleriniyapılandırır.

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": "<certificate password>"
        }
      }
    }
  }
}

Varsayılan değer, ClientCertificateMode.NoCertificate Kestrel istemciden bir sertifika istemeyecek veya gerektirmeyecek yerdir.

Daha fazla bilgi için bkz. ASP.NET Core sertifika kimlik doğrulamasını yapılandırma.

Bağlantı günlüğü

UseConnectionLoggingBir bağlantıda bayt düzeyinde iletişim Için hata ayıklama düzeyi günlüklerini yayma çağrısı. Bağlantı günlüğü, TLS şifreleme ve proxy 'nin arkasındaki gibi alt düzey iletişimde sorunları gidermeye yardımcı olur. UseConnectionLoggingDaha önce yerleştirilmişse UseHttps , şifrelenmiş trafik günlüğe kaydedilir. UseConnectionLoggingÖğesinden sonra yerleştirilmişse UseHttps , şifresi çözülmüş trafik günlüğe kaydedilir. Bu yerleşik bağlantı ara yazılımı.

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

TCP yuvasına bağlama

ListenYöntemi BIR TCP yuvasına bağlanır ve bir seçenek lambda X. 509.440 sertifika yapılandırmasına izin verir:

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

Örnek, HTTPS 'yi ile bir uç nokta için yapılandırır ListenOptions . Belirli uç noktalara yönelik diğer ayarları yapılandırmak için aynı API 'yi kullanın Kestrel .

Windows 'da, otomatik olarak imzalanan sertifikalar New-SelfSignedCertificate PowerShell cmdlet 'ikullanılarak oluşturulabilir. Desteklenmeyen bir örnek için bkz. UpdateIISExpressSSLForChrome.ps1.

MacOS, Linux ve Windows 'da, Sertifikalar OpenSSLkullanılarak oluşturulabilir.

UNIX yuvasına bağlama

ListenUnixSocketAşağıdaki örnekte gösterildiği gibi NGINX ile gelişmiş performans için ile birlikte bir UNIX yuvası dinleyin:

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

NGINX yapılandırma dosyasında, server > location > proxy_pass girdisini olarak ayarlayın http://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} , için belirtilen yuvanın adıdır ListenUnixSocket (örneğin, kestrel-test.sock Önceki örnekte).
Yuvanın NGINX tarafından yazılabilir olduğundan emin olun (örneğin, chmod go+w /tmp/kestrel-test.sock ).

Bağlantı noktası 0

Bağlantı noktası numarası 0 belirtildiğinde, Kestrel dinamik olarak kullanılabilir bir bağlantı noktasına bağlanır. Aşağıdaki örnek, çalışma zamanında hangi bağlantı noktasının bağlandığını nasıl belirleyeceğini göstermektedir Kestrel :

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

Uygulama çalıştırıldığında konsol penceresi çıkışı, uygulamanın erişilebileceği dinamik bağlantı noktasını gösterir:

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

Sınırlamalar

Aşağıdaki yaklaşımlar ile uç noktaları yapılandırın:

UseUrls
--urls komut satırı bağımsız değişkeni
urls Ana bilgisayar yapılandırma anahtarı
ASPNETCORE_URLS ortam değişkeni

Bu yöntemler, kodun dışındaki sunucularla kod çalışmasını sağlamak için yararlıdır Kestrel . Ancak, aşağıdaki sınırlamalara dikkat edin:

HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlanmamışsa (örneğin, KestrelServerOptions Bu makalede daha önce gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanılarak), https bu yaklaşımlar ile kullanılamaz.
Hem hem de Listen UseUrls yaklaşımları aynı anda kullanıldığında, uç noktalar Listen UseUrls uç noktaları geçersiz kılar.

IIS uç nokta yapılandırması

IIS kullanırken, IIS geçersiz kılma bağlamaları için URL bağlamaları veya ya da tarafından ayarlanır Listen UseUrls . daha fazla bilgi için bkz. ASP.NET Core modülü.

ListenOptions. Protocols

ProtocolsÖzelliği, HttpProtocols bir bağlantı uç noktasında veya sunucu IÇIN etkin HTTP protokollerini () belirler. ProtocolsSabit listesinden özelliğe bir değer atayın HttpProtocols .

`HttpProtocols` sabit listesi değeri	Bağlantı protokolü izin verildi
`Http1`	Yalnızca HTTP/1.1. , TLS olmadan veya ile kullanılabilir.
`Http2`	Yalnızca HTTP/2. Yalnızca istemci önceki bir bilgi modunuDESTEKLIYORSA, TLS olmadan kullanılabilir.
`Http1AndHttp2`	HTTP/1.1 ve HTTP/2. HTTP/2, istemcinin TLS uygulama katmanı protokol anlaşması (ALPN) el sıkışmasında http/2 seçmesini gerektirir; Aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 ' dir.

ListenOptions.ProtocolsHerhangi bir uç nokta için varsayılan değer HttpProtocols.Http1AndHttp2 .

HTTP/2 için TLS kısıtlamaları:

TLS sürüm 1,2 veya üzeri
Yeniden anlaşma devre dışı
Sıkıştırma devre dışı
En az kısa ömürlü anahtar değişim boyutları:
- Eliptik Eğri Diffie-Hellman (ECDHE) [ RFC4492 ] : 224 bit minimum
- Sınırlı alan Diffie-Hellman (DHE) [ TLS12 ] : 2048 bit minimum
Şifre paketi yasaklandı.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE] P-256 eliptik eğrisi [ FIPS186 ] Varsayılan olarak desteklenir.

Aşağıdaki örnek, 8000 numaralı bağlantı noktasında HTTP/1.1 ve HTTP/2 bağlantılarına izin verir. Bağlantılar, sağlanan bir sertifikayla TLS ile güvenlidir:

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

Linux 'ta, CipherSuitesPolicy TLS el sıkışmaları her bağlantı temelinde filtrelemek için kullanılabilir:

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

Bağlantı ara yazılımı

Özel bağlantı ara yazılımı, gerekirse belirli şifrelemeler için bağlantı başına TLS el sıkışmaları filtreleyebilir.

Aşağıdaki örnek, NotSupportedException uygulamanın desteklemediği herhangi bir şifre algoritması için oluşturur. Alternatif olarak, ılshandshakefeature. CipherAlgorithm öğesini kabul edilebilir şifreleme paketleri listesi ile tanımlayın ve karşılaştırın.

CipherAlgorithmType. null şifre algoritması ile hiçbir şifreleme kullanılmaz.

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

Bağlantı filtrelemesi, bir lambda aracılığıyla da yapılandırılabilir IConnectionBuilder :

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

HTTP protokolünü yapılandırmadan ayarla

CreateDefaultBuilder``serverOptions.Configure(context.Configuration.GetSection("Kestrel"))yapılandırmayı yüklemek için varsayılan olarak çağırır Kestrel .

Aşağıdaki appsettings.json örnek, tüm uç noktalar için varsayılan bağlantı protokolü olarak http/1.1 'yi kurar:

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

Aşağıdaki appsettings.json örnek, belirli bir uç nokta IÇIN http/1.1 bağlantı protokolünü belirler:

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

Yapılandırma tarafından ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

URL önekleri

UseUrls, --urls Komut satırı bağımsız değişkeni, urls ana bilgisayar yapılandırma anahtarı veya ASPNETCORE_URLS ortam değişkeni kullanılırken, URL önekleri aşağıdaki biçimlerden birinde olabilir.

Yalnızca HTTP URL ön ekleri geçerlidir. Kestrel , kullanılarak URL bağlamaları yapılandırılırken HTTPS 'YI desteklemez UseUrls .

Bağlantı noktası numarası olan IPv4 adresi
```
http://65.55.39.10:80/
```
0.0.0.0 Tüm IPv4 adreslerine bağlanan özel bir durumdur.
Bağlantı noktası numarasına sahip IPv6 adresi
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] , IPv4 'un IPv6 eşdeğeridir 0.0.0.0 .
Bağlantı noktası numarası olan ana bilgisayar adı
```
http://contoso.com:80/
http://*:80/
```
, Ve ana bilgisayar adları * + özel değildir. Geçerli bir IP adresi olarak tanınmayan veya localhost tüm IPv4 ve IPv6 IP 'lerine bağlanan her şey. farklı ana bilgisayar adlarını aynı bağlantı noktasında farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya bir ters proxy sunucusu kullanın. Ters proxy sunucu örnekleri IIS, NGINX veya Apache içerir.

Uyarı

Ters Proxy yapılandırmasında barındırma, konak filtrelemeyigerektirir.
Port numarası localhost veya bağlantı noktası numarası ile geri döngü IP 'si olan ana bilgisayar adı
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
localhostBelirtildiğinde, Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlamayı dener. İstenen bağlantı noktası, herhangi bir geri döngü arabirimindeki başka bir hizmet tarafından kullanılıyorsa Kestrel başlatılamıyor. Herhangi bir geri döngü arabirimi başka bir nedenle kullanılamıyorsa (genellikle IPv6 desteklenmediği için), Kestrel bir uyarı kaydeder.