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