]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
b6b66573 | 5 | openssl-req - PKCS#10 certificate request and certificate generating utility |
aba3e65f DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<req> | |
169394d4 | 10 | [B<-help>] |
e8769719 RS |
11 | [B<-inform> B<DER>|B<PEM>] |
12 | [B<-outform> B<DER>|B<PEM>] | |
13 | [B<-in> I<filename>] | |
14 | [B<-passin> I<arg>] | |
15 | [B<-out> I<filename>] | |
16 | [B<-passout> I<arg>] | |
aba3e65f | 17 | [B<-text>] |
21a85f19 | 18 | [B<-pubkey>] |
aba3e65f DSH |
19 | [B<-noout>] |
20 | [B<-verify>] | |
21 | [B<-modulus>] | |
22 | [B<-new>] | |
fed8bd90 | 23 | [B<-rand> I<files>] |
e8769719 | 24 | [B<-writerand> I<file>] |
2f0ea936 | 25 | [B<-newkey> I<arg>] |
aba3e65f | 26 | [B<-nodes>] |
e8769719 RS |
27 | [B<-key> I<filename>] |
28 | [B<-keyform> B<DER>|B<PEM>] | |
29 | [B<-keyout> I<filename>] | |
30 | [B<-keygen_engine> I<id>] | |
8dc57d76 | 31 | [B<-I<digest>>] |
e8769719 | 32 | [B<-config> I<filename>] |
57eb1d32 | 33 | [B<-multivalue-rdn>] |
aba3e65f | 34 | [B<-x509>] |
e8769719 RS |
35 | [B<-days> I<n>] |
36 | [B<-set_serial> I<n>] | |
8a208cba | 37 | [B<-newhdr>] |
e8769719 RS |
38 | [B<-addext> I<ext>] |
39 | [B<-extensions> I<section>] | |
40 | [B<-reqexts> I<section>] | |
7bb89f09 | 41 | [B<-precert>] |
1fc6d41b | 42 | [B<-utf8>] |
c0455cbb | 43 | [B<-nameopt>] |
e5fa864f DSH |
44 | [B<-reqopt>] |
45 | [B<-subject>] | |
e8769719 RS |
46 | [B<-subj> I<arg>] |
47 | [B<-sigopt> I<nm>:I<v>] | |
bad40585 BM |
48 | [B<-batch>] |
49 | [B<-verbose>] | |
e8769719 RS |
50 | [B<-engine> I<id>] |
51 | [B<-sm2-id> I<string>] | |
52 | [B<-sm2-hex-id> I<hex-string>] | |
aba3e65f | 53 | |
9f3c076b | 54 | =for openssl ifdef engine keygen_engine sm2-id sm2-hex-id |
1738c0ce | 55 | |
aba3e65f DSH |
56 | =head1 DESCRIPTION |
57 | ||
35a810bb | 58 | This command primarily creates and processes certificate requests |
aba3e65f DSH |
59 | in PKCS#10 format. It can additionally create self signed certificates |
60 | for use as root CAs for example. | |
61 | ||
3dfda1a6 | 62 | =head1 OPTIONS |
aba3e65f DSH |
63 | |
64 | =over 4 | |
65 | ||
169394d4 MR |
66 | =item B<-help> |
67 | ||
68 | Print out a usage message. | |
69 | ||
777182a0 | 70 | =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> |
aba3e65f | 71 | |
777182a0 RS |
72 | The input and formats; the default is B<PEM>. |
73 | See L<openssl(1)/Format Options> for details. | |
aba3e65f | 74 | |
777182a0 | 75 | The data is a PKCS#10 object. |
aba3e65f | 76 | |
e8769719 | 77 | =item B<-in> I<filename> |
aba3e65f DSH |
78 | |
79 | This specifies the input filename to read a request from or standard input | |
80 | if this option is not specified. A request is only read if the creation | |
81 | options (B<-new> and B<-newkey>) are not specified. | |
82 | ||
e8769719 | 83 | =item B<-sigopt> I<nm>:I<v> |
d7b2124a P |
84 | |
85 | Pass options to the signature algorithm during sign or verify operations. | |
86 | Names and values of these options are algorithm-specific. | |
87 | ||
3a4e43de | 88 | =item B<-passin> I<arg>, B<-passout> I<arg> |
20432eae | 89 | |
3a4e43de RS |
90 | The password source for the input and output file. |
91 | For more information about the format of B<arg> | |
92 | see L<openssl(1)/Pass Phrase Options>. | |
20432eae | 93 | |
e8769719 | 94 | =item B<-out> I<filename> |
aba3e65f DSH |
95 | |
96 | This specifies the output filename to write to or standard output by | |
97 | default. | |
98 | ||
99 | =item B<-text> | |
100 | ||
c4de074e | 101 | Prints out the certificate request in text form. |
aba3e65f | 102 | |
e5fa864f DSH |
103 | =item B<-subject> |
104 | ||
c4de074e | 105 | Prints out the request subject (or certificate subject if B<-x509> is |
e5fa864f DSH |
106 | specified) |
107 | ||
21a85f19 DSH |
108 | =item B<-pubkey> |
109 | ||
c4de074e | 110 | Outputs the public key. |
21a85f19 | 111 | |
aba3e65f DSH |
112 | =item B<-noout> |
113 | ||
c4de074e | 114 | This option prevents output of the encoded version of the request. |
aba3e65f DSH |
115 | |
116 | =item B<-modulus> | |
117 | ||
c4de074e | 118 | This option prints out the value of the modulus of the public key |
aba3e65f DSH |
119 | contained in the request. |
120 | ||
121 | =item B<-verify> | |
122 | ||
c4de074e | 123 | Verifies the signature on the request. |
aba3e65f DSH |
124 | |
125 | =item B<-new> | |
126 | ||
c4de074e | 127 | This option generates a new certificate request. It will prompt |
aba3e65f DSH |
128 | the user for the relevant field values. The actual fields |
129 | prompted for and their maximum and minimum sizes are specified | |
130 | in the configuration file and any requested extensions. | |
131 | ||
132 | If the B<-key> option is not used it will generate a new RSA private | |
133 | key using information specified in the configuration file. | |
134 | ||
a397aca4 | 135 | =item B<-rand> I<files>, B<-writerand> I<file> |
fb0b844a | 136 | |
a397aca4 | 137 | See L<openssl(1)/Random State Options> for more information. |
3ee1eac2 | 138 | |
e8769719 | 139 | =item B<-newkey> I<arg> |
aba3e65f | 140 | |
c4de074e | 141 | This option creates a new certificate request and a new private |
2f0ea936 RL |
142 | key. The argument takes one of several forms. |
143 | ||
144 | B<rsa:>I<nbits>, where | |
145 | I<nbits> is the number of bits, generates an RSA key I<nbits> | |
146 | in size. If I<nbits> is omitted, i.e. B<-newkey> I<rsa> specified, | |
e5fa864f DSH |
147 | the default key size, specified in the configuration file is used. |
148 | ||
2f0ea936 | 149 | All other algorithms support the B<-newkey> I<alg>:I<file> form, where file |
35a810bb | 150 | may be an algorithm parameter file, created with C<openssl genpkey -genparam> |
2f0ea936 | 151 | or an X.509 certificate for a key with appropriate algorithm. |
e5fa864f | 152 | |
2f0ea936 RL |
153 | B<param:>I<file> generates a key using the parameter file or certificate |
154 | I<file>, the algorithm is determined by the parameters. I<algname>:I<file> | |
155 | use algorithm I<algname> and parameter file I<file>: the two algorithms must | |
156 | match or an error occurs. I<algname> just uses algorithm I<algname>, and | |
157 | parameters, if necessary should be specified via B<-pkeyopt> parameter. | |
e5fa864f | 158 | |
2f0ea936 RL |
159 | B<dsa:>I<filename> generates a DSA key using the parameters |
160 | in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with | |
161 | ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R | |
162 | 34.10-2001 key (requires B<gost> engine configured in the configuration | |
e5fa864f | 163 | file). If just B<gost2001> is specified a parameter set should be |
e8769719 | 164 | specified by B<-pkeyopt> I<paramset:X> |
e5fa864f | 165 | |
2f0ea936 | 166 | =item B<-pkeyopt> I<opt>:I<value> |
49131a7d | 167 | |
2f0ea936 | 168 | Set the public key algorithm option I<opt> to I<value>. The precise set of |
49131a7d | 169 | options supported depends on the public key algorithm used and its |
f5c14c63 RL |
170 | implementation. |
171 | See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details. | |
aba3e65f | 172 | |
e8769719 | 173 | =item B<-key> I<filename> |
aba3e65f DSH |
174 | |
175 | This specifies the file to read the private key from. It also | |
176 | accepts PKCS#8 format private keys for PEM format files. | |
177 | ||
e8769719 | 178 | =item B<-keyform> B<DER>|B<PEM> |
aba3e65f | 179 | |
777182a0 RS |
180 | The format of the private key; the default is B<PEM>. |
181 | See L<openssl(1)/Format Options> for details. | |
aba3e65f | 182 | |
e8769719 | 183 | =item B<-keyout> I<filename> |
aba3e65f | 184 | |
c4de074e | 185 | This gives the filename to write the newly created private key to. |
aba3e65f DSH |
186 | If this option is not specified then the filename present in the |
187 | configuration file is used. | |
188 | ||
189 | =item B<-nodes> | |
190 | ||
c4de074e | 191 | If this option is specified then if a private key is created it |
aba3e65f DSH |
192 | will not be encrypted. |
193 | ||
8dc57d76 | 194 | =item B<-I<digest>> |
e5fa864f | 195 | |
c4de074e | 196 | This specifies the message digest to sign the request. |
c03726ca RS |
197 | Any digest supported by the OpenSSL B<dgst> command can be used. |
198 | This overrides the digest algorithm specified in | |
e5fa864f | 199 | the configuration file. |
aba3e65f | 200 | |
e5fa864f DSH |
201 | Some public key algorithms may override this choice. For instance, DSA |
202 | signatures always use SHA1, GOST R 34.10 signatures always use | |
f112dc82 | 203 | GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest. |
aba3e65f | 204 | |
e8769719 | 205 | =item B<-config> I<filename> |
aba3e65f | 206 | |
c4de074e | 207 | This allows an alternative configuration file to be specified. |
e9681f83 RS |
208 | Optional; for a description of the default value, |
209 | see L<openssl(1)/COMMAND SUMMARY>. | |
aba3e65f | 210 | |
e8769719 | 211 | =item B<-subj> I<arg> |
bad40585 | 212 | |
c4de074e | 213 | Sets subject name for new request or supersedes the subject name |
bad40585 | 214 | when processing a request. |
a43384fd | 215 | The arg must be formatted as C</type0=value0/type1=value1/type2=...>. |
3d362f19 BK |
216 | Keyword characters may be escaped by \ (backslash), and whitespace is retained. |
217 | Empty values are permitted, but the corresponding type will not be included | |
218 | in the request. | |
bad40585 | 219 | |
57eb1d32 NL |
220 | =item B<-multivalue-rdn> |
221 | ||
c4de074e | 222 | This option causes the -subj argument to be interpreted with full |
57eb1d32 NL |
223 | support for multivalued RDNs. Example: |
224 | ||
a43384fd | 225 | C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> |
57eb1d32 | 226 | |
a43384fd | 227 | If -multi-rdn is not used then the UID value is C<123456+CN=John Doe>. |
57eb1d32 | 228 | |
aba3e65f DSH |
229 | =item B<-x509> |
230 | ||
c4de074e | 231 | This option outputs a self signed certificate instead of a certificate |
aba3e65f DSH |
232 | request. This is typically used to generate a test certificate or |
233 | a self signed root CA. The extensions added to the certificate | |
cc5ba6a7 | 234 | (if any) are specified in the configuration file. Unless specified |
2f0ea936 | 235 | using the B<-set_serial> option, a large random number will be used for |
3aba132d | 236 | the serial number. |
aba3e65f | 237 | |
888adbe0 TM |
238 | If existing request is specified with the B<-in> option, it is converted |
239 | to the self signed certificate otherwise new request is created. | |
240 | ||
e8769719 | 241 | =item B<-days> I<n> |
aba3e65f | 242 | |
c4de074e | 243 | When the B<-x509> option is being used this specifies the number of |
2f0ea936 | 244 | days to certify the certificate for, otherwise it is ignored. I<n> should |
05de3a5b | 245 | be a positive integer. The default is 30 days. |
aba3e65f | 246 | |
e8769719 | 247 | =item B<-set_serial> I<n> |
cc5ba6a7 | 248 | |
c4de074e | 249 | Serial number to use when outputting a self signed certificate. This |
a43384fd | 250 | may be specified as a decimal value or a hex value if preceded by C<0x>. |
cc5ba6a7 | 251 | |
e8769719 | 252 | =item B<-addext> I<ext> |
bfa470a4 RL |
253 | |
254 | Add a specific extension to the certificate (if the B<-x509> option is | |
255 | present) or certificate request. The argument must have the form of | |
256 | a key=value pair as it would appear in a config file. | |
257 | ||
258 | This option can be given multiple times. | |
259 | ||
e8769719 | 260 | =item B<-extensions> I<section> |
fbecbc8c | 261 | |
e8769719 | 262 | =item B<-reqexts> I<section> |
aba3e65f | 263 | |
c4de074e | 264 | These options specify alternative sections to include certificate |
aba3e65f DSH |
265 | extensions (if the B<-x509> option is present) or certificate |
266 | request extensions. This allows several different sections to | |
267 | be used in the same configuration file to specify requests for | |
268 | a variety of purposes. | |
269 | ||
7bb89f09 RP |
270 | =item B<-precert> |
271 | ||
c4de074e | 272 | A poison extension will be added to the certificate, making it a |
7bb89f09 RP |
273 | "pre-certificate" (see RFC6962). This can be submitted to Certificate |
274 | Transparency logs in order to obtain signed certificate timestamps (SCTs). | |
275 | These SCTs can then be embedded into the pre-certificate as an extension, before | |
276 | removing the poison and signing the certificate. | |
277 | ||
65b3dff7 RP |
278 | This implies the B<-new> flag. |
279 | ||
1fc6d41b DSH |
280 | =item B<-utf8> |
281 | ||
c4de074e | 282 | This option causes field values to be interpreted as UTF8 strings, by |
1fc6d41b DSH |
283 | default they are interpreted as ASCII. This means that the field |
284 | values, whether prompted from a terminal or obtained from a | |
285 | configuration file, must be valid UTF8 strings. | |
286 | ||
e8769719 | 287 | =item B<-nameopt> I<option> |
c0455cbb | 288 | |
c4de074e | 289 | Option which determines how the subject or issuer names are displayed. The |
2f0ea936 | 290 | I<option> argument can be a single option or multiple options separated by |
c0455cbb | 291 | commas. Alternatively the B<-nameopt> switch may be used more than once to |
8bc93d2f | 292 | set multiple options. See the L<openssl-x509(1)> manual page for details. |
c0455cbb | 293 | |
2f0ea936 | 294 | =item B<-reqopt> I<option> |
e5fa864f | 295 | |
2f0ea936 | 296 | Customise the output format used with B<-text>. The I<option> argument can be |
1bc74519 | 297 | a single option or multiple options separated by commas. |
e5fa864f | 298 | |
8bc93d2f | 299 | See discussion of the B<-certopt> parameter in the L<openssl-x509(1)> |
e5fa864f DSH |
300 | command. |
301 | ||
8a208cba DSH |
302 | =item B<-newhdr> |
303 | ||
2b4ffc65 | 304 | Adds the word B<NEW> to the PEM file header and footer lines on the outputted |
8a208cba DSH |
305 | request. Some software (Netscape certificate server) and some CAs need this. |
306 | ||
bad40585 BM |
307 | =item B<-batch> |
308 | ||
c4de074e | 309 | Non-interactive mode. |
bad40585 BM |
310 | |
311 | =item B<-verbose> | |
312 | ||
c4de074e | 313 | Print extra details about the operations being performed. |
bad40585 | 314 | |
e8769719 | 315 | =item B<-engine> I<id> |
bfa35550 | 316 | |
35a810bb | 317 | Specifying an engine (by its unique I<id> string) will cause this command |
bfa35550 RL |
318 | to attempt to obtain a functional reference to the specified engine, |
319 | thus initialising it if needed. The engine will then be set as the default | |
320 | for all available algorithms. | |
321 | ||
e8769719 | 322 | =item B<-keygen_engine> I<id> |
e5fa864f | 323 | |
2f0ea936 | 324 | Specifies an engine (by its unique I<id> string) which would be used |
e5fa864f DSH |
325 | for key generation operations. |
326 | ||
bc42bd62 PY |
327 | =item B<-sm2-id> |
328 | ||
dbb72124 PY |
329 | Specify the ID string to use when verifying an SM2 certificate request. The ID |
330 | string is required by the SM2 signature algorithm for signing and verification. | |
bc42bd62 PY |
331 | |
332 | =item B<-sm2-hex-id> | |
333 | ||
d3329973 PY |
334 | Specify a binary ID string to use when verifying an SM2 certificate request. The |
335 | argument for this option is string of hexadecimal digits. | |
bc42bd62 | 336 | |
aba3e65f DSH |
337 | =back |
338 | ||
339 | =head1 CONFIGURATION FILE FORMAT | |
340 | ||
19d2bb57 | 341 | The configuration options are specified in the B<req> section of |
aba3e65f DSH |
342 | the configuration file. As with all configuration files if no |
343 | value is specified in the specific section (i.e. B<req>) then | |
344 | the initial unnamed or B<default> section is searched too. | |
345 | ||
346 | The options available are described in detail below. | |
347 | ||
348 | =over 4 | |
349 | ||
b38f9f66 DSH |
350 | =item B<input_password output_password> |
351 | ||
352 | The passwords for the input private key file (if present) and | |
353 | the output private key file (if one will be created). The | |
a3fe382e DSH |
354 | command line options B<passin> and B<passout> override the |
355 | configuration file values. | |
b38f9f66 | 356 | |
aba3e65f DSH |
357 | =item B<default_bits> |
358 | ||
a7626557 EK |
359 | Specifies the default key size in bits. |
360 | ||
361 | This option is used in conjunction with the B<-new> option to generate | |
362 | a new key. It can be overridden by specifying an explicit key size in | |
363 | the B<-newkey> option. The smallest accepted key size is 512 bits. If | |
364 | no key size is specified then 2048 bits is used. | |
aba3e65f DSH |
365 | |
366 | =item B<default_keyfile> | |
367 | ||
368 | This is the default filename to write a private key to. If not | |
369 | specified the key is written to standard output. This can be | |
19d2bb57 | 370 | overridden by the B<-keyout> option. |
aba3e65f DSH |
371 | |
372 | =item B<oid_file> | |
373 | ||
374 | This specifies a file containing additional B<OBJECT IDENTIFIERS>. | |
375 | Each line of the file should consist of the numerical form of the | |
376 | object identifier followed by white space then the short name followed | |
1bc74519 | 377 | by white space and finally the long name. |
aba3e65f DSH |
378 | |
379 | =item B<oid_section> | |
380 | ||
381 | This specifies a section in the configuration file containing extra | |
5e76807b DSH |
382 | object identifiers. Each line should consist of the short name of the |
383 | object identifier followed by B<=> and the numerical form. The short | |
aba3e65f DSH |
384 | and long names are the same when this option is used. |
385 | ||
386 | =item B<RANDFILE> | |
387 | ||
3ee1eac2 RS |
388 | At startup the specified file is loaded into the random number generator, |
389 | and at exit 256 bytes will be written to it. | |
a4cfd178 | 390 | It is used for private key generation. |
aba3e65f | 391 | |
b38f9f66 | 392 | =item B<encrypt_key> |
aba3e65f DSH |
393 | |
394 | If this is set to B<no> then if a private key is generated it is | |
395 | B<not> encrypted. This is equivalent to the B<-nodes> command line | |
6e6bc352 | 396 | option. For compatibility B<encrypt_rsa_key> is an equivalent option. |
aba3e65f DSH |
397 | |
398 | =item B<default_md> | |
399 | ||
f112dc82 MC |
400 | This option specifies the digest algorithm to use. Any digest supported by the |
401 | OpenSSL B<dgst> command can be used. This option can be overridden on the | |
402 | command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore | |
403 | any digest that has been set. | |
aba3e65f | 404 | |
b38f9f66 | 405 | =item B<string_mask> |
aba3e65f | 406 | |
b38f9f66 DSH |
407 | This option masks out the use of certain string types in certain |
408 | fields. Most users will not need to change this option. | |
aba3e65f DSH |
409 | |
410 | It can be set to several values B<default> which is also the default | |
1bc74519 | 411 | option uses PrintableStrings, T61Strings and BMPStrings if the |
aba3e65f DSH |
412 | B<pkix> value is used then only PrintableStrings and BMPStrings will |
413 | be used. This follows the PKIX recommendation in RFC2459. If the | |
414 | B<utf8only> option is used then only UTF8Strings will be used: this | |
b38f9f66 | 415 | is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> |
aba3e65f | 416 | option just uses PrintableStrings and T61Strings: certain software has |
b38f9f66 | 417 | problems with BMPStrings and UTF8Strings: in particular Netscape. |
aba3e65f DSH |
418 | |
419 | =item B<req_extensions> | |
420 | ||
c4de074e | 421 | This specifies the configuration file section containing a list of |
aba3e65f | 422 | extensions to add to the certificate request. It can be overridden |
1bc74519 | 423 | by the B<-reqexts> command line switch. See the |
9b86974e | 424 | L<x509v3_config(5)> manual page for details of the |
137de5b1 | 425 | extension section format. |
aba3e65f DSH |
426 | |
427 | =item B<x509_extensions> | |
428 | ||
c4de074e | 429 | This specifies the configuration file section containing a list of |
aba3e65f DSH |
430 | extensions to add to certificate generated when the B<-x509> switch |
431 | is used. It can be overridden by the B<-extensions> command line switch. | |
432 | ||
6e6bc352 DSH |
433 | =item B<prompt> |
434 | ||
c4de074e | 435 | If set to the value B<no> this disables prompting of certificate fields |
6e6bc352 DSH |
436 | and just takes values from the config file directly. It also changes the |
437 | expected format of the B<distinguished_name> and B<attributes> sections. | |
438 | ||
1fc6d41b DSH |
439 | =item B<utf8> |
440 | ||
c4de074e | 441 | If set to the value B<yes> then field values to be interpreted as UTF8 |
1fc6d41b DSH |
442 | strings, by default they are interpreted as ASCII. This means that |
443 | the field values, whether prompted from a terminal or obtained from a | |
444 | configuration file, must be valid UTF8 strings. | |
445 | ||
aba3e65f DSH |
446 | =item B<attributes> |
447 | ||
c4de074e | 448 | This specifies the section containing any request attributes: its format |
6e6bc352 DSH |
449 | is the same as B<distinguished_name>. Typically these may contain the |
450 | challengePassword or unstructuredName types. They are currently ignored | |
451 | by OpenSSL's request signing utilities but some CAs might want them. | |
aba3e65f DSH |
452 | |
453 | =item B<distinguished_name> | |
454 | ||
19d2bb57 | 455 | This specifies the section containing the distinguished name fields to |
6e6bc352 DSH |
456 | prompt for when generating a certificate or certificate request. The format |
457 | is described in the next section. | |
458 | ||
459 | =back | |
460 | ||
461 | =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT | |
462 | ||
463 | There are two separate formats for the distinguished name and attribute | |
464 | sections. If the B<prompt> option is set to B<no> then these sections | |
465 | just consist of field names and values: for example, | |
aba3e65f | 466 | |
6e6bc352 DSH |
467 | CN=My Name |
468 | OU=My Organization | |
657e60fa | 469 | emailAddress=someone@somewhere.org |
6e6bc352 | 470 | |
35a810bb RL |
471 | This allows external programs (e.g. GUI based) to generate a template file with |
472 | all the field names and values and just pass it to this command. An example | |
8a208cba | 473 | of this kind of configuration file is contained in the B<EXAMPLES> section. |
6e6bc352 | 474 | |
8a208cba | 475 | Alternatively if the B<prompt> option is absent or not set to B<no> then the |
6e6bc352 DSH |
476 | file contains field prompting information. It consists of lines of the form: |
477 | ||
478 | fieldName="prompt" | |
479 | fieldName_default="default field value" | |
480 | fieldName_min= 2 | |
481 | fieldName_max= 4 | |
aba3e65f | 482 | |
20432eae | 483 | "fieldName" is the field name being used, for example commonName (or CN). |
19d2bb57 | 484 | The "prompt" string is used to ask the user to enter the relevant |
aba3e65f DSH |
485 | details. If the user enters nothing then the default value is used if no |
486 | default value is present then the field is omitted. A field can | |
487 | still be omitted if a default value is present if the user just | |
488 | enters the '.' character. | |
489 | ||
490 | The number of characters entered must be between the fieldName_min and | |
491 | fieldName_max limits: there may be additional restrictions based | |
492 | on the field being used (for example countryName can only ever be | |
493 | two characters long and must fit in a PrintableString). | |
494 | ||
495 | Some fields (such as organizationName) can be used more than once | |
496 | in a DN. This presents a problem because configuration files will | |
6e6bc352 | 497 | not recognize the same name occurring twice. To avoid this problem |
8a208cba | 498 | if the fieldName contains some characters followed by a full stop |
aba3e65f DSH |
499 | they will be ignored. So for example a second organizationName can |
500 | be input by calling it "1.organizationName". | |
501 | ||
502 | The actual permitted field names are any object identifier short or | |
503 | long names. These are compiled into OpenSSL and include the usual | |
504 | values such as commonName, countryName, localityName, organizationName, | |
208b2d54 | 505 | organizationalUnitName, stateOrProvinceName. Additionally emailAddress |
005247af | 506 | is included as well as name, surname, givenName, initials, and dnQualifier. |
aba3e65f DSH |
507 | |
508 | Additional object identifiers can be defined with the B<oid_file> or | |
509 | B<oid_section> options in the configuration file. Any additional fields | |
510 | will be treated as though they were a DirectoryString. | |
511 | ||
af29811e | 512 | |
aba3e65f DSH |
513 | =head1 EXAMPLES |
514 | ||
515 | Examine and verify certificate request: | |
516 | ||
5e76807b | 517 | openssl req -in req.pem -text -verify -noout |
aba3e65f DSH |
518 | |
519 | Create a private key and then generate a certificate request from it: | |
520 | ||
740ceb5b | 521 | openssl genrsa -out key.pem 2048 |
5e76807b | 522 | openssl req -new -key key.pem -out req.pem |
aba3e65f DSH |
523 | |
524 | The same but just using req: | |
525 | ||
740ceb5b | 526 | openssl req -newkey rsa:2048 -keyout key.pem -out req.pem |
aba3e65f DSH |
527 | |
528 | Generate a self signed root certificate: | |
529 | ||
740ceb5b | 530 | openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem |
5e76807b | 531 | |
bc42bd62 PY |
532 | Create an SM2 private key and then generate a certificate request from it: |
533 | ||
534 | openssl ecparam -genkey -name SM2 -out sm2.key | |
535 | openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "sm2_id:1234567812345678" | |
536 | ||
537 | Examine and verify an SM2 certificate request: | |
538 | ||
539 | openssl req -verify -in sm2.csr -sm3 -sm2-id 1234567812345678 | |
540 | ||
5e76807b DSH |
541 | Example of a file pointed to by the B<oid_file> option: |
542 | ||
1bc74519 RS |
543 | 1.2.3.4 shortName A longer Name |
544 | 1.2.3.6 otherName Other longer Name | |
5e76807b DSH |
545 | |
546 | Example of a section pointed to by B<oid_section> making use of variable | |
547 | expansion: | |
548 | ||
549 | testoid1=1.2.3.5 | |
550 | testoid2=${testoid1}.6 | |
551 | ||
6e6bc352 | 552 | Sample configuration file prompting for field values: |
5e76807b DSH |
553 | |
554 | [ req ] | |
1bc74519 RS |
555 | default_bits = 2048 |
556 | default_keyfile = privkey.pem | |
557 | distinguished_name = req_distinguished_name | |
558 | attributes = req_attributes | |
559 | req_extensions = v3_ca | |
5e76807b DSH |
560 | |
561 | dirstring_type = nobmp | |
562 | ||
563 | [ req_distinguished_name ] | |
1bc74519 RS |
564 | countryName = Country Name (2 letter code) |
565 | countryName_default = AU | |
566 | countryName_min = 2 | |
567 | countryName_max = 2 | |
5e76807b | 568 | |
1bc74519 | 569 | localityName = Locality Name (eg, city) |
5e76807b | 570 | |
1bc74519 | 571 | organizationalUnitName = Organizational Unit Name (eg, section) |
5e76807b | 572 | |
1bc74519 RS |
573 | commonName = Common Name (eg, YOUR name) |
574 | commonName_max = 64 | |
5e76807b | 575 | |
1bc74519 RS |
576 | emailAddress = Email Address |
577 | emailAddress_max = 40 | |
5e76807b DSH |
578 | |
579 | [ req_attributes ] | |
1bc74519 RS |
580 | challengePassword = A challenge password |
581 | challengePassword_min = 4 | |
582 | challengePassword_max = 20 | |
5e76807b DSH |
583 | |
584 | [ v3_ca ] | |
585 | ||
586 | subjectKeyIdentifier=hash | |
587 | authorityKeyIdentifier=keyid:always,issuer:always | |
a7be5759 | 588 | basicConstraints = critical, CA:true |
aba3e65f | 589 | |
6e6bc352 DSH |
590 | Sample configuration containing all field values: |
591 | ||
592 | ||
1bc74519 | 593 | RANDFILE = $ENV::HOME/.rnd |
6e6bc352 DSH |
594 | |
595 | [ req ] | |
1bc74519 RS |
596 | default_bits = 2048 |
597 | default_keyfile = keyfile.pem | |
598 | distinguished_name = req_distinguished_name | |
599 | attributes = req_attributes | |
600 | prompt = no | |
601 | output_password = mypass | |
6e6bc352 DSH |
602 | |
603 | [ req_distinguished_name ] | |
1bc74519 RS |
604 | C = GB |
605 | ST = Test State or Province | |
606 | L = Test Locality | |
607 | O = Organization Name | |
608 | OU = Organizational Unit Name | |
609 | CN = Common Name | |
610 | emailAddress = test@email.address | |
6e6bc352 DSH |
611 | |
612 | [ req_attributes ] | |
1bc74519 | 613 | challengePassword = A challenge password |
6e6bc352 | 614 | |
bfa470a4 RL |
615 | Example of giving the most common attributes (subject and extensions) |
616 | on the command line: | |
617 | ||
618 | openssl req -new -subj "/C=GB/CN=foo" \ | |
619 | -addext "subjectAltName = DNS:foo.co.uk" \ | |
620 | -addext "certificatePolicies = 1.2.3.4" \ | |
621 | -newkey rsa:2048 -keyout key.pem -out req.pem | |
622 | ||
6e6bc352 | 623 | |
aba3e65f DSH |
624 | =head1 NOTES |
625 | ||
aba3e65f DSH |
626 | The certificate requests generated by B<Xenroll> with MSIE have extensions |
627 | added. It includes the B<keyUsage> extension which determines the type of | |
628 | key (signature only or general purpose) and any additional OIDs entered | |
777182a0 | 629 | by the script in an B<extendedKeyUsage> extension. |
aba3e65f DSH |
630 | |
631 | =head1 DIAGNOSTICS | |
632 | ||
633 | The following messages are frequently asked about: | |
634 | ||
1bc74519 RS |
635 | Using configuration from /some/path/openssl.cnf |
636 | Unable to load config info | |
aba3e65f | 637 | |
b2bdfb63 | 638 | This is followed some time later by: |
aba3e65f | 639 | |
1bc74519 RS |
640 | unable to find 'distinguished_name' in config |
641 | problems making Certificate Request | |
aba3e65f DSH |
642 | |
643 | The first error message is the clue: it can't find the configuration | |
644 | file! Certain operations (like examining a certificate request) don't | |
645 | need a configuration file so its use isn't enforced. Generation of | |
19d2bb57 | 646 | certificates or requests however does need a configuration file. This |
aba3e65f DSH |
647 | could be regarded as a bug. |
648 | ||
649 | Another puzzling message is this: | |
650 | ||
651 | Attributes: | |
652 | a0:00 | |
653 | ||
654 | this is displayed when no attributes are present and the request includes | |
655 | the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 | |
656 | 0x00). If you just see: | |
657 | ||
658 | Attributes: | |
659 | ||
660 | then the B<SET OF> is missing and the encoding is technically invalid (but | |
661 | it is tolerated). See the description of the command line option B<-asn1-kludge> | |
662 | for more information. | |
663 | ||
aba3e65f DSH |
664 | =head1 BUGS |
665 | ||
19d2bb57 UM |
666 | OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively |
667 | treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. | |
aba3e65f DSH |
668 | This can cause problems if you need characters that aren't available in |
669 | PrintableStrings and you don't want to or can't use BMPStrings. | |
670 | ||
671 | As a consequence of the T61String handling the only correct way to represent | |
672 | accented characters in OpenSSL is to use a BMPString: unfortunately Netscape | |
673 | currently chokes on these. If you have to use accented characters with Netscape | |
674 | and MSIE then you currently need to use the invalid T61String form. | |
675 | ||
6e6bc352 DSH |
676 | The current prompting is not very friendly. It doesn't allow you to confirm what |
677 | you've just entered. Other things like extensions in certificate requests are | |
678 | statically defined in the configuration file. Some of these: like an email | |
679 | address in subjectAltName should be input by the user. | |
aba3e65f DSH |
680 | |
681 | =head1 SEE ALSO | |
682 | ||
b6b66573 DMSP |
683 | L<openssl(1)>, |
684 | L<openssl-x509(1)>, | |
685 | L<openssl-ca(1)>, | |
686 | L<openssl-genrsa(1)>, | |
687 | L<openssl-gendsa(1)>, | |
688 | L<config(5)>, | |
1bc74519 | 689 | L<x509v3_config(5)> |
aba3e65f | 690 | |
e2f92610 RS |
691 | =head1 COPYRIGHT |
692 | ||
d7b2124a | 693 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 694 | |
449040b4 | 695 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
696 | this file except in compliance with the License. You can obtain a copy |
697 | in the file LICENSE in the source distribution or at | |
698 | L<https://www.openssl.org/source/license.html>. | |
699 | ||
700 | =cut |