Настройка конечных точек для веб-сервера Kestrel для ASP.NET Core

Kestrel конечные точки предоставляют инфраструктуру для прослушивания входящих запросов и маршрутизации их в соответствующее ПО промежуточного слоя. Сочетание адреса и протокола определяет конечную точку.

• Адрес указывает сетевой интерфейс, который сервер прослушивает для входящих запросов, таких как TCP-порт.
• Протокол задает связь между клиентом и сервером, например HTTP/1.1, HTTP/2 или HTTP/3.
• Конечную точку можно защитить с помощью https схемы URL-адреса или UseHttps метода.

Конечные точки можно настроить с помощью URL-адресов, JSON и appsettings.jsonкода. В этой статье описывается, как использовать каждый параметр для настройки конечной точки:

• Настройка конечных точек
• Настройка HTTPS
• Настройка протоколов HTTP

Конечная точка по умолчанию

Новые проекты ASP.NET Core настроены для привязки к случайному порту HTTP от 5000 до 5300 и случайному порту HTTPS от 7000 до 7300. Выбранные порты хранятся в созданном Properties/launchSettings.json файле и могут быть изменены разработчиком. Файл launchSetting.json используется только в локальной разработке.

Если конфигурации конечной точки нет, Kestrel привязывается к http://localhost:5000.

Настройка конечных точек

Kestrel конечные точки прослушивают входящие подключения. При создании конечной точки необходимо настроить адрес, который он будет прослушивать. Обычно это TCP-адрес и номер порта.

Существует несколько вариантов настройки конечных точек:

• Настройка конечных точек с URL-адресами
• Укажите только порты
• Настройка конечных точек в appsettings.json
• Настройка конечных точек в коде

Настройка конечных точек с URL-адресами

В следующих разделах объясняется, как настроить конечные точки с помощью следующих разделов:

• Переменная среды ASPNETCORE_URLS.
• Аргументы командной строки --urls.
• Ключ конфигурации узла urls.
• Метод расширения UseUrls.
• Свойство WebApplication.Urls.

Форматы URL-адресов

URL-адреса указывают IP-адреса или адреса узлов с портами и протоколами, на которых должен прослушивать сервер. Порт может быть опущен, если это протокол по умолчанию (обычно 80 и 443). URL-адреса могут находиться в любом из следующих форматов.

• IPv4-адрес с номером порта

  http://65.55.39.10:80/
  

  0.0.0.0 является особым случаем, соответствующим привязке ко всем IPv4-адресам.

• IPv6-адрес с номером порта

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

  [::] является IPv6-аналогом IPv4-адреса 0.0.0.0.

• Узел подстановочного знака с номером порта

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

  Что-либо не распознано как допустимый IP-адрес или localhost рассматривается как подстановочный знак, который привязывается ко всем адресам IPv4 и IPv6. Некоторые люди любят использовать * или + быть более явными. Чтобы привязать разные имена узлов к разным приложениям ASP.NET Core по одному порту, используйте HTTP.sys или обратный прокси-сервер.

  Примеры обратного прокси-сервера включают IIS, YARP, Nginx и Apache.

• Имя localhost узла с номером порта или IP-адресом обратного цикла с номером порта

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

  Если указать localhost, Kestrel попытается привязаться к обоим интерфейсам замыкания на себя IPv4 и IPv6. Если запрошенный порт уже используется другой службой в одном из интерфейсов замыкания на себя, Kestrel не будет запущен. Если один из интерфейсов замыкания на себя недоступен по любой другой причине (чаще всего из-за отсутствия поддержки IPv6), Kestrel зарегистрирует предупреждение.

Несколько префиксов URL-адресов можно указать с помощью разделителя с запятой (;):

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

Дополнительные сведения см. в разделе "Переопределение конфигурации".

Префиксы URL-адреса HTTPS

Префиксы URL-адреса HTTPS можно использовать для определения конечных точек только в том случае, если сертификат по умолчанию указан в конфигурации конечной точки HTTPS. Например, используйте KestrelServerOptions конфигурацию или файл конфигурации, как показано далее в этой статье.

Дополнительные сведения см. в разделе "Настройка HTTPS".

Укажите только порты

Приложения и контейнеры часто получают только порт для прослушивания, например порта 80, без дополнительных ограничений, таких как узел или путь. HTTP_PORTS и HTTPS_PORTS — это ключи конфигурации, указывающие порты прослушивания для Kestrel серверов и HTTP.sys. Эти ключи могут быть указаны в виде переменных среды, определенных с DOTNET_ префиксами или ASPNETCORE_ напрямую через любые другие входные данные конфигурации, например appsettings.json. Каждый из них представляет собой список значений портов с запятой, как показано в следующем примере:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Приведенный выше пример сокращен для следующей конфигурации, которая указывает схему (HTTP или HTTPS) и любой узел или IP-адрес.

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

Ключи конфигурации HTTP_PORTS и HTTPS_PORTS имеют более низкий приоритет и переопределяются URL-адресами или значениями, предоставленными непосредственно в коде. Сертификаты по-прежнему необходимо настроить отдельно с помощью механики для HTTPS для конкретного сервера.

Настройка конечных точек в appsettings.json

Kestrel может загружать конечные точки из экземпляра IConfiguration . По умолчанию Kestrel конфигурация загружается из Kestrel раздела и конечных точек настраивается в Kestrel:Endpoints:

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

Предшествующий пример:

• Используется appsettings.json в качестве источника конфигурации. Однако можно использовать любой IConfiguration источник.
• Добавляет конечную точку с именем MyHttpEndpoint порта 8080.

Дополнительные сведения о настройке конечных точек с помощью JSON см. в последующих разделах этой статьи, посвященных настройке HTTPS и настройке протоколов HTTP в appsettings.json.

Перезагрузка конечных точек из конфигурации

Перезагрузите конфигурацию конечной точки при включении изменения источника конфигурации по умолчанию. Его можно отключить с помощью KestrelServerOptions.Configure(IConfiguration, Boolean).

При сигнале об изменении выполняются следующие действия:

• Новая конфигурация сравнивается со старой, и любая конечная точка без изменений конфигурации не изменяется.
• Для удаленных или измененных конечных точек выделяется 5 секунд для завершения обработки запросов и завершения работы.
• Запускаются новые или измененные конечные точки.

Клиенты, подключающиеся к измененной конечной точке, могут быть отключены или получить отказ в подключении при перезапуске конечной точки.

ConfigurationLoader

KestrelServerOptions.Configure возвращает значение типа KestrelConfigurationLoader. Метод загрузчика Endpoint(String, Action<EndpointConfiguration>) , который можно использовать для дополнения параметров настроенной конечной точки:

var builder = WebApplication.CreateBuilder(args);

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

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

Можно обратиться напрямую к KestrelServerOptions.ConfigurationLoader, чтобы и далее выполнять итерацию с существующим загрузчиком, например, предоставленным WebApplicationBuilder.WebHost.

• Раздел конфигурации для каждой конечной точки доступен в параметрах в методе Endpoint, чтобы можно было прочитать пользовательские параметры.
• KestrelServerOptions.Configure(IConfiguration) можно вызывать несколько раз, но используется только последняя конфигурация, если Load не вызывается явным образом в предыдущих экземплярах. Узел по умолчанию не вызывается Load таким образом, чтобы его раздел конфигурации по умолчанию мог быть заменен.
• KestrelConfigurationLoader зеркально Listen отражает семейство API из KestrelServerOptions перегрузки Endpoint , поэтому конечные точки кода и конфигурации можно настроить в том же месте. Эти перегрузки не используют имена и используют только параметры по умолчанию из конфигурации.

Настройка конечных точек в коде

KestrelServerOptions предоставляет методы настройки конечных точек в коде:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Listen Когда api UseUrls используются одновременно, Listen конечные точки переопределяют UseUrls конечные точки.

Привязка к TCP-сокету

ListenLocalhostМетоды Listenи ListenAnyIP методы привязываются к сокету TCP:

var builder = WebApplication.CreateBuilder(args);

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

Предшествующий пример:

• Настраивает конечные точки, прослушивающие порт 5000 и 5001.
• Настраивает HTTPS для конечной точки с UseHttps помощью метода ListenOptionsрасширения. Дополнительные сведения см. в разделе "Настройка HTTPS" в коде.

В Windows самозаверяющие сертификаты создаются с помощью командлета PowerShell New-SelfSignedCertificate. Неподдерживаемый пример: UpdateIISExpressSSLForChrome.ps1.

В macOS, Linux и Windows сертификаты создаются с помощью OpenSSL.

Привязка к сокету UNIX

Вы можете прослушивать сокет UNIX с помощью ListenUnixSocket, чтобы улучшить производительность Nginx, как показано в следующем примере:

var builder = WebApplication.CreateBuilder(args);

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

• В файле конфигурации Nginx установите для записи server>location>proxy_pass значение http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} — это имя сокета, предоставленного для ListenUnixSocket (как kestrel-test.sock в предыдущем примере).
• Убедитесь, что сокет доступен для записи Nginx (например, chmod go+w /tmp/kestrel-test.sock).

Настройка значений по умолчанию конечной точки

ConfigureEndpointDefaults(Action<ListenOptions>) указывает конфигурацию, которая выполняется для каждой указанной конечной точки. Вызов ConfigureEndpointDefaults несколько раз заменяет предыдущую конфигурацию.

var builder = WebApplication.CreateBuilder(args);

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

Примечание.

К конечным точкам, созданным путем вызова Listen перед вызовом ConfigureEndpointDefaults, не будут применяться значения по умолчанию.

Динамическая привязка портов

При указании Kestrel номера 0 порта динамически привязывается к доступному порту. В следующем примере показано, как определить, к какому порту привязан Kestrel во время выполнения:

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

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

        // ...
    }
});

В некоторых ситуациях динамическая привязка порта недоступна:

• KestrelServerOptions.ListenLocalhost
• Привязка HTTP/1.1 или HTTP/2 на основе TCP с HTTP/3 на основе QUIC.

Настройка HTTPS

Kestrel поддерживает защиту конечных точек с помощью HTTPS. Данные, отправляемые по протоколу HTTPS, шифруются с помощью протокола TLS для повышения безопасности данных, передаваемых между клиентом и сервером.

Для HTTPS требуется сертификат TLS. Сертификат TLS хранится на сервере и Kestrel настроен для его использования. Приложение может использовать сертификат разработки ASP.NET Core HTTPS в локальной среде разработки. Сертификат разработки не установлен в неразвитых средах. В рабочей среде сертификат TLS должен быть явно настроен. Как минимум необходимо указать сертификат по умолчанию.

Способ настройки HTTPS и сертификата TLS зависит от того, как настроены конечные точки:

• Если префиксы URL-адреса или только порты используются для определения конечных точек, HTTPS можно использовать только в том случае, если сертификат по умолчанию указан в конфигурации конечной точки HTTPS. Сертификат по умолчанию можно настроить одним из следующих параметров:
• Настройка HTTPS в appsettings.json
• Настройка HTTPS в коде

Настройка HTTPS в appsettings.json

Kestrel имеет доступ к схеме конфигурации параметров приложения HTTPS по умолчанию. Настройте несколько конечных точек, включая URL-адреса и сертификаты для использования, либо из файла на диске, либо из хранилища сертификатов.

Любая конечная точка HTTPS, которая не указывает сертификат (HttpsDefaultCert в следующем примере) возвращается к сертификату, определенному в Certificates:Default разделе или сертификате разработки.

В следующем примере используется appsettings.jsonлюбой источник конфигурации:

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

Предупреждение

В предыдущем примере пароли сертификатов хранятся в виде обычного текста в appsettings.json. Токен $CREDENTIAL_PLACEHOLDER$ используется в качестве заполнителя для пароля каждого сертификата. Сведения о безопасном хранении паролей сертификатов в средах разработки см. в статье Защита секретов в разработке. Сведения о безопасном хранении паролей сертификатов в рабочих средах см. в статье Поставщик конфигурации Azure Key Vault. Секреты, используемые для разработки, не следует использовать для рабочей среды или тестирования.

Заметки о схеме

• Имена конечных точек не учитывает регистр. Например, выражение HTTPS and Https являются эквивалентными.
• Параметр Url является обязательным для каждой конечной точки. Формат этого параметра такой же, как для параметра конфигурации Urls верхнего уровня, только он ограничен одиночным значением. См . форматы URL-адресов, приведенные ранее в этой статье.
• Эти конечные точки заменяют те, которые определены в конфигурации верхнего уровня Urls , а не добавляются в них. Конечные точки, определенные в коде через Listen, объединяются с конечными точками, определенными в разделе конфигурации.
• Раздел Certificate является необязательным. Если раздел Certificate не указан, используются значения по умолчанию, определенные в Certificates:Default. Если значения по умолчанию недоступны, используется сертификат разработки. Если значений по умолчанию нет и сертификат разработки отсутствует, сервер выдаст исключение и не сможет запуститься.
• В Certificate этом разделе поддерживается несколько источников сертификатов.
• Любое количество конечных точек может быть определено в Configuration, если они не вызывают конфликтов портов.

Источники сертификатов

Узлы сертификатов можно настроить для загрузки сертификатов из нескольких источников:

• Path и Password для загрузки файлов .pfx;
• Path, KeyPath и Password для загрузки файлов .pem/.crt и .key;
• Subject и Store для загрузки из хранилища сертификатов.

Например, Certificates:Default сертификат можно указать следующим образом:

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

Настройка сертификатов клиента в appsettings.json

ClientCertificateMode используется для настройки поведения сертификата клиента.

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

Предупреждение

В предыдущем примере пароли сертификатов хранятся в виде обычного текста в appsettings.json. Токен $CREDENTIAL_PLACEHOLDER$ используется в качестве заполнителя для пароля каждого сертификата. Сведения о безопасном хранении паролей сертификатов в средах разработки см. в статье Защита секретов в разработке. Сведения о безопасном хранении паролей сертификатов в рабочих средах см. в статье Поставщик конфигурации Azure Key Vault. Секреты, используемые для разработки, не следует использовать для рабочей среды или тестирования.

Значением по умолчанию является, где Kestrel не запрашивается или требуется ClientCertificateMode.NoCertificateсертификат от клиента.

Дополнительные сведения см. в статье Настройка проверки подлинности по сертификату в ASP.NET Core.

Настройка протоколов SSL/TLS в appsettings.json

Протоколы SSL — это протоколы, используемые для шифрования и расшифровки трафика между двумя одноранговыми узлами, обычно клиентом и сервером.

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

Предупреждение

В предыдущем примере пароли сертификатов хранятся в виде обычного текста в appsettings.json. Токен $CREDENTIAL_PLACEHOLDER$ используется в качестве заполнителя для пароля каждого сертификата. Сведения о безопасном хранении паролей сертификатов в средах разработки см. в статье Защита секретов в разработке. Сведения о безопасном хранении паролей сертификатов в рабочих средах см. в статье Поставщик конфигурации Azure Key Vault. Секреты, используемые для разработки, не следует использовать для рабочей среды или тестирования.

Значение по умолчанию SslProtocols.None указывает Kestrel использовать параметры операционной системы по умолчанию для выбора оптимального протокола. Если вам не требуется по какой-либо причине выбрать определенный протокол, используйте значение по умолчанию.

Настройка HTTPS в коде

При использовании Listen API UseHttps метод ListenOptions расширения доступен для настройки HTTPS.

var builder = WebApplication.CreateBuilder(args);

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

Параметры ListenOptions.UseHttps:

• filename — это путь и имя файла сертификата, связанного с каталогом, где находятся файлы содержимого приложения.
• password — это пароль для доступа к данным сертификата X.509.
• configureOptions — это Action для настройки HttpsConnectionAdapterOptions. Возвращает ListenOptions.
• storeName — это хранилище сертификатов, из которого выполняется загрузка сертификата.
• subject — это имя субъекта для сертификата.
• allowInvalid указывает, следует ли учитывать недопустимые сертификаты, например самозаверяющие сертификаты.
• location — это расположение хранилища, из которого загружается сертификат.
• serverCertificate — это сертификат X.509.

Полный UseHttps список перегрузок см. в разделе UseHttps.

Настройка сертификатов клиента в коде

ClientCertificateMode настраивает требования к сертификату клиента.

var builder = WebApplication.CreateBuilder(args);

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

Значением по умолчанию является, где Kestrel не запрашивается или требуется NoCertificateсертификат от клиента.

Дополнительные сведения см. в статье Настройка проверки подлинности по сертификату в ASP.NET Core.

Настройка по умолчанию HTTPS в коде

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) указывает конфигурацию Action для каждой конечной точки HTTPS. Вызов ConfigureHttpsDefaults несколько раз заменяет предыдущие Action экземпляры последним Action заданным.

var builder = WebApplication.CreateBuilder(args);

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

Примечание.

К конечным точкам, созданным путем вызова Listen перед вызовом ConfigureHttpsDefaults, не будут применяться значения по умолчанию.

Настройка протоколов SSL/TLS в коде

Протоколы SSL — это протоколы, используемые для шифрования и расшифровки трафика между двумя одноранговыми узлами, традиционно клиентом и сервером.

var builder = WebApplication.CreateBuilder(args);

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

Настройка фильтра наборов шифров TLS в коде

В Linux для фильтрации подтверждений TLS по каждому соединению можно использовать CipherSuitesPolicy:

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

Настройка указания имени сервера

Можно использовать указание имени сервера (SNI) для размещения нескольких доменов в одном IP-адресе и порте. SNI можно использовать для экономии ресурсов, обслуживая несколько сайтов с одного сервера.

Для использования SNI клиент отправляет имя узла для безопасного сеанса серверу во время подтверждения TLS, чтобы сервер предоставил правильный сертификат. Клиент использует предоставленный сертификат для зашифрованного соединения с сервером во время безопасного сеанса, который следует после подтверждения TLS.

Все веб-сайты нужно выполнять на одном и том же экземпляре Kestrel. Kestrel не поддерживает совместное использование IP-адреса и порта на нескольких экземплярах без обратного прокси-сервера.

SNI можно настроить двумя способами:

• Настроив сопоставление имен узлов и параметров HTTPS в конфигурации. Например, JSON в файле appsettings.json.
• Создав конечную точку в коде и выбрав сертификат, используя имя узла с обратным вызовом ServerCertificateSelector.

Настройка SNI в appsettings.json

Kestrel поддерживает SNI, как определено в конфигурации. Конечную точку можно настроить с помощью объекта Sni, который содержит сопоставление имен узлов и параметров HTTPS. Имя узла подключения соответствует параметрам, и они используются для этого подключения.

Следующая конфигурация добавляет конечную точку с именем MySniEndpoint, которая использует SNI для выбора параметров HTTPS на основе имени узла:

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

Предупреждение

В предыдущем примере пароли сертификатов хранятся в виде обычного текста в appsettings.json. Токен $CREDENTIAL_PLACEHOLDER$ используется в качестве заполнителя для пароля каждого сертификата. Сведения о безопасном хранении паролей сертификатов в средах разработки см. в статье Защита секретов в разработке. Сведения о безопасном хранении паролей сертификатов в рабочих средах см. в статье Поставщик конфигурации Azure Key Vault. Секреты, используемые для разработки, не следует использовать для рабочей среды или тестирования.

Параметры HTTPS, которые можно переопределить с помощью SNI:

• Certificate настраивает источник сертификата.
• Protocols настраивает разрешенные протоколы HTTP.
• SslProtocols настраивает разрешенные протоколы SSL.
• ClientCertificateMode настраивает требования к сертификату клиента.

Имя узла поддерживает сопоставление с подстановочными знаками:

• Точное соответствие. Например, a.example.org соответствует a.example.org.
• Префикс подстановочного знака. Если имеется несколько совпадений с подстановочными знаками, выбирается самый длинный шаблон. Например, *.example.org соответствует b.example.org и c.example.org.
• Подстановочный знак полностью. * соответствует всем остальным элементам, в том числе клиентам, которые не используют SNI и не отправляют имя узла.

Соответствующая конфигурация SNI применяется к конечной точке подключения, переопределяя значения в этой конечной точке. Если подключение не совпадает с настроенным именем узла SNI, подключение отказано.

Настройка SNI с помощью кода

Kestrel поддерживает SNI с несколькими API обратного вызова:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI с обратным вызовом ServerCertificateSelector

Kestrel поддерживает SNI через обратный вызов 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 с обратным вызовом ServerOptionsSelectionCallback

Kestrel поддерживает дополнительную динамическую конфигурацию TLS через обратный вызов ServerOptionsSelectionCallback. Функция обратного вызова вызывается один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат и конфигурацию TLS. Сертификаты по умолчанию и ConfigureHttpsDefaults не используются с этим обратным вызовом.

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 с обратным вызовом TlsHandshakeCallbackOptions

Kestrel поддерживает дополнительную динамическую конфигурацию TLS через обратный вызов TlsHandshakeCallbackOptions.OnConnection. Функция обратного вызова вызывается один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат, конфигурацию TLS и другие параметры сервера. Сертификаты по умолчанию и ConfigureHttpsDefaults не используются с этим обратным вызовом.

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

Kestrel поддерживает все часто используемые версии HTTP. Конечные точки можно настроить для поддержки разных версий HTTP с помощью HttpProtocols перечисления, указывающего доступные параметры версии HTTP.

Протокол TLS требуется для поддержки нескольких версий HTTP. Подтверждение установки связи TLS Application-Layer Protocol Negotiation (ALPN) используется для согласования протокола подключения между клиентом и сервером, если конечная точка поддерживает несколько протоколов.

Значение HttpProtocols	Допустимый протокол подключения
Http1	Только HTTP/1.1. Можно использовать с протоколом TLS или без него.
Http2	Только HTTP/2. Может использоваться без TLS только в том случае, если клиент поддерживает режим предварительного знания.
Http3	Только HTTP/3. Требуется TLS. Клиент может потребоваться настроить только для использования ПРОТОКОЛА HTTP/3.
Http1AndHttp2	HTTP/1.1 и HTTP/2. Для использования HTTP/2 требуется, чтобы клиент выбрал HTTP/2 при подтверждении согласования протокола уровня приложений (ALPN); в противном случае используется подключение по умолчанию HTTP/1.1.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 и HTTP/3. Первый клиентский запрос обычно использует HTTP/1.1 или HTTP/2, а alt-svc заголовок ответа запрашивает обновление клиента до HTTP/3. Для HTTP/2 и HTTP/3 требуется TLS; в противном случае подключение по умолчанию используется по протоколу HTTP/1.1.

Значение протокола по умолчанию для конечной точки HttpProtocols.Http1AndHttp2.

Ограничения TLS для HTTP/2:

• TSL 1.2 или более поздней версии.
• Повторное согласование отключено.
• Сжатие отключено.
• Минимальные временные размеры обмена ключами:
  • эллиптическая кривая Диффи — Хелмана (ECDHE) [RFC4492]: не менее 224 бит;
  • конечное поле Диффи — Хелмана (DHE) [TLS12]: не менее 2048 бит;
• Набор шифров не запрещен.

По умолчанию поддерживается TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] с эллиптической кривой P-256 [FIPS186].

Настройка протоколов HTTP в appsettings.json

В следующем примере appsettings.json для отдельной конечной точки устанавливается протокол подключения HTTP/1.1:

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

Протокол по умолчанию можно настроить в Kestrel:EndpointDefaults разделе. В следующем примере appsettings.json для всех конечных точек устанавливается протокол подключения по умолчанию HTTP/1.1:

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

Указанные в коде протоколы переопределяют значения, заданные в конфигурации.

Настройка протоколов HTTP в коде

ListenOptions.Protocols используется для указания протоколов с HttpProtocols перечислением.

В следующем примере настраивается конечная точка для подключений HTTP/1.1, HTTP/2 и HTTP/3 через порт 8000. Эти подключения шифруются по протоколу TLS с использованием предоставленного сертификата:

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

См. также

• Kestrel веб-сервер в ASP.NET Core
• Настройка параметров веб-сервера Kestrel для ASP.NET Core