Edit

Share via

dotnet dev-certs

  • Article

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 containing directories must already exist and access to them should be restricted. 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 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 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