Skip to content
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.

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

Add support for trusting dev certs on linux #56582

Merged
merged 12 commits into from
Jul 29, 2024
Merged

Conversation

amcasey
Copy link
Member

@amcasey amcasey commented Jul 2, 2024

Overview

There's no consistent way to do this that works for all clients on all Linux distros, but this approach gives us pretty good coverage. In particular, we aim to support .NET (esp HttpClient), Chromium, and Firefox on Ubuntu- and Fedora-based distros.

Certificate trust is applied per-user, which is simpler and preferable for security reasons, but comes with the notable downside that the process can't be completed within the tool - the user has to update an environment variable, probably in their user profile. In particular, OpenSSL consumes the SSL_CERT_DIR environment variable to determine where it should look for trusted certificates.

We break establishing trust into two categories: OpenSSL, which backs .NET, and NSS databases (henceforth, nssdb), which backs browsers.

To establish trust in OpenSSL, we put the certificate in ~/.dotnet/corefx/cryptography/trusted, run a simplified version of OpenSSL's c_rehash tool on the directory, and ask the user to update SSL_CERT_DIR.

To establish trust in nssdb, we search the home directory for Firefox profiles and ~/.pki/nssdb. For each one found, we add an entry to the nssdb therein.

Each of these locations (the trusted certificate folder and the list of nssdbs) can be overridden with an environment variable.

This large number of steps introduces a problem that doesn't exist on Windows or macOS - the dev cert can end up trusted by some clients but not by others. This change introduces a TrustLevel concept so that we can produce clearer output when this happens.

The only non-bundled tools required to update certificate trust are openssl (the CLI) and certutil. sudo is not required, since all changes are within the user's home directory.

Comparison with community tools

There are some community projects that have added this functionality, but they differ from this implementation in some notable ways:

  1. We're using the same certificate as on Windows and macOS - it's not a CA
  2. We're only trusting the certificate for a single-user
  3. We require the additional step of setting SSL_CERT_DIR
  4. We require OpenSSL 1.1.1h or greater to handle the fact that our cert is not a CA

Work outside this repo

  1. We need to update the docs. Presently, they say this is impossible. Instead, they should explain limitations and provide troubleshooting steps
  2. More docs: https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-8.0&tabs=visual-studio%2Clinux-ubuntu#ssl-linux
  3. We need to update the docker tools docs (cc @richlander).
  4. We need to write manual testing instructions for pre-release validation
  5. We could consider pre-setting SSL_CERT_DIR in our official docker images
  6. We could consider setting SSL_CERT_DIR in install-dotnet.sh (assuming it's already setting things like DOTNET_ROOT)

@dotnet-issue-labeler dotnet-issue-labeler bot added the area-networking Includes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions label Jul 2, 2024
@amcasey
Copy link
Member Author

amcasey commented Jul 2, 2024

FYI @tmds

@richlander
Copy link
Member

richlander commented Jul 9, 2024

It would be good to develop a POC for this with both Docker multi-stage build and SDK publish.

We could consider pre-setting SSL_CERT_DIR in our official docker images

I don't grasp why we would do this.

@baronfel @MichaelSimons

@amcasey
Copy link
Member Author

amcasey commented Jul 9, 2024

It would be good to develop a POC for this with both Docker multi-stage build and SDK publish.

I'm not sure what these things are. I think you might be saying we should validate that the new functionality works in some specific scenarios, but I'm not familiar with those scenarios.

We could consider pre-setting SSL_CERT_DIR in our official docker images

I don't grasp why we would do this.

It's entirely possible that my comment doesn't make sense. What I had in mind is that, for OpenSSL to trust a certificate, it needs to be in a folder that is listed in the SSL_CERT_DIR environment variable. dotnet dev-certs can't set an environment variable in the containing process and adding it to the user's profile is fraught for both social and technical reasons. However, in a docker image, it seems like we could do that on the user's behalf (add our well-known trusted-certificate directory to SSL_CERT_DIR).

@javiercn
Copy link
Member

javiercn commented Jul 9, 2024

It would be good to develop a POC for this with both Docker multi-stage build and SDK publish.

I'm not sure what these things are. I think you might be saying we should validate that the new functionality works in some specific scenarios, but I'm not familiar with those scenarios.

We could consider pre-setting SSL_CERT_DIR in our official docker images

I don't grasp why we would do this.

It's entirely possible that my comment doesn't make sense. What I had in mind is that, for OpenSSL to trust a certificate, it needs to be in a folder that is listed in the SSL_CERT_DIR environment variable. dotnet dev-certs can't set an environment variable in the containing process and adding it to the user's profile is fraught for both social and technical reasons. However, in a docker image, it seems like we could do that on the user's behalf (add our well-known trusted-certificate directory to SSL_CERT_DIR).

We can just update our Dockerfile to include it, the same way it has an instruction to expose the right ports. No need to set the environment variable in the container image directly.

@richlander
Copy link
Member

richlander commented Jul 9, 2024

However, in a docker image, it seems like we could do that on the user's behalf (add our well-known trusted-certificate directory to SSL_CERT_DIR).

We're unlikely to do that. We don't want to change the trust model of the container images we ship. If you can add certs in the directory, you can set the ENV.

I'm asking for E2E examples for the scenario that this feature targets. We can help you if you are not familiar with the specifics. As a general rule, high-level Linux features (and certs are pretty high-level) should be fully validated with the container workflow. I'm seeing a lot of assumptions here.

Separately, if you are just on a raw Linux box, why not use update-ca-certificates? That's the standard, tool, yes?

@amcasey
Copy link
Member Author

amcasey commented Jul 9, 2024

However, in a docker image, it seems like we could do that on the user's behalf (add our well-known trusted-certificate directory to SSL_CERT_DIR).

We're unlikely to do that. We don't want to change the trust model of the container images we ship.

Fine by me.

If you can add certs in the directory, you can set the ENV.

I can't tell if you mean you, the dotnet dev-certs owner, or you, the dotnet dev-certs invoker. Somewhat moot if we're not doing it either way.

I'm asking for E2E examples for the scenario that this feature targets.

Examples in the sense of user-facing samples or in the sense of manual validation?

We can help you if you are not familiar with the specifics.

That would be great.

As a general rule, high-level Linux features (and certs are pretty high-level) should be fully validated with the container workflow.

I've been using both docker and GUI VMs for my validation, but I expect more real-world tests once it's ready for the Aspire folks to play with.

I'm seeing a lot of assumptions here.

Tell me more? This is definitely uncertain terrain, but we've been through several rounds of consultation and prototyping.

Separately, if you are just on a raw Linux box, why not use update-ca-certificates? That's the standard, tool, yes?

The main reasons are:

  1. The aspnetcore dev cert is not a CA, so it doesn't play nicely with standard tools like update-ca-certificates.
  2. Invoking update-ca-certificates requires sudo, which isn't a great user experience.
  3. update-ca-certificates trusts the certificate for all users on a box, which has security consequences (and is just plain confusing since the cert is stored and trusted by browsers on a per-user basis).

@richlander
Copy link
Member

Ok. I think I understand a bit better now.

Here are some workflows we documented many years ago: https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md#linux. I'm assuming for an environment where the browser is your local machine and the app is in a container that the new workflow would be very similar. Is that fair?

@amcasey
Copy link
Member Author

amcasey commented Jul 9, 2024

Ok. I think I understand a bit better now.

Here are some workflows we documented many years ago: https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md#linux. I'm assuming for an environment where the browser is your local machine and the app is in a container that the new workflow would be very similar. Is that fair?

Yeah, I think you'd just additionally run dotnet dev-certs https --trust on the local machine. Of course, things get more complicated if the code running in the container is making requests with HttpClient that also need to be validated with the dev cert.

@richlander
Copy link
Member

We can collaborate offline on a workflow / writeup if you'd like. I did the same with that doc I shared with @javiercn.

@amcasey
Copy link
Member Author

amcasey commented Jul 9, 2024

Sounds great. Let me get it through threat modelling first so we don't have to redo the docs if our approach changes.

@amcasey
Copy link
Member Author

amcasey commented Jul 9, 2024

Force push is a rebase on top of #56701.

@amcasey
Copy link
Member Author

amcasey commented Jul 10, 2024

Force push is just picking up fresh changes from #56701, since it wasn't working on Windows.

@amcasey amcasey marked this pull request as ready for review July 23, 2024 22:28
There's no consistent way to do this that works for all clients on all Linux distros, but this approach gives us pretty good coverage.  In particular, we aim to support .NET (esp HttpClient), Chromium, and Firefox on Ubuntu- and Fedora-based distros.

Certificate trust is applied per-user, which is simpler and preferable for security reasons, but comes with the notable downside that the process can't be completed within the tool - the user has to update an environment variable, probably in their user profile.  In particular, OpenSSL consumes the `SSL_CERT_DIR` environment variable to determine where it should look for trusted certificates.

We break establishing trust into two categories: OpenSSL, which backs .NET, and NSS databases (henceforth, nssdb), which backs browsers.

To establish trust in OpenSSL, we put the certificate in `~/.dotnet/corefx/cryptography/trusted`, run a simplified version of OpenSSL's `c_rehash` tool on the directory, and ask the user to update `SSL_CERT_DIR`.

To establish trust in nssdb, we search the home directory for Firefox profiles and `~/.pki/nssdb`.  For each one found, we add an entry to the nssdb therein.

Each of these locations (the trusted certificate folder and the list of nssdbs) can be overridden with an environment variable.

This large number of steps introduces a problem that doesn't exist on Windows or macOS - the dev cert can end up trusted by some clients but not by others.  This change introduces a `TrustLevel` concept so that we can produce clearer output when this happens.

The only non-bundled tools required to update certificate trust are `openssl` (the CLI) and `certutil`.  `sudo` is not required, since all changes are within the user's home directory.
@amcasey
Copy link
Member Author

amcasey commented Jul 23, 2024

Force push just replaces the merge with a rebase. The code is the same.

Copy link
Member

@javiercn javiercn left a comment

Choose a reason for hiding this comment

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

Looks great, left a couple of comments, but nothing major that we can't solve afterwards if we wanted to.

@amcasey amcasey merged commit 27ae082 into dotnet:main Jul 29, 2024
26 checks passed
@amcasey amcasey deleted the linux-dev-certs branch July 29, 2024 17:53
@dotnet-policy-service dotnet-policy-service bot added this to the 9.0-rc1 milestone Jul 29, 2024
amcasey added a commit to amcasey/aspnetcore that referenced this pull request Jul 31, 2024
* Add support for trusting dev certs on linux

There's no consistent way to do this that works for all clients on all Linux distros, but this approach gives us pretty good coverage.  In particular, we aim to support .NET (esp HttpClient), Chromium, and Firefox on Ubuntu- and Fedora-based distros.

Certificate trust is applied per-user, which is simpler and preferable for security reasons, but comes with the notable downside that the process can't be completed within the tool - the user has to update an environment variable, probably in their user profile.  In particular, OpenSSL consumes the `SSL_CERT_DIR` environment variable to determine where it should look for trusted certificates.

We break establishing trust into two categories: OpenSSL, which backs .NET, and NSS databases (henceforth, nssdb), which backs browsers.

To establish trust in OpenSSL, we put the certificate in `~/.dotnet/corefx/cryptography/trusted`, run a simplified version of OpenSSL's `c_rehash` tool on the directory, and ask the user to update `SSL_CERT_DIR`.

To establish trust in nssdb, we search the home directory for Firefox profiles and `~/.pki/nssdb`.  For each one found, we add an entry to the nssdb therein.

Each of these locations (the trusted certificate folder and the list of nssdbs) can be overridden with an environment variable.

This large number of steps introduces a problem that doesn't exist on Windows or macOS - the dev cert can end up trusted by some clients but not by others.  This change introduces a `TrustLevel` concept so that we can produce clearer output when this happens.

The only non-bundled tools required to update certificate trust are `openssl` (the CLI) and `certutil`.  `sudo` is not required, since all changes are within the user's home directory.

* Also trust certificates in the Current User/Root store

A belt-and-suspenders approach for dotnet trust (i.e. in addition to OpenSSL trust) that has the notable advantage of not requiring any environment variables.

* Clarify the mac-specific comments in GetDevelopmentCertificateFromStore

(cherry picked from commit 27ae082)
amcasey added a commit to amcasey/dotnet.sdk that referenced this pull request Aug 2, 2024
As of dotnet/aspnetcore#56582, `--trust` is supported on (key distros of) Linux.
Unofficially, it will likely work on others as well.
amcasey added a commit to amcasey/dotnet.sdk that referenced this pull request Aug 2, 2024
As of dotnet/aspnetcore#56582, `--trust` is supported on (key distros of) Linux.
Unofficially, it will likely work on others as well.
wtgodbe pushed a commit that referenced this pull request Aug 8, 2024
* Look up trusted certs consistently on windows (#56701)

* Search for trusted certificates consistently on Windows

1. Don't use thumbprint so we don't get flagged for using SHA-1
2. Make TrustCertificateCore and RemoveCertificateFromTrustedRoots consistent

* Add a note about our usage of Thumbprint on macOS

* Clean up assumptions about root store

* FindBySubjectName expects a string

* Search by serial number to avoid having to parse subject name

* Fix typo

Co-authored-by: Martin Costello <[email protected]>

* Call DisposeCertificates more consistently

---------

Co-authored-by: Martin Costello <[email protected]>
(cherry picked from commit ed7ea40)

* Make dev-certs import consistent with kestrel (#57014)

* Make dev-certs import consistent with kestrel

Kestrel checks the subject name and our magic extension - import was only checking the extension.  They can't easily share a method because import has a test hook.

(cherry picked from commit 06155c0)

* Add support for trusting dev certs on linux (#56582)

* Add support for trusting dev certs on linux

There's no consistent way to do this that works for all clients on all Linux distros, but this approach gives us pretty good coverage.  In particular, we aim to support .NET (esp HttpClient), Chromium, and Firefox on Ubuntu- and Fedora-based distros.

Certificate trust is applied per-user, which is simpler and preferable for security reasons, but comes with the notable downside that the process can't be completed within the tool - the user has to update an environment variable, probably in their user profile.  In particular, OpenSSL consumes the `SSL_CERT_DIR` environment variable to determine where it should look for trusted certificates.

We break establishing trust into two categories: OpenSSL, which backs .NET, and NSS databases (henceforth, nssdb), which backs browsers.

To establish trust in OpenSSL, we put the certificate in `~/.dotnet/corefx/cryptography/trusted`, run a simplified version of OpenSSL's `c_rehash` tool on the directory, and ask the user to update `SSL_CERT_DIR`.

To establish trust in nssdb, we search the home directory for Firefox profiles and `~/.pki/nssdb`.  For each one found, we add an entry to the nssdb therein.

Each of these locations (the trusted certificate folder and the list of nssdbs) can be overridden with an environment variable.

This large number of steps introduces a problem that doesn't exist on Windows or macOS - the dev cert can end up trusted by some clients but not by others.  This change introduces a `TrustLevel` concept so that we can produce clearer output when this happens.

The only non-bundled tools required to update certificate trust are `openssl` (the CLI) and `certutil`.  `sudo` is not required, since all changes are within the user's home directory.

* Also trust certificates in the Current User/Root store

A belt-and-suspenders approach for dotnet trust (i.e. in addition to OpenSSL trust) that has the notable advantage of not requiring any environment variables.

* Clarify the mac-specific comments in GetDevelopmentCertificateFromStore

(cherry picked from commit 27ae082)

* Revert 9.0-specific changes

* Restrict permissions to the dev cert directory (#56985)

* Create directories with secure permissions

If we're creating it, make it 700.  If it already exists, warn if it's not 700.

* Don't create a directory specified by the user

(cherry picked from commit 1470e00)
@adityamandaleeka adityamandaleeka added the blog-candidate Consider mentioning this in the release blog post label Aug 10, 2024
Copy link
Contributor

@amcasey, this change will be considered for inclusion in the blog post for the release it'll ship in. Nice work!

Please ensure that the original comment in this thread contains a clear explanation of what the change does, why it's important (what problem does it solve?), and, if relevant, include things like code samples and/or performance numbers.

This content may not be exactly what goes into the blog post, but it will help the team putting together the announcement.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-networking Includes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions blog-candidate Consider mentioning this in the release blog post
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants