1dotnet-dev-certs(1) .NET Documentation dotnet-dev-certs(1)
2
6 This article applies to: ✔️ .NET Core 3.1 SDK and later versions
7
9 dotnet-dev-certs - Generates a self-signed certificate to enable HTTPS
10 use in development.
11
13 dotnet dev-certs https
14 [-c|--check] [--clean] [-ep|--export-path <PATH>]
15 [--format] [-i|--import] [-np|--no-password]
16 [-p|--password] [-q|--quiet] [-t|--trust]
17 [-v|--verbose] [--version]
18 dotnet dev-certs https -h|--help
20
22 The dotnet dev-certs command manages a self-signed certificate to en‐
23 able HTTPS use in local web app development. Its main functions are:
24 • Generating a certificate for use with HTTPS endpoints during develop‐
26 ment.
27 • Trusting the generated certificate on the local machine.
29 • Removing the generated certificate from the local machine.
31 • Exporting a certificate in various formats so that it can be used by
33 other tools.
34 • Importing an existing certificate generated by the tool into the lo‐
36 cal machine.
37 Commands
39 • https
40 dotnet dev-certs has only one command: https. The dotnet dev-certs
42 https command with no options checks if a development certificate is
43 present in the current user’s certificate store on the machine. If
44 the command finds a development certificate, it displays a message
45 like the following example:
46 A valid HTTPS certificate is already present.
48 If the command doesn’t find a development certificate, it creates one
50 in the current user’s certificate store, the store named My in the
51 location CurrentUser. The physical location of the certificate is an
52 implementation detail of the .NET runtime that could change at any
53 time. On macOS in .NET 7.0, the certificate is stored in the user
54 key chain and as a PFX file: ~/.aspnet/https-aspnetcore-local‐
55 host-<Thumbprint[0..5]>.pfx.
56 After creating a certificate, the command displays a message like the
58 following example:
59 The HTTPS developer certificate was generated successfully.
61 By default, the newly created certificate is not trusted. To trust
63 the certificate, use the --trust option.
64 To create a file that you can use with other tools, use the --export-
66 path option.
67
69 • -c|--check
70 Checks for the existence of the development certificate but doesn’t
72 perform any action. Use this option with the --trust option to check
73 if the certificate is not only valid but also trusted.
74 • --clean
76 Removes all HTTPS development certificates from the certificate store
78 by using the .NET certificate store API. Doesn’t remove any physical
79 files that were created by using the --export-path option. On macOS
80 in .NET 7.0, the dotnet dev-certs command creates the certificate on
81 a path on disk, and the clean operation removes that certificate
82 file.
83 If there’s at least one certificate in the certificate store, the
85 command displays a message like the following example:
86 Cleaning HTTPS development certificates
88 from the machine.
89 A prompt might get displayed to confirm
90 the removal of some of the certificates.
91 HTTPS development certificates
93 successfully removed from the machine.
94 • -ep|--export-path <PATH>
96 Exports the certificate to a file so that it can be used by other
98 tools. Specify the full path to the exported certificate file, in‐
99 cluding the file name. The type of certificate files that are creat‐
100 ed depends on which options are used with --export-path:
101 Options What is exported
103 ────────────────────────────────────────────────────────
104 --export-path The public part of the
105 certificate as a PFX file.
106 --export-path --format PEM The public part of the
107 certificate in PEM format.
108 No separate .key file is
109 created.
110 --export-path --password The public and private
111 parts of the certificate
112 as a PFX file.
113 --export-path --password The public and private
114 --format PEM parts of the certificate
115 as a pair of files in PEM
116 format. The key file has
117 the .key extension and is
118 protected by the given
119 password.
120 --export-path --no-pass‐ The public and private
121 word --format PEM parts of the certificate
122 as a pair of files in PEM
123 format. The key file has
124 the .key extension and is
125 exported in plain text.
126 The --no-password option
127 is intended for internal
128 testing use only.
129 • --format
131 When used with --export-path, specifies the format of the exported
133 certificate file. Valid values are PFX and PEM, case-insensitive.
134 PFX is the default.
135 The file format is independent of the file name extension. For exam‐
137 ple, if you specify --format pfx and --export-path ./cert.pem, you’ll
138 get a file named cert.pem in PFX format.
139 For information about the effect of this option when used with
141 --password, --no-password, or without either of those options, see
142 –export-path earlier in this article.
143 • -i|--import <PATH>
145 Imports the provided HTTPS development certificate into the local ma‐
147 chine. Requires that you also specify the --clean option, which
148 clears out any existing HTTPS developer certificates.
149 PATH specifies a path to a PFX certificate file. Provide the pass‐
151 word with the --password option.
152 • -np|--no-password
154 Doesn’t use a password for the key when exporting a certificate to
156 PEM format files. The key file is exported in plain text. This op‐
157 tion is not applicable to PFX files and is intended for internal
158 testing use only.
159 • -p|--password
161 Specifies the password to use:
163 • When exporting the development certificate to a PFX or PEM file.
165 • When importing a PFX file.
167 When exporting with --format PEM, the public and private parts of the
169 certificate are exported as a pair of files in PEM format. The key
170 file has the .key extension and is protected by the given password.
171 In addition to the file name specified for the --export-path option,
172 the command creates another file in the same directory with the same
173 name but a .key extension. For example, the following command will
174 generate a file named localhost.pem and a file named localhost.key in
175 the /home/user directory:
176 dotnet dev-certs https --format pem -ep /home/user/localhost.pem -p $CREDENTIAL_PLACEHOLDER$
178 In the example, $CREDENTIAL_PLACEHOLDER$ represents a password.
180 • -q|--quiet
182 Display warnings and errors only.
184 • -t|--trust
186 Trusts the certificate on the local machine.
188 If this option isn’t specified, the certificate is added to the cer‐
190 tificate store but not to a trusted list.
191 When combined with the --check option, validates that the certificate
193 is trusted.
194 • -v|--verbose
196 Display debug information.
198
200 • Check for the presence of a development certificate, and create one
201 in the default certificate store if one doesn’t exist yet. But don’t
202 trust the certificate.
203 dotnet dev-certs https
205 • Remove any development certificates that already exist on the local
207 machine.
208 dotnet dev-certs https --clean
210 • Import a PFX file.
212 dotnet dev-certs https --clean --import ./certificate.pfx -p $CREDENTIAL_PLACEHOLDER$
214 In the preceding example, $CREDENTIAL_PLACEHOLDER$ represents a pass‐
216 word.
217 • Check if a trusted development certificate is present on the local
219 machine.
220 dotnet dev-certs https --check --trust
222 • Create a certificate, trust it, and export it to a PFX file.
224 dotnet dev-certs https -ep ./certificate.pfx -p $CREDENTIAL_PLACEHOLDER$ --trust
226 • Create a certificate, trust it, and export it to a PEM file.
228 dotnet dev-certs https -ep ./certificate.crt --trust --format PEM
230 • Create a certificate, trust it, and export it to a PEM file including
232 the private key:
233 dotnet dev-certs https -ep ./certificate.crt -p $CREDENTIAL_PLACEHOLDER$ --trust --format PEM
235
237 • Generate self-signed certificates with the .NET CLI
238 • Enforce HTTPS in ASP.NET Core
240 • Troubleshoot certificate problems such as certificate not trusted
242 • Hosting ASP.NET Core images with Docker over HTTPS
244 • Hosting ASP.NET Core images with Docker Compose over HTTPS
246 2022-10-10 dotnet-dev-certs(1)