diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 560e8d37d221..d92e7c804acc 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -502,13 +502,13 @@ Supported configurations described next: * Replace the default certificate from configuration * Change the defaults in code -*No configuration* +#### No configuration Kestrel listens on `http://localhost:5000` and `https://localhost:5001` (if a default cert is available). -*Replace the default certificate from configuration* +#### Replace the default certificate from configuration `CreateDefaultBuilder` calls `Configure(context.Configuration.GetSection("Kestrel"))` by default to load Kestrel configuration. A default HTTPS app settings configuration schema is available for Kestrel. Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store. @@ -546,7 +546,8 @@ In the following *appsettings.json* example: "Https": { "Url": "https://*:5004", "Certificate": { - "Path": "", + "Path": "", + "KeyPath": "", "Password": "" } } @@ -561,7 +562,27 @@ In the following *appsettings.json* example: } ``` -An alternative to using **Path** and **Password** for any certificate node is to specify the certificate using certificate store fields. For example, the **Certificates** > **Default** certificate can be specified as: +Schema notes: + +* Endpoints names are case-insensitive. For example, `HTTPS` and `Https` are equivalent. +* The `Url` parameter is required for each endpoint. The format for this parameter is the same as the top-level `Urls` configuration parameter except that it's limited to a single value. +* These endpoints replace those defined in the top-level `Urls` configuration rather than adding to them. Endpoints defined in code via `Listen` are cumulative with the endpoints defined in the configuration section. +* The `Certificate` section is optional. If the `Certificate` section isn't specified, the defaults defined in earlier scenarios are used. If no defaults are available, the server throws an exception and fails to start. +* The `Certificate` section supports multiple certificate sources: + * **Path**–**Password** + * **Path**–**KeyPath**‐**Password** + * **Subject**–**Store** +* Any number of endpoints may be defined in this way so long as they don't cause port conflicts. + +##### Certificate sources + +Certificate nodes can be configured to load certificates from a number of sources: + +* **Path** and **Password** to load *.pfx* files. +* **Path**, **KeyPath** and **Password** to load *.pem*/*.crt* and *.key* files. +* **Subject** and **Store** to load from the certificate store. + +For example, the **Certificates** > **Default** certificate can be specified as: ```json "Default": { @@ -572,15 +593,9 @@ An alternative to using **Path** and **Password** for any certificate node is to } ``` -Schema notes: +##### ConfigurationLoader -* Endpoints names are case-insensitive. For example, `HTTPS` and `Https` are valid. -* The `Url` parameter is required for each endpoint. The format for this parameter is the same as the top-level `Urls` configuration parameter except that it's limited to a single value. -* These endpoints replace those defined in the top-level `Urls` configuration rather than adding to them. Endpoints defined in code via `Listen` are cumulative with the endpoints defined in the configuration section. -* The `Certificate` section is optional. If the `Certificate` section isn't specified, the defaults defined in earlier scenarios are used. If no defaults are available, the server throws an exception and fails to start. -* The `Certificate` section supports both **Path**–**Password** and **Subject**–**Store** certificates. -* Any number of endpoints may be defined in this way so long as they don't cause port conflicts. -* `options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a `KestrelConfigurationLoader` with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: +`options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: ```csharp webBuilder.UseKestrel((context, serverOptions) => @@ -599,7 +614,7 @@ webBuilder.UseKestrel((context, serverOptions) => * Multiple configurations may be loaded by calling `options.Configure(context.Configuration.GetSection("{SECTION}"))` again with another section. Only the last configuration is used, unless `Load` is explicitly called on prior instances. The metapackage doesn't call `Load` so that its default configuration section may be replaced. * `KestrelConfigurationLoader` mirrors the `Listen` family of APIs from `KestrelServerOptions` as `Endpoint` overloads, so code and config endpoints may be configured in the same place. These overloads don't use names and only consume default settings from configuration. -*Change the defaults in code* +#### Change the defaults in code `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` can be used to change default settings for `ListenOptions` and `HttpsConnectionAdapterOptions`, including overriding the default certificate specified in the prior scenario. `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` should be called before any endpoints are configured. @@ -618,7 +633,7 @@ webBuilder.ConfigureKestrel(serverOptions => }); ``` -*Kestrel support for SNI* +#### Kestrel support for SNI [Server Name Indication (SNI)](https://tools.ietf.org/html/rfc6066#section-3) can be used to host multiple domains on the same IP address and port. For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake. @@ -1490,13 +1505,13 @@ Supported configurations described next: * Replace the default certificate from configuration * Change the defaults in code -*No configuration* +#### No configuration Kestrel listens on `http://localhost:5000` and `https://localhost:5001` (if a default cert is available). -*Replace the default certificate from configuration* +#### Replace the default certificate from configuration `CreateDefaultBuilder` calls `Configure(context.Configuration.GetSection("Kestrel"))` by default to load Kestrel configuration. A default HTTPS app settings configuration schema is available for Kestrel. Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store. @@ -1570,9 +1585,32 @@ Schema notes: * The `Url` parameter is required for each endpoint. The format for this parameter is the same as the top-level `Urls` configuration parameter except that it's limited to a single value. * These endpoints replace those defined in the top-level `Urls` configuration rather than adding to them. Endpoints defined in code via `Listen` are cumulative with the endpoints defined in the configuration section. * The `Certificate` section is optional. If the `Certificate` section isn't specified, the defaults defined in earlier scenarios are used. If no defaults are available, the server throws an exception and fails to start. -* The `Certificate` section supports both **Path**–**Password** and **Subject**–**Store** certificates. +* The `Certificate` section supports multiple certificate sources: + * **Path**–**Password** + * **Subject**–**Store** * Any number of endpoints may be defined in this way so long as they don't cause port conflicts. -* `options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a `KestrelConfigurationLoader` with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: + +##### Certificate sources + +Certificate nodes can be configured to load certificates from a number of sources: + +* **Path** and **Password** to load *.pfx* files. +* **Subject** and **Store** to load from the certificate store. + +For example, the **Certificates** > **Default** certificate can be specified as: + +```json +"Default": { + "Subject": "", + "Store": "", + "Location": "", + "AllowInvalid": "" +} +``` + +##### ConfigurationLoader + +`options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -1594,7 +1632,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => * Multiple configurations may be loaded by calling `options.Configure(context.Configuration.GetSection("{SECTION}"))` again with another section. Only the last configuration is used, unless `Load` is explicitly called on prior instances. The metapackage doesn't call `Load` so that its default configuration section may be replaced. * `KestrelConfigurationLoader` mirrors the `Listen` family of APIs from `KestrelServerOptions` as `Endpoint` overloads, so code and config endpoints may be configured in the same place. These overloads don't use names and only consume default settings from configuration. -*Change the defaults in code* +#### Change the defaults in code `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` can be used to change default settings for `ListenOptions` and `HttpsConnectionAdapterOptions`, including overriding the default certificate specified in the prior scenario. `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` should be called before any endpoints are configured. @@ -1616,7 +1654,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => }); ``` -*Kestrel support for SNI* +#### Kestrel support for SNI [Server Name Indication (SNI)](https://tools.ietf.org/html/rfc6066#section-3) can be used to host multiple domains on the same IP address and port. For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake. @@ -2354,13 +2392,13 @@ Supported configurations described next: * Replace the default certificate from configuration * Change the defaults in code -*No configuration* +#### No configuration Kestrel listens on `http://localhost:5000` and `https://localhost:5001` (if a default cert is available). -*Replace the default certificate from configuration* +#### Replace the default certificate from configuration `CreateDefaultBuilder` calls `Configure(context.Configuration.GetSection("Kestrel"))` by default to load Kestrel configuration. A default HTTPS app settings configuration schema is available for Kestrel. Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store. @@ -2434,9 +2472,32 @@ Schema notes: * The `Url` parameter is required for each endpoint. The format for this parameter is the same as the top-level `Urls` configuration parameter except that it's limited to a single value. * These endpoints replace those defined in the top-level `Urls` configuration rather than adding to them. Endpoints defined in code via `Listen` are cumulative with the endpoints defined in the configuration section. * The `Certificate` section is optional. If the `Certificate` section isn't specified, the defaults defined in earlier scenarios are used. If no defaults are available, the server throws an exception and fails to start. -* The `Certificate` section supports both **Path**–**Password** and **Subject**–**Store** certificates. +* The `Certificate` section supports multiple certificate sources: + * **Path**–**Password** + * **Subject**–**Store** * Any number of endpoints may be defined in this way so long as they don't cause port conflicts. -* `options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a `KestrelConfigurationLoader` with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: + +##### Certificate sources + +Certificate nodes can be configured to load certificates from a number of sources: + +* **Path** and **Password** to load *.pfx* files. +* **Subject** and **Store** to load from the certificate store. + +For example, the **Certificates** > **Default** certificate can be specified as: + +```json +"Default": { + "Subject": "", + "Store": "", + "Location": "", + "AllowInvalid": "" +} +``` + +##### ConfigurationLoader + +`options.Configure(context.Configuration.GetSection("{SECTION}"))` returns a with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -2458,7 +2519,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => * Multiple configurations may be loaded by calling `options.Configure(context.Configuration.GetSection("{SECTION}"))` again with another section. Only the last configuration is used, unless `Load` is explicitly called on prior instances. The metapackage doesn't call `Load` so that its default configuration section may be replaced. * `KestrelConfigurationLoader` mirrors the `Listen` family of APIs from `KestrelServerOptions` as `Endpoint` overloads, so code and config endpoints may be configured in the same place. These overloads don't use names and only consume default settings from configuration. -*Change the defaults in code* +#### Change the defaults in code `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` can be used to change default settings for `ListenOptions` and `HttpsConnectionAdapterOptions`, including overriding the default certificate specified in the prior scenario. `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` should be called before any endpoints are configured. @@ -2480,7 +2541,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => }); ``` -*Kestrel support for SNI* +#### Kestrel support for SNI [Server Name Indication (SNI)](https://tools.ietf.org/html/rfc6066#section-3) can be used to host multiple domains on the same IP address and port. For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.