oracular (1) dotnet-dev-certs.1.gz
dotnet dev-certs
This article applies to: ✔️ .NET Core 3.1 SDK and later versions
NAME
dotnet-dev-certs - Generates a self-signed certificate to enable HTTPS use in development.
SYNOPSIS
dotnet dev-certs https
[-c|--check] [--clean] [-ep|--export-path <PATH>]
[--format] [-i|--import] [-np|--no-password]
[-p|--password] [-q|--quiet] [-t|--trust]
[-v|--verbose] [--version]
dotnet dev-certs https -h|--help
DESCRIPTION
The dotnet dev-certs command manages a self-signed certificate to enable HTTPS use in local web app
development. Its main functions are:
• Generating a certificate for use with HTTPS endpoints during development.
• Trusting the generated certificate on the local machine.
• Removing the generated certificate from the local machine.
• Exporting a certificate in various formats so that it can be used by other tools.
• Importing an existing certificate generated by the tool into the local machine.
Commands
• https
dotnet dev-certs has only one command: https. The dotnet dev-certs https command with no options
checks if a development certificate is present in the current user’s certificate store on the machine.
If the command finds a development certificate, it displays a message like the following example:
A valid HTTPS certificate is already present.
If the command doesn’t find a development certificate, it creates one in the current user’s certificate
store, the store named My in the location CurrentUser. The physical location of the certificate is an
implementation detail of the .NET runtime that could change at any time. On macOS in .NET 7.0, the
certificate is stored in the user key chain and as a PFX file: ~/.aspnet/https-aspnetcore-
localhost-<Thumbprint[0..5]>.pfx.
After creating a certificate, the command displays a message like the following example:
The HTTPS developer certificate was generated successfully.
By default, the newly created certificate is not trusted. To trust the certificate, use the --trust
option.
To create a file that you can use with other tools, use the --export-path option.
OPTIONS
• -c|--check
Checks for the existence of the development certificate but doesn’t perform any action. Use this
option with the --trust option to check if the certificate is not only valid but also trusted.
• --clean
Removes all HTTPS development certificates from the certificate store by using the .NET certificate
store API. Doesn’t remove any physical files that were created by using the --export-path option. On
macOS in .NET 7.0, the dotnet dev-certs command creates the certificate on a path on disk, and the
clean operation removes that certificate file.
If there’s at least one certificate in the certificate store, the command displays a message like the
following example:
Cleaning HTTPS development certificates
from the machine.
A prompt might get displayed to confirm
the removal of some of the certificates.
HTTPS development certificates
successfully removed from the machine.
• -ep|--export-path <PATH>
Exports the certificate to a file so that it can be used by other tools. Specify the full path to the
exported certificate file, including the file name. The type of certificate files that are created
depends on which options are used with --export-path:
Options What is exported
──────────────────────────────────────────────────────────────────────────────
--export-path The public part of the certificate as
a PFX file.
--export-path --format PEM The public part of the certificate in
PEM format. No separate .key file is
created.
--export-path --password The public and private parts of the
certificate as a PFX file.
--export-path --password --format PEM The public and private parts of the
certificate as a pair of files in PEM
format. The key file has the .key
extension and is protected by the
given password.
--export-path --no-password --format The public and private parts of the
PEM certificate as a pair of files in PEM
format. The key file has the .key
extension and is exported in plain
text. The --no-password option is
intended for internal testing use
only.
• --format
When used with --export-path, specifies the format of the exported certificate file. Valid values are
PFX and PEM, case-insensitive. PFX is the default.
The file format is independent of the file name extension. For example, if you specify --format pfx
and --export-path ./cert.pem, you’ll get a file named cert.pem in PFX format.
For information about the effect of this option when used with --password, --no-password, or without
either of those options, see –export-path earlier in this article.
• -i|--import <PATH>
Imports the provided HTTPS development certificate into the local machine. Requires that you also
specify the --clean option, which clears out any existing HTTPS developer certificates.
PATH specifies a path to a PFX certificate file. Provide the password with the --password option.
• -np|--no-password
Doesn’t use a password for the key when exporting a certificate to PEM format files. The key file is
exported in plain text. This option is not applicable to PFX files and is intended for internal
testing use only.
• -p|--password
Specifies the password to use:
• When exporting the development certificate to a PFX or PEM file.
• When importing a PFX file.
When exporting with --format PEM, the public and private parts of the certificate are exported as a
pair of files in PEM format. The key file has the .key extension and is protected by the given
password. In addition to the file name specified for the --export-path option, the command creates
another file in the same directory with the same name but a .key extension. For example, the following
command will generate a file named localhost.pem and a file named localhost.key in the /home/user
directory:
dotnet dev-certs https --format pem -ep /home/user/localhost.pem -p $CREDENTIAL_PLACEHOLDER$
In the example, $CREDENTIAL_PLACEHOLDER$ represents a password.
• -q|--quiet
Display warnings and errors only.
• -t|--trust
Trusts the certificate on the local machine.
If this option isn’t specified, the certificate is added to the certificate store but not to a trusted
list.
When combined with the --check option, validates that the certificate is trusted.
• -v|--verbose
Display debug information.
EXAMPLES
• Check for the presence of a development certificate, and create one in the default certificate store if
one doesn’t exist yet. But don’t trust the certificate.
dotnet dev-certs https
• Remove any development certificates that already exist on the local machine.
dotnet dev-certs https --clean
• Import a PFX file.
dotnet dev-certs https --clean --import ./certificate.pfx -p $CREDENTIAL_PLACEHOLDER$
In the preceding example, $CREDENTIAL_PLACEHOLDER$ represents a password.
• Check if a trusted development certificate is present on the local machine.
dotnet dev-certs https --check --trust
• Create a certificate, trust it, and export it to a PFX file.
dotnet dev-certs https -ep ./certificate.pfx -p $CREDENTIAL_PLACEHOLDER$ --trust
• Create a certificate, trust it, and export it to a PEM file.
dotnet dev-certs https -ep ./certificate.crt --trust --format PEM
• Create a certificate, trust it, and export it to a PEM file including the private key:
dotnet dev-certs https -ep ./certificate.crt -p $CREDENTIAL_PLACEHOLDER$ --trust --format PEM
SEE ALSO
• Generate self-signed certificates with the .NET CLI
• Enforce HTTPS in ASP.NET Core
• Troubleshoot certificate problems such as certificate not trusted
• Hosting ASP.NET Core images with Docker over HTTPS
• Hosting ASP.NET Core images with Docker Compose over HTTPS
2024-10-02 dotnet-dev-certs(1)