]>
Commit | Line | Data |
---|---|---|
aba3e65f | 1 | =pod |
625c781d | 2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} |
9fcb9702 | 3 | |
aba3e65f DSH |
4 | =head1 NAME |
5 | ||
4b537191 | 6 | openssl-x509 - Certificate display and signing command |
aba3e65f DSH |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<x509> | |
169394d4 | 11 | [B<-help>] |
e8769719 RS |
12 | [B<-inform> B<DER>|B<PEM>] |
13 | [B<-outform> B<DER>|B<PEM>] | |
6d382c74 DDO |
14 | [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] |
15 | [B<-CAform> B<DER>|B<PEM>|B<P12>] | |
16 | [B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] | |
e8769719 RS |
17 | [B<-in> I<filename>] |
18 | [B<-out> I<filename>] | |
aba3e65f DSH |
19 | [B<-serial>] |
20 | [B<-hash>] | |
94805c84 | 21 | [B<-subject_hash>] |
65718c51 | 22 | [B<-subject_hash_old>] |
94805c84 | 23 | [B<-issuer_hash>] |
65718c51 | 24 | [B<-issuer_hash_old>] |
fc1d88f0 | 25 | [B<-ocspid>] |
aba3e65f DSH |
26 | [B<-subject>] |
27 | [B<-issuer>] | |
a91dedca | 28 | [B<-email>] |
14023fe3 | 29 | [B<-ocsp_uri>] |
aba3e65f DSH |
30 | [B<-startdate>] |
31 | [B<-enddate>] | |
32 | [B<-purpose>] | |
33 | [B<-dates>] | |
e8769719 | 34 | [B<-checkend> I<num>] |
aba3e65f | 35 | [B<-modulus>] |
74cc3b58 | 36 | [B<-pubkey>] |
aba3e65f DSH |
37 | [B<-fingerprint>] |
38 | [B<-alias>] | |
39 | [B<-noout>] | |
40 | [B<-trustout>] | |
41 | [B<-clrtrust>] | |
9868232a | 42 | [B<-clrreject>] |
e8769719 RS |
43 | [B<-addtrust> I<arg>] |
44 | [B<-addreject> I<arg>] | |
45 | [B<-setalias> I<arg>] | |
46 | [B<-days> I<arg>] | |
47 | [B<-set_serial> I<n>] | |
16d56043 | 48 | [B<-signkey> I<arg>] |
65718c51 | 49 | [B<-badsig>] |
e8769719 | 50 | [B<-passin> I<arg>] |
aba3e65f DSH |
51 | [B<-x509toreq>] |
52 | [B<-req>] | |
e8769719 RS |
53 | [B<-CA> I<filename>] |
54 | [B<-CAkey> I<filename>] | |
aba3e65f | 55 | [B<-CAcreateserial>] |
e8769719 | 56 | [B<-CAserial> I<filename>] |
52958608 | 57 | [B<-new>] |
65718c51 RS |
58 | [B<-next_serial>] |
59 | [B<-nocert>] | |
e8769719 RS |
60 | [B<-force_pubkey> I<filename>] |
61 | [B<-subj> I<arg>] | |
aba3e65f | 62 | [B<-text>] |
e8769719 RS |
63 | [B<-ext> I<extensions>] |
64 | [B<-certopt> I<option>] | |
65718c51 RS |
65 | [B<-checkhost> I<host>] |
66 | [B<-checkemail> I<host>] | |
67 | [B<-checkip> I<ipaddr>] | |
8dc57d76 | 68 | [B<-I<digest>>] |
aba3e65f | 69 | [B<-clrext>] |
e8769719 RS |
70 | [B<-extfile> I<filename>] |
71 | [B<-extensions> I<section>] | |
72 | [B<-sigopt> I<nm>:I<v>] | |
2292c8e1 | 73 | [B<-vfyopt> I<nm>:I<v>] |
4a60bb18 | 74 | [B<-preserve_dates>] |
bc24e3ee | 75 | {- $OpenSSL::safe::opt_name_synopsis -} |
9fcb9702 | 76 | {- $OpenSSL::safe::opt_r_synopsis -} |
d55e4487 | 77 | {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} |
aba3e65f | 78 | |
9f3c076b | 79 | =for openssl ifdef engine subject_hash_old issuer_hash_old |
1738c0ce | 80 | |
aba3e65f DSH |
81 | =head1 DESCRIPTION |
82 | ||
4b537191 | 83 | This command is a multi-purposes certificate command. It can |
35a810bb | 84 | be used to display certificate information, convert certificates to |
aba3e65f DSH |
85 | various forms, sign certificate requests like a "mini CA" or edit |
86 | certificate trust settings. | |
87 | ||
88 | Since there are a large number of options they will split up into | |
89 | various sections. | |
90 | ||
32d21c1e | 91 | =head1 OPTIONS |
aba3e65f | 92 | |
05ea606a | 93 | =head2 Input, Output, and General Purpose Options |
aba3e65f DSH |
94 | |
95 | =over 4 | |
96 | ||
169394d4 MR |
97 | =item B<-help> |
98 | ||
99 | Print out a usage message. | |
100 | ||
6d382c74 | 101 | =item B<-inform> B<DER>|B<PEM> |
aba3e65f | 102 | |
6d382c74 | 103 | The CSR input format; the default is B<PEM>. |
777182a0 | 104 | See L<openssl(1)/Format Options> for details. |
aba3e65f | 105 | |
6d382c74 DDO |
106 | The input is normally an X.509 certificate file of any format, |
107 | but this can change if other options such as B<-req> are used. | |
108 | ||
109 | B<-outform> B<DER>|B<PEM> | |
110 | ||
111 | The output format; the default is B<PEM>. | |
112 | See L<openssl(1)/Format Options> for details. | |
aba3e65f | 113 | |
e8769719 | 114 | =item B<-in> I<filename> |
aba3e65f DSH |
115 | |
116 | This specifies the input filename to read a certificate from or standard input | |
117 | if this option is not specified. | |
118 | ||
e8769719 | 119 | =item B<-out> I<filename> |
aba3e65f DSH |
120 | |
121 | This specifies the output filename to write to or standard output by | |
122 | default. | |
123 | ||
8dc57d76 | 124 | =item B<-I<digest>> |
9868232a | 125 | |
c4de074e | 126 | The digest to use. |
c03726ca RS |
127 | This affects any signing or display option that uses a message |
128 | digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. | |
35a810bb | 129 | Any digest supported by the L<openssl-dgst(1)> command can be used. |
0b2d4755 DSH |
130 | If not specified then SHA1 is used with B<-fingerprint> or |
131 | the default digest for the signing algorithm is used, typically SHA256. | |
9868232a | 132 | |
4a60bb18 TS |
133 | =item B<-preserve_dates> |
134 | ||
56a98c3e DO |
135 | When signing a certificate, preserve the "notBefore" and "notAfter" dates |
136 | instead of adjusting them to current time and duration. | |
137 | Cannot be used with the B<-days> option. | |
4a60bb18 | 138 | |
9fcb9702 RS |
139 | {- $OpenSSL::safe::opt_r_synopsis -} |
140 | ||
018aaeb4 RS |
141 | {- $OpenSSL::safe::opt_engine_item -} |
142 | ||
6bd4e3f2 P |
143 | {- $OpenSSL::safe::opt_provider_item -} |
144 | ||
aba3e65f DSH |
145 | =back |
146 | ||
05ea606a | 147 | =head2 Display Options |
aba3e65f DSH |
148 | |
149 | Note: the B<-alias> and B<-purpose> options are also display options | |
f5c14c63 | 150 | but are described in the L</Trust Settings> section. |
aba3e65f DSH |
151 | |
152 | =over 4 | |
153 | ||
154 | =item B<-text> | |
155 | ||
c4de074e | 156 | Prints out the certificate in text form. Full details are output including the |
aba3e65f DSH |
157 | public key, signature algorithms, issuer and subject names, serial number |
158 | any extensions present and any trust settings. | |
159 | ||
e8769719 | 160 | =item B<-ext> I<extensions> |
c2908538 PY |
161 | |
162 | Prints out the certificate extensions in text form. Extensions are specified | |
163 | with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier". | |
164 | See the L<x509v3_config(5)> manual page for the extension names. | |
165 | ||
e8769719 | 166 | =item B<-certopt> I<option> |
0a3ea5d3 | 167 | |
2f0ea936 | 168 | Customise the output format used with B<-text>. The I<option> argument |
c4de074e P |
169 | can be a single option or multiple options separated by commas. The |
170 | B<-certopt> switch may be also be used more than once to set multiple | |
f5c14c63 | 171 | options. See the L</Text Options> section for more information. |
0a3ea5d3 | 172 | |
65718c51 RS |
173 | =item B<-checkhost> I<host> |
174 | ||
175 | Check that the certificate matches the specified host. | |
176 | ||
177 | =item B<-checkemail> I<email> | |
178 | ||
179 | Check that the certificate matches the specified email address. | |
180 | ||
181 | =item B<-checkip> I<ipaddr> | |
182 | ||
183 | Check that the certificate matches the specified IP address. | |
184 | ||
aba3e65f DSH |
185 | =item B<-noout> |
186 | ||
67ee899c | 187 | This option prevents output of the encoded version of the certificate. |
aba3e65f | 188 | |
74cc3b58 BL |
189 | =item B<-pubkey> |
190 | ||
c4de074e | 191 | Outputs the certificate's SubjectPublicKeyInfo block in PEM format. |
74cc3b58 | 192 | |
aba3e65f DSH |
193 | =item B<-modulus> |
194 | ||
c4de074e | 195 | This option prints out the value of the modulus of the public key |
aba3e65f DSH |
196 | contained in the certificate. |
197 | ||
198 | =item B<-serial> | |
199 | ||
c4de074e | 200 | Outputs the certificate serial number. |
aba3e65f | 201 | |
94805c84 | 202 | =item B<-subject_hash> |
aba3e65f | 203 | |
c4de074e | 204 | Outputs the "hash" of the certificate subject name. This is used in OpenSSL to |
938ead8f | 205 | form an index to allow certificates in a directory to be looked up by subject |
aba3e65f DSH |
206 | name. |
207 | ||
94805c84 RL |
208 | =item B<-issuer_hash> |
209 | ||
c4de074e | 210 | Outputs the "hash" of the certificate issuer name. |
94805c84 | 211 | |
fc1d88f0 RS |
212 | =item B<-ocspid> |
213 | ||
c4de074e | 214 | Outputs the OCSP hash values for the subject name and public key. |
fc1d88f0 | 215 | |
94805c84 RL |
216 | =item B<-hash> |
217 | ||
c4de074e | 218 | Synonym for "-subject_hash" for backward compatibility reasons. |
94805c84 | 219 | |
0e0c6821 DSH |
220 | =item B<-subject_hash_old> |
221 | ||
c4de074e | 222 | Outputs the "hash" of the certificate subject name using the older algorithm |
e90fc053 | 223 | as used by OpenSSL before version 1.0.0. |
0e0c6821 DSH |
224 | |
225 | =item B<-issuer_hash_old> | |
226 | ||
c4de074e | 227 | Outputs the "hash" of the certificate issuer name using the older algorithm |
e90fc053 | 228 | as used by OpenSSL before version 1.0.0. |
0e0c6821 | 229 | |
aba3e65f DSH |
230 | =item B<-subject> |
231 | ||
c4de074e | 232 | Outputs the subject name. |
aba3e65f DSH |
233 | |
234 | =item B<-issuer> | |
235 | ||
c4de074e | 236 | Outputs the issuer name. |
aba3e65f | 237 | |
bc24e3ee | 238 | {- $OpenSSL::safe::opt_name_item -} |
bd4e1527 | 239 | |
a91dedca DSH |
240 | =item B<-email> |
241 | ||
c4de074e | 242 | Outputs the email address(es) if any. |
a91dedca | 243 | |
14023fe3 DSH |
244 | =item B<-ocsp_uri> |
245 | ||
c4de074e | 246 | Outputs the OCSP responder address(es) if any. |
14023fe3 | 247 | |
aba3e65f DSH |
248 | =item B<-startdate> |
249 | ||
c4de074e | 250 | Prints out the start date of the certificate, that is the notBefore date. |
aba3e65f DSH |
251 | |
252 | =item B<-enddate> | |
253 | ||
c4de074e | 254 | Prints out the expiry date of the certificate, that is the notAfter date. |
aba3e65f DSH |
255 | |
256 | =item B<-dates> | |
257 | ||
c4de074e | 258 | Prints out the start and expiry dates of a certificate. |
aba3e65f | 259 | |
e8769719 | 260 | =item B<-checkend> I<arg> |
fc1d88f0 | 261 | |
2f0ea936 | 262 | Checks if the certificate expires within the next I<arg> seconds and exits |
9c0586d5 | 263 | nonzero if yes it will expire or zero if not. |
fc1d88f0 | 264 | |
aba3e65f DSH |
265 | =item B<-fingerprint> |
266 | ||
9422d45d RS |
267 | Calculates and outputs the digest of the DER encoded version of the entire |
268 | certificate (see digest options). | |
269 | This is commonly called a "fingerprint". Because of the nature of message | |
270 | digests, the fingerprint of a certificate is unique to that certificate and | |
271 | two certificates with the same fingerprint can be considered to be the same. | |
aba3e65f | 272 | |
aba3e65f DSH |
273 | =back |
274 | ||
05ea606a | 275 | =head2 Trust Settings |
aba3e65f | 276 | |
aba3e65f DSH |
277 | A B<trusted certificate> is an ordinary certificate which has several |
278 | additional pieces of information attached to it such as the permitted | |
279 | and prohibited uses of the certificate and an "alias". | |
280 | ||
281 | Normally when a certificate is being verified at least one certificate | |
282 | must be "trusted". By default a trusted certificate must be stored | |
283 | locally and must be a root CA: any certificate chain ending in this CA | |
284 | is then usable for any purpose. | |
285 | ||
13938ace DSH |
286 | Trust settings currently are only used with a root CA. They allow a finer |
287 | control over the purposes the root CA can be used for. For example a CA | |
288 | may be trusted for SSL client but not SSL server use. | |
aba3e65f | 289 | |
35a810bb RL |
290 | See the description in L<openssl-verify(1)> for more information |
291 | on the meaning of trust settings. | |
aba3e65f | 292 | |
657e60fa | 293 | Future versions of OpenSSL will recognize trust settings on any |
13938ace DSH |
294 | certificate: not just root CAs. |
295 | ||
296 | ||
aba3e65f DSH |
297 | =over 4 |
298 | ||
299 | =item B<-trustout> | |
300 | ||
35a810bb | 301 | Output a B<trusted> certificate rather than an ordinary. An ordinary |
aba3e65f DSH |
302 | or trusted certificate can be input but by default an ordinary |
303 | certificate is output and any trust settings are discarded. With the | |
304 | B<-trustout> option a trusted certificate is output. A trusted | |
305 | certificate is automatically output if any trust settings are modified. | |
306 | ||
e8769719 | 307 | =item B<-setalias> I<arg> |
aba3e65f | 308 | |
c4de074e | 309 | Sets the alias of the certificate. This will allow the certificate |
19d2bb57 | 310 | to be referred to using a nickname for example "Steve's Certificate". |
aba3e65f DSH |
311 | |
312 | =item B<-alias> | |
313 | ||
c4de074e | 314 | Outputs the certificate alias, if any. |
aba3e65f DSH |
315 | |
316 | =item B<-clrtrust> | |
317 | ||
c4de074e | 318 | Clears all the permitted or trusted uses of the certificate. |
aba3e65f | 319 | |
9868232a | 320 | =item B<-clrreject> |
aba3e65f | 321 | |
c4de074e | 322 | Clears all the prohibited or rejected uses of the certificate. |
aba3e65f | 323 | |
e8769719 | 324 | =item B<-addtrust> I<arg> |
aba3e65f | 325 | |
c4de074e | 326 | Adds a trusted certificate use. |
0daccd4d VD |
327 | Any object name can be used here but currently only B<clientAuth> (SSL client |
328 | use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and | |
329 | B<anyExtendedKeyUsage> are used. | |
330 | As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or | |
331 | enables all purposes when trusted. | |
555b22cf | 332 | Other OpenSSL applications may define additional uses. |
aba3e65f | 333 | |
e8769719 | 334 | =item B<-addreject> I<arg> |
aba3e65f | 335 | |
c4de074e | 336 | Adds a prohibited use. It accepts the same values as the B<-addtrust> |
aba3e65f DSH |
337 | option. |
338 | ||
339 | =item B<-purpose> | |
340 | ||
c4de074e | 341 | This option performs tests on the certificate extensions and outputs |
f5c14c63 RL |
342 | the results. For a more complete description see the |
343 | L</CERTIFICATE EXTENSIONS> section. | |
aba3e65f DSH |
344 | |
345 | =back | |
346 | ||
05ea606a | 347 | =head2 Signing Options |
aba3e65f | 348 | |
35a810bb | 349 | This command can be used to sign certificates and requests: it |
aba3e65f DSH |
350 | can thus behave like a "mini CA". |
351 | ||
352 | =over 4 | |
353 | ||
16d56043 | 354 | =item B<-signkey> I<arg> |
aba3e65f | 355 | |
c4de074e | 356 | This option causes the input file to be self signed using the supplied |
6d382c74 | 357 | private key or engine. |
aba3e65f | 358 | |
56a98c3e DO |
359 | It sets the issuer name to the subject name (i.e., makes it self-issued) |
360 | and changes the public key to the supplied value (unless overridden by | |
361 | B<-force_pubkey>). It sets the validity start date to the current time | |
362 | and the end date to a value determined by the B<-days> option. | |
363 | It retains any certificate extensions unless the B<-clrext> option is supplied; | |
364 | this includes, for example, any existing key identifier extensions. | |
aba3e65f | 365 | |
65718c51 RS |
366 | =item B<-badsig> |
367 | ||
368 | Corrupt the signature before writing it; this can be useful | |
369 | for testing. | |
370 | ||
e8769719 | 371 | =item B<-sigopt> I<nm>:I<v> |
d7b2124a | 372 | |
2292c8e1 RL |
373 | Pass options to the signature algorithm during sign operations. |
374 | Names and values of these options are algorithm-specific. | |
375 | ||
376 | =item B<-vfyopt> I<nm>:I<v> | |
377 | ||
378 | Pass options to the signature algorithm during verify operations. | |
d7b2124a P |
379 | Names and values of these options are algorithm-specific. |
380 | ||
e8769719 | 381 | =item B<-passin> I<arg> |
fc1d88f0 | 382 | |
2a33470b DDO |
383 | The key and certificate file password source. |
384 | For more information about the format of I<arg> | |
3a4e43de | 385 | see L<openssl(1)/Pass Phrase Options>. |
fc1d88f0 | 386 | |
aba3e65f DSH |
387 | =item B<-clrext> |
388 | ||
c4de074e | 389 | Delete any extensions from a certificate. This option is used when a |
aba3e65f DSH |
390 | certificate is being created from another certificate (for example with |
391 | the B<-signkey> or the B<-CA> options). Normally all extensions are | |
392 | retained. | |
393 | ||
6d382c74 | 394 | =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> |
aba3e65f | 395 | |
777182a0 | 396 | The key format; the default is B<PEM>. |
6d382c74 | 397 | The only value with effect is B<ENGINE>; all others have become obsolete. |
777182a0 RS |
398 | See L<openssl(1)/Format Options> for details. |
399 | ||
6d382c74 DDO |
400 | =item B<-CAform> B<DER>|B<PEM>|B<P12>, |
401 | ||
402 | The format for the CA certificate. | |
403 | This option has no effect and is retained for backward compatibility. | |
777182a0 | 404 | |
6d382c74 DDO |
405 | =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> |
406 | ||
407 | The format for the CA key; the default is B<PEM>. | |
408 | The only value with effect is B<ENGINE>; all others have become obsolete. | |
777182a0 | 409 | See L<openssl(1)/Format Options> for details. |
aba3e65f | 410 | |
e8769719 | 411 | =item B<-days> I<arg> |
aba3e65f | 412 | |
c4de074e | 413 | Specifies the number of days to make a certificate valid for. The default |
4a60bb18 | 414 | is 30 days. Cannot be used with the B<-preserve_dates> option. |
aba3e65f DSH |
415 | |
416 | =item B<-x509toreq> | |
417 | ||
c4de074e | 418 | Converts a certificate into a certificate request. The B<-signkey> option |
aba3e65f DSH |
419 | is used to pass the required private key. |
420 | ||
421 | =item B<-req> | |
422 | ||
c4de074e | 423 | By default a certificate is expected on input. With this option a |
aba3e65f DSH |
424 | certificate request is expected instead. |
425 | ||
e8769719 | 426 | =item B<-set_serial> I<n> |
cc5ba6a7 | 427 | |
c4de074e | 428 | Specifies the serial number to use. This option can be used with either |
cc5ba6a7 DSH |
429 | the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA> |
430 | option the serial number file (as specified by the B<-CAserial> or | |
431 | B<-CAcreateserial> options) is not used. | |
432 | ||
a43384fd | 433 | The serial number can be decimal or hex (if preceded by C<0x>). |
cc5ba6a7 | 434 | |
e8769719 | 435 | =item B<-CA> I<filename> |
aba3e65f | 436 | |
c4de074e | 437 | Specifies the CA certificate to be used for signing. When this option is |
35a810bb RL |
438 | present, this command behaves like a "mini CA". The input file is signed by |
439 | this CA using this option: that is its issuer name is set to the subject name | |
aba3e65f DSH |
440 | of the CA and it is digitally signed using the CAs private key. |
441 | ||
442 | This option is normally combined with the B<-req> option. Without the | |
443 | B<-req> option the input is a certificate which must be self signed. | |
444 | ||
e8769719 | 445 | =item B<-CAkey> I<filename> |
aba3e65f | 446 | |
c4de074e | 447 | Sets the CA private key to sign a certificate with. If this option is |
aba3e65f DSH |
448 | not specified then it is assumed that the CA private key is present in |
449 | the CA certificate file. | |
450 | ||
e8769719 | 451 | =item B<-CAserial> I<filename> |
aba3e65f | 452 | |
c4de074e | 453 | Sets the CA serial number file to use. |
aba3e65f DSH |
454 | |
455 | When the B<-CA> option is used to sign a certificate it uses a serial | |
d53df3d0 | 456 | number specified in a file. This file consists of one line containing |
aba3e65f DSH |
457 | an even number of hex digits with the serial number to use. After each |
458 | use the serial number is incremented and written out to the file again. | |
459 | ||
460 | The default filename consists of the CA certificate file base name with | |
1948394d RL |
461 | F<.srl> appended. For example if the CA certificate file is called |
462 | F<mycacert.pem> it expects to find a serial number file called | |
463 | F<mycacert.srl>. | |
aba3e65f | 464 | |
d6257073 | 465 | =item B<-CAcreateserial> |
aba3e65f | 466 | |
c4de074e | 467 | With this option the CA serial number file is created if it does not exist: |
8100490a | 468 | it will contain the serial number "02" and the certificate being signed will |
46aa6078 RS |
469 | have the 1 as its serial number. If the B<-CA> option is specified |
470 | and the serial number file does not exist a random number is generated; | |
471 | this is the recommended practice. | |
aba3e65f | 472 | |
e8769719 | 473 | =item B<-extfile> I<filename> |
aba3e65f | 474 | |
c4de074e | 475 | File containing certificate extensions to use. If not specified then |
aba3e65f DSH |
476 | no extensions are added to the certificate. |
477 | ||
e8769719 | 478 | =item B<-extensions> I<section> |
aba3e65f | 479 | |
c4de074e | 480 | The section to add certificate extensions from. If this option is not |
aba3e65f DSH |
481 | specified then the extensions should either be contained in the unnamed |
482 | (default) section or the default section should contain a variable called | |
137de5b1 | 483 | "extensions" which contains the section to use. See the |
9b86974e | 484 | L<x509v3_config(5)> manual page for details of the |
137de5b1 | 485 | extension section format. |
aba3e65f | 486 | |
52958608 DO |
487 | =item B<-new> |
488 | ||
489 | Generate a certificate from scratch, not using an input certificate | |
490 | or certificate request. So the B<-in> option must not be used in this case. | |
491 | Instead, the B<-subj> and <-force_pubkey> options need to be given. | |
492 | ||
65718c51 RS |
493 | =item B<-next_serial> |
494 | ||
495 | Set the serial to be one more than the number in the certificate. | |
496 | ||
497 | =item B<-nocert> | |
498 | ||
499 | Do not generate or output a certificate. | |
500 | ||
e8769719 | 501 | =item B<-force_pubkey> I<filename> |
902efde1 | 502 | |
2f0ea936 | 503 | When a certificate is created set its public key to the key in I<filename> |
56a98c3e | 504 | instead of the key contained in the input or given with the B<-signkey> option. |
52958608 | 505 | |
56a98c3e DO |
506 | This option is useful for creating self-issued certificates that are not |
507 | self-signed, for instance when the key cannot be used for signing, such as DH. | |
52958608 DO |
508 | It can also be used in conjunction with b<-new> and B<-subj> to directly |
509 | generate a certificate containing any desired public key. | |
902efde1 | 510 | |
e8769719 | 511 | =item B<-subj> I<arg> |
52958608 DO |
512 | |
513 | When a certificate is created set its subject name to the given value. | |
5a0991d0 | 514 | |
a43384fd | 515 | The arg must be formatted as C</type0=value0/type1=value1/type2=...>. |
5a0991d0 | 516 | Special characters may be escaped by C<\> (backslash), whitespace is retained. |
52958608 | 517 | Empty values are permitted, but the corresponding type will not be included |
5a0991d0 DDO |
518 | in the certificate. |
519 | Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN). | |
520 | Multi-valued RDNs can be formed by placing a C<+> character instead of a C</> | |
521 | between the AttributeValueAssertions (AVAs) that specify the members of the set. | |
522 | Example: | |
523 | ||
524 | C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> | |
52958608 DO |
525 | |
526 | Unless the B<-CA> option is given the issuer is set to the same value. | |
527 | ||
528 | This option can be used in conjunction with the B<-force_pubkey> option | |
529 | to create a certificate even without providing an input certificate | |
530 | or certificate request. | |
531 | ||
aba3e65f DSH |
532 | =back |
533 | ||
05ea606a | 534 | =head2 Text Options |
0a3ea5d3 DSH |
535 | |
536 | As well as customising the name output format, it is also possible to | |
537 | customise the actual fields printed using the B<certopt> options when | |
538 | the B<text> option is present. The default behaviour is to print all fields. | |
539 | ||
72da660d LJ |
540 | =over 4 |
541 | ||
0a3ea5d3 DSH |
542 | =item B<compatible> |
543 | ||
c4de074e | 544 | Use the old format. This is equivalent to specifying no output options at all. |
0a3ea5d3 DSH |
545 | |
546 | =item B<no_header> | |
547 | ||
c4de074e P |
548 | Don't print header information: that is the lines saying "Certificate" |
549 | and "Data". | |
0a3ea5d3 DSH |
550 | |
551 | =item B<no_version> | |
552 | ||
c4de074e | 553 | Don't print out the version number. |
0a3ea5d3 DSH |
554 | |
555 | =item B<no_serial> | |
556 | ||
c4de074e | 557 | Don't print out the serial number. |
0a3ea5d3 DSH |
558 | |
559 | =item B<no_signame> | |
560 | ||
c4de074e | 561 | Don't print out the signature algorithm used. |
0a3ea5d3 DSH |
562 | |
563 | =item B<no_validity> | |
564 | ||
c4de074e | 565 | Don't print the validity, that is the B<notBefore> and B<notAfter> fields. |
0a3ea5d3 DSH |
566 | |
567 | =item B<no_subject> | |
568 | ||
c4de074e | 569 | Don't print out the subject name. |
0a3ea5d3 DSH |
570 | |
571 | =item B<no_issuer> | |
572 | ||
c4de074e | 573 | Don't print out the issuer name. |
0a3ea5d3 DSH |
574 | |
575 | =item B<no_pubkey> | |
576 | ||
c4de074e | 577 | Don't print out the public key. |
0a3ea5d3 DSH |
578 | |
579 | =item B<no_sigdump> | |
580 | ||
c4de074e | 581 | Don't give a hexadecimal dump of the certificate signature. |
0a3ea5d3 DSH |
582 | |
583 | =item B<no_aux> | |
584 | ||
c4de074e | 585 | Don't print out certificate trust information. |
0a3ea5d3 DSH |
586 | |
587 | =item B<no_extensions> | |
588 | ||
c4de074e | 589 | Don't print out any X509V3 extensions. |
0a3ea5d3 DSH |
590 | |
591 | =item B<ext_default> | |
592 | ||
c4de074e P |
593 | Retain default extension behaviour: attempt to print out unsupported |
594 | certificate extensions. | |
0a3ea5d3 DSH |
595 | |
596 | =item B<ext_error> | |
597 | ||
c4de074e | 598 | Print an error message for unsupported certificate extensions. |
0a3ea5d3 DSH |
599 | |
600 | =item B<ext_parse> | |
601 | ||
602 | ASN1 parse unsupported extensions. | |
603 | ||
604 | =item B<ext_dump> | |
605 | ||
c4de074e | 606 | Hex dump unsupported extensions. |
0a3ea5d3 | 607 | |
e890dcdb DSH |
608 | =item B<ca_default> |
609 | ||
35a810bb | 610 | The value used by L<openssl-ca(1)>, equivalent to B<no_issuer>, B<no_pubkey>, |
39a47008 | 611 | B<no_header>, and B<no_version>. |
e890dcdb | 612 | |
0a3ea5d3 DSH |
613 | =back |
614 | ||
aba3e65f DSH |
615 | =head1 EXAMPLES |
616 | ||
617 | Note: in these examples the '\' means the example should be all on one | |
618 | line. | |
619 | ||
620 | Display the contents of a certificate: | |
621 | ||
1675f6eb | 622 | openssl x509 -in cert.pem -noout -text |
aba3e65f | 623 | |
c2908538 PY |
624 | Display the "Subject Alternative Name" extension of a certificate: |
625 | ||
626 | openssl x509 -in cert.pem -noout -ext subjectAltName | |
627 | ||
afc901e0 | 628 | Display more extensions of a certificate: |
c2908538 PY |
629 | |
630 | openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType | |
631 | ||
9868232a | 632 | Display the certificate serial number: |
aba3e65f | 633 | |
1675f6eb | 634 | openssl x509 -in cert.pem -noout -serial |
aba3e65f | 635 | |
bd4e1527 DSH |
636 | Display the certificate subject name: |
637 | ||
638 | openssl x509 -in cert.pem -noout -subject | |
639 | ||
640 | Display the certificate subject name in RFC2253 form: | |
641 | ||
642 | openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 | |
643 | ||
644 | Display the certificate subject name in oneline form on a terminal | |
645 | supporting UTF8: | |
646 | ||
0501f02b | 647 | openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb |
bd4e1527 | 648 | |
9868232a DSH |
649 | Display the certificate SHA1 fingerprint: |
650 | ||
1675f6eb | 651 | openssl x509 -sha1 -in cert.pem -noout -fingerprint |
aba3e65f DSH |
652 | |
653 | Convert a certificate from PEM to DER format: | |
654 | ||
1675f6eb | 655 | openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER |
aba3e65f DSH |
656 | |
657 | Convert a certificate to a certificate request: | |
658 | ||
1675f6eb | 659 | openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem |
aba3e65f DSH |
660 | |
661 | Convert a certificate request into a self signed certificate using | |
662 | extensions for a CA: | |
663 | ||
d428bf8c | 664 | openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ |
1bc74519 | 665 | -signkey key.pem -out cacert.pem |
aba3e65f | 666 | |
19d2bb57 | 667 | Sign a certificate request using the CA certificate above and add user |
aba3e65f DSH |
668 | certificate extensions: |
669 | ||
d428bf8c | 670 | openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ |
1bc74519 | 671 | -CA cacert.pem -CAkey key.pem -CAcreateserial |
aba3e65f DSH |
672 | |
673 | ||
674 | Set a certificate to be trusted for SSL client use and change set its alias to | |
675 | "Steve's Class 1 CA" | |
676 | ||
c653b569 | 677 | openssl x509 -in cert.pem -addtrust clientAuth \ |
1bc74519 | 678 | -setalias "Steve's Class 1 CA" -out trust.pem |
aba3e65f | 679 | |
0286d944 DSH |
680 | =head1 NOTES |
681 | ||
bd4e1527 DSH |
682 | The conversion to UTF8 format used with the name options assumes that |
683 | T61Strings use the ISO8859-1 character set. This is wrong but Netscape | |
684 | and MSIE do this as do many certificates. So although this is incorrect | |
685 | it is more likely to display the majority of certificates correctly. | |
686 | ||
a91dedca DSH |
687 | The B<-email> option searches the subject name and the subject alternative |
688 | name extension. Only unique email addresses will be printed out: it will | |
689 | not print the same address more than once. | |
690 | ||
5f2f0b55 DSH |
691 | =head1 CERTIFICATE EXTENSIONS |
692 | ||
693 | The B<-purpose> option checks the certificate extensions and determines | |
694 | what the certificate can be used for. The actual checks done are rather | |
695 | complex and include various hacks and workarounds to handle broken | |
696 | certificates and software. | |
697 | ||
698 | The same code is used when verifying untrusted certificates in chains | |
699 | so this section is useful if a chain is rejected by the verify code. | |
700 | ||
701 | The basicConstraints extension CA flag is used to determine whether the | |
702 | certificate can be used as a CA. If the CA flag is true then it is a CA, | |
703 | if the CA flag is false then it is not a CA. B<All> CAs should have the | |
704 | CA flag set to true. | |
705 | ||
706 | If the basicConstraints extension is absent then the certificate is | |
707 | considered to be a "possible CA" other extensions are checked according | |
708 | to the intended use of the certificate. A warning is given in this case | |
709 | because the certificate should really not be regarded as a CA: however | |
710 | it is allowed to be a CA to work around some broken software. | |
711 | ||
712 | If the certificate is a V1 certificate (and thus has no extensions) and | |
713 | it is self signed it is also assumed to be a CA but a warning is again | |
714 | given: this is to work around the problem of Verisign roots which are V1 | |
715 | self signed certificates. | |
716 | ||
717 | If the keyUsage extension is present then additional restraints are | |
718 | made on the uses of the certificate. A CA certificate B<must> have the | |
719 | keyCertSign bit set if the keyUsage extension is present. | |
720 | ||
721 | The extended key usage extension places additional restrictions on the | |
722 | certificate uses. If this extension is present (whether critical or not) | |
723 | the key can only be used for the purposes specified. | |
724 | ||
725 | A complete description of each test is given below. The comments about | |
726 | basicConstraints and keyUsage and V1 certificates above apply to B<all> | |
727 | CA certificates. | |
728 | ||
729 | ||
730 | =over 4 | |
731 | ||
732 | =item B<SSL Client> | |
733 | ||
734 | The extended key usage extension must be absent or include the "web client | |
735 | authentication" OID. keyUsage must be absent or it must have the | |
736 | digitalSignature bit set. Netscape certificate type must be absent or it must | |
737 | have the SSL client bit set. | |
738 | ||
739 | =item B<SSL Client CA> | |
740 | ||
741 | The extended key usage extension must be absent or include the "web client | |
742 | authentication" OID. Netscape certificate type must be absent or it must have | |
743 | the SSL CA bit set: this is used as a work around if the basicConstraints | |
744 | extension is absent. | |
745 | ||
746 | =item B<SSL Server> | |
747 | ||
748 | The extended key usage extension must be absent or include the "web server | |
749 | authentication" and/or one of the SGC OIDs. keyUsage must be absent or it | |
750 | must have the digitalSignature, the keyEncipherment set or both bits set. | |
751 | Netscape certificate type must be absent or have the SSL server bit set. | |
752 | ||
753 | =item B<SSL Server CA> | |
754 | ||
755 | The extended key usage extension must be absent or include the "web server | |
756 | authentication" and/or one of the SGC OIDs. Netscape certificate type must | |
757 | be absent or the SSL CA bit must be set: this is used as a work around if the | |
758 | basicConstraints extension is absent. | |
759 | ||
760 | =item B<Netscape SSL Server> | |
761 | ||
762 | For Netscape SSL clients to connect to an SSL server it must have the | |
763 | keyEncipherment bit set if the keyUsage extension is present. This isn't | |
764 | always valid because some cipher suites use the key for digital signing. | |
765 | Otherwise it is the same as a normal SSL server. | |
766 | ||
767 | =item B<Common S/MIME Client Tests> | |
768 | ||
769 | The extended key usage extension must be absent or include the "email | |
770 | protection" OID. Netscape certificate type must be absent or should have the | |
77a795e4 | 771 | S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type |
5f2f0b55 DSH |
772 | then the SSL client bit is tolerated as an alternative but a warning is shown: |
773 | this is because some Verisign certificates don't set the S/MIME bit. | |
774 | ||
775 | =item B<S/MIME Signing> | |
776 | ||
c4eec78d KS |
777 | In addition to the common S/MIME client tests the digitalSignature bit or |
778 | the nonRepudiation bit must be set if the keyUsage extension is present. | |
5f2f0b55 DSH |
779 | |
780 | =item B<S/MIME Encryption> | |
781 | ||
782 | In addition to the common S/MIME tests the keyEncipherment bit must be set | |
783 | if the keyUsage extension is present. | |
784 | ||
785 | =item B<S/MIME CA> | |
786 | ||
787 | The extended key usage extension must be absent or include the "email | |
788 | protection" OID. Netscape certificate type must be absent or must have the | |
789 | S/MIME CA bit set: this is used as a work around if the basicConstraints | |
1bc74519 | 790 | extension is absent. |
5f2f0b55 DSH |
791 | |
792 | =item B<CRL Signing> | |
793 | ||
794 | The keyUsage extension must be absent or it must have the CRL signing bit | |
795 | set. | |
796 | ||
797 | =item B<CRL Signing CA> | |
798 | ||
799 | The normal CA tests apply. Except in this case the basicConstraints extension | |
800 | must be present. | |
801 | ||
802 | =back | |
803 | ||
aba3e65f DSH |
804 | =head1 BUGS |
805 | ||
aba3e65f DSH |
806 | Extensions in certificates are not transferred to certificate requests and |
807 | vice versa. | |
808 | ||
809 | It is possible to produce invalid certificates or requests by specifying the | |
810 | wrong private key or using inconsistent options in some cases: these should | |
811 | be checked. | |
812 | ||
9868232a | 813 | There should be options to explicitly set such things as start and end |
aba3e65f DSH |
814 | dates rather than an offset from the current time. |
815 | ||
aba3e65f DSH |
816 | =head1 SEE ALSO |
817 | ||
b6b66573 DMSP |
818 | L<openssl(1)>, |
819 | L<openssl-req(1)>, | |
820 | L<openssl-ca(1)>, | |
821 | L<openssl-genrsa(1)>, | |
822 | L<openssl-gendsa(1)>, | |
823 | L<openssl-verify(1)>, | |
1bc74519 | 824 | L<x509v3_config(5)> |
aba3e65f | 825 | |
c3932222 BM |
826 | =head1 HISTORY |
827 | ||
0e0c6821 DSH |
828 | The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options |
829 | before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding | |
35a810bb RL |
830 | of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical |
831 | version of the DN using SHA1. This means that any directories using the old | |
832 | form must have their links rebuilt using L<openssl-rehash(1)> or similar. | |
0e0c6821 | 833 | |
6d382c74 DDO |
834 | All B<-keyform> and B<-CAkeyform> values except B<ENGINE> |
835 | have become obsolete in OpenSSL 3.0.0 and have no effect. | |
836 | ||
837 | The B<-CAform> option has become obsolete in OpenSSL 3.0.0 and has no effect. | |
838 | ||
0f221d9c P |
839 | The B<-engine> option was deprecated in OpenSSL 3.0. |
840 | ||
a18cf8fc RS |
841 | The B<-C> option was removed in OpenSSL 3.0. |
842 | ||
e2f92610 RS |
843 | =head1 COPYRIGHT |
844 | ||
33388b44 | 845 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 846 | |
449040b4 | 847 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
848 | this file except in compliance with the License. You can obtain a copy |
849 | in the file LICENSE in the source distribution or at | |
850 | L<https://www.openssl.org/source/license.html>. | |
851 | ||
852 | =cut |