ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma

Makale
11/06/2024

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Kestrel uç noktalar, gelen istekleri dinlemek ve uygun ara yazılıma yönlendirmek için altyapı sağlar. Adres ve protokol birleşimi bir uç noktayı tanımlar.

Adres, sunucunun TCP bağlantı noktası gibi gelen istekler için dinlediği ağ arabirimini belirtir.
Protokol http/1.1, HTTP/2 veya HTTP/3 gibi istemci ve sunucu arasındaki iletişimi belirtir.
Url şeması veya UseHttps yöntemi kullanılarak bir uç noktanın https güvenliği sağlanabilir.

Uç noktalar URL'ler, içindeki JSON appsettings.jsonve kod kullanılarak yapılandırılabilir. Bu makalede, bir uç noktayı yapılandırmak için her seçeneğin nasıl kullanılacağı açıklanır:

Uç noktaları yapılandırma
HTTPS'yi yapılandırma
HTTP protokollerini yapılandırma

Varsayılan uç nokta

Yeni ASP.NET Core projeleri, 5000-5300 arasında rastgele bir HTTP bağlantı noktasına ve 7000-7300 arasında rastgele bir HTTPS bağlantı noktasına bağlanacak şekilde yapılandırılır. Seçilen bağlantı noktaları oluşturulan Properties/launchSettings.json dosyada depolanır ve geliştirici tarafından değiştirilebilir. Dosya launchSetting.json yalnızca yerel geliştirmede kullanılır.

Uç nokta yapılandırması yoksa öğesine Kestrel bağlanır http://localhost:5000.

Uç noktaları yapılandırma

Kestrel uç noktalar gelen bağlantıları dinler. Uç nokta oluşturulduğunda, dinleyeceği adresle yapılandırılması gerekir. Bu genellikle bir TCP adresi ve bağlantı noktası numarasıdır.

Uç noktaları yapılandırmak için çeşitli seçenekler vardır:

UÇ noktaları URL'lerle yapılandırma
Yalnızca bağlantı noktalarını belirtin
appsettings.json'de uç noktaları yapılandırma
Kodda uç noktaları yapılandırma

UÇ noktaları URL'lerle yapılandırma

Aşağıdaki bölümlerde, kullanarak uç noktaların nasıl yapılandır yapılacağı açıklanmaktadır:

ASPNETCORE_URLS ortam değişkeni.
--urls komut satırı bağımsız değişkeni.
urls ana bilgisayar yapılandırma anahtarı.
UseUrls uzantı yöntemi.
WebApplication.Urls mülk.

URL biçimleri

URL'ler, sunucunun dinlemesi gereken bağlantı noktaları ve protokollere sahip IP veya konak adreslerini gösterir. Protokol için varsayılan bağlantı noktasıysa (genellikle 80 ve 443) bağlantı noktası atlanabilir. URL'ler aşağıdaki biçimlerden herhangi birinde olabilir.

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ıyla IPv6 adresi
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.
Bağlantı noktası numarasına sahip joker konak
```
http://contoso.com:80/
http://*:80/
```
Geçerli bir IP adresi olarak tanınmayan veya localhost tüm IPv4 ve IPv6 adreslerine bağlanan joker karakter olarak kabul edilen her şey. Bazı kişiler kullanmak * veya + daha açık olmak ister. Farklı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya ters ara sunucu kullanın.

Ters ara sunucu örnekleri IIS, YARP, Nginx ve Apache'dir.
Bağlantı noktası numarası veya bağlantı noktası numarası ile geri döngü IP'siyle ana bilgisayar adı localhost
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Geri döngü arabirimi herhangi bir nedenle kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

Noktalı virgül (;) sınırlayıcı kullanılarak birden çok URL ön eki belirtilebilir:

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

Daha fazla bilgi için bkz . Yapılandırmayı geçersiz kılma.

HTTPS URL ön ekleri

HTTPS URL ön ekleri yalnızca HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlandığında uç noktaları tanımlamak için kullanılabilir. Örneğin, bu makalenin ilerleyen bölümlerinde gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanınKestrelServerOptions.

Daha fazla bilgi için bkz . HTTPS'yi yapılandırma.

Yalnızca bağlantı noktalarını belirtin

Uygulamalara ve kapsayıcılara genellikle konak veya yol gibi ek kısıtlamalar olmadan yalnızca 80 numaralı bağlantı noktası gibi dinlemeleri için bir bağlantı noktası verilir. HTTP_PORTS ve HTTPS_PORTS, ve HTTP.sys sunucuları için Kestrel dinleme bağlantı noktalarını belirten yapılandırma anahtarlarıdır. Bu anahtarlar, veya ASPNETCORE_ ön ekleriyle DOTNET_ tanımlanan ortam değişkenleri olarak belirtilebilir veya gibi appsettings.jsonbaşka bir yapılandırma girişi aracılığıyla doğrudan belirtilebilir. Her biri, aşağıdaki örnekte gösterildiği gibi noktalı virgülle ayrılmış bağlantı noktası değerleri listesidir:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Yukarıdaki örnek, şemayı (HTTP veya HTTPS) ve herhangi bir konağı veya IP'yi belirten aşağıdaki yapılandırmanın kısaltmasıdır.

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

HTTP_PORTS ve HTTPS_PORTS yapılandırma anahtarları daha düşük önceliklidir ve doğrudan kodda sağlanan URL'ler veya değerler tarafından geçersiz kılınabilir. Sertifikaların yine de HTTPS için sunucuya özgü mekanikler aracılığıyla ayrı olarak yapılandırılması gerekir.

appsettings.json'de uç noktaları yapılandırma

Kestrel bir IConfiguration örnekten uç noktaları yükleyebilir. Varsayılan olarak, Kestrel yapılandırma bölümünden Kestrel yüklenir ve uç noktalar içinde Kestrel:Endpointsyapılandırılır:

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

Yukarıdaki örnek:

Yapılandırma kaynağı olarak kullanır appsettings.json . Ancak, herhangi bir IConfiguration kaynak kullanılabilir.
8080 numaralı bağlantı noktasına adlı MyHttpEndpoint bir uç nokta ekler.

JSON ile uç noktaları yapılandırma hakkında daha fazla bilgi için, bu makalede https yapılandırmayı ve appsettings.json'de HTTP protokollerini yapılandırmayı ele alan sonraki bölümlere bakın.

Uç noktaları yapılandırmadan yeniden yükleme

Yapılandırma kaynağı değiştiğinde uç nokta yapılandırması varsayılan olarak yeniden yükleniyor. kullanılarak KestrelServerOptions.Configure(IConfiguration, Boolean)devre dışı bırakılabilir.

Bir değişiklik sinyali alınırsa aşağıdaki adımlar uygulanır:

Yeni yapılandırma eski yapılandırmayla karşılaştırılır ve yapılandırma değişikliği olmayan uç noktalar değiştirilmez.
Kaldırılan veya değiştirilen uç noktalara işleme isteklerini tamamlamak ve kapatmak için 5 saniye verilir.
Yeni veya değiştirilmiş uç noktalar başlatılır.

Değiştirilen uç noktaya bağlanan istemcilerin bağlantısı kesilebilir veya uç nokta yeniden başlatılırken reddedilebilir.

ConfigurationLoader

KestrelServerOptions.Configure bir KestrelConfigurationLoaderdöndürür. Yükleyicinin Endpoint(String, Action<EndpointConfiguration>) , yapılandırılmış bir uç noktanın ayarlarını desteklemek için kullanılabilecek yöntemi:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader , tarafından WebApplicationBuilder.WebHostsağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemindeki Endpoint seçeneklerde kullanılabilir.
KestrelServerOptions.Configure(IConfiguration) birden çok kez çağrılabilir, ancak önceki örneklerde açıkça çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Varsayılan ana bilgisayar, varsayılan yapılandırma bölümünün değiştirilebilmesi için çağrı Load yapmaz.
KestrelConfigurationLoaderListen, API KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Kodda uç noktaları yapılandırma

KestrelServerOptions kodda uç noktaları yapılandırmak için yöntemler sağlar:

Hem hem de Listen UseUrls API'leri aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.

TCP yuvasına bağlama

Listen, ListenLocalhostve ListenAnyIP yöntemleri bir TCP yuvasına bağlanır:

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

Yukarıdaki örnek:

5000 ve 5001 numaralı bağlantı noktalarını dinleyen uç noktaları yapılandırılır.
üzerinde uzantı yöntemiyle bir uç nokta için HTTPS'yi UseHttps yapılandırıyor ListenOptions. Daha fazla bilgi için bkz . Kodda HTTPS'yi yapılandırma.

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

macOS, Linux ve Windows'da sertifikalar OpenSSL kullanılarak oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket dinleyin:

var builder = WebApplication.CreateBuilder(args);

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

Nginx yapılandırma dosyasında girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET} , verilen ListenUnixSocket yuvanın adıdır (ö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).

Uç nokta varsayılanlarını yapılandırma

ConfigureEndpointDefaults(Action<ListenOptions>) belirtilen her uç nokta için çalışan yapılandırmayı belirtir. Birden çok kez çağrılması ConfigureEndpointDefaults önceki yapılandırmanın yerini alır.

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureEndpointDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Dinamik bağlantı noktası bağlama

Bağlantı noktası numarası 0 belirtildiğinde, Kestrel kullanılabilir bir bağlantı noktasına dinamik olarak bağlanır. Aşağıdaki örnekte çalışma zamanında hangi bağlantı noktası Kestrel bağlı olduğunu belirleme adımları gösterilmektedir:

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

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

        // ...
    }
});

Bağlantı noktasını dinamik olarak bağlama bazı durumlarda kullanılamaz:

KestrelServerOptions.ListenLocalhost
TCP tabanlı HTTP/1.1 veya HTTP/2 ve QUIC tabanlı HTTP/3'ün birbirine bağlanması.

HTTPS’yi yapılandırma

Kestrel HTTPS ile uç noktaların güvenliğini sağlamayı destekler. HTTPS üzerinden gönderilen veriler, istemci ile sunucu arasında aktarılan verilerin güvenliğini artırmak için Aktarım Katmanı Güvenliği (TLS) kullanılarak şifrelenir.

HTTPS bir TLS sertifikası gerektirir. TLS sertifikası sunucuda depolanır ve Kestrel bunu kullanacak şekilde yapılandırılır. Bir uygulama, yerel geliştirme ortamında ASP.NET Core HTTPS geliştirme sertifikasını kullanabilir. Geliştirme sertifikası, geliştirme olmayan ortamlarda yüklü değildir. Üretimde bir TLS sertifikası açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

HTTPS ve TLS sertifikasının yapılandırılma şekli, uç noktaların nasıl yapılandırıldığına bağlıdır:

URL ön ekleri veya bağlantı noktalarını belirtme yalnızca uç noktaları tanımlamak için kullanılıyorsa, HTTPS yalnızca HTTPS uç nokta yapılandırmasında varsayılan bir sertifika sağlandığında kullanılabilir. Varsayılan sertifika aşağıdaki seçeneklerden biriyle yapılandırılabilir:
appsettings.json'de HTTPS'yi yapılandırma
Kodda HTTPS'yi yapılandırma

appsettings.json'de HTTPS'yi yapılandırma

için Kestrelvarsayılan BIR HTTPS uygulama ayarları yapılandırma şeması sağlanır. Disk üzerindeki bir dosyadan veya bir sertifika deposundan URL'ler ve kullanılacak sertifikalar dahil olmak üzere birden çok uç nokta yapılandırın.

Sertifika belirtmeyen herhangi bir HTTPS uç noktası (HttpsDefaultCert aşağıdaki örnekte) veya geliştirme sertifikası altında Certificates:Default tanımlanan sertifikaya geri döner.

Aşağıdaki örnek içindir appsettings.json, ancak herhangi bir yapılandırma kaynağı kullanılabilir:

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

Uyarı

Yukarıdaki örnekte, sertifika parolası içinde appsettings.jsondüz metin olarak depolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

Şema notları

Uç nokta adları büyük /küçük harfe duyarlı değildir. Örneğin ve HTTPS Https eşdeğerdir.
Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst düzey Urls yapılandırma parametresiyle aynıdır. Bu makalenin önceki bölümlerinde yer alan URL biçimlerine bakın.
Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, içinde Certificates:Default tanımlanan 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şlatılamaz.
Certificate bölümü birden çok sertifika kaynağını destekler.
Bağlantı noktası çakışmalarına neden olmayan herhangi bir sayıda uç nokta içinde Configurationtanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, çeşitli kaynaklardan sertifika yüklenecek şekilde yapılandırılabilir:

Pathve Password .pfx dosyalarını yüklemek için.
Pathve KeyPath .pem.crt/ ve .key dosyalarını yüklemek için.Password
Subject ve Store sertifika deposundan 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>"
}

appsettings.json'de istemci sertifikalarını yapılandırma

ClientCertificateMode , istemci sertifikası davranışını yapılandırmak için kullanılır.

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

Uyarı

Varsayılan değer, istemciden sertifika istemediği veya gerektirmediği Kestrel değeridirClientCertificateMode.NoCertificate.

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

appsettings.json'de SSL/TLS protokollerini yapılandırma

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

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

Uyarı

varsayılan değeri, SslProtocols.Noneen iyi protokolü seçmek için işletim sistemi varsayılanlarının kullanılmasına neden olur Kestrel . Protokol seçmek için belirli bir nedeniniz yoksa varsayılanı kullanın.

Kodda HTTPS'yi yapılandırma

API kullanılırken Listen , https'yi UseHttps yapılandırmak için üzerindeki ListenOptions uzantı yöntemi kullanılabilir.

var builder = WebApplication.CreateBuilder(args);

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

ListenOptions.UseHttps 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 , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. ListenOptionsdöndürür.
storeName , sertifikanın yüklendiği sertifika deposudur.
subject sertifikanın konu adıdır.
allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
location , sertifikanın yüklenecek depo konumudur.
serverCertificate X.509 sertifikasıdır.

Aşırı yüklemelerin UseHttps tam listesi için bkz UseHttps. .

Kodda istemci sertifikalarını yapılandırma

ClientCertificateMode istemci sertifikası gereksinimlerini yapılandırmaktadır.

var builder = WebApplication.CreateBuilder(args);

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

Varsayılan değer, istemciden sertifika istemediği veya gerektirmediği Kestrel değeridirNoCertificate.

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

Kodda HTTPS varsayılanlarını yapılandırma

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>), her HTTPS uç noktası için çalıştırılacak bir yapılandırma Action belirtir. Birden çok kez çağrılması ConfigureHttpsDefaults , önceki Action örneklerin yerini belirtilen son Action örnekle değiştirir.

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureHttpsDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Kodda SSL/TLS protokollerini yapılandırma

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

var builder = WebApplication.CreateBuilder(args);

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

Kodda TLS şifreleme paketleri filtresini yapılandırma

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına göre filtrelemek için kullanılabilir:

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

Sunucu Adı Gösterimini Yapılandır

Sunucu Adı Göstergesi (SNI), aynı IP adresi ve bağlantı noktasında birden çok etki alanını barındırmak için kullanılabilir. SNI, bir sunucudan birden çok siteye hizmet vererek kaynakları korumak için kullanılabilir.

SNI'nin çalışması için istemci, sunucunun doğru sertifikayı sağlayabilmesi için TLS el sıkışması sırasında güvenli oturum için ana bilgisayar adını sunucuya gönderir. İstemci, TLS el sıkışmasını izleyen güvenli oturum sırasında sunucuyla şifreli iletişim için döşenmiş sertifikayı kullanır.

Tüm web siteleri aynı Kestrel örnekte çalıştırılmalıdır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.

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

Yapılandırma'da konak adları ve HTTPS seçenekleri arasında bir eşleme yapılandırın. Örneğin, dosyadaki appsettings.json JSON.
Kodda bir uç nokta oluşturun ve geri arama ile ServerCertificateSelector konak adını kullanarak bir sertifika seçin.

appsettings.json'de SNI'yi yapılandırma

Kestrel yapılandırmada tanımlanan SNI'leri destekler. Uç nokta, konak adları ve HTTPS seçenekleri arasında eşleme içeren bir nesneyle Sni 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, konak adına göre HTTPS seçeneklerini seçmek için SNI kullanan adlı MySniEndpoint 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": "$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$"
      }
    }
  }
}

Uyarı

SNI tarafından geçersiz kılınabilecek HTTPS seçenekleri:

Certificatesertifika kaynağını yapılandırıyor.
Protocols izin verilen HTTP protokollerini yapılandırıyor.
SslProtocols izin verilen SSL protokollerini yapılandırıyor.
ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Tam eşleşme. Örneğin, a.example.org ile eşleşir a.example.org.
Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa en uzun desen seçilir. Örneğin, *.example.org ve c.example.orgile eşleşirb.example.org.
Tam joker karakter. * , SNI kullanmayan ve ana bilgisayar adı göndermeyen istemciler de dahil olmak üzere diğer her şeyle eşleşir.

Eşleşen SNI yapılandırması, bağlantının uç noktasına uygulanır ve uç nokta üzerindeki değerleri geçersiz kılılır. Bir bağlantı yapılandırılmış bir SNI ana bilgisayar adıyla eşleşmiyorsa, bağlantı reddedilir.

SNI'yi kodla yapılandırma

Kestrel birkaç geri çağırma API'siyle SNI'yı destekler:

ServerCertificateSelector
ServerOptionsSelectionCallback
TlsHandshakeCallbackOptions

SNI ile `ServerCertificateSelector`

Kestrel geri çağırma yoluyla SNI'yi ServerCertificateSelector destekler. Uygulamanın ana bilgisayar adını incelemesine ve uygun sertifikayı seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır:

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 ile `ServerOptionsSelectionCallback`

Kestrel geri çağırma yoluyla ServerOptionsSelectionCallback ek dinamik TLS yapılandırmasını destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı ve TLS yapılandırmasını seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır. Varsayılan sertifikalar ve ConfigureHttpsDefaults bu geri çağırma ile kullanılmaz.

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 ile `TlsHandshakeCallbackOptions`

Kestrel geri çağırma yoluyla TlsHandshakeCallbackOptions.OnConnection ek dinamik TLS yapılandırmasını destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı, TLS yapılandırmasını ve diğer sunucu seçeneklerini seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır. Varsayılan sertifikalar ve ConfigureHttpsDefaults bu geri çağırma ile kullanılmaz.

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

HTTP protokollerini yapılandırma

Kestrel yaygın olarak kullanılan tüm HTTP sürümlerini destekler. Uç noktalar, kullanılabilir HTTP sürümü seçeneklerini belirten sabit listesi kullanılarak HttpProtocols farklı HTTP sürümlerini destekleyecek şekilde yapılandırılabilir.

Birden fazla HTTP sürümünü desteklemek için TLS gereklidir. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır.

`HttpProtocols` değer	Bağlantı protokolüne izin verilir
`Http1`	Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
`Http2`	Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa kullanılabilir.
`Http3`	Yalnızca HTTP/3. TLS gerektirir. İstemcinin yalnızca HTTP/3 kullanacak şekilde yapılandırılması gerekebilir.
`Http1AndHttp2`	HTTP/1.1 ve HTTP/2. HTTP/2, istemcinin TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışmasında HTTP/2'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olur.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 ve HTTP/3. İlk istemci isteği normalde HTTP/1.1 veya HTTP/2 kullanır ve `alt-svc` yanıt üst bilgisi istemciden HTTP/3'e yükseltmesini ister. HTTP/2 ve HTTP/3 TLS gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1'dir.

Uç nokta için varsayılan protokol değeri şeklindedir HttpProtocols.Http1AndHttp2.

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

TLS sürüm 1.2 veya üzeri
Yeniden anlaşma devre dışı bırakıldı
Sıkıştırma devre dışı bırakıldı
Minimum kısa ömürlü anahtar değişimi boyutları:
- Eliptik eğri Diffie-Hellman (ECDHE) [RFC4492]: en az 224 bit
- Sonlu alan Diffie-Hellman (DHE) [TLS12]: 2048 bit minimum
Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta eğrisi [FIPS186] varsayılan olarak desteklenir.

appsettings.json'de HTTP protokollerini yapılandırma

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Bölümünde varsayılan bir protokol yapılandırılabilir Kestrel:EndpointDefaults . Aşağıdaki appsettings.json örnek, tüm uç noktalar için varsayılan bağlantı protokolü olarak HTTP/1.1'i oluşturur:

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

Yapılandırmaya göre ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

Kodda HTTP protokollerini yapılandırma

ListenOptions.Protocols , sabit listesiyle HttpProtocols protokolleri belirtmek için kullanılır.

Aşağıdaki örnek, bağlantı noktası 8000'de HTTP/1.1, HTTP/2 ve HTTP/3 bağlantıları için bir uç nokta yapılandırılır. Bağlantıların güvenliği, sağlanan bir sertifikayla TLS tarafından sağlanır:

var builder = WebApplication.CreateBuilder(args);

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

Ayrıca bkz.

ASP.NET Core projeleri, 5000-5300 arasında rastgele bir HTTP bağlantı noktasına ve 7000-7300 arasında rastgele bir HTTPS bağlantı noktasına bağlanacak şekilde yapılandırılır. Bu varsayılan yapılandırma, oluşturulan Properties/launchSettings.json dosyada belirtilir ve geçersiz kılınabilir. Bağlantı noktası belirtilmezse, Kestrel öğesine http://localhost:5000bağlanır.

URL'leri belirtmek için şunları kullanın:

ASPNETCORE_URLS ortam değişkeni.
--urls komut satırı bağımsız değişkeni.
urls ana bilgisayar yapılandırma anahtarı.
UseUrls uzantı 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 olarak yapılandırın (örneğin, "Urls": "http://localhost:8000;http://localhost:8001").

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

Geliştirme sertifikası oluşturulur:

.NET SDK'sı yüklendiğinde.
Dev-certs aracı bir sertifika oluşturmak için kullanılır.

Geliştirme sertifikası yalnızca sertifikayı oluşturan kullanıcı tarafından kullanılabilir. Bazı tarayıcılar, yerel geliştirme sertifikasına güvenmek için açık izin verilmesini gerektirir.

Proje şablonları, uygulamaları varsayılan olarak HTTPS üzerinde çalışacak şekilde yapılandırıp HTTPS yeniden yönlendirme ve HSTS desteği içerir.

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

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

KestrelServerOptions konfigürasyon:

ConfigureEndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>) belirtilen her uç nokta için çalıştırılacak yapılandırmayı Action belirtir. Birden çok kez çağrılması ConfigureEndpointDefaults , öncekilerin Actionyerini belirtilen son Action değerle değiştirir:

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureEndpointDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Configure(IConfiguration)

uç noktalarının bir IConfigurationiçinden yüklenmesini sağlarKestrel. Yapılandırmanın kapsamı için Kestrelyapılandırma bölümü olarak belirlenmiş olmalıdır. Aşırı Configure(IConfiguration, bool) yükleme, yapılandırma kaynağı değiştiğinde uç noktaların yeniden yüklenmesini etkinleştirmek için kullanılabilir.

Varsayılan olarak, Kestrel yapılandırma bölümünden Kestrel yüklenir ve değişiklikler yeniden yüklenir:

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

Yapılandırmayı yeniden yükleme etkinleştirildiyse ve bir değişiklik sinyali verirseniz aşağıdaki adımlar uygulanır:

Yeni yapılandırma eski yapılandırmayla karşılaştırılır, yapılandırma değişikliği olmayan tüm uç noktalar değiştirilmez.
Kaldırılan veya değiştirilen uç noktalara işleme isteklerini tamamlamak ve kapatmak için 5 saniye verilir.
Yeni veya değiştirilmiş uç noktalar başlatılır.

Değiştirilen uç noktaya bağlanan istemcilerin bağlantısı kesilebilir veya uç nokta yeniden başlatılırken reddedilebilir.

YapılandırmaHttpsDefaults

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) her HTTPS uç noktası için çalıştırılacak bir yapılandırma Action belirtir. Birden çok kez çağrılması ConfigureHttpsDefaults , öncekileri Actionbelirtilen son Action değerle değiştirir.

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureHttpsDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

ListenOptions.UseHttps

HTTPS kullanmak için yapılandırın Kestrel .

ListenOptions.UseHttps Uzantı -ları:

UseHttps: HTTPS'yi varsayılan sertifikayla kullanacak şekilde yapılandırın Kestrel . 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 , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. ListenOptionsdöndürür.
storeName , sertifikanın yüklendiği sertifika deposudur.
subject sertifikanın konu adıdır.
allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
location , sertifikanın yüklenecek depo konumudur.
serverCertificate X.509 sertifikasıdır.

Üretimde HTTPS açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

Sertifikalar, Windows Sertifika Deposu'ndan farklı olarak diskten okunuyorsa, yetkisiz erişimi önlemek için ilgili dizinin uygun izinlere sahip olması gerekir.

Desteklenen yapılandırmalar aşağıda açıklanmıştır:

Yapılandırma yok
Varsayılan sertifikayı yapılandırmadan değiştirme
Koddaki varsayılanları değiştirme

Yapılandırma yok

Kestrel üzerinde http://localhost:5000dinler.

Varsayılan sertifikayı yapılandırmadan değiştirme

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

true Geçersiz sertifikaların (örneğin, otomatik olarak imzalanan sertifikalar) kullanılmasına izin vermek için olarak ayarlayınAllowInvalid.
Sertifika belirtmeyen herhangi bir HTTPS uç noktası (HttpsDefaultCert aşağıdaki örnekte) veya geliştirme sertifikası altında Certificates:Default tanımlanan sertifikaya geri döner.

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

Uyarı

Yukarıdaki örnekte, sertifika parolaları içinde düz metin olarak appsettings.jsondepolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , her sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

Şema notları:

Uç nokta adları büyük /küçük harfe duyarlı değildir. Örneğin ve HTTPS Https eşdeğerdir.
Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst düzey Urls yapılandırma parametresiyle aynıdır.
Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, içinde Certificates:Default tanımlanan 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şlatılamaz.
Certificate bölümü birden çok sertifika kaynağını destekler.
Bağlantı noktası çakışmalarına neden olmadığı sürece yapılandırmada herhangi bir sayıda uç nokta tanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, çeşitli kaynaklardan sertifika yüklenecek şekilde yapılandırılabilir:

Pathve Password .pfx dosyalarını yüklemek için.
Pathve KeyPath .pem.crt/ ve .key dosyalarını yüklemek için.Password
Subject ve Store sertifika deposundan 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

Configure(IConfiguration)KestrelConfigurationLoader, yapılandırılmış bir Endpoint(String, Action<EndpointConfiguration>) uç noktanın ayarlarını desteklemek için kullanılabilecek bir yöntemle döndürür:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader , tarafından WebApplicationBuilder.WebHostsağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemindeki Endpoint seçeneklerde kullanılabilir.
Başka bir bölümle yeniden çağrılarak Configure(IConfiguration) birden çok yapılandırma yüklenebilir. Önceki örneklerde açıkça çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Meta paket çağrısı Load yapmaz, böylece varsayılan yapılandırma bölümü değiştirilebilir.
KestrelConfigurationLoaderListen, API KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Koddaki varsayılanları değiştirme

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

var builder = WebApplication.CreateBuilder(args);

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

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

Sunucu Adı Göstergesini kullanarak uç noktaları yapılandırma

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

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

Kodda bir uç nokta oluşturun ve geri arama ile ServerCertificateSelector konak adını kullanarak bir sertifika seçin.
Yapılandırma'da konak adları ve HTTPS seçenekleri arasında bir eşleme yapılandırın. Örneğin, dosyadaki appsettings.json JSON.

SNI ile `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

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

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

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

SNI ile `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

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

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

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

SNI ile `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

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

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

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

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

Yapılandırmada SNI

Aşağıdaki yapılandırma, konak adına göre HTTPS seçeneklerini seçmek için SNI kullanan adlı MySniEndpoint 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": "$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$"
      }
    }
  }
}

Uyarı

SNI tarafından geçersiz kılınabilecek HTTPS seçenekleri:

Certificatesertifika kaynağını yapılandırıyor.
Protocols izin verilen HTTP protokollerini yapılandırıyor.
SslProtocols izin verilen SSL protokollerini yapılandırıyor.
ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Tam eşleşme. Örneğin, a.example.org ile eşleşir a.example.org.
Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa en uzun desen seçilir. Örneğin, *.example.org ve c.example.orgile eşleşirb.example.org.
Tam joker karakter. * , SNI kullanmayan ve ana bilgisayar adı göndermeyen istemciler de dahil olmak üzere diğer her şeyle eşleşir.

SNI gereksinimleri

Tüm web siteleri aynı Kestrel örnekte çalıştırılmalıdır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.

SSL/TLS Protokolleri

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

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

Uyarı

İstemci Sertifikaları

ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Uyarı

Varsayılan değer, istemciden sertifika istemeyeceği veya gerektirmeyeceği yerdir ClientCertificateMode.NoCertificate Kestrel .

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

Bağlantı günlüğü

Bağlantıda bayt düzeyi iletişim için Hata ayıklama düzeyi günlükleri yaymak için çağrısı UseConnectionLogging yapın. Bağlantı günlüğü, TLS şifrelemesi sırasında ve ara sunucuların arkasında olduğu gibi düşük düzeyli iletişim sorunlarını gidermek için yararlıdır. önüne UseHttpsyerleştirilirse UseConnectionLogging şifrelenmiş trafik günlüğe kaydedilir. sonra yerleştirilirse UseConnectionLogging UseHttps, şifresi çözülen trafik günlüğe kaydedilir. Bu yerleşik Bağlantı Ara Yazılımı'dır.

var builder = WebApplication.CreateBuilder(args);

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

TCP yuvasına bağlama

Listen yöntemi bir TCP yuvasına bağlanır ve lambda seçenekleri X.509 sertifika yapılandırmasına izin verir:

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

Örnek, ile ListenOptionsbir uç nokta için HTTPS'yi yapılandırıyor. Belirli uç noktaların diğer Kestrel ayarlarını yapılandırmak için aynı API'yi kullanın.

macOS, Linux ve Windows'da sertifikalar OpenSSL kullanılarak oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket dinleyin:

var builder = WebApplication.CreateBuilder(args);

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

Nginx yapılandırma dosyasında girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET} , verilen ListenUnixSocket yuvanın adıdır (ö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

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

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

        // ...
    }
});

Bağlantı noktasını dinamik olarak bağlama bazı durumlarda kullanılamaz:

ListenLocalhost
TCP tabanlı HTTP/1.1 veya HTTP/2 ve QUIC tabanlı HTTP/3'ün birbirine bağlanması.

Sınırlamalar

Uç noktaları aşağıdaki yaklaşımlarla yapılandırın:

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

Bu yöntemler, dışındaki Kestrelsunucularla kod çalışması için kullanışlıdır. Ancak aşağıdaki sınırlamalara dikkat edin:

HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlanmadığı sürece (örneğin, bu makalede daha önce gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanma KestrelServerOptions ) HTTPS bu yaklaşımlarla kullanılamaz.
Hem hem de Listen yaklaşımları aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.UseUrls

IIS uç noktası yapılandırması

IIS kullanırken, IIS geçersiz kılma bağlamaları için URL bağlamaları veya UseUrlstarafından Listen ayarlanır. Daha fazla bilgi için bkz . ASP.NET Çekirdek Modülü.

ListenOptions.Protocols

özelliği, Protocols bir bağlantı uç noktasında veya sunucu için etkinleştirilen HTTP protokollerini (HttpProtocols) oluşturur. Enum'dan özelliğine Protocols bir değer atayın HttpProtocols .

`HttpProtocols` sabit listesi değeri	Bağlantı protokolüne izin verilir
`Http1`	Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
`Http2`	Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa kullanılabilir.
`Http3`	Yalnızca HTTP/3. TLS gerektirir. İstemcinin yalnızca HTTP/3 kullanacak şekilde yapılandırılması gerekebilir.
`Http1AndHttp2`	HTTP/1.1 ve HTTP/2. HTTP/2, istemcinin TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışmasında HTTP/2'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olur.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 ve HTTP/3. İlk istemci isteği normalde HTTP/1.1 veya HTTP/2 kullanır ve `alt-svc` yanıt üst bilgisi istemciden HTTP/3'e yükseltmesini ister. HTTP/2 ve HTTP/3 TLS gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1'dir.

Herhangi bir uç nokta için varsayılan ListenOptions.Protocols değer şeklindedir HttpProtocols.Http1AndHttp2.

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

TLS sürüm 1.2 veya üzeri
Yeniden anlaşma devre dışı bırakıldı
Sıkıştırma devre dışı bırakıldı
Minimum kısa ömürlü anahtar değişimi boyutları:
- Eliptik eğri Diffie-Hellman (ECDHE) [RFC4492]: en az 224 bit
- Sonlu alan Diffie-Hellman (DHE) [TLS12]: 2048 bit minimum
Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta 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ın güvenliği, sağlanan bir sertifikayla TLS tarafından sağlanır:

var builder = WebApplication.CreateBuilder(args);

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

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına göre filtrelemek için kullanılabilir:

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

Bağlantı Ara Yazılımı

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

Aşağıdaki örnek, uygulamanın desteklemediği herhangi bir şifreleme algoritması için oluşturur NotSupportedException . Alternatif olarak, kabul edilebilir şifreleme paketlerinin listesini tanımlayın ve karşılaştırın ITlsHandshakeFeature.CipherAlgorithm .

Şifreleme algoritması ile CipherAlgorithmType.Null şifreleme kullanılmaz.

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

Yapılandırmadan HTTP protokollerini ayarlama

Varsayılan olarak, Kestrel yapılandırma bölümünden Kestrel yüklenir. Aşağıdaki appsettings.json örnek, tüm uç noktalar için varsayılan bağlantı protokolü olarak HTTP/1.1'i oluşturur:

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

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Yapılandırmaya göre ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

URL ön ekleri

UseUrlskullanırken, --urls komut satırı bağımsız değişkeni, urls konak yapılandırma anahtarı veya ASPNETCORE_URLS ortam değişkeni, URL ön ekleri aşağıdaki biçimlerden herhangi birinde olabilir.

Yalnızca HTTP URL ön ekleri geçerlidir. Kestrel kullanarak UseUrlsURL bağlamalarını yapılandırırken HTTPS'yi desteklemez.

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ıyla IPv6 adresi
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.
Bağlantı noktası numarasıyla ana bilgisayar adı
```
http://contoso.com:80/
http://*:80/
```
Ana bilgisayar adları , *ve +ö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ı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya ters ara sunucu kullanın. Ters ara sunucu örnekleri IIS, Nginx veya Apache'dir.

Uyarı

Ters ara sunucu yapılandırmasında barındırmak için ana bilgisayar filtrelemesi gerekir.
Bağlantı noktası numarası veya bağlantı noktası numarası ile geri döngü IP'siyle ana localhost bilgisayar adı
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Geri döngü arabirimi herhangi bir nedenle kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

ASP.NET Core projeleri, 5000-5300 arasında rastgele bir HTTP bağlantı noktasına ve 7000-7300 arasında rastgele bir HTTPS bağlantı noktasına bağlanacak şekilde yapılandırılır. Bu varsayılan yapılandırma, oluşturulan Properties/launchSettings.json dosyada belirtilir ve geçersiz kılınabilir. Herhangi bir bağlantı noktası belirtilmezse şu Kestrel bağlantı noktalarına bağlanır:

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

URL'leri belirtmek için şunları kullanın:

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

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

Geliştirme sertifikası oluşturulur:

.NET SDK'sı yüklendiğinde.
Dev-certs aracı bir sertifika oluşturmak için kullanılır.

Proje şablonları, uygulamaları varsayılan olarak HTTPS üzerinde çalışacak şekilde yapılandırıp HTTPS yeniden yönlendirme ve HSTS desteği içerir.

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

KestrelServerOptions konfigürasyon:

ConfigureEndpointDefaults

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureEndpointDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Configure(IConfiguration)

Varsayılan olarak, Kestrel yapılandırma bölümünden Kestrel yüklenir ve değişiklikler yeniden yüklenir:

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

Yapılandırmayı yeniden yükleme etkinleştirildiyse ve bir değişiklik sinyali verirseniz aşağıdaki adımlar uygulanır:

Yeni yapılandırma eski yapılandırmayla karşılaştırılır, yapılandırma değişikliği olmayan tüm uç noktalar değiştirilmez.
Kaldırılan veya değiştirilen uç noktalara işleme isteklerini tamamlamak ve kapatmak için 5 saniye verilir.
Yeni veya değiştirilmiş uç noktalar başlatılır.

Değiştirilen uç noktaya bağlanan istemcilerin bağlantısı kesilebilir veya uç nokta yeniden başlatılırken reddedilebilir.

YapılandırmaHttpsDefaults

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureHttpsDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

ListenOptions.UseHttps

HTTPS kullanmak için yapılandırın Kestrel .

ListenOptions.UseHttps Uzantı -ları:

UseHttps: HTTPS'yi varsayılan sertifikayla kullanacak şekilde yapılandırın Kestrel . 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 , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. ListenOptionsdöndürür.
storeName , sertifikanın yüklendiği sertifika deposudur.
subject sertifikanın konu adıdır.
allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
location , sertifikanın yüklenecek depo konumudur.
serverCertificate X.509 sertifikasıdır.

Üretimde HTTPS açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

Desteklenen yapılandırmalar aşağıda açıklanmıştır:

Yapılandırma yok
Varsayılan sertifikayı yapılandırmadan değiştirme
Koddaki varsayılanları değiştirme

Yapılandırma yok

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

Varsayılan sertifikayı yapılandırmadan değiştirme

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

true Geçersiz sertifikaların (örneğin, otomatik olarak imzalanan sertifikalar) kullanılmasına izin vermek için olarak ayarlayınAllowInvalid.
Sertifika belirtmeyen herhangi bir HTTPS uç noktası (HttpsDefaultCert aşağıdaki örnekte) veya geliştirme sertifikası altında Certificates:Default tanımlanan sertifikaya geri döner.

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

Uyarı

Şema notları:

Uç nokta adları büyük /küçük harfe duyarlı değildir. Örneğin ve HTTPS Https eşdeğerdir.
Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst düzey Urls yapılandırma parametresiyle aynıdır.
Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, içinde Certificates:Default tanımlanan 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şlatılamaz.
Certificate bölümü birden çok sertifika kaynağını destekler.
Bağlantı noktası çakışmalarına neden olmadığı sürece yapılandırmada herhangi bir sayıda uç nokta tanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, çeşitli kaynaklardan sertifika yüklenecek şekilde yapılandırılabilir:

Pathve Password .pfx dosyalarını yüklemek için.
Pathve KeyPath .pem.crt/ ve .key dosyalarını yüklemek için.Password
Subject ve Store sertifika deposundan 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

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader , tarafından WebApplicationBuilder.WebHostsağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemindeki Endpoint seçeneklerde kullanılabilir.
Başka bir bölümle yeniden çağrılarak Configure(IConfiguration) birden çok yapılandırma yüklenebilir. Önceki örneklerde açıkça çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Meta paket çağrısı Load yapmaz, böylece varsayılan yapılandırma bölümü değiştirilebilir.
KestrelConfigurationLoaderListen, API KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Koddaki varsayılanları değiştirme

var builder = WebApplication.CreateBuilder(args);

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

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

Sunucu Adı Göstergesini kullanarak uç noktaları yapılandırma

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

Kodda bir uç nokta oluşturun ve geri arama ile ServerCertificateSelector konak adını kullanarak bir sertifika seçin.
Yapılandırma'da konak adları ve HTTPS seçenekleri arasında bir eşleme yapılandırın. Örneğin, dosyadaki appsettings.json JSON.

SNI ile `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

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

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

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

SNI ile `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

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

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

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

SNI ile `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

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

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

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

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

Yapılandırmada SNI

Aşağıdaki yapılandırma, konak adına göre HTTPS seçeneklerini seçmek için SNI kullanan adlı MySniEndpoint 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": "$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$"
      }
    }
  }
}

Uyarı

SNI tarafından geçersiz kılınabilecek HTTPS seçenekleri:

Certificatesertifika kaynağını yapılandırıyor.
Protocols izin verilen HTTP protokollerini yapılandırıyor.
SslProtocols izin verilen SSL protokollerini yapılandırıyor.
ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Tam eşleşme. Örneğin, a.example.org ile eşleşir a.example.org.
Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa en uzun desen seçilir. Örneğin, *.example.org ve c.example.orgile eşleşirb.example.org.
Tam joker karakter. * , SNI kullanmayan ve ana bilgisayar adı göndermeyen istemciler de dahil olmak üzere diğer her şeyle eşleşir.

SNI gereksinimleri

Tüm web siteleri aynı Kestrel örnekte çalıştırılmalıdır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.

SSL/TLS Protokolleri

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

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

Uyarı

İstemci Sertifikaları

ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Uyarı

Varsayılan değer, istemciden sertifika istemeyeceği veya gerektirmeyeceği yerdir ClientCertificateMode.NoCertificate Kestrel .

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

Bağlantı günlüğü

var builder = WebApplication.CreateBuilder(args);

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

TCP yuvasına bağlama

Listen yöntemi bir TCP yuvasına bağlanır ve lambda seçenekleri X.509 sertifika yapılandırmasına izin verir:

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

Örnek, ile ListenOptionsbir uç nokta için HTTPS'yi yapılandırıyor. Belirli uç noktaların diğer Kestrel ayarlarını yapılandırmak için aynı API'yi kullanın.

macOS, Linux ve Windows'da sertifikalar OpenSSL kullanılarak oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket dinleyin:

var builder = WebApplication.CreateBuilder(args);

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

Nginx yapılandırma dosyasında girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET} , verilen ListenUnixSocket yuvanın adıdır (ö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

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

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

        // ...
    }
});

Sınırlamalar

Uç noktaları aşağıdaki yaklaşımlarla yapılandırın:

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

Bu yöntemler, dışındaki Kestrelsunucularla kod çalışması için kullanışlıdır. Ancak aşağıdaki sınırlamalara dikkat edin:

HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlanmadığı sürece (örneğin, bu makalede daha önce gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanma KestrelServerOptions ) HTTPS bu yaklaşımlarla kullanılamaz.
Hem hem de Listen yaklaşımları aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.UseUrls

IIS uç noktası yapılandırması

IIS kullanırken, IIS geçersiz kılma bağlamaları için URL bağlamaları veya UseUrlstarafından Listen ayarlanır. Daha fazla bilgi için bkz . ASP.NET Çekirdek Modülü.

ListenOptions.Protocols

`HttpProtocols` sabit listesi değeri	Bağlantı protokolüne izin verilir
`Http1`	Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
`Http2`	Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa 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'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olur.

Herhangi bir uç nokta için varsayılan ListenOptions.Protocols değer şeklindedir HttpProtocols.Http1AndHttp2.

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

TLS sürüm 1.2 veya üzeri
Yeniden anlaşma devre dışı bırakıldı
Sıkıştırma devre dışı bırakıldı
Minimum kısa ömürlü anahtar değişimi boyutları:
- Eliptik eğri Diffie-Hellman (ECDHE) [RFC4492]: en az 224 bit
- Sonlu alan Diffie-Hellman (DHE) [TLS12]: 2048 bit minimum
Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta 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ın güvenliği, sağlanan bir sertifikayla TLS tarafından sağlanır:

var builder = WebApplication.CreateBuilder(args);

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

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına göre filtrelemek için kullanılabilir:

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

Bağlantı Ara Yazılımı

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

Şifreleme algoritması ile CipherAlgorithmType.Null şifreleme kullanılmaz.

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

Yapılandırmadan HTTP protokollerini ayarlama

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

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Yapılandırmaya göre ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

URL ön ekleri

Yalnızca HTTP URL ön ekleri geçerlidir. Kestrel kullanarak UseUrlsURL bağlamalarını yapılandırırken HTTPS'yi desteklemez.

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ıyla IPv6 adresi
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.
Bağlantı noktası numarasıyla ana bilgisayar adı
```
http://contoso.com:80/
http://*:80/
```
Ana bilgisayar adları , *ve +ö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ı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya ters ara sunucu kullanın. Ters ara sunucu örnekleri IIS, Nginx veya Apache'dir.

Uyarı

Ters ara sunucu yapılandırmasında barındırmak için ana bilgisayar filtrelemesi gerekir.
Bağlantı noktası numarası veya bağlantı noktası numarası ile geri döngü IP'siyle ana localhost bilgisayar adı
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Geri döngü arabirimi herhangi bir nedenle kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

Varsayılan olarak, ASP.NET Core şu şekilde bağlanır:

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

URL'leri belirtmek için şunları kullanın:

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

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

Geliştirme sertifikası oluşturulur:

.NET SDK'sı yüklendiğinde.
Dev-certs aracı bir sertifika oluşturmak için kullanılır.

Bazı tarayıcılar, yerel geliştirme sertifikasına güvenmek için açık izin verilmesini gerektirir.

Proje şablonları, uygulamaları varsayılan olarak HTTPS üzerinde çalışacak şekilde yapılandırıp HTTPS yeniden yönlendirme ve HSTS desteği içerir.

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

KestrelServerOptions konfigürasyon:

ConfigureEndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>) belirtilen her uç nokta için çalıştırılacak yapılandırmayı Action belirtir. Birden çok kez çağrılması ConfigureEndpointDefaults , öncekileri Actionbelirtilen son Action değerle değiştirir.

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

Not

Çağrıdan ConfigureEndpointDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Configure(IConfiguration)

uç noktalarının bir IConfigurationiçinden yüklenmesini sağlarKestrel. Yapılandırmanın kapsamı için Kestrelyapılandırma bölümü olarak belirlenmiş olmalıdır.

Aşırı Configure(IConfiguration, bool) yükleme, yapılandırma kaynağı değiştiğinde uç noktaların yeniden yüklenmesini etkinleştirmek için kullanılabilir.

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

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

Yapılandırmayı yeniden yükleme etkinleştirildiyse ve bir değişiklik sinyali verirseniz aşağıdaki adımlar uygulanır:

Yeni yapılandırma eski yapılandırmayla karşılaştırılır, yapılandırma değişikliği olmayan tüm uç noktalar değiştirilmez.
Kaldırılan veya değiştirilen uç noktalara işleme isteklerini tamamlamak ve kapatmak için 5 saniye verilir.
Yeni veya değiştirilmiş uç noktalar başlatılır.

Değiştirilen uç noktaya bağlanan istemcilerin bağlantısı kesilebilir veya uç nokta yeniden başlatılırken reddedilebilir.

YapılandırmaHttpsDefaults

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

Not

Çağrıdan ConfigureHttpsDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

ListenOptions.UseHttps

HTTPS kullanmak için yapılandırın Kestrel .

ListenOptions.UseHttps Uzantı -ları:

UseHttps: HTTPS'yi varsayılan sertifikayla kullanacak şekilde yapılandırın Kestrel . 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 , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. ListenOptionsdöndürür.
storeName , sertifikanın yüklendiği sertifika deposudur.
subject sertifikanın konu adıdır.
allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
location , sertifikanın yüklenecek depo konumudur.
serverCertificate X.509 sertifikasıdır.

Üretimde HTTPS açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

Desteklenen yapılandırmalar aşağıda açıklanmıştır:

Yapılandırma yok
Varsayılan sertifikayı yapılandırmadan değiştirme
Koddaki varsayılanları değiştirme

Yapılandırma yok

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

Varsayılan sertifikayı yapılandırmadan değiştirme

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

true Geçersiz sertifikaların (örneğin, otomatik olarak imzalanan sertifikalar) kullanılmasına izin vermek için olarak ayarlayınAllowInvalid.
Sertifika belirtmeyen herhangi bir HTTPS uç noktası (HttpsDefaultCert aşağıdaki örnekte) veya geliştirme sertifikası altında Certificates:Default tanımlanan sertifikaya geri döner.

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

Uyarı

Şema notları:

Uç nokta adları büyük /küçük harfe duyarlı değildir. Örneğin ve HTTPS Https eşdeğerdir.
Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst düzey Urls yapılandırma parametresiyle aynıdır.
Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, içinde Certificates:Default tanımlanan 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şlatılamaz.
Certificate bölümü birden çok sertifika kaynağını destekler.
Bağlantı noktası çakışmalarına neden olmadığı sürece yapılandırmada herhangi bir sayıda uç nokta tanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, çeşitli kaynaklardan sertifika yüklenecek şekilde yapılandırılabilir:

Pathve Password .pfx dosyalarını yüklemek için.
Pathve KeyPath .pem.crt/ ve .key dosyalarını yüklemek için.Password
Subject ve Store sertifika deposundan 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ılmış bir .Endpoint(string name, listenOptions => { }) uç noktanın ayarlarını desteklemek için kullanılabilecek bir yöntemle 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 CreateDefaultBuildersağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemindeki Endpoint 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 çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Meta paket çağrısı Load yapmaz, böylece varsayılan yapılandırma bölümü değiştirilebilir.
KestrelConfigurationLoaderListen, API KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Koddaki varsayılanları değiştirme

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

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

Sunucu Adı Göstergesini kullanarak uç noktaları yapılandırma

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

Kodda bir uç nokta oluşturun ve geri arama ile ServerCertificateSelector konak adını kullanarak bir sertifika seçin.
Yapılandırma'da konak adları ve HTTPS seçenekleri arasında bir eşleme yapılandırın. Örneğin, dosyadaki appsettings.json JSON.

SNI ile `ServerCertificateSelector`

Kestrel geri çağırma yoluyla SNI'yi ServerCertificateSelector destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır. Aşağıdaki geri çağırma kodu, proje Program.cs dosyasının ConfigureWebHostDefaults 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;
            };
        });
    });
});

SNI ile `ServerOptionsSelectionCallback`

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

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

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

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

Yapılandırmada SNI

Aşağıdaki yapılandırma, konak adına göre HTTPS seçeneklerini seçmek için SNI kullanan adlı MySniEndpoint 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": "$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$"
      }
    }
  }
}

Uyarı

SNI tarafından geçersiz kılınabilecek HTTPS seçenekleri:

Certificatesertifika kaynağını yapılandırıyor.
Protocols izin verilen HTTP protokollerini yapılandırıyor.
SslProtocols izin verilen SSL protokollerini yapılandırıyor.
ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

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

Tam eşleşme. Örneğin, a.example.org ile eşleşir a.example.org.
Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa en uzun desen seçilir. Örneğin, *.example.org ve c.example.orgile eşleşirb.example.org.
Tam joker karakter. * , SNI kullanmayan ve ana bilgisayar adı göndermeyen istemciler de dahil olmak üzere diğer her şeyle eşleşir.

SNI gereksinimleri

Hedef çerçevede netcoreapp2.1 veya sonraki sürümlerde çalışıyor. Veya daha sonraki bir tarihte net461 geri arama çağrılır, ancak name her zaman nullolur. name ayrıcanull, istemci TLS el sıkışmasında ana bilgisayar adı parametresini sağlamazsa da olur.
Tüm web siteleri aynı Kestrel örnekte çalışır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.

SSL/TLS Protokolleri

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

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

Uyarı

İstemci Sertifikaları

ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadı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": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Uyarı

Varsayılan değer, istemciden sertifika istemeyeceği veya gerektirmeyeceği yerdir ClientCertificateMode.NoCertificate Kestrel .

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

Bağlantı günlüğü

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

TCP yuvasına bağlama

Listen yöntemi bir TCP yuvasına bağlanır ve lambda seçenekleri X.509 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, ile ListenOptionsbir uç nokta için HTTPS'yi yapılandırıyor. Belirli uç noktaların diğer Kestrel ayarlarını yapılandırmak için aynı API'yi kullanın.

macOS, Linux ve Windows'da sertifikalar OpenSSL kullanılarak oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket 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 girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET} , verilen ListenUnixSocket yuvanın adıdır (ö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

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ışı, uygulamaya ulaşabileceğiniz dinamik bağlantı noktasını gösterir:

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

Sınırlamalar

Uç noktaları aşağıdaki yaklaşımlarla yapılandırın:

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

Bu yöntemler, dışındaki Kestrelsunucularla kod çalışması için kullanışlıdır. Ancak aşağıdaki sınırlamalara dikkat edin:

HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlanmadığı sürece (örneğin, bu makalede daha önce gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanma KestrelServerOptions ) HTTPS bu yaklaşımlarla kullanılamaz.
Hem hem de Listen yaklaşımları aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.UseUrls

IIS uç noktası yapılandırması

IIS kullanırken, IIS geçersiz kılma bağlamaları için URL bağlamaları veya UseUrlstarafından Listen ayarlanır. Daha fazla bilgi için bkz . ASP.NET Çekirdek Modülü.

ListenOptions.Protocols

`HttpProtocols` sabit listesi değeri	Bağlantı protokolüne izin verilir
`Http1`	Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
`Http2`	Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa 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'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olur.

Herhangi bir uç nokta için varsayılan ListenOptions.Protocols değer şeklindedir HttpProtocols.Http1AndHttp2.

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

TLS sürüm 1.2 veya üzeri
Yeniden anlaşma devre dışı bırakıldı
Sıkıştırma devre dışı bırakıldı
Minimum kısa ömürlü anahtar değişimi boyutları:
- Eliptik eğri Diffie-Hellman (ECDHE) [RFC4492]: en az 224 bit
- Sonlu alan Diffie-Hellman (DHE) [TLS12]: 2048 bit minimum
Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta 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ın güvenliği, sağlanan bir sertifikayla TLS tarafından sağlanır:

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

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına göre 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 şifreler için TLS el sıkışmalarını bağlantı başına filtreleyebilir.

Aşağıdaki örnek, uygulamanın desteklemediği herhangi bir şifreleme algoritması için oluşturur NotSupportedException . Alternatif olarak, ITlsHandshakeFeature.CipherAlgorithm öğesini tanımlayıp kabul edilebilir şifreleme paketlerinin listesiyle karşılaştırın.

CipherAlgorithmType.Null şifreleme algoritması ile ş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ı filtreleme bir IConnectionBuilder lambda aracılığıyla da yapılandırılabilir:

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

Yapılandırmadan HTTP protokollerini ayarlama

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

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

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

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Yapılandırmaya göre ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

URL ön ekleri

Yalnızca HTTP URL ön ekleri geçerlidir. Kestrel kullanarak UseUrlsURL bağlamalarını yapılandırırken HTTPS'yi desteklemez.

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ıyla IPv6 adresi
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.
Bağlantı noktası numarasıyla ana bilgisayar adı
```
http://contoso.com:80/
http://*:80/
```
Ana bilgisayar adları , *ve +ö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ı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya ters ara sunucu kullanın. Ters ara sunucu örnekleri IIS, Nginx veya Apache'dir.

Uyarı

Ters ara sunucu yapılandırmasında barındırmak için ana bilgisayar filtrelemesi gerekir.
Bağlantı noktası numarası veya bağlantı noktası numarası ile geri döngü IP'siyle ana localhost bilgisayar adı
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Geri döngü arabirimi herhangi bir nedenle kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

Aracılığıyla paylaş

ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma

Varsayılan uç nokta

Uç noktaları yapılandırma

UÇ noktaları URL'lerle yapılandırma

URL biçimleri

HTTPS URL ön ekleri

Yalnızca bağlantı noktalarını belirtin

appsettings.json'de uç noktaları yapılandırma

Uç noktaları yapılandırmadan yeniden yükleme

ConfigurationLoader

Kodda uç noktaları yapılandırma

TCP yuvasına bağlama

Unix yuvasına bağlama

Uç nokta varsayılanlarını yapılandırma

Dinamik bağlantı noktası bağlama

HTTPS’yi yapılandırma

appsettings.json'de HTTPS'yi yapılandırma

Şema notları

Sertifika kaynakları

appsettings.json'de istemci sertifikalarını yapılandırma

appsettings.json'de SSL/TLS protokollerini yapılandırma

Kodda HTTPS'yi yapılandırma

Kodda istemci sertifikalarını yapılandırma

Kodda HTTPS varsayılanlarını yapılandırma

Kodda SSL/TLS protokollerini yapılandırma

Kodda TLS şifreleme paketleri filtresini yapılandırma

Sunucu Adı Gösterimini Yapılandır

appsettings.json'de SNI'yi yapılandırma

SNI'yi kodla yapılandırma

SNI ile ServerCertificateSelector

SNI ile ServerOptionsSelectionCallback

SNI ile TlsHandshakeCallbackOptions

HTTP protokollerini yapılandırma

appsettings.json'de HTTP protokollerini yapılandırma

Kodda HTTP protokollerini yapılandırma

Ayrıca bkz.

ConfigureEndpointDefaults

Configure(IConfiguration)

YapılandırmaHttpsDefaults

ListenOptions.UseHttps

Yapılandırma yok

Varsayılan sertifikayı yapılandırmadan değiştirme

Sertifika kaynakları

ConfigurationLoader

Koddaki varsayılanları değiştirme

Sunucu Adı Göstergesini kullanarak uç noktaları yapılandırma

SNI ile ServerCertificateSelector

SNI ile ServerOptionsSelectionCallback

SNI ile TlsHandshakeCallbackOptions

Yapılandırmada SNI

SNI gereksinimleri

SSL/TLS Protokolleri

İstemci Sertifikaları

Bağlantı günlüğü

TCP yuvasına bağlama

Unix yuvasına bağlama

Bağlantı noktası 0

Sınırlamalar

IIS uç noktası yapılandırması

ListenOptions.Protocols

Bağlantı Ara Yazılımı

Yapılandırmadan HTTP protokollerini ayarlama

URL ön ekleri

ConfigureEndpointDefaults

Configure(IConfiguration)

YapılandırmaHttpsDefaults

ListenOptions.UseHttps

Yapılandırma yok

Varsayılan sertifikayı yapılandırmadan değiştirme

Sertifika kaynakları

ConfigurationLoader

Koddaki varsayılanları değiştirme

Sunucu Adı Göstergesini kullanarak uç noktaları yapılandırma

SNI ile ServerCertificateSelector

SNI ile ServerOptionsSelectionCallback

SNI ile TlsHandshakeCallbackOptions

Yapılandırmada SNI

SNI gereksinimleri

SSL/TLS Protokolleri

SNI ile `ServerCertificateSelector`

SNI ile `ServerOptionsSelectionCallback`

SNI ile `TlsHandshakeCallbackOptions`

SNI ile `ServerCertificateSelector`

SNI ile `ServerOptionsSelectionCallback`

SNI ile `TlsHandshakeCallbackOptions`

SNI ile `ServerCertificateSelector`

SNI ile `ServerOptionsSelectionCallback`

SNI ile `TlsHandshakeCallbackOptions`

SNI ile `ServerCertificateSelector`

SNI ile `ServerOptionsSelectionCallback`