Skip to content

Add PEM config info to Kestrel doc #20913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
JamesNK wants to merge 5 commits into from
Closed

Add PEM config info to Kestrel doc #20913

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f04d248
Add PEM config info to Kestrel doc
JamesNK Dec 10, 2020
e618e2c
Update
JamesNK Dec 10, 2020
ad77613
Update
JamesNK Dec 10, 2020
ed4684f
pem or crt files
JamesNK Dec 10, 2020
ba7b8cf
Apply suggestions from code review
JamesNK Jan 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 87 additions & 26 deletions aspnetcore/fundamentals/servers/kestrel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<a name="configuration"></a>

*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.

Expand Down Expand Up @@ -546,7 +546,8 @@ In the following *appsettings.json* example:
"Https": {
"Url": "https://*:5004",
"Certificate": {
"Path": "<path to .pfx file>",
"Path": "<path to .pem or .crt file>",
"KeyPath": "<path to .key file>",
"Password": "<certificate password>"
}
}
Expand All @@ -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.
Copy link
Copy Markdown
Contributor

@blowdart blowdart Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you link back to the Urls parameter so people can easily see the format? If not, duplicate the format here.

* 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.
Copy link
Copy Markdown
Contributor

@blowdart blowdart Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs an example. I know what it means, but would all readers?

Copy link
Copy Markdown
Contributor

@Rick-Anderson Rick-Anderson Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just checking, is it literally Urls or is it the plural of Url? This needs to be a literal and you can't make literals plural by tacking on a s

* 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.
Copy link
Copy Markdown
Contributor

@blowdart blowdart Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What earlier scenarios? Specify them or link to them. Also what exception?

Copy link
Copy Markdown
Contributor

@Rick-Anderson Rick-Anderson Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is an earlier scenario? The style guide prefers previous, but you need to be specific, such as

If the Certificate section isn't specified, the defaults, defined previously, are used.

* The `Certificate` section supports multiple certificate sources:
* **Path**&ndash;**Password**
* **Path**&ndash;**KeyPath**&dash;**Password**
* **Subject**&ndash;**Store**
* Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
Copy link
Copy Markdown
Contributor

@blowdart blowdart Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

port conflicts needs explaining.


##### 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": {
Expand All @@ -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**&ndash;**Password** and **Subject**&ndash;**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 <xref:Microsoft.AspNetCore.Server.Kestrel.KestrelConfigurationLoader> with an `.Endpoint(string name, listenOptions => { })` method that can be used to supplement a configured endpoint's settings:

```csharp
webBuilder.UseKestrel((context, serverOptions) =>
Expand All @@ -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.

Expand All @@ -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.
Copy link
Copy Markdown
Contributor

@blowdart blowdart Jan 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Provided rather than furnished? Easier to understand


Expand Down Expand Up @@ -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).

<a name="configuration"></a>

*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.

Expand Down Expand Up @@ -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**&ndash;**Password** and **Subject**&ndash;**Store** certificates.
* The `Certificate` section supports multiple certificate sources:
* **Path**&ndash;**Password**
* **Subject**&ndash;**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": "<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}"))` returns a <xref:Microsoft.AspNetCore.Server.Kestrel.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) =>
Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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).

<a name="configuration"></a>

*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.

Expand Down Expand Up @@ -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**&ndash;**Password** and **Subject**&ndash;**Store** certificates.
* The `Certificate` section supports multiple certificate sources:
* **Path**&ndash;**Password**
* **Subject**&ndash;**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": "<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}"))` returns a <xref:Microsoft.AspNetCore.Server.Kestrel.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) =>
Expand All @@ -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.

Expand All @@ -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.

Expand Down