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