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