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