Skip to content

Remove special Firefox instructions in >=.NET 6 sections #33472

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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tdykstra wants to merge 3 commits into from
Closed

Remove special Firefox instructions in >=.NET 6 sections #33472

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
61b14af
Remove special Firefox instructions in >=.NET 6 sections
tdykstra Aug 29, 2024
ea619ed
Update aspnetcore/security/enforcing-ssl.md
tdykstra Sep 5, 2024
f45ab8b
Update aspnetcore/security/enforcing-ssl.md
tdykstra Sep 5, 2024
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
96 changes: 5 additions & 91 deletions aspnetcore/security/enforcing-ssl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,8 +201,6 @@ dotnet new webapp --no-https

## Trust the ASP.NET Core HTTPS development certificate on Windows and macOS

For the Firefox browser, see the next section.

The .NET Core SDK includes an HTTPS development certificate. The certificate is installed as part of the first-run experience. For example, `dotnet --info` produces a variation of the following output:

```cli
Expand Down Expand Up @@ -231,55 +229,13 @@ dotnet dev-certs https --help

<a name="trust-ff"></a>

### Trust the HTTPS certificate with Firefox to prevent SEC_ERROR_INADEQUATE_KEY_USAGE error
Comment thread
amcasey marked this conversation as resolved.

The Firefox browser uses its own certificate store, and therefore doesn't trust the [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) or [Kestrel](xref:fundamentals/servers/kestrel) developer certificates.

There are two approaches to trusting the HTTPS certificate with Firefox, create a policy file or configure with the FireFox browser. Configuring with the browser creates the policy file, so the two approaches are equivalent.

#### Create a policy file to trust HTTPS certificate with Firefox

Create a policy file (`policies.json`) at:

* Windows: `%PROGRAMFILES%\Mozilla Firefox\distribution\`
* MacOS: `Firefox.app/Contents/Resources/distribution`
* Linux: See [Trust the certificate with Firefox on Linux](#trust-ff-linux) in this article.

Add the following JSON to the Firefox policy file:

```json
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
```

The preceding policy file makes Firefox trust certificates from the trusted certificates in the Windows certificate store. The next section provides an alternative approach to create the preceding policy file by using the Firefox browser.

<a name="trust-ff-ba"></a>

### Configure trust of HTTPS certificate using Firefox browser

Set `security.enterprise_roots.enabled` = `true` using the following instructions:

1. Enter `about:config` in the FireFox browser.
1. Select **Accept the Risk and Continue** if you accept the risk.
1. Select **Show All**
1. Set `security.enterprise_roots.enabled` = `true`
1. Exit and restart Firefox

For more information, see [Setting Up Certificate Authorities (CAs) in Firefox](https://support.mozilla.org/kb/setting-certificate-authorities-firefox) and the [mozilla/policy-templates/README file](https://github.com/mozilla/policy-templates/blob/master/README.md).

## How to set up a developer certificate for Docker

See [this GitHub issue](https://github.com/dotnet/AspNetCore.Docs/issues/6199).

## Trust HTTPS certificate on Linux

Establishing trust is distribution and browser specific. The following sections provide instructions for some popular distributions and the Chromium browsers (Edge and Chrome) and for Firefox.
Establishing trust is distribution and browser specific. The following sections provide instructions for some popular distributions and the Chromium browsers (Edge and Chrome).

### Trust HTTPS certificate on Linux with linux-dev-certs

Expand Down Expand Up @@ -345,36 +301,6 @@ For chromium browsers on Linux:

<a name="trust-ff-linux"></a>

#### Trust the certificate with Firefox on Linux

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Why delete, rather than update, this section? It seems like we could just tell people to run certutil as for Chromium.

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

There's a note in an unedited part of this document (above) that says certutil is "legacy". I'm not sure why - maybe just the specific version linked?

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Above, where it says to run certutil twice, it should probably only be run once - with "P,," for Chromium or "C,," for Firefox.

@Rick-Anderson Rick-Anderson Sep 6, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Why delete, rather than update, this section? It seems like we could just tell people to run certutil as for Chromium.

Are the instructions different using certutil on FF different than for Chromium? If not, we'll make sure the Chromium instructions say Chromium and FF.

@Rick-Anderson Rick-Anderson Sep 6, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

There's a note in an unedited part of this document (above) that says certutil is "legacy". I'm not sure why - maybe just the specific version linked?

the legacy comment is only for the the Red Hat Enterprise Linux tab

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Are the instructions different using certutil on FF different than for Chromium? If not, we'll make sure the Chromium instructions say Chromium and FF.

The two differences are the usage, as noted in my comment, and the location of the database. Otherwise, it should be the same.


* Export the certificate with the following command:

```vstscli
dotnet dev-certs https
sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
```

The path in the preceding command is specific for Ubuntu. For other distributions, select an appropriate path or use the path for the Certificate Authorities (CAs).

* Create a JSON file at `/usr/lib/firefox/distribution/policies.json` with the following command:

```sh
cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
"policies": {
"Certificates": {
"Install": [
"/usr/local/share/ca-certificates/aspnet/https.crt"
]
}
}
}
EOF
```
Note: Ubuntu 21.10 Firefox comes as a snap package and the installation folder is `/snap/firefox/current/usr/lib/firefox`.

See [Configure trust of HTTPS certificate using Firefox browser](#trust-ff-ba) in this article for an alternative way to configure the policy file using the browser.

# [Red Hat Enterprise Linux](#tab/linux-rhel)

> [!WARNING]
Expand Down Expand Up @@ -428,13 +354,6 @@ certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n ${CertificateName} -i ${ProjectD
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
```

#### Mozilla Firefox

```sh
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
```

#### Create An Alias To Test With Curl

> [!IMPORTANT]
Expand All @@ -450,7 +369,6 @@ alias curl="curl --cacert ${ProjectDirectory}/${CertificateName}.crt"

```sh
certutil -d sql:$HOME/.pki/nssdb -D -n ${CertificateName}
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -D -n ${CertificateName}
rm ${ProjectDirectory}/${CertificateName}.crt
dotnet dev-certs https --clean
```
Expand Down Expand Up @@ -514,13 +432,6 @@ certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n ${CertificateName} -i ${ProjectD
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
```

#### Mozilla Firefox

```sh
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
```

#### Create An Alias To Test With Curl

> [!IMPORTANT]
Expand All @@ -536,7 +447,6 @@ alias curl="curl --cacert ${ProjectDirectory}/${CertificateName}.crt"

```sh
certutil -d sql:$HOME/.pki/nssdb -D -n ${CertificateName}
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -D -n ${CertificateName}
rm ${ProjectDirectory}/${CertificateName}.crt
dotnet dev-certs https --clean
```
Expand Down Expand Up @@ -905,6 +815,8 @@ dotnet dev-certs https --help

### Trust the HTTPS certificate with Firefox to prevent SEC_ERROR_INADEQUATE_KEY_USAGE error

In some instances the Firefox browser uses its own certificate store, and therefore doesn't trust the [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) or [Kestrel](xref:fundamentals/servers/kestrel) developer certificates and requires the following instructions.

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This seems to overlap substantially with the following paragraph.


The Firefox browser uses its own certificate store, and therefore doesn't trust the [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) or [Kestrel](xref:fundamentals/servers/kestrel) developer certificates.

There are two approaches to trusting the HTTPS certificate with Firefox, create a policy file or configure with the FireFox browser. Configuring with the browser creates the policy file, so the two approaches are equivalent.
Expand Down Expand Up @@ -1003,6 +915,8 @@ For chromium browsers on Linux:

### Trust the certificate with Firefox on Linux

In some instances the Firefox browser uses its own certificate store, and therefore doesn't trust the [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) or [Kestrel](xref:fundamentals/servers/kestrel) developer certificates and requires the following instructions.

@Rick-Anderson Rick-Anderson Sep 6, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@amcasey and @tdykstra I think in the FF section we should add something like the following:

In some instances theses instructions don't work with Firefox on Linux. See [Trust the HTTPS certificate with Firefox](https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-5.0&tabs=visual-studio%2Clinux-ubuntu#trust-the-https-certificate-with-firefox-to-prevent-sec_error_inadequate_key_usage-error-1] for alternative instructions. The link goes back to .NET 5 and has all the previous instructions.

@amcasey amcasey Sep 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

AFAIK, the old instructions apply to old version of Firefox, rather than to old versions of .NET. If you're on a new enough .NET that --trust works, no Firefox-specific steps should be required. Otherwise, the instructions should be as for Chromium, but with "C,," and different locations.

Or maybe I've misunderstood your suggestion? I'm not entirely sure where in the document this text occurs.

@Rick-Anderson Rick-Anderson Sep 6, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

AFAIK, the old instructions apply to old version of Firefox, rather than to old versions of .NET. If you're on a new enough .NET that --trust works, no Firefox-specific steps should be required. Otherwise, the instructions should be as for Chromium, but with "C,," and different locations.

Or maybe I've misunderstood your suggestion? I'm not entirely sure where in the document this text occurs.

Great, we'll replace that with older versions of FF

* Export the certificate with the following command:

```vstscli
Expand Down