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