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