]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
b6b66573 | 5 | openssl-ca - sample minimal CA application |
aba3e65f DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<ca> | |
169394d4 | 10 | [B<-help>] |
aba3e65f | 11 | [B<-verbose>] |
e8769719 RS |
12 | [B<-config> I<filename>] |
13 | [B<-name> I<section>] | |
aba3e65f | 14 | [B<-gencrl>] |
e8769719 RS |
15 | [B<-revoke> I<file>] |
16 | [B<-valid> I<file>] | |
17 | [B<-status> I<serial>] | |
fc1d88f0 | 18 | [B<-updatedb>] |
e8769719 RS |
19 | [B<-crl_reason> I<reason>] |
20 | [B<-crl_hold> I<instruction>] | |
21 | [B<-crl_compromise> I<time>] | |
22 | [B<-crl_CA_compromise> I<time>] | |
23 | [B<-crldays> I<days>] | |
24 | [B<-crlhours> I<hours>] | |
25 | [B<-crlexts> I<section>] | |
26 | [B<-startdate> I<date>] | |
27 | [B<-enddate> I<date>] | |
28 | [B<-days> I<arg>] | |
29 | [B<-md> I<arg>] | |
30 | [B<-policy> I<arg>] | |
31 | [B<-keyfile> I<arg>] | |
32 | [B<-keyform> B<DER>|B<PEM>] | |
33 | [B<-key> I<arg>] | |
34 | [B<-passin> I<arg>] | |
35 | [B<-cert> I<file>] | |
d6df2b28 | 36 | [B<-selfsign>] |
e8769719 RS |
37 | [B<-in> I<file>] |
38 | [B<-out> I<file>] | |
82fc1d9c | 39 | [B<-notext>] |
e8769719 | 40 | [B<-outdir> I<dir>] |
aba3e65f | 41 | [B<-infiles>] |
e8769719 RS |
42 | [B<-spkac> I<file>] |
43 | [B<-ss_cert> I<file>] | |
aba3e65f | 44 | [B<-preserveDN>] |
89da653f | 45 | [B<-noemailDN>] |
aba3e65f DSH |
46 | [B<-batch>] |
47 | [B<-msie_hack>] | |
e8769719 RS |
48 | [B<-extensions> I<section>] |
49 | [B<-extfile> I<section>] | |
50 | [B<-engine> I<id>] | |
51 | [B<-subj> I<arg>] | |
57eb1d32 | 52 | [B<-utf8>] |
e8769719 | 53 | [B<-sigopt> I<nm>:I<v>] |
6755ff11 | 54 | [B<-create_serial>] |
ffb46830 | 55 | [B<-rand_serial>] |
57eb1d32 | 56 | [B<-multivalue-rdn>] |
fed8bd90 | 57 | [B<-rand> I<files>] |
e8769719 RS |
58 | [B<-writerand> I<file>] |
59 | [B<-sm2-id> I<string>] | |
60 | [B<-sm2-hex-id> I<hex-string>] | |
aba3e65f | 61 | |
1738c0ce RS |
62 | =for comment ifdef engine sm2-id sm2-hex-id |
63 | ||
aba3e65f DSH |
64 | =head1 DESCRIPTION |
65 | ||
35a810bb | 66 | This command is a minimal CA application. It can be used |
aba3e65f DSH |
67 | to sign certificate requests in a variety of forms and generate |
68 | CRLs it also maintains a text database of issued certificates | |
69 | and their status. | |
70 | ||
71 | The options descriptions will be divided into each purpose. | |
72 | ||
3dfda1a6 | 73 | =head1 OPTIONS |
aba3e65f DSH |
74 | |
75 | =over 4 | |
76 | ||
6755ff11 MR |
77 | =item B<-help> |
78 | ||
79 | Print out a usage message. | |
80 | ||
81 | =item B<-verbose> | |
82 | ||
c4de074e | 83 | This prints extra details about the operations being performed. |
6755ff11 | 84 | |
e8769719 | 85 | =item B<-config> I<filename> |
aba3e65f | 86 | |
c4de074e | 87 | Specifies the configuration file to use. |
e9681f83 RS |
88 | Optional; for a description of the default value, |
89 | see L<openssl(1)/COMMAND SUMMARY>. | |
aba3e65f | 90 | |
e8769719 | 91 | =item B<-name> I<section> |
8a0a9392 | 92 | |
c4de074e | 93 | Specifies the configuration file section to use (overrides |
8a0a9392 BM |
94 | B<default_ca> in the B<ca> section). |
95 | ||
e8769719 | 96 | =item B<-in> I<filename> |
aba3e65f | 97 | |
c4de074e | 98 | An input filename containing a single certificate request to be |
aba3e65f DSH |
99 | signed by the CA. |
100 | ||
e8769719 | 101 | =item B<-ss_cert> I<filename> |
aba3e65f | 102 | |
c4de074e | 103 | A single self-signed certificate to be signed by the CA. |
aba3e65f | 104 | |
e8769719 | 105 | =item B<-spkac> I<filename> |
aba3e65f | 106 | |
c4de074e | 107 | A file containing a single Netscape signed public key and challenge |
d618f703 | 108 | and additional field values to be signed by the CA. See the B<SPKAC FORMAT> |
fc1d88f0 | 109 | section for information on the required input and output format. |
aba3e65f DSH |
110 | |
111 | =item B<-infiles> | |
112 | ||
c4de074e | 113 | If present this should be the last option, all subsequent arguments |
1bc74519 | 114 | are taken as the names of files containing certificate requests. |
aba3e65f | 115 | |
e8769719 | 116 | =item B<-out> I<filename> |
aba3e65f | 117 | |
c4de074e | 118 | The output file to output certificates to. The default is standard |
aba3e65f | 119 | output. The certificate details will also be printed out to this |
fc1d88f0 | 120 | file in PEM format (except that B<-spkac> outputs DER format). |
aba3e65f | 121 | |
e8769719 | 122 | =item B<-outdir> I<directory> |
aba3e65f | 123 | |
c4de074e | 124 | The directory to output certificates to. The certificate will be |
aba3e65f | 125 | written to a filename consisting of the serial number in hex with |
1948394d | 126 | F<.pem> appended. |
aba3e65f DSH |
127 | |
128 | =item B<-cert> | |
129 | ||
c4de074e | 130 | The CA certificate file. |
aba3e65f | 131 | |
e8769719 | 132 | =item B<-keyfile> I<filename> |
aba3e65f | 133 | |
c4de074e | 134 | The private key to sign requests with. |
aba3e65f | 135 | |
e8769719 | 136 | =item B<-keyform> B<DER>|B<PEM> |
fc1d88f0 | 137 | |
c4de074e | 138 | The format of the data in the private key file. |
fc1d88f0 RS |
139 | The default is PEM. |
140 | ||
e8769719 | 141 | =item B<-sigopt> I<nm>:I<v> |
d7b2124a P |
142 | |
143 | Pass options to the signature algorithm during sign or verify operations. | |
144 | Names and values of these options are algorithm-specific. | |
145 | ||
e8769719 | 146 | =item B<-key> I<password> |
aba3e65f | 147 | |
c4de074e | 148 | The password used to encrypt the private key. Since on some |
aba3e65f | 149 | systems the command line arguments are visible (e.g. Unix with |
f5c14c63 | 150 | the L<ps(1)> utility) this option should be used with caution. |
aba3e65f | 151 | |
d6df2b28 RL |
152 | =item B<-selfsign> |
153 | ||
c4de074e | 154 | Indicates the issued certificates are to be signed with the key |
d6df2b28 | 155 | the certificate requests were signed with (given with B<-keyfile>). |
42b91f28 | 156 | Certificate requests signed with a different key are ignored. If |
d6df2b28 RL |
157 | B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is |
158 | ignored. | |
159 | ||
160 | A consequence of using B<-selfsign> is that the self-signed | |
161 | certificate appears among the entries in the certificate database | |
162 | (see the configuration option B<database>), and uses the same | |
163 | serial number counter as all other certificates sign with the | |
164 | self-signed certificate. | |
165 | ||
e8769719 | 166 | =item B<-passin> I<arg> |
bd08a2bd | 167 | |
c4de074e | 168 | The key password source. For more information about the format of B<arg> |
e8769719 | 169 | see L<openssl(1)/Pass phrase options>. |
bad40585 | 170 | |
82fc1d9c DSH |
171 | =item B<-notext> |
172 | ||
c4de074e | 173 | Don't output the text form of a certificate to the output file. |
82fc1d9c | 174 | |
e8769719 | 175 | =item B<-startdate> I<date> |
aba3e65f | 176 | |
c4de074e | 177 | This allows the start date to be explicitly set. The format of the |
909873bd PY |
178 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or |
179 | YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In | |
a970b14f | 180 | both formats, seconds SS and timezone Z must be present. |
aba3e65f | 181 | |
e8769719 | 182 | =item B<-enddate> I<date> |
aba3e65f | 183 | |
c4de074e | 184 | This allows the expiry date to be explicitly set. The format of the |
909873bd PY |
185 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or |
186 | YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In | |
a970b14f | 187 | both formats, seconds SS and timezone Z must be present. |
aba3e65f | 188 | |
e8769719 | 189 | =item B<-days> I<arg> |
aba3e65f | 190 | |
c4de074e | 191 | The number of days to certify the certificate for. |
aba3e65f | 192 | |
e8769719 | 193 | =item B<-md> I<alg> |
aba3e65f | 194 | |
c4de074e | 195 | The message digest to use. |
35a810bb | 196 | Any digest supported by the L<openssl-dgst(1)> command can be used. For signing |
aabbc24e MC |
197 | algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message |
198 | digest that is set is ignored. This option also applies to CRLs. | |
aba3e65f | 199 | |
e8769719 | 200 | =item B<-policy> I<arg> |
aba3e65f | 201 | |
c4de074e | 202 | This option defines the CA "policy" to use. This is a section in |
aba3e65f DSH |
203 | the configuration file which decides which fields should be mandatory |
204 | or match the CA certificate. Check out the B<POLICY FORMAT> section | |
205 | for more information. | |
206 | ||
207 | =item B<-msie_hack> | |
208 | ||
35a810bb RL |
209 | This is a deprecated option to make this command work with very old versions |
210 | of the IE certificate enrollment control "certenr3". It used UniversalStrings | |
aba3e65f | 211 | for almost everything. Since the old control has various security bugs |
a95d7574 | 212 | its use is strongly discouraged. |
aba3e65f DSH |
213 | |
214 | =item B<-preserveDN> | |
215 | ||
53b1899e | 216 | Normally the DN order of a certificate is the same as the order of the |
1bc74519 | 217 | fields in the relevant policy section. When this option is set the order |
19d2bb57 | 218 | is the same as the request. This is largely for compatibility with the |
53b1899e DSH |
219 | older IE enrollment control which would only accept certificates if their |
220 | DNs match the order of the request. This is not needed for Xenroll. | |
aba3e65f | 221 | |
89da653f BM |
222 | =item B<-noemailDN> |
223 | ||
224 | The DN of a certificate can contain the EMAIL field if present in the | |
225 | request DN, however it is good policy just having the e-mail set into | |
226 | the altName extension of the certificate. When this option is set the | |
227 | EMAIL field is removed from the certificate' subject and set only in | |
228 | the, eventually present, extensions. The B<email_in_dn> keyword can be | |
229 | used in the configuration file to enable this behaviour. | |
230 | ||
aba3e65f DSH |
231 | =item B<-batch> |
232 | ||
c4de074e | 233 | This sets the batch mode. In this mode no questions will be asked |
aba3e65f DSH |
234 | and all certificates will be certified automatically. |
235 | ||
e8769719 | 236 | =item B<-extensions> I<section> |
aba3e65f | 237 | |
c4de074e | 238 | The section of the configuration file containing certificate extensions |
dfebac32 BM |
239 | to be added when a certificate is issued (defaults to B<x509_extensions> |
240 | unless the B<-extfile> option is used). If no extension section is | |
241 | present then, a V1 certificate is created. If the extension section | |
143b6316 | 242 | is present (even if it is empty), then a V3 certificate is created. See the |
9b86974e | 243 | L<x509v3_config(5)> manual page for details of the |
137de5b1 | 244 | extension section format. |
dfebac32 | 245 | |
e8769719 | 246 | =item B<-extfile> I<file> |
dfebac32 | 247 | |
c4de074e | 248 | An additional configuration file to read certificate extensions from |
dfebac32 BM |
249 | (using the default section unless the B<-extensions> option is also |
250 | used). | |
aba3e65f | 251 | |
e8769719 | 252 | =item B<-engine> I<id> |
bfa35550 | 253 | |
2f0ea936 | 254 | Specifying an engine (by its unique I<id> string) will cause B<ca> |
bfa35550 RL |
255 | to attempt to obtain a functional reference to the specified engine, |
256 | thus initialising it if needed. The engine will then be set as the default | |
257 | for all available algorithms. | |
258 | ||
e8769719 | 259 | =item B<-subj> I<arg> |
57eb1d32 | 260 | |
c4de074e | 261 | Supersedes subject name given in the request. |
2f0ea936 | 262 | The arg must be formatted as C</type0=value0/type1=value1/type2=...>. |
3d362f19 BK |
263 | Keyword characters may be escaped by \ (backslash), and whitespace is retained. |
264 | Empty values are permitted, but the corresponding type will not be included | |
265 | in the resulting certificate. | |
57eb1d32 NL |
266 | |
267 | =item B<-utf8> | |
268 | ||
c4de074e | 269 | This option causes field values to be interpreted as UTF8 strings, by |
57eb1d32 NL |
270 | default they are interpreted as ASCII. This means that the field |
271 | values, whether prompted from a terminal or obtained from a | |
272 | configuration file, must be valid UTF8 strings. | |
273 | ||
6755ff11 MR |
274 | =item B<-create_serial> |
275 | ||
c4de074e | 276 | If reading serial from the text file as specified in the configuration |
6755ff11 MR |
277 | fails, specifying this option creates a new random serial to be used as next |
278 | serial number. | |
ffb46830 RS |
279 | To get random serial numbers, use the B<-rand_serial> flag instead; this |
280 | should only be used for simple error-recovery. | |
281 | ||
282 | =item B<-rand_serial> | |
283 | ||
284 | Generate a large random number to use as the serial number. | |
285 | This overrides any option or configuration to use a serial number file. | |
6755ff11 | 286 | |
57eb1d32 NL |
287 | =item B<-multivalue-rdn> |
288 | ||
4c583c36 | 289 | This option causes the -subj argument to be interpreted with full |
57eb1d32 NL |
290 | support for multivalued RDNs. Example: |
291 | ||
292 | I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> | |
293 | ||
2f0ea936 | 294 | If B<-multi-rdn> is not used then the UID value is I<123456+CN=John Doe>. |
57eb1d32 | 295 | |
fed8bd90 | 296 | =item B<-rand> I<files> |
3ee1eac2 | 297 | |
fed8bd90 | 298 | The files containing random data used to seed the random number generator. |
3ee1eac2 RS |
299 | Multiple files can be specified separated by an OS-dependent character. |
300 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for | |
301 | all others. | |
302 | ||
e8769719 | 303 | =item B<-writerand> I<file> |
3ee1eac2 RS |
304 | |
305 | Writes random data to the specified I<file> upon exit. | |
306 | This can be used with a subsequent B<-rand> flag. | |
307 | ||
e8769719 | 308 | =item B<-sm2-id> I<string> |
bc42bd62 PY |
309 | |
310 | Specify the ID string to use when verifying an SM2 certificate. The ID string is | |
311 | required by the SM2 signature algorithm for signing and verification. | |
312 | ||
e8769719 | 313 | =item B<-sm2-hex-id> I<hex-string> |
bc42bd62 PY |
314 | |
315 | Specify a binary ID string to use when signing or verifying using an SM2 | |
316 | certificate. The argument for this option is string of hexadecimal digits. | |
317 | ||
aba3e65f DSH |
318 | =back |
319 | ||
320 | =head1 CRL OPTIONS | |
321 | ||
322 | =over 4 | |
323 | ||
324 | =item B<-gencrl> | |
325 | ||
c4de074e | 326 | This option generates a CRL based on information in the index file. |
aba3e65f | 327 | |
e8769719 | 328 | =item B<-crldays> I<num> |
aba3e65f | 329 | |
c4de074e | 330 | The number of days before the next CRL is due. That is the days from |
aba3e65f DSH |
331 | now to place in the CRL nextUpdate field. |
332 | ||
e8769719 | 333 | =item B<-crlhours> I<num> |
aba3e65f | 334 | |
c4de074e | 335 | The number of hours before the next CRL is due. |
aba3e65f | 336 | |
e8769719 | 337 | =item B<-revoke> I<filename> |
aba3e65f | 338 | |
c4de074e | 339 | A filename containing a certificate to revoke. |
aba3e65f | 340 | |
e8769719 | 341 | =item B<-valid> I<filename> |
b4b42ce6 | 342 | |
c4de074e | 343 | A filename containing a certificate to add a Valid certificate entry. |
b4b42ce6 | 344 | |
e8769719 | 345 | =item B<-status> I<serial> |
fc1d88f0 | 346 | |
c4de074e | 347 | Displays the revocation status of the certificate with the specified |
fc1d88f0 RS |
348 | serial number and exits. |
349 | ||
350 | =item B<-updatedb> | |
351 | ||
352 | Updates the database index to purge expired certificates. | |
353 | ||
e8769719 | 354 | =item B<-crl_reason> I<reason> |
d618f703 | 355 | |
2f0ea936 | 356 | Revocation reason, where I<reason> is one of: B<unspecified>, B<keyCompromise>, |
d618f703 | 357 | B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>, |
2f0ea936 | 358 | B<certificateHold> or B<removeFromCRL>. The matching of I<reason> is case |
d618f703 DSH |
359 | insensitive. Setting any revocation reason will make the CRL v2. |
360 | ||
42b91f28 | 361 | In practice B<removeFromCRL> is not particularly useful because it is only used |
d618f703 DSH |
362 | in delta CRLs which are not currently implemented. |
363 | ||
e8769719 | 364 | =item B<-crl_hold> I<instruction> |
d618f703 DSH |
365 | |
366 | This sets the CRL revocation reason code to B<certificateHold> and the hold | |
2f0ea936 | 367 | instruction to I<instruction> which must be an OID. Although any OID can be |
d618f703 DSH |
368 | used only B<holdInstructionNone> (the use of which is discouraged by RFC2459) |
369 | B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used. | |
370 | ||
e8769719 | 371 | =item B<-crl_compromise> I<time> |
d618f703 DSH |
372 | |
373 | This sets the revocation reason to B<keyCompromise> and the compromise time to | |
2f0ea936 | 374 | I<time>. I<time> should be in GeneralizedTime format that is I<YYYYMMDDHHMMSSZ>. |
d618f703 | 375 | |
e8769719 | 376 | =item B<-crl_CA_compromise> I<time> |
d618f703 DSH |
377 | |
378 | This is the same as B<crl_compromise> except the revocation reason is set to | |
379 | B<CACompromise>. | |
380 | ||
e8769719 | 381 | =item B<-crlexts> I<section> |
aba3e65f | 382 | |
c4de074e | 383 | The section of the configuration file containing CRL extensions to |
aba3e65f DSH |
384 | include. If no CRL extension section is present then a V1 CRL is |
385 | created, if the CRL extension section is present (even if it is | |
386 | empty) then a V2 CRL is created. The CRL extensions specified are | |
387 | CRL extensions and B<not> CRL entry extensions. It should be noted | |
137de5b1 | 388 | that some software (for example Netscape) can't handle V2 CRLs. See |
9b86974e | 389 | L<x509v3_config(5)> manual page for details of the |
137de5b1 | 390 | extension section format. |
aba3e65f DSH |
391 | |
392 | =back | |
393 | ||
394 | =head1 CONFIGURATION FILE OPTIONS | |
395 | ||
35a810bb | 396 | The section of the configuration file containing options for this command |
8a0a9392 BM |
397 | is found as follows: If the B<-name> command line option is used, |
398 | then it names the section to be used. Otherwise the section to | |
399 | be used must be named in the B<default_ca> option of the B<ca> section | |
400 | of the configuration file (or in the default section of the | |
401 | configuration file). Besides B<default_ca>, the following options are | |
402 | read directly from the B<ca> section: | |
403 | RANDFILE | |
404 | preserve | |
405 | msie_hack | |
406 | With the exception of B<RANDFILE>, this is probably a bug and may | |
407 | change in future releases. | |
408 | ||
409 | Many of the configuration file options are identical to command line | |
aba3e65f DSH |
410 | options. Where the option is present in the configuration file |
411 | and the command line the command line value is used. Where an | |
412 | option is described as mandatory then it must be present in | |
413 | the configuration file or the command line equivalent (if | |
414 | any) used. | |
415 | ||
416 | =over 4 | |
417 | ||
5e76807b DSH |
418 | =item B<oid_file> |
419 | ||
420 | This specifies a file containing additional B<OBJECT IDENTIFIERS>. | |
421 | Each line of the file should consist of the numerical form of the | |
422 | object identifier followed by white space then the short name followed | |
1bc74519 | 423 | by white space and finally the long name. |
5e76807b DSH |
424 | |
425 | =item B<oid_section> | |
426 | ||
427 | This specifies a section in the configuration file containing extra | |
428 | object identifiers. Each line should consist of the short name of the | |
429 | object identifier followed by B<=> and the numerical form. The short | |
430 | and long names are the same when this option is used. | |
431 | ||
aba3e65f DSH |
432 | =item B<new_certs_dir> |
433 | ||
c4de074e | 434 | The same as the B<-outdir> command line option. It specifies |
aba3e65f DSH |
435 | the directory where new certificates will be placed. Mandatory. |
436 | ||
437 | =item B<certificate> | |
438 | ||
c4de074e | 439 | The same as B<-cert>. It gives the file containing the CA |
aba3e65f DSH |
440 | certificate. Mandatory. |
441 | ||
442 | =item B<private_key> | |
443 | ||
c4de074e | 444 | Same as the B<-keyfile> option. The file containing the |
aba3e65f DSH |
445 | CA private key. Mandatory. |
446 | ||
447 | =item B<RANDFILE> | |
448 | ||
3ee1eac2 RS |
449 | At startup the specified file is loaded into the random number generator, |
450 | and at exit 256 bytes will be written to it. | |
aba3e65f DSH |
451 | |
452 | =item B<default_days> | |
453 | ||
c4de074e | 454 | The same as the B<-days> option. The number of days to certify |
1bc74519 | 455 | a certificate for. |
aba3e65f DSH |
456 | |
457 | =item B<default_startdate> | |
458 | ||
c4de074e | 459 | The same as the B<-startdate> option. The start date to certify |
aba3e65f DSH |
460 | a certificate for. If not set the current time is used. |
461 | ||
462 | =item B<default_enddate> | |
463 | ||
c4de074e | 464 | The same as the B<-enddate> option. Either this option or |
aba3e65f DSH |
465 | B<default_days> (or the command line equivalents) must be |
466 | present. | |
467 | ||
468 | =item B<default_crl_hours default_crl_days> | |
469 | ||
c4de074e | 470 | The same as the B<-crlhours> and the B<-crldays> options. These |
aba3e65f DSH |
471 | will only be used if neither command line option is present. At |
472 | least one of these must be present to generate a CRL. | |
473 | ||
474 | =item B<default_md> | |
475 | ||
aabbc24e MC |
476 | The same as the B<-md> option. Mandatory except where the signing algorithm does |
477 | not require a digest (i.e. Ed25519 and Ed448). | |
aba3e65f DSH |
478 | |
479 | =item B<database> | |
480 | ||
c4de074e | 481 | The text database file to use. Mandatory. This file must be present |
aba3e65f DSH |
482 | though initially it will be empty. |
483 | ||
d6df2b28 RL |
484 | =item B<unique_subject> |
485 | ||
c4de074e | 486 | If the value B<yes> is given, the valid certificate entries in the |
d6df2b28 RL |
487 | database must have unique subjects. if the value B<no> is given, |
488 | several valid certificate entries may have the exact same subject. | |
489 | The default value is B<yes>, to be compatible with older (pre 0.9.8) | |
490 | versions of OpenSSL. However, to make CA certificate roll-over easier, | |
491 | it's recommended to use the value B<no>, especially if combined with | |
492 | the B<-selfsign> command line option. | |
493 | ||
5af88441 MC |
494 | Note that it is valid in some circumstances for certificates to be created |
495 | without any subject. In the case where there are multiple certificates without | |
df443918 | 496 | subjects this does not count as a duplicate. |
5af88441 | 497 | |
c5aba56c | 498 | =item B<serial> |
aba3e65f | 499 | |
c4de074e | 500 | A text file containing the next serial number to use in hex. Mandatory. |
aba3e65f DSH |
501 | This file must be present and contain a valid serial number. |
502 | ||
8fbb2af3 RL |
503 | =item B<crlnumber> |
504 | ||
c4de074e | 505 | A text file containing the next CRL number to use in hex. The crl number |
8fbb2af3 RL |
506 | will be inserted in the CRLs only if this file exists. If this file is |
507 | present, it must contain a valid CRL number. | |
508 | ||
aba3e65f DSH |
509 | =item B<x509_extensions> |
510 | ||
c4de074e | 511 | The same as B<-extensions>. |
aba3e65f DSH |
512 | |
513 | =item B<crl_extensions> | |
514 | ||
c4de074e | 515 | The same as B<-crlexts>. |
aba3e65f DSH |
516 | |
517 | =item B<preserve> | |
518 | ||
c4de074e | 519 | The same as B<-preserveDN> |
aba3e65f | 520 | |
89da653f BM |
521 | =item B<email_in_dn> |
522 | ||
c4de074e | 523 | The same as B<-noemailDN>. If you want the EMAIL field to be removed |
89da653f BM |
524 | from the DN of the certificate simply set this to 'no'. If not present |
525 | the default is to allow for the EMAIL filed in the certificate's DN. | |
526 | ||
aba3e65f DSH |
527 | =item B<msie_hack> |
528 | ||
c4de074e | 529 | The same as B<-msie_hack> |
aba3e65f DSH |
530 | |
531 | =item B<policy> | |
532 | ||
c4de074e | 533 | The same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section |
aba3e65f DSH |
534 | for more information. |
535 | ||
b325518f | 536 | =item B<name_opt>, B<cert_opt> |
e890dcdb | 537 | |
c4de074e | 538 | These options allow the format used to display the certificate details |
e890dcdb DSH |
539 | when asking the user to confirm signing. All the options supported by |
540 | the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used | |
541 | here, except the B<no_signame> and B<no_sigdump> are permanently set | |
542 | and cannot be disabled (this is because the certificate signature cannot | |
543 | be displayed because the certificate has not been signed at this point). | |
544 | ||
6f2f534b | 545 | For convenience the values B<ca_default> are accepted by both to produce |
e890dcdb DSH |
546 | a reasonable output. |
547 | ||
548 | If neither option is present the format used in earlier versions of | |
549 | OpenSSL is used. Use of the old format is B<strongly> discouraged because | |
550 | it only displays fields mentioned in the B<policy> section, mishandles | |
551 | multicharacter string types and does not display extensions. | |
552 | ||
791bd0cd DSH |
553 | =item B<copy_extensions> |
554 | ||
c4de074e | 555 | Determines how extensions in certificate requests should be handled. |
791bd0cd DSH |
556 | If set to B<none> or this option is not present then extensions are |
557 | ignored and not copied to the certificate. If set to B<copy> then any | |
558 | extensions present in the request that are not already present are copied | |
559 | to the certificate. If set to B<copyall> then all extensions in the | |
560 | request are copied to the certificate: if the extension is already present | |
561 | in the certificate it is deleted first. See the B<WARNINGS> section before | |
562 | using this option. | |
563 | ||
564 | The main use of this option is to allow a certificate request to supply | |
565 | values for certain extensions such as subjectAltName. | |
566 | ||
aba3e65f DSH |
567 | =back |
568 | ||
569 | =head1 POLICY FORMAT | |
570 | ||
571 | The policy section consists of a set of variables corresponding to | |
572 | certificate DN fields. If the value is "match" then the field value | |
573 | must match the same field in the CA certificate. If the value is | |
574 | "supplied" then it must be present. If the value is "optional" then | |
575 | it may be present. Any fields not mentioned in the policy section | |
576 | are silently deleted, unless the B<-preserveDN> option is set but | |
577 | this can be regarded more of a quirk than intended behaviour. | |
578 | ||
579 | =head1 SPKAC FORMAT | |
580 | ||
581 | The input to the B<-spkac> command line option is a Netscape | |
582 | signed public key and challenge. This will usually come from | |
1bc74519 | 583 | the B<KEYGEN> tag in an HTML form to create a new private key. |
35a810bb | 584 | It is however possible to create SPKACs using L<openssl-spkac(1)>. |
aba3e65f DSH |
585 | |
586 | The file should contain the variable SPKAC set to the value of | |
587 | the SPKAC and also the required DN components as name value pairs. | |
588 | If you need to include the same component twice then it can be | |
589 | preceded by a number and a '.'. | |
590 | ||
fc1d88f0 RS |
591 | When processing SPKAC format, the output is DER if the B<-out> |
592 | flag is used, but PEM format if sending to stdout or the B<-outdir> | |
593 | flag is used. | |
594 | ||
aba3e65f DSH |
595 | =head1 EXAMPLES |
596 | ||
35a810bb RL |
597 | Note: these examples assume that the directory structure this command |
598 | assumes is already set up and the relevant files already exist. This | |
599 | usually involves creating a CA certificate and private key with | |
600 | L<openssl-req(1)>, a serial number file and an empty index file and | |
601 | placing them in the relevant directories. | |
aba3e65f | 602 | |
1948394d RL |
603 | To use the sample configuration file below the directories F<demoCA>, |
604 | F<demoCA/private> and F<demoCA/newcerts> would be created. The CA | |
605 | certificate would be copied to F<demoCA/cacert.pem> and its private | |
606 | key to F<demoCA/private/cakey.pem>. A file F<demoCA/serial> would be | |
aba3e65f | 607 | created containing for example "01" and the empty index file |
1948394d | 608 | F<demoCA/index.txt>. |
aba3e65f DSH |
609 | |
610 | ||
611 | Sign a certificate request: | |
612 | ||
1675f6eb | 613 | openssl ca -in req.pem -out newcert.pem |
aba3e65f | 614 | |
bc42bd62 PY |
615 | Sign an SM2 certificate request: |
616 | ||
617 | openssl ca -in sm2.csr -out sm2.crt -md sm3 -sigopt "sm2_id:1234567812345678" -sm2-id "1234567812345678" | |
618 | ||
d428bf8c DSH |
619 | Sign a certificate request, using CA extensions: |
620 | ||
621 | openssl ca -in req.pem -extensions v3_ca -out newcert.pem | |
622 | ||
aba3e65f DSH |
623 | Generate a CRL |
624 | ||
1675f6eb | 625 | openssl ca -gencrl -out crl.pem |
aba3e65f DSH |
626 | |
627 | Sign several requests: | |
628 | ||
1675f6eb | 629 | openssl ca -infiles req1.pem req2.pem req3.pem |
aba3e65f DSH |
630 | |
631 | Certify a Netscape SPKAC: | |
632 | ||
1675f6eb | 633 | openssl ca -spkac spkac.txt |
aba3e65f DSH |
634 | |
635 | A sample SPKAC file (the SPKAC line has been truncated for clarity): | |
636 | ||
637 | SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 | |
638 | CN=Steve Test | |
639 | emailAddress=steve@openssl.org | |
640 | 0.OU=OpenSSL Group | |
641 | 1.OU=Another Group | |
642 | ||
35a810bb | 643 | A sample configuration file with the relevant sections for this command: |
aba3e65f DSH |
644 | |
645 | [ ca ] | |
646 | default_ca = CA_default # The default ca section | |
1bc74519 | 647 | |
aba3e65f DSH |
648 | [ CA_default ] |
649 | ||
650 | dir = ./demoCA # top dir | |
651 | database = $dir/index.txt # index file. | |
1bc74519 RS |
652 | new_certs_dir = $dir/newcerts # new certs dir |
653 | ||
aba3e65f DSH |
654 | certificate = $dir/cacert.pem # The CA cert |
655 | serial = $dir/serial # serial no file | |
ffb46830 | 656 | #rand_serial = yes # for random serial#'s |
aba3e65f DSH |
657 | private_key = $dir/private/cakey.pem# CA private key |
658 | RANDFILE = $dir/private/.rand # random number file | |
1bc74519 | 659 | |
aba3e65f DSH |
660 | default_days = 365 # how long to certify for |
661 | default_crl_days= 30 # how long before next CRL | |
662 | default_md = md5 # md to use | |
663 | ||
664 | policy = policy_any # default policy | |
89da653f | 665 | email_in_dn = no # Don't add the email into cert DN |
aba3e65f | 666 | |
1bc74519 RS |
667 | name_opt = ca_default # Subject name display option |
668 | cert_opt = ca_default # Certificate display option | |
669 | copy_extensions = none # Don't copy extensions from request | |
e890dcdb | 670 | |
aba3e65f DSH |
671 | [ policy_any ] |
672 | countryName = supplied | |
673 | stateOrProvinceName = optional | |
674 | organizationName = optional | |
675 | organizationalUnitName = optional | |
676 | commonName = supplied | |
677 | emailAddress = optional | |
678 | ||
aba3e65f DSH |
679 | =head1 FILES |
680 | ||
681 | Note: the location of all files can change either by compile time options, | |
19d2bb57 | 682 | configuration file entries, environment variables or command line options. |
aba3e65f DSH |
683 | The values below reflect the default values. |
684 | ||
685 | /usr/local/ssl/lib/openssl.cnf - master configuration file | |
686 | ./demoCA - main CA directory | |
687 | ./demoCA/cacert.pem - CA certificate | |
688 | ./demoCA/private/cakey.pem - CA private key | |
689 | ./demoCA/serial - CA serial number file | |
690 | ./demoCA/serial.old - CA serial number backup file | |
691 | ./demoCA/index.txt - CA text database file | |
692 | ./demoCA/index.txt.old - CA text database backup file | |
693 | ./demoCA/certs - certificate output file | |
694 | ./demoCA/.rnd - CA random seed information | |
695 | ||
aba3e65f DSH |
696 | =head1 RESTRICTIONS |
697 | ||
1bc74519 | 698 | The text database index file is a critical part of the process and |
aba3e65f DSH |
699 | if corrupted it can be difficult to fix. It is theoretically possible |
700 | to rebuild the index file from all the issued certificates and a current | |
701 | CRL: however there is no option to do this. | |
702 | ||
cb26a20c | 703 | V2 CRL features like delta CRLs are not currently supported. |
aba3e65f DSH |
704 | |
705 | Although several requests can be input and handled at once it is only | |
77a795e4 | 706 | possible to include one SPKAC or self-signed certificate. |
aba3e65f DSH |
707 | |
708 | =head1 BUGS | |
709 | ||
77a795e4 | 710 | The use of an in-memory text database can cause problems when large |
aba3e65f DSH |
711 | numbers of certificates are present because, as the name implies |
712 | the database has to be kept in memory. | |
713 | ||
35a810bb | 714 | This command really needs rewriting or the required functionality |
aba3e65f | 715 | exposed at either a command or interface level so a more friendly utility |
be739b0c RS |
716 | (perl script or GUI) can handle things properly. The script |
717 | B<CA.pl> helps a little but not very much. | |
aba3e65f DSH |
718 | |
719 | Any fields in a request that are not present in a policy are silently | |
89da653f BM |
720 | deleted. This does not happen if the B<-preserveDN> option is used. To |
721 | enforce the absence of the EMAIL field within the DN, as suggested by | |
722 | RFCs, regardless the contents of the request' subject the B<-noemailDN> | |
723 | option can be used. The behaviour should be more friendly and | |
724 | configurable. | |
aba3e65f | 725 | |
42b91f28 | 726 | Canceling some commands by refusing to certify a certificate can |
aba3e65f DSH |
727 | create an empty file. |
728 | ||
791bd0cd DSH |
729 | =head1 WARNINGS |
730 | ||
35a810bb | 731 | This command is quirky and at times downright unfriendly. |
1f309464 | 732 | |
35a810bb RL |
733 | This command was originally meant as an example of how to do |
734 | things in a CA. It was not supposed to be used as a full blown CA itself: | |
1f309464 LJ |
735 | nevertheless some people are using it for this purpose. |
736 | ||
35a810bb RL |
737 | This command command is effectively a single user command: no locking |
738 | is done on the various files and attempts to run more than one B<openssl ca> | |
739 | command on the same database can have unpredictable results. | |
1f309464 | 740 | |
791bd0cd DSH |
741 | The B<copy_extensions> option should be used with caution. If care is |
742 | not taken then it can be a security risk. For example if a certificate | |
743 | request contains a basicConstraints extension with CA:TRUE and the | |
744 | B<copy_extensions> value is set to B<copyall> and the user does not spot | |
42b91f28 | 745 | this when the certificate is displayed then this will hand the requester |
791bd0cd DSH |
746 | a valid CA certificate. |
747 | ||
748 | This situation can be avoided by setting B<copy_extensions> to B<copy> | |
749 | and including basicConstraints with CA:FALSE in the configuration file. | |
750 | Then if the request contains a basicConstraints extension it will be | |
751 | ignored. | |
752 | ||
753 | It is advisable to also include values for other extensions such | |
754 | as B<keyUsage> to prevent a request supplying its own values. | |
755 | ||
756 | Additional restrictions can be placed on the CA certificate itself. | |
757 | For example if the CA certificate has: | |
758 | ||
759 | basicConstraints = CA:TRUE, pathlen:0 | |
760 | ||
761 | then even if a certificate is issued with CA:TRUE it will not be valid. | |
762 | ||
909873bd PY |
763 | =head1 HISTORY |
764 | ||
765 | Since OpenSSL 1.1.1, the program follows RFC5280. Specifically, | |
766 | certificate validity period (specified by any of B<-startdate>, | |
767 | B<-enddate> and B<-days>) will be encoded as UTCTime if the dates are | |
768 | earlier than year 2049 (included), and as GeneralizedTime if the dates | |
769 | are in year 2050 or later. | |
770 | ||
aba3e65f DSH |
771 | =head1 SEE ALSO |
772 | ||
b6b66573 DMSP |
773 | L<openssl(1)>, |
774 | L<openssl-req(1)>, | |
775 | L<openssl-spkac(1)>, | |
776 | L<openssl-x509(1)>, | |
777 | L<CA.pl(1)>, | |
778 | L<config(5)>, | |
779 | L<x509v3_config(5)> | |
aba3e65f | 780 | |
e2f92610 RS |
781 | =head1 COPYRIGHT |
782 | ||
d7b2124a | 783 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 784 | |
449040b4 | 785 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
786 | this file except in compliance with the License. You can obtain a copy |
787 | in the file LICENSE in the source distribution or at | |
788 | L<https://www.openssl.org/source/license.html>. | |
789 | ||
790 | =cut |