Debian Codegraph @

upstream/debian-unstable/man1/openssl-req.1ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-REQ 1SSL"
58 .TH OPENSSL-REQ 1SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-req \- PKCS#10 certificate request and certificate generating command
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBopenssl\fR \fBreq\fR
68 [\fB\-help\fR]
69 [\fB\-cipher\fR]
70 [\fB\-inform\fR \fBDER\fR|\fBPEM\fR]
71 [\fB\-outform\fR \fBDER\fR|\fBPEM\fR]
72 [\fB\-in\fR \fIfilename\fR]
73 [\fB\-passin\fR \fIarg\fR]
74 [\fB\-out\fR \fIfilename\fR]
75 [\fB\-passout\fR \fIarg\fR]
76 [\fB\-text\fR]
77 [\fB\-pubkey\fR]
78 [\fB\-noout\fR]
79 [\fB\-verify\fR]
80 [\fB\-modulus\fR]
81 [\fB\-new\fR]
82 [\fB\-newkey\fR \fIarg\fR]
83 [\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR]
84 [\fB\-noenc\fR]
85 [\fB\-nodes\fR]
86 [\fB\-key\fR \fIfilename\fR|\fIuri\fR]
87 [\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR]
88 [\fB\-keyout\fR \fIfilename\fR]
89 [\fB\-keygen_engine\fR \fIid\fR]
90 [\fB\-\fR\f(BIdigest\fR]
91 [\fB\-config\fR \fIfilename\fR]
92 [\fB\-section\fR \fIname\fR]
93 [\fB\-x509\fR]
94 [\fB\-x509v1\fR]
95 [\fB\-CA\fR \fIfilename\fR|\fIuri\fR]
96 [\fB\-CAkey\fR \fIfilename\fR|\fIuri\fR]
97 [\fB\-not_before\fR \fIdate\fR]
98 [\fB\-not_after\fR \fIdate\fR]
99 [\fB\-days\fR \fIn\fR]
100 [\fB\-set_serial\fR \fIn\fR]
101 [\fB\-newhdr\fR]
102 [\fB\-copy_extensions\fR \fIarg\fR]
103 [\fB\-extensions\fR \fIsection\fR]
104 [\fB\-reqexts\fR \fIsection\fR]
105 [\fB\-addext\fR \fIext\fR]
106 [\fB\-precert\fR]
107 [\fB\-utf8\fR]
108 [\fB\-reqopt\fR]
109 [\fB\-subject\fR]
110 [\fB\-subj\fR \fIarg\fR]
111 [\fB\-multivalue\-rdn\fR]
112 [\fB\-sigopt\fR \fInm\fR:\fIv\fR]
113 [\fB\-vfyopt\fR \fInm\fR:\fIv\fR]
114 [\fB\-batch\fR]
115 [\fB\-verbose\fR]
116 [\fB\-quiet\fR]
117 [\fB\-nameopt\fR \fIoption\fR]
118 [\fB\-rand\fR \fIfiles\fR]
119 [\fB\-writerand\fR \fIfile\fR]
120 [\fB\-engine\fR \fIid\fR]
121 [\fB\-provider\fR \fIname\fR]
122 [\fB\-provider\-path\fR \fIpath\fR]
123 [\fB\-provparam\fR \fI[name:]key=value\fR]
124 [\fB\-propquery\fR \fIpropq\fR]
125 .SH DESCRIPTION
126 .IX Header "DESCRIPTION"
127 This command primarily creates and processes certificate requests (CSRs)
128 in PKCS#10 format. It can additionally create self-signed certificates
129 for use as root CAs for example.
130 .SH OPTIONS
131 .IX Header "OPTIONS"
132 .IP \fB\-help\fR 4
133 .IX Item "-help"
134 Print out a usage message.
135 .IP "\fB\-inform\fR \fBDER\fR|\fBPEM\fR" 4
136 .IX Item "-inform DER|PEM"
137 The CSR input file format to use; by default PEM is tried first.
138 See \fBopenssl\-format\-options\fR\|(1) for details.
139 .IP "\fB\-outform\fR \fBDER\fR|\fBPEM\fR" 4
140 .IX Item "-outform DER|PEM"
141 The output format; unspecified by default.
142 See \fBopenssl\-format\-options\fR\|(1) for details.
143 .Sp
144 The data is a PKCS#10 object.
145 .IP "\fB\-cipher\fR \fIname\fR" 4
146 .IX Item "-cipher name"
147 Specify the cipher to be used for encrypting the private key.
148 If no cipher is specified, AES\-256\-CBC will be used by default.
149 You can override this by providing any valid OpenSSL cipher name.
150 .IP "\fB\-in\fR \fIfilename\fR" 4
151 .IX Item "-in filename"
152 This specifies the input filename to read a request from.
153 This defaults to standard input unless \fB\-x509\fR or \fB\-CA\fR is specified.
154 A request is only read if the creation options
155 (\fB\-new\fR or \fB\-newkey\fR or \fB\-precert\fR) are not specified.
156 .IP "\fB\-sigopt\fR \fInm\fR:\fIv\fR" 4
157 .IX Item "-sigopt nm:v"
158 Pass options to the signature algorithm during sign operations.
159 Names and values of these options are algorithm-specific.
160 .IP "\fB\-vfyopt\fR \fInm\fR:\fIv\fR" 4
161 .IX Item "-vfyopt nm:v"
162 Pass options to the signature algorithm during verify operations.
163 Names and values of these options are algorithm-specific.
164 .IP "\fB\-passin\fR \fIarg\fR" 4
165 .IX Item "-passin arg"
166 The password source for private key and certificate input.
167 For more information about the format of \fBarg\fR
168 see \fBopenssl\-passphrase\-options\fR\|(1).
169 .IP "\fB\-passout\fR \fIarg\fR" 4
170 .IX Item "-passout arg"
171 The password source for the output file.
172 For more information about the format of \fBarg\fR
173 see \fBopenssl\-passphrase\-options\fR\|(1).
174 .IP "\fB\-out\fR \fIfilename\fR" 4
175 .IX Item "-out filename"
176 This specifies the output filename to write to or standard output by default.
177 .IP \fB\-text\fR 4
178 .IX Item "-text"
179 Prints out the certificate request in text form.
180 .IP \fB\-subject\fR 4
181 .IX Item "-subject"
182 Prints out the certificate request subject
183 (or certificate subject if \fB\-x509\fR is in use).
184 .IP \fB\-pubkey\fR 4
185 .IX Item "-pubkey"
186 Prints out the public key.
187 .IP \fB\-noout\fR 4
188 .IX Item "-noout"
189 This option prevents output of the encoded version of the certificate request.
190 .IP \fB\-modulus\fR 4
191 .IX Item "-modulus"
192 Prints out the value of the modulus of the public key contained in the request.
193 .IP \fB\-verify\fR 4
194 .IX Item "-verify"
195 Verifies the self-signature on the request. If the verification fails,
196 the program will immediately exit, i.e. further option processing
197 (e.g. \fB\-text\fR) is skipped.
198 .IP \fB\-new\fR 4
199 .IX Item "-new"
200 This option generates a new certificate request. It will prompt
201 the user for the relevant field values. The actual fields
202 prompted for and their maximum and minimum sizes are specified
203 in the configuration file and any requested extensions.
204 .Sp
205 If the \fB\-key\fR option is not given it will generate a new private key
206 using information specified in the configuration file or given with
207 the \fB\-newkey\fR and \fB\-pkeyopt\fR options,
208 else by default an RSA key with 2048 bits length.
209 .IP "\fB\-newkey\fR \fIarg\fR" 4
210 .IX Item "-newkey arg"
211 This option is used to generate a new private key unless \fB\-key\fR is given.
212 It is subsequently used as if it was given using the \fB\-key\fR option.
213 .Sp
214 This option implies the \fB\-new\fR flag to create a new certificate request
215 or a new certificate in case \fB\-x509\fR is used.
216 .Sp
217 The argument takes one of several forms.
218 .Sp
219 [\fBrsa:\fR]\fInbits\fR generates an RSA key \fInbits\fR in size.
220 If \fInbits\fR is omitted, i.e., \fB\-newkey\fR \fBrsa\fR is specified,
221 the default key size specified in the configuration file
222 with the \fBdefault_bits\fR option is used if present, else 2048.
223 .Sp
224 All other algorithms support the \fB\-newkey\fR \fIalgname\fR:\fIfile\fR form, where
225 \&\fIfile\fR is an algorithm parameter file, created with \f(CW\*(C`openssl genpkey \-genparam\*(C'\fR
226 or an X.509 certificate for a key with appropriate algorithm.
227 .Sp
228 \&\fBparam:\fR\fIfile\fR generates a key using the parameter file or certificate
229 \&\fIfile\fR, the algorithm is determined by the parameters.
230 .Sp
231 \&\fIalgname\fR[:\fIfile\fR] generates a key using the given algorithm \fIalgname\fR.
232 If a parameter file \fIfile\fR is given then the parameters specified there
233 are used, where the algorithm parameters must match \fIalgname\fR.
234 If algorithm parameters are not given,
235 any necessary parameters should be specified via the \fB\-pkeyopt\fR option.
236 .Sp
237 \&\fBdsa:\fR\fIfilename\fR generates a DSA key using the parameters
238 in the file \fIfilename\fR. \fBec:\fR\fIfilename\fR generates EC key (usable both with
239 ECDSA or ECDH algorithms), \fBgost2001:\fR\fIfilename\fR generates GOST R
240 34.10\-2001 key (requires \fBgost\fR engine configured in the configuration
241 file). If just \fBgost2001\fR is specified a parameter set should be
242 specified by \fB\-pkeyopt\fR \fIparamset:X\fR
243 .IP "\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR" 4
244 .IX Item "-pkeyopt opt:value"
245 Set the public key algorithm option \fIopt\fR to \fIvalue\fR. The precise set of
246 options supported depends on the public key algorithm used and its
247 implementation.
248 See "KEY GENERATION OPTIONS" in \fBopenssl\-genpkey\fR\|(1) for more details.
249 .IP "\fB\-key\fR \fIfilename\fR|\fIuri\fR" 4
250 .IX Item "-key filename|uri"
251 This option provides the private key for signing a new certificate or
252 certificate request.
253 Unless \fB\-in\fR is given, the corresponding public key is placed in
254 the new certificate or certificate request, resulting in a self-signature.
255 .Sp
256 For certificate signing this option is overridden by the \fB\-CA\fR option.
257 .Sp
258 This option also accepts PKCS#8 format private keys for PEM format files.
259 .IP "\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4
260 .IX Item "-keyform DER|PEM|P12|ENGINE"
261 The format of the private key; unspecified by default.
262 See \fBopenssl\-format\-options\fR\|(1) for details.
263 .IP "\fB\-keyout\fR \fIfilename\fR" 4
264 .IX Item "-keyout filename"
265 This gives the filename to write any private key to that has been newly created
266 or read from \fB\-key\fR. If neither the \fB\-keyout\fR option nor the \fB\-key\fR option
267 are given then the filename specified in the configuration file with the
268 \&\fBdefault_keyfile\fR option is used, if present. Thus, if you want to write the
269 private key and the \fB\-key\fR option is provided, you should provide the
270 \&\fB\-keyout\fR option explicitly. If a new key is generated and no filename is
271 specified the key is written to standard output.
272 .IP \fB\-noenc\fR 4
273 .IX Item "-noenc"
274 If this option is specified then if a private key is created it
275 will not be encrypted.
276 .IP \fB\-nodes\fR 4
277 .IX Item "-nodes"
278 This option is deprecated since OpenSSL 3.0; use \fB\-noenc\fR instead.
279 .IP \fB\-\fR\f(BIdigest\fR 4
280 .IX Item "-digest"
281 This specifies the message digest to sign the request.
282 Any digest supported by the OpenSSL \fBdgst\fR command can be used.
283 This overrides the digest algorithm specified in
284 the configuration file.
285 .Sp
286 Some public key algorithms may override this choice. For instance, DSA
287 signatures always use SHA1, GOST R 34.10 signatures always use
288 GOST R 34.11\-94 (\fB\-md_gost94\fR), Ed25519 and Ed448 never use any digest.
289 .IP "\fB\-config\fR \fIfilename\fR" 4
290 .IX Item "-config filename"
291 This allows an alternative configuration file to be specified.
292 Optional; for a description of the default value,
293 see "COMMAND SUMMARY" in \fBopenssl\fR\|(1).
294 .IP "\fB\-section\fR \fIname\fR" 4
295 .IX Item "-section name"
296 Specifies the name of the section to use; the default is \fBreq\fR.
297 .IP "\fB\-subj\fR \fIarg\fR" 4
298 .IX Item "-subj arg"
299 Sets subject name for new request or supersedes the subject name
300 when processing a certificate request.
301 .Sp
302 The arg must be formatted as \f(CW\*(C`/type0=value0/type1=value1/type2=...\*(C'\fR.
303 Special characters may be escaped by \f(CW\*(C`\e\*(C'\fR (backslash), whitespace is retained.
304 Empty values are permitted, but the corresponding type will not be included
305 in the request.
306 Giving a single \f(CW\*(C`/\*(C'\fR will lead to an empty sequence of RDNs (a NULL-DN).
307 Multi-valued RDNs can be formed by placing a \f(CW\*(C`+\*(C'\fR character instead of a \f(CW\*(C`/\*(C'\fR
308 between the AttributeValueAssertions (AVAs) that specify the members of the set.
309 Example:
310 .Sp
311 \&\f(CW\*(C`/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\*(C'\fR
312 .IP \fB\-multivalue\-rdn\fR 4
313 .IX Item "-multivalue-rdn"
314 This option has been deprecated and has no effect.
315 .IP \fB\-x509\fR 4
316 .IX Item "-x509"
317 This option outputs a certificate instead of a certificate request.
318 This is typically used to generate test certificates.
319 It is implied by the \fB\-CA\fR option.
320 .Sp
321 This option implies the \fB\-new\fR flag if \fB\-in\fR is not given.
322 .Sp
323 If an existing request is specified with the \fB\-in\fR option, it is converted
324 to a certificate; otherwise a request is created from scratch.
325 .Sp
326 Unless specified using the \fB\-set_serial\fR option,
327 a large random number will be used for the serial number.
328 .Sp
329 Unless the \fB\-copy_extensions\fR option is used,
330 X.509 extensions are not copied from any provided request input file.
331 .Sp
332 X.509 extensions to be added can be specified in the configuration file,
333 possibly using the \fB\-config\fR and \fB\-extensions\fR options,
334 and/or using the \fB\-addext\fR option.
335 .Sp
336 Unless \fB\-x509v1\fR is given, generated certificates bear X.509 version 3.
337 Unless specified otherwise,
338 key identifier extensions are included as described in \fBx509v3_config\fR\|(5).
339 .IP \fB\-x509v1\fR 4
340 .IX Item "-x509v1"
341 Request generation of certificates with X.509 version 1.
342 This implies \fB\-x509\fR.
343 If X.509 extensions are given, anyway X.509 version 3 is set.
344 .IP "\fB\-CA\fR \fIfilename\fR|\fIuri\fR" 4
345 .IX Item "-CA filename|uri"
346 Specifies the "CA" certificate to be used for signing a new certificate
347 and implies use of \fB\-x509\fR.
348 When present, this behaves like a "micro CA" as follows:
349 The subject name of the "CA" certificate is placed as issuer name in the new
350 certificate, which is then signed using the "CA" key given as specified below.
351 .IP "\fB\-CAkey\fR \fIfilename\fR|\fIuri\fR" 4
352 .IX Item "-CAkey filename|uri"
353 Sets the "CA" private key to sign a certificate with.
354 The private key must match the public key of the certificate given with \fB\-CA\fR.
355 If this option is not provided then the key must be present in the \fB\-CA\fR input.
356 .IP "\fB\-not_before\fR \fIdate\fR" 4
357 .IX Item "-not_before date"
358 When \fB\-x509\fR is in use this allows the start date to be explicitly set,
359 otherwise it is ignored. The format of \fIdate\fR is YYMMDDHHMMSSZ (the
360 same as an ASN1 UTCTime structure), or YYYYMMDDHHMMSSZ (the same as an
361 ASN1 GeneralizedTime structure). In both formats, seconds SS and
362 timezone Z must be present.
363 Alternatively, you can also use "today".
364 .IP "\fB\-not_after\fR \fIdate\fR" 4
365 .IX Item "-not_after date"
366 When \fB\-x509\fR is in use this allows the expiry date to be explicitly
367 set, otherwise it is ignored. The format of \fIdate\fR is YYMMDDHHMMSSZ
368 (the same as an ASN1 UTCTime structure), or YYYYMMDDHHMMSSZ (the same as
369 an ASN1 GeneralizedTime structure). In both formats, seconds SS and
370 timezone Z must be present.
371 Alternatively, you can also use "today".
372 .Sp
373 This overrides the \fB\-days\fR option.
374 .IP "\fB\-days\fR \fIn\fR" 4
375 .IX Item "-days n"
376 When \fB\-x509\fR is in use this specifies the number of days from today to
377 certify the certificate for, otherwise it is ignored. \fIn\fR should
378 be a positive integer. The default is 30 days.
379 .Sp
380 Regardless of the option \fB\-not_before\fR, the days are always counted from
381 today.
382 When used together with the option \fB\-not_after\fR, the explicit expiry
383 date takes precedence.
384 .IP "\fB\-set_serial\fR \fIn\fR" 4
385 .IX Item "-set_serial n"
386 Serial number to use when outputting a self-signed certificate.
387 This may be specified as a decimal value or a hex value if preceded by \f(CW\*(C`0x\*(C'\fR.
388 If not given, a large random number will be used.
389 .IP "\fB\-copy_extensions\fR \fIarg\fR" 4
390 .IX Item "-copy_extensions arg"
391 Determines how X.509 extensions in certificate requests should be handled
392 when \fB\-x509\fR is in use.
393 If \fIarg\fR is \fBnone\fR or this option is not present then extensions are ignored.
394 If \fIarg\fR is \fBcopy\fR or \fBcopyall\fR then
395 all extensions in the request are copied to the certificate.
396 .Sp
397 The main use of this option is to allow a certificate request to supply
398 values for certain extensions such as subjectAltName.
399 .IP "\fB\-extensions\fR \fIsection\fR, \fB\-reqexts\fR \fIsection\fR" 4
400 .IX Item "-extensions section, -reqexts section"
401 Can be used to override the name of the configuration file section
402 from which X.509 extensions are included
403 in the certificate (when \fB\-x509\fR is in use) or certificate request.
404 This allows several different sections to be used in the same configuration
405 file to specify requests for a variety of purposes.
406 .IP "\fB\-addext\fR \fIext\fR" 4
407 .IX Item "-addext ext"
408 Add a specific extension to the certificate (if \fB\-x509\fR is in use)
409 or certificate request. The argument must have the form of
410 a \f(CW\*(C`key=value\*(C'\fR pair as it would appear in a config file.
411 .Sp
412 If an extension is added using this option that has the same OID as one
413 defined in the extension section of the config file, it overrides that one.
414 .Sp
415 This option can be given multiple times.
416 Doing so, the same key must not be given more than once.
417 .IP \fB\-precert\fR 4
418 .IX Item "-precert"
419 A poison extension will be added to the certificate, making it a
420 "pre-certificate" (see RFC6962). This can be submitted to Certificate
421 Transparency logs in order to obtain signed certificate timestamps (SCTs).
422 These SCTs can then be embedded into the pre-certificate as an extension, before
423 removing the poison and signing the certificate.
424 .Sp
425 This implies the \fB\-new\fR flag.
426 .IP \fB\-utf8\fR 4
427 .IX Item "-utf8"
428 This option causes field values to be interpreted as UTF8 strings, by
429 default they are interpreted as ASCII. This means that the field
430 values, whether prompted from a terminal or obtained from a
431 configuration file, must be valid UTF8 strings.
432 .IP "\fB\-reqopt\fR \fIoption\fR" 4
433 .IX Item "-reqopt option"
434 Customise the printing format used with \fB\-text\fR. The \fIoption\fR argument can be
435 a single option or multiple options separated by commas.
436 .Sp
437 See discussion of the \fB\-certopt\fR parameter in the \fBopenssl\-x509\fR\|(1)
438 command.
439 .IP \fB\-newhdr\fR 4
440 .IX Item "-newhdr"
441 Adds the word \fBNEW\fR to the PEM file header and footer lines on the outputted
442 request. Some software (Netscape certificate server) and some CAs need this.
443 .IP \fB\-batch\fR 4
444 .IX Item "-batch"
445 Non-interactive mode.
446 .IP \fB\-verbose\fR 4
447 .IX Item "-verbose"
448 Print extra details about the operations being performed.
449 .IP \fB\-quiet\fR 4
450 .IX Item "-quiet"
451 Print fewer details about the operations being performed, which may be
452 handy during batch scripts or pipelines (specifically "progress dots"
453 during key generation are suppressed).
454 .IP "\fB\-keygen_engine\fR \fIid\fR" 4
455 .IX Item "-keygen_engine id"
456 Specifies an engine (by its unique \fIid\fR string) which would be used
457 for key generation operations.
458 .IP "\fB\-nameopt\fR \fIoption\fR" 4
459 .IX Item "-nameopt option"
460 This specifies how the subject or issuer names are displayed.
461 See \fBopenssl\-namedisplay\-options\fR\|(1) for details.
462 .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
463 .IX Item "-rand files, -writerand file"
464 See "Random State Options" in \fBopenssl\fR\|(1) for details.
465 .IP "\fB\-engine\fR \fIid\fR" 4
466 .IX Item "-engine id"
467 See "Engine Options" in \fBopenssl\fR\|(1).
468 This option is deprecated.
469 .IP "\fB\-provider\fR \fIname\fR" 4
470 .IX Item "-provider name"
471 .PD 0
472 .IP "\fB\-provider\-path\fR \fIpath\fR" 4
473 .IX Item "-provider-path path"
474 .IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4
475 .IX Item "-provparam [name:]key=value"
476 .IP "\fB\-propquery\fR \fIpropq\fR" 4
477 .IX Item "-propquery propq"
478 .PD
479 See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7).
480 .SH "CONFIGURATION FILE FORMAT"
481 .IX Header "CONFIGURATION FILE FORMAT"
482 The configuration options are specified in the \fBreq\fR section of
483 the configuration file. An alternate name be specified by using the
484 \&\fB\-section\fR option.
485 As with all configuration files, if no
486 value is specified in the specific section then
487 the initial unnamed or \fBdefault\fR section is searched too.
488 .PP
489 The options available are described in detail below.
490 .IP "\fBinput_password\fR, \fBoutput_password\fR" 4
491 .IX Item "input_password, output_password"
492 The passwords for the input private key file (if present) and
493 the output private key file (if one will be created). The
494 command line options \fBpassin\fR and \fBpassout\fR override the
495 configuration file values.
496 .IP \fBdefault_bits\fR 4
497 .IX Item "default_bits"
498 Specifies the default key size in bits.
499 .Sp
500 This option is used in conjunction with the \fB\-new\fR option to generate
501 a new key. It can be overridden by specifying an explicit key size in
502 the \fB\-newkey\fR option. The smallest accepted key size is 512 bits. If
503 no key size is specified then 2048 bits is used.
504 .IP \fBdefault_keyfile\fR 4
505 .IX Item "default_keyfile"
506 This is the default filename to write a private key to. If not
507 specified the key is written to standard output. This can be
508 overridden by the \fB\-keyout\fR option.
509 .IP \fBoid_file\fR 4
510 .IX Item "oid_file"
511 This specifies a file containing additional \fBOBJECT IDENTIFIERS\fR.
512 Each line of the file should consist of the numerical form of the
513 object identifier followed by whitespace then the short name followed
514 by whitespace and finally the long name.
515 .IP \fBoid_section\fR 4
516 .IX Item "oid_section"
517 This specifies a section in the configuration file containing extra
518 object identifiers. Each line should consist of the short name of the
519 object identifier followed by \fB=\fR and the numerical form. The short
520 and long names are the same when this option is used.
521 .IP \fBRANDFILE\fR 4
522 .IX Item "RANDFILE"
523 At startup the specified file is loaded into the random number generator,
524 and at exit 256 bytes will be written to it.
525 It is used for private key generation.
526 .IP \fBencrypt_key\fR 4
527 .IX Item "encrypt_key"
528 If this is set to \fBno\fR then if a private key is generated it is
529 \&\fBnot\fR encrypted. This is equivalent to the \fB\-noenc\fR command line
530 option. For compatibility \fBencrypt_rsa_key\fR is an equivalent option.
531 .IP \fBdefault_md\fR 4
532 .IX Item "default_md"
533 This option specifies the digest algorithm to use. Any digest supported by the
534 OpenSSL \fBdgst\fR command can be used. This option can be overridden on the
535 command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
536 any digest that has been set.
537 .IP \fBstring_mask\fR 4
538 .IX Item "string_mask"
539 This option masks out the use of certain string types in certain
540 fields. Most users will not need to change this option. It can be set to
541 several values:
542 .RS 4
543 .IP "\fButf8only\fR \- only UTF8Strings are used (this is the default value)" 4
544 .IX Item "utf8only - only UTF8Strings are used (this is the default value)"
545 .PD 0
546 .IP "\fBpkix\fR \- any string type except T61Strings" 4
547 .IX Item "pkix - any string type except T61Strings"
548 .IP "\fBnombstr\fR \- any string type except BMPStrings and UTF8Strings" 4
549 .IX Item "nombstr - any string type except BMPStrings and UTF8Strings"
550 .IP "\fBdefault\fR \- any kind of string type" 4
551 .IX Item "default - any kind of string type"
552 .RE
553 .RS 4
554 .PD
555 .Sp
556 Note that \fButf8only\fR is the PKIX recommendation in RFC 5280, and the
557 default \fBstring_mask\fR; \fBdefault\fR is not the default option. The \fBnombstr\fR
558 value is a workaround for some software that has problems with variable-sized
559 BMPStrings and UTF8Strings.
560 .RE
561 .IP \fBreq_extensions\fR 4
562 .IX Item "req_extensions"
563 This specifies the configuration file section containing a list of
564 extensions to add to the certificate request. It can be overridden
565 by the \fB\-reqexts\fR (or \fB\-extensions\fR) command line switch. See the
566 \&\fBx509v3_config\fR\|(5) manual page for details of the
567 extension section format.
568 .IP \fBx509_extensions\fR 4
569 .IX Item "x509_extensions"
570 This specifies the configuration file section containing a list of
571 extensions to add to certificate generated when \fB\-x509\fR is in use.
572 It can be overridden by the \fB\-extensions\fR command line switch.
573 .IP \fBprompt\fR 4
574 .IX Item "prompt"
575 If set to the value \fBno\fR this disables prompting of certificate fields
576 and just takes values from the config file directly. It also changes the
577 expected format of the \fBdistinguished_name\fR and \fBattributes\fR sections.
578 .IP \fButf8\fR 4
579 .IX Item "utf8"
580 If set to the value \fByes\fR then field values to be interpreted as UTF8
581 strings, by default they are interpreted as ASCII. This means that
582 the field values, whether prompted from a terminal or obtained from a
583 configuration file, must be valid UTF8 strings.
584 .IP \fBattributes\fR 4
585 .IX Item "attributes"
586 This specifies the section containing any request attributes: its format
587 is the same as \fBdistinguished_name\fR. Typically these may contain the
588 challengePassword or unstructuredName types. They are currently ignored
589 by OpenSSL's request signing utilities but some CAs might want them.
590 .IP \fBdistinguished_name\fR 4
591 .IX Item "distinguished_name"
592 This specifies the section containing the distinguished name fields to
593 prompt for when generating a certificate or certificate request. The format
594 is described in the next section.
595 .SH "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT"
596 .IX Header "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT"
597 There are two separate formats for the distinguished name and attribute
598 sections. If the \fBprompt\fR option is set to \fBno\fR then these sections
599 just consist of field names and values: for example,
600 .PP
601 .Vb 3
602 \& CN=My Name
603 \& OU=My Organization
604 \& [email protected]
605 .Ve
606 .PP
607 This allows external programs (e.g. GUI based) to generate a template file with
608 all the field names and values and just pass it to this command. An example
609 of this kind of configuration file is contained in the \fBEXAMPLES\fR section.
610 .PP
611 Alternatively if the \fBprompt\fR option is absent or not set to \fBno\fR then the
612 file contains field prompting information. It consists of lines of the form:
613 .PP
614 .Vb 4
615 \& fieldName="prompt"
616 \& fieldName_default="default field value"
617 \& fieldName_min= 2
618 \& fieldName_max= 4
619 .Ve
620 .PP
621 "fieldName" is the field name being used, for example commonName (or CN).
622 The "prompt" string is used to ask the user to enter the relevant
623 details. If the user enters nothing then the default value is used if no
624 default value is present then the field is omitted. A field can
625 still be omitted if a default value is present if the user just
626 enters the '.' character.
627 .PP
628 The number of characters entered must be between the fieldName_min and
629 fieldName_max limits: there may be additional restrictions based
630 on the field being used (for example countryName can only ever be
631 two characters long and must fit in a PrintableString).
632 .PP
633 Some fields (such as organizationName) can be used more than once
634 in a DN. This presents a problem because configuration files will
635 not recognize the same name occurring twice. To avoid this problem
636 if the fieldName contains some characters followed by a full stop
637 they will be ignored. So for example a second organizationName can
638 be input by calling it "1.organizationName".
639 .PP
640 The actual permitted field names are any object identifier short or
641 long names. These are compiled into OpenSSL and include the usual
642 values such as commonName, countryName, localityName, organizationName,
643 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
644 is included as well as name, surname, givenName, initials, and dnQualifier.
645 .PP
646 Additional object identifiers can be defined with the \fBoid_file\fR or
647 \&\fBoid_section\fR options in the configuration file. Any additional fields
648 will be treated as though they were a DirectoryString.
649 .SH EXAMPLES
650 .IX Header "EXAMPLES"
651 Examine and verify certificate request:
652 .PP
653 .Vb 1
654 \& openssl req \-in req.pem \-text \-verify \-noout
655 .Ve
656 .PP
657 Specify the cipher to be used for encrypting the private key:
658 .PP
659 .Vb 1
660 \& openssl req \-newkey rsa:2048 \-keyout privatekey.pem \-out request.csr \-cipher aes\-256\-cbc
661 .Ve
662 .PP
663 Create a private key and then generate a certificate request from it:
664 .PP
665 .Vb 2
666 \& openssl genrsa \-out key.pem 2048
667 \& openssl req \-new \-key key.pem \-out req.pem
668 .Ve
669 .PP
670 The same but just using req:
671 .PP
672 .Vb 1
673 \& openssl req \-newkey rsa:2048 \-keyout key.pem \-out req.pem
674 .Ve
675 .PP
676 Generate a self-signed root certificate:
677 .PP
678 .Vb 1
679 \& openssl req \-x509 \-newkey rsa:2048 \-keyout key.pem \-out req.pem
680 .Ve
681 .PP
682 Create an SM2 private key and then generate a certificate request from it:
683 .PP
684 .Vb 2
685 \& openssl ecparam \-genkey \-name SM2 \-out sm2.key
686 \& openssl req \-new \-key sm2.key \-out sm2.csr \-sm3 \-sigopt "distid:1234567812345678"
687 .Ve
688 .PP
689 Examine and verify an SM2 certificate request:
690 .PP
691 .Vb 1
692 \& openssl req \-verify \-in sm2.csr \-sm3 \-vfyopt "distid:1234567812345678"
693 .Ve
694 .PP
695 Example of a file pointed to by the \fBoid_file\fR option:
696 .PP
697 .Vb 2
698 \& 1.2.3.4 shortName A longer Name
699 \& 1.2.3.6 otherName Other longer Name
700 .Ve
701 .PP
702 Example of a section pointed to by \fBoid_section\fR making use of variable
703 expansion:
704 .PP
705 .Vb 2
706 \& testoid1=1.2.3.5
707 \& testoid2=${testoid1}.6
708 .Ve
709 .PP
710 Sample configuration file prompting for field values:
711 .PP
712 .Vb 6
713 \& [ req ]
714 \& default_bits = 2048
715 \& default_keyfile = privkey.pem
716 \& distinguished_name = req_distinguished_name
717 \& attributes = req_attributes
718 \& req_extensions = v3_ca
719 \&
720 \& dirstring_type = nombstr
721 \&
722 \& [ req_distinguished_name ]
723 \& countryName = Country Name (2 letter code)
724 \& countryName_default = AU
725 \& countryName_min = 2
726 \& countryName_max = 2
727 \&
728 \& localityName = Locality Name (eg, city)
729 \&
730 \& organizationalUnitName = Organizational Unit Name (eg, section)
731 \&
732 \& commonName = Common Name (eg, YOUR name)
733 \& commonName_max = 64
734 \&
735 \& emailAddress = Email Address
736 \& emailAddress_max = 40
737 \&
738 \& [ req_attributes ]
739 \& challengePassword = A challenge password
740 \& challengePassword_min = 4
741 \& challengePassword_max = 20
742 \&
743 \& [ v3_ca ]
744 \&
745 \& subjectKeyIdentifier=hash
746 \& authorityKeyIdentifier=keyid:always,issuer:always
747 \& basicConstraints = critical, CA:true
748 .Ve
749 .PP
750 Sample configuration containing all field values:
751 .PP
752 .Vb 7
753 \& [ req ]
754 \& default_bits = 2048
755 \& default_keyfile = keyfile.pem
756 \& distinguished_name = req_distinguished_name
757 \& attributes = req_attributes
758 \& prompt = no
759 \& output_password = mypass
760 \&
761 \& [ req_distinguished_name ]
762 \& C = GB
763 \& ST = Test State or Province
764 \& L = Test Locality
765 \& O = Organization Name
766 \& OU = Organizational Unit Name
767 \& CN = Common Name
768 \& emailAddress = [email protected]
769 \&
770 \& [ req_attributes ]
771 \& challengePassword = A challenge password
772 .Ve
773 .PP
774 Example of giving the most common attributes (subject and extensions)
775 on the command line:
776 .PP
777 .Vb 4
778 \& openssl req \-new \-subj "/C=GB/CN=foo" \e
779 \& \-addext "subjectAltName = DNS:foo.co.uk" \e
780 \& \-addext "certificatePolicies = 1.2.3.4" \e
781 \& \-newkey rsa:2048 \-keyout key.pem \-out req.pem
782 .Ve
783 .SH NOTES
784 .IX Header "NOTES"
785 The certificate requests generated by \fBXenroll\fR with MSIE have extensions
786 added. It includes the \fBkeyUsage\fR extension which determines the type of
787 key (signature only or general purpose) and any additional OIDs entered
788 by the script in an \fBextendedKeyUsage\fR extension.
789 .SH DIAGNOSTICS
790 .IX Header "DIAGNOSTICS"
791 The following messages are frequently asked about:
792 .PP
793 .Vb 2
794 \& Using configuration from /some/path/openssl.cnf
795 \& Unable to load config info
796 .Ve
797 .PP
798 This is followed some time later by:
799 .PP
800 .Vb 2
801 \& unable to find \*(Aqdistinguished_name\*(Aq in config
802 \& problems making Certificate Request
803 .Ve
804 .PP
805 The first error message is the clue: it can't find the configuration
806 file! Certain operations (like examining a certificate request) don't
807 need a configuration file so its use isn't enforced. Generation of
808 certificates or requests however does need a configuration file. This
809 could be regarded as a bug.
810 .PP
811 Another puzzling message is this:
812 .PP
813 .Vb 2
814 \& Attributes:
815 \& a0:00
816 .Ve
817 .PP
818 this is displayed when no attributes are present and the request includes
819 the correct empty \fBSET OF\fR structure (the DER encoding of which is 0xa0
820 0x00). If you just see:
821 .PP
822 .Vb 1
823 \& Attributes:
824 .Ve
825 .PP
826 then the \fBSET OF\fR is missing and the encoding is technically invalid (but
827 it is tolerated). See the description of the command line option \fB\-asn1\-kludge\fR
828 for more information.
829 .SH BUGS
830 .IX Header "BUGS"
831 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
832 treats them as ISO\-8859\-1 (Latin 1), Netscape and MSIE have similar behaviour.
833 This can cause problems if you need characters that aren't available in
834 PrintableStrings and you don't want to or can't use BMPStrings.
835 .PP
836 As a consequence of the T61String handling the only correct way to represent
837 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
838 currently chokes on these. If you have to use accented characters with Netscape
839 and MSIE then you currently need to use the invalid T61String form.
840 .PP
841 The current prompting is not very friendly. It doesn't allow you to confirm what
842 you've just entered. Other things like extensions in certificate requests are
843 statically defined in the configuration file. Some of these: like an email
844 address in subjectAltName should be input by the user.
845 .SH "SEE ALSO"
846 .IX Header "SEE ALSO"
847 \&\fBopenssl\fR\|(1),
848 \&\fBopenssl\-x509\fR\|(1),
849 \&\fBopenssl\-ca\fR\|(1),
850 \&\fBopenssl\-genrsa\fR\|(1),
851 \&\fBopenssl\-gendsa\fR\|(1),
852 \&\fBconfig\fR\|(5),
853 \&\fBx509v3_config\fR\|(5)
854 .SH HISTORY
855 .IX Header "HISTORY"
856 The default encryption cipher was changed from 3DES to AES\-256 in OpenSSL 3.5.
857 .PP
858 The \fB\-section\fR option was added in OpenSSL 3.0.0.
859 .PP
860 The \fB\-multivalue\-rdn\fR option has become obsolete in OpenSSL 3.0.0 and
861 has no effect.
862 .PP
863 The \fB\-engine\fR option was deprecated in OpenSSL 3.0.
864 The <\-nodes> option was deprecated in OpenSSL 3.0, too; use \fB\-noenc\fR instead.
865 .PP
866 The \fB\-reqexts\fR option has been made an alias of \fB\-extensions\fR in OpenSSL 3.2.
867 .PP
868 Since OpenSSL 3.2,
869 generated certificates bear X.509 version 3 unless \fB\-x509v1\fR is given,
870 and key identifier extensions are included by default.
871 .PP
872 Since OpenSSL 3.3, the \fB\-verify\fR option will exit with 1 on failure.
873 .SH COPYRIGHT
874 .IX Header "COPYRIGHT"
875 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
876 .PP
877 Licensed under the Apache License 2.0 (the "License"). You may not use
878 this file except in compliance with the License. You can obtain a copy
879 in the file LICENSE in the source distribution or at
880 <https://www.openssl.org/source/license.html>.