skip to content

What does dotnet dev-certs https --trust do for local ASP.NET Core development, and when do you reach for --check, --clean or --export-path?

level: juniorimportance: should knowfreq 36%

answer

  1. installed, but not trusted
  2. localhost certificate from the SDK's first run
  3. --trust, then restart the browser
  4. --clean when it is broken or expired
  5. --export-path for a container

basics

~20 s

The .NET SDK creates an ASP.NET Core HTTPS development certificate for localhost but does not trust it; dotnet dev-certs https --trust adds it to the trusted stores so browsers accept https://localhost. --check tests it, --clean removes it, --export-path copies it out.

solid answer

~50 s

On first use the .NET SDK generates a localhost certificate, the "ASP.NET Core HTTPS development certificate", in the current user's store (unless `DOTNET_GENERATE_ASPNET_CERTIFICATE` is `false`), and Kestrel falls back to it for an HTTPS endpoint with no certificate configured, such as the launch profile's `https://localhost:7xxx`. It is installed but not trusted, so browsers warn. `dotnet dev-certs https --trust` trusts it, creating one if needed: Windows and macOS stores, and on Linux OpenSSL and browser stores where supported (officially Ubuntu and Fedora). `--check` reports whether a certificate exists, and with `--trust` whether it is trusted. `--clean` removes all development certificates, the fix for an expired or corrupted one before running `--trust` again. `-ep`/`--export-path` with `--password`, or `--format Pem` with `--no-password`, exports it, for example to mount into a container. On the .NET 10 SDK the export directory must already exist.

code

bash · 13 lines
bash
# Trust the development certificate (creates it if missing)
dotnet dev-certs https --trust

# Is there a certificate, and is it trusted?
dotnet dev-certs https --check --trust

# Start over when the certificate is broken or expired
dotnet dev-certs https --clean
dotnet dev-certs https --trust

# Export for a container; create the folder first
mkdir -p ~/.aspnet/https
dotnet dev-certs https -ep ~/.aspnet/https/refills.pfx -p "$DEV_CERT_PASSWORD"

go deeper

for a junior

Remember that the SDK's localhost certificate starts untrusted, and that dotnet dev-certs https --trust fixes the browser warning.

for a middle

Explain --check, --clean and the export options, how trust differs on Windows, macOS and Linux, and why the browser may need a restart.

for a senior

Set up HTTPS for containerised local development safely: export with a password into a directory you created, mount at run time, and keep development certificates out of images.

for a principal

Standardise local HTTPS across a team, including Linux workstations and dev containers, so certificate problems do not become a recurring onboarding cost.

## What the development certificate is Running `https://localhost` needs a certificate for `localhost`. The .NET SDK creates one, the **ASP.NET Core HTTPS development certificate**, during its first-run experience and stores it in the current user's certificate store. It is meant only for local development: - Kestrel uses it when an HTTPS endpoint has no certificate configured, which is exactly the case for the `https` launch profile the templates write. - It is **installed but not trusted**, so the browser shows a certificate warning and tools such as `curl` or `HttpClient` refuse the connection. - In the .NET 10 SDK the certificate also covers `*.dev.localhost` (for the `--localhost-tld` template option) and `*.dev.internal`, so a certificate trusted under an older SDK should be trusted again after upgrading. - Setting `DOTNET_GENERATE_ASPNET_CERTIFICATE=false` before the SDK's first run skips generating it, which the docs recommend for container images and virtual machines meant for redistribution. Production certificates are a different subject: they are configured on the server's endpoints, not created by this tool. ## The commands | Command | What it does | |---|---| | `dotnet dev-certs https` | creates the certificate if none exists | | `dotnet dev-certs https --trust` (`-t`) | trusts it, creating one if necessary | | `dotnet dev-certs https --check` (`-c`) | reports whether a valid certificate exists, changing nothing | | `dotnet dev-certs https --check --trust` | also reports whether it is trusted | | `dotnet dev-certs https --clean` | removes all HTTPS development certificates from the machine | | `dotnet dev-certs https -ep <path>` | exports it to a file (PFX by default) | | `dotnet dev-certs https --import <path>` (`-i`) | imports a certificate, replacing existing ones | Export options: `-p`/`--password` protects the key, `--format Pem` writes PEM files, and `-np`/`--no-password` must be given explicitly to export a PEM key without a password. `--check-trust-machine-readable` prints the check's result as JSON for scripts. ## Trust per platform 1. **Windows**: `--trust` adds the certificate to the current user's trusted root store, after a confirmation prompt. 2. **macOS**: it is added to the keychain and marked trusted; the system may ask for a password. 3. **Linux**: distributions differ. The tool exports the certificate to a folder under the user's home directory for OpenSSL, which needs `SSL_CERT_DIR` to include it, and updates browser certificate databases when `certutil` is available. The docs list official support for Ubuntu and Fedora only; other distributions need manual steps. After trusting, restart the browser, which caches certificate decisions. ## Common fixes - **Browser still warns after `--trust`**: run `dotnet dev-certs https --clean`, then `dotnet dev-certs https --trust`, then restart the browser. This also recovers from an expired development certificate. - **A container needs HTTPS in development**: export the certificate with a password into a directory that already exists, mount it into the container, and point Kestrel's default certificate at it. Since .NET 9, `--export-path` fails if the directory does not exist ("There was an error exporting the HTTPS developer certificate to a file."), so create it first with permissions you chose. - **CI or scripts need to know the state**: `--check --trust` returns a non-zero exit code when the certificate is missing or untrusted. ## What it does not do - It does not touch HSTS: browsers that cached HSTS for a custom local host name keep enforcing it regardless of the certificate. - It does not cover arbitrary local names. The .NET 10 SDK's certificate lists `localhost`, `*.dev.localhost`, `*.dev.internal`, `host.docker.internal`, `host.containers.internal` and both loopback addresses; any other custom local domain needs its own certificate.

  • Why does dotnet dev-certs https -ep fail on the .NET 10 SDK when the folder does not exist?
    Since .NET 9 (and 8.0.10) the tool refuses to create the target directory, because the exported file contains the private key and it does not want to choose that directory's permissions for you. Create the directory yourself with appropriate permissions, then run the export again.
  • Should the ASP.NET Core development certificate be baked into a container image?
    No. The docs warn against creating a development certificate in an image or VM meant for redistribution, since everyone with the image shares the key; set `DOTNET_GENERATE_ASPNET_CERTIFICATE=false` there. For local container development, export the certificate from your machine and mount it at run time instead.

  • Installing the .NET SDK leaves the development certificate already trusted.
  • dotnet dev-certs https --clean only removes the trust, keeping the certificate.
  • The development certificate can secure the production site if it is trusted.
  • dotnet dev-certs https --check fixes an untrusted certificate.
  • On the .NET 10 SDK, --export-path creates any missing folders for you.

Assumes the .NET 10 SDK, whose development certificate adds *.dev.localhost and should be re-trusted after upgrading; since .NET 9 (and 8.0.10) --export-path no longer creates a missing directory.