From f04d248f1f6daa20cbe88aec9b3ce45f9ca2b7b6 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 10 Dec 2020 13:39:56 +1300 Subject: [PATCH 1/5] Add PEM config info to Kestrel doc --- aspnetcore/fundamentals/servers/kestrel.md | 24 +++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 560e8d37d221..160a6ff10f31 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. @@ -599,7 +599,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 +618,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 +1490,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. @@ -1594,7 +1594,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 +1616,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 +2354,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. @@ -2458,7 +2458,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 +2480,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. From e618e2c963b397932d7b22d4f3d0bb4183ecc857 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 10 Dec 2020 13:52:06 +1300 Subject: [PATCH 2/5] Update --- aspnetcore/fundamentals/servers/kestrel.md | 32 +++++++++++++++------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 160a6ff10f31..6b67b44d232c 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -546,7 +546,8 @@ In the following *appsettings.json* example: "Https": { "Url": "https://*:5004", "Certificate": { - "Path": "", + "Path": "", + "KeyPath": "", "Password": "" } } @@ -561,7 +562,24 @@ 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 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 **Path**–**Password**, **Path**–**KeyPath**‐**Password**, and **Subject**–**Store** certificates. +* 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* 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 +590,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 `KestrelConfigurationLoader` with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings: ```csharp webBuilder.UseKestrel((context, serverOptions) => From ad7761308e443e3f35653e8493c9e007e3cc7b78 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 10 Dec 2020 14:00:45 +1300 Subject: [PATCH 3/5] Update --- aspnetcore/fundamentals/servers/kestrel.md | 59 ++++++++++++++++++++-- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 6b67b44d232c..6bef8bd799cc 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -568,7 +568,10 @@ 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 **Path**–**Password**, **Path**–**KeyPath**‐**Password**, and **Subject**–**Store** certificates. +* 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 @@ -1582,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 `KestrelConfigurationLoader` 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) => @@ -2446,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 `KestrelConfigurationLoader` 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) => From ed4684f0fda1000227bcfccc4299bc7d650b4c41 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 11 Dec 2020 09:39:21 +1300 Subject: [PATCH 4/5] pem or crt files --- aspnetcore/fundamentals/servers/kestrel.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 6bef8bd799cc..b3571827d79c 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -546,7 +546,7 @@ In the following *appsettings.json* example: "Https": { "Url": "https://*:5004", "Certificate": { - "Path": "", + "Path": "", "KeyPath": "", "Password": "" } @@ -579,7 +579,7 @@ Schema notes: 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* and *.key* 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: From ba7b8cfaced9477e532aeee6ccf8d9829049ea43 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 5 Jan 2021 10:36:42 +1300 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index b3571827d79c..d92e7c804acc 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -564,7 +564,7 @@ In the following *appsettings.json* example: Schema notes: -* Endpoints names are case-insensitive. For example, `HTTPS` and `Https` are valid. +* 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. @@ -595,7 +595,7 @@ For example, the **Certificates** > **Default** certificate can be specified as: ##### ConfigurationLoader -`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) => @@ -1610,7 +1610,7 @@ For example, the **Certificates** > **Default** certificate can be specified as: ##### ConfigurationLoader -`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 public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -2497,7 +2497,7 @@ For example, the **Certificates** > **Default** certificate can be specified as: ##### ConfigurationLoader -`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 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>