2
0

req.pod 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678
  1. =pod
  2. =head1 NAME
  3. req - PKCS#10 certificate request and certificate generating utility.
  4. =head1 SYNOPSIS
  5. B<openssl> B<req>
  6. [B<-inform PEM|DER>]
  7. [B<-outform PEM|DER>]
  8. [B<-in filename>]
  9. [B<-passin arg>]
  10. [B<-out filename>]
  11. [B<-passout arg>]
  12. [B<-text>]
  13. [B<-pubkey>]
  14. [B<-noout>]
  15. [B<-verify>]
  16. [B<-modulus>]
  17. [B<-new>]
  18. [B<-rand file(s)>]
  19. [B<-newkey rsa:bits>]
  20. [B<-newkey alg:file>]
  21. [B<-nodes>]
  22. [B<-key filename>]
  23. [B<-keyform PEM|DER>]
  24. [B<-keyout filename>]
  25. [B<-keygen_engine id>]
  26. [B<-[digest]>]
  27. [B<-config filename>]
  28. [B<-subj arg>]
  29. [B<-multivalue-rdn>]
  30. [B<-x509>]
  31. [B<-days n>]
  32. [B<-set_serial n>]
  33. [B<-asn1-kludge>]
  34. [B<-no-asn1-kludge>]
  35. [B<-newhdr>]
  36. [B<-extensions section>]
  37. [B<-reqexts section>]
  38. [B<-utf8>]
  39. [B<-nameopt>]
  40. [B<-reqopt>]
  41. [B<-subject>]
  42. [B<-subj arg>]
  43. [B<-batch>]
  44. [B<-verbose>]
  45. [B<-engine id>]
  46. =head1 DESCRIPTION
  47. The B<req> command primarily creates and processes certificate requests
  48. in PKCS#10 format. It can additionally create self signed certificates
  49. for use as root CAs for example.
  50. =head1 COMMAND OPTIONS
  51. =over 4
  52. =item B<-inform DER|PEM>
  53. This specifies the input format. The B<DER> option uses an ASN1 DER encoded
  54. form compatible with the PKCS#10. The B<PEM> form is the default format: it
  55. consists of the B<DER> format base64 encoded with additional header and
  56. footer lines.
  57. =item B<-outform DER|PEM>
  58. This specifies the output format, the options have the same meaning as the
  59. B<-inform> option.
  60. =item B<-in filename>
  61. This specifies the input filename to read a request from or standard input
  62. if this option is not specified. A request is only read if the creation
  63. options (B<-new> and B<-newkey>) are not specified.
  64. =item B<-passin arg>
  65. the input file password source. For more information about the format of B<arg>
  66. see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
  67. =item B<-out filename>
  68. This specifies the output filename to write to or standard output by
  69. default.
  70. =item B<-passout arg>
  71. the output file password source. For more information about the format of B<arg>
  72. see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
  73. =item B<-text>
  74. prints out the certificate request in text form.
  75. =item B<-subject>
  76. prints out the request subject (or certificate subject if B<-x509> is
  77. specified)
  78. =item B<-pubkey>
  79. outputs the public key.
  80. =item B<-noout>
  81. this option prevents output of the encoded version of the request.
  82. =item B<-modulus>
  83. this option prints out the value of the modulus of the public key
  84. contained in the request.
  85. =item B<-verify>
  86. verifies the signature on the request.
  87. =item B<-new>
  88. this option generates a new certificate request. It will prompt
  89. the user for the relevant field values. The actual fields
  90. prompted for and their maximum and minimum sizes are specified
  91. in the configuration file and any requested extensions.
  92. If the B<-key> option is not used it will generate a new RSA private
  93. key using information specified in the configuration file.
  94. =item B<-subj arg>
  95. Replaces subject field of input request with specified data and outputs
  96. modified request. The arg must be formatted as
  97. I</type0=value0/type1=value1/type2=...>,
  98. characters may be escaped by \ (backslash), no spaces are skipped.
  99. =item B<-rand file(s)>
  100. a file or files containing random data used to seed the random number
  101. generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
  102. Multiple files can be specified separated by a OS-dependent character.
  103. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
  104. all others.
  105. =item B<-newkey arg>
  106. this option creates a new certificate request and a new private
  107. key. The argument takes one of several forms. B<rsa:nbits>, where
  108. B<nbits> is the number of bits, generates an RSA key B<nbits>
  109. in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
  110. the default key size, specified in the configuration file is used.
  111. All other algorithms support the B<-newkey alg:file> form, where file may be
  112. an algorithm parameter file, created by the B<genpkey -genparam> command
  113. or and X.509 certificate for a key with approriate algorithm.
  114. B<param:file> generates a key using the parameter file or certificate B<file>,
  115. the algorithm is determined by the parameters. B<algname:file> use algorithm
  116. B<algname> and parameter file B<file>: the two algorithms must match or an
  117. error occurs. B<algname> just uses algorithm B<algname>, and parameters,
  118. if neccessary should be specified via B<-pkeyopt> parameter.
  119. B<dsa:filename> generates a DSA key using the parameters
  120. in the file B<filename>. B<ec:filename> generates EC key (usable both with
  121. ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
  122. 34.10-2001 key (requires B<ccgost> engine configured in the configuration
  123. file). If just B<gost2001> is specified a parameter set should be
  124. specified by B<-pkeyopt paramset:X>
  125. =item B<-pkeyopt opt:value>
  126. set the public key algorithm option B<opt> to B<value>. The precise set of
  127. options supported depends on the public key algorithm used and its
  128. implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
  129. for more details.
  130. =item B<-key filename>
  131. This specifies the file to read the private key from. It also
  132. accepts PKCS#8 format private keys for PEM format files.
  133. =item B<-keyform PEM|DER>
  134. the format of the private key file specified in the B<-key>
  135. argument. PEM is the default.
  136. =item B<-keyout filename>
  137. this gives the filename to write the newly created private key to.
  138. If this option is not specified then the filename present in the
  139. configuration file is used.
  140. =item B<-nodes>
  141. if this option is specified then if a private key is created it
  142. will not be encrypted.
  143. =item B<-[digest]>
  144. this specifies the message digest to sign the request with (such as
  145. B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
  146. the configuration file.
  147. Some public key algorithms may override this choice. For instance, DSA
  148. signatures always use SHA1, GOST R 34.10 signatures always use
  149. GOST R 34.11-94 (B<-md_gost94>).
  150. =item B<-config filename>
  151. this allows an alternative configuration file to be specified,
  152. this overrides the compile time filename or any specified in
  153. the B<OPENSSL_CONF> environment variable.
  154. =item B<-subj arg>
  155. sets subject name for new request or supersedes the subject name
  156. when processing a request.
  157. The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
  158. characters may be escaped by \ (backslash), no spaces are skipped.
  159. =item B<-multivalue-rdn>
  160. this option causes the -subj argument to be interpreted with full
  161. support for multivalued RDNs. Example:
  162. I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
  163. If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
  164. =item B<-x509>
  165. this option outputs a self signed certificate instead of a certificate
  166. request. This is typically used to generate a test certificate or
  167. a self signed root CA. The extensions added to the certificate
  168. (if any) are specified in the configuration file. Unless specified
  169. using the B<set_serial> option B<0> will be used for the serial
  170. number.
  171. =item B<-days n>
  172. when the B<-x509> option is being used this specifies the number of
  173. days to certify the certificate for. The default is 30 days.
  174. =item B<-set_serial n>
  175. serial number to use when outputting a self signed certificate. This
  176. may be specified as a decimal value or a hex value if preceded by B<0x>.
  177. It is possible to use negative serial numbers but this is not recommended.
  178. =item B<-extensions section>
  179. =item B<-reqexts section>
  180. these options specify alternative sections to include certificate
  181. extensions (if the B<-x509> option is present) or certificate
  182. request extensions. This allows several different sections to
  183. be used in the same configuration file to specify requests for
  184. a variety of purposes.
  185. =item B<-utf8>
  186. this option causes field values to be interpreted as UTF8 strings, by
  187. default they are interpreted as ASCII. This means that the field
  188. values, whether prompted from a terminal or obtained from a
  189. configuration file, must be valid UTF8 strings.
  190. =item B<-nameopt option>
  191. option which determines how the subject or issuer names are displayed. The
  192. B<option> argument can be a single option or multiple options separated by
  193. commas. Alternatively the B<-nameopt> switch may be used more than once to
  194. set multiple options. See the L<x509(1)|x509(1)> manual page for details.
  195. =item B<-reqopt>
  196. customise the output format used with B<-text>. The B<option> argument can be
  197. a single option or multiple options separated by commas.
  198. See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
  199. command.
  200. =item B<-asn1-kludge>
  201. by default the B<req> command outputs certificate requests containing
  202. no attributes in the correct PKCS#10 format. However certain CAs will only
  203. accept requests containing no attributes in an invalid form: this
  204. option produces this invalid format.
  205. More precisely the B<Attributes> in a PKCS#10 certificate request
  206. are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
  207. if no attributes are present then they should be encoded as an
  208. empty B<SET OF>. The invalid form does not include the empty
  209. B<SET OF> whereas the correct form does.
  210. It should be noted that very few CAs still require the use of this option.
  211. =item B<-no-asn1-kludge>
  212. Reverses effect of B<-asn1-kludge>
  213. =item B<-newhdr>
  214. Adds the word B<NEW> to the PEM file header and footer lines on the outputed
  215. request. Some software (Netscape certificate server) and some CAs need this.
  216. =item B<-batch>
  217. non-interactive mode.
  218. =item B<-verbose>
  219. print extra details about the operations being performed.
  220. =item B<-engine id>
  221. specifying an engine (by its unique B<id> string) will cause B<req>
  222. to attempt to obtain a functional reference to the specified engine,
  223. thus initialising it if needed. The engine will then be set as the default
  224. for all available algorithms.
  225. =item B<-keygen_engine id>
  226. specifies an engine (by its unique B<id> string) which would be used
  227. for key generation operations.
  228. =back
  229. =head1 CONFIGURATION FILE FORMAT
  230. The configuration options are specified in the B<req> section of
  231. the configuration file. As with all configuration files if no
  232. value is specified in the specific section (i.e. B<req>) then
  233. the initial unnamed or B<default> section is searched too.
  234. The options available are described in detail below.
  235. =over 4
  236. =item B<input_password output_password>
  237. The passwords for the input private key file (if present) and
  238. the output private key file (if one will be created). The
  239. command line options B<passin> and B<passout> override the
  240. configuration file values.
  241. =item B<default_bits>
  242. This specifies the default key size in bits. If not specified then
  243. 512 is used. It is used if the B<-new> option is used. It can be
  244. overridden by using the B<-newkey> option.
  245. =item B<default_keyfile>
  246. This is the default filename to write a private key to. If not
  247. specified the key is written to standard output. This can be
  248. overridden by the B<-keyout> option.
  249. =item B<oid_file>
  250. This specifies a file containing additional B<OBJECT IDENTIFIERS>.
  251. Each line of the file should consist of the numerical form of the
  252. object identifier followed by white space then the short name followed
  253. by white space and finally the long name.
  254. =item B<oid_section>
  255. This specifies a section in the configuration file containing extra
  256. object identifiers. Each line should consist of the short name of the
  257. object identifier followed by B<=> and the numerical form. The short
  258. and long names are the same when this option is used.
  259. =item B<RANDFILE>
  260. This specifies a filename in which random number seed information is
  261. placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
  262. It is used for private key generation.
  263. =item B<encrypt_key>
  264. If this is set to B<no> then if a private key is generated it is
  265. B<not> encrypted. This is equivalent to the B<-nodes> command line
  266. option. For compatibility B<encrypt_rsa_key> is an equivalent option.
  267. =item B<default_md>
  268. This option specifies the digest algorithm to use. Possible values
  269. include B<md5 sha1 mdc2>. If not present then MD5 is used. This
  270. option can be overridden on the command line.
  271. =item B<string_mask>
  272. This option masks out the use of certain string types in certain
  273. fields. Most users will not need to change this option.
  274. It can be set to several values B<default> which is also the default
  275. option uses PrintableStrings, T61Strings and BMPStrings if the
  276. B<pkix> value is used then only PrintableStrings and BMPStrings will
  277. be used. This follows the PKIX recommendation in RFC2459. If the
  278. B<utf8only> option is used then only UTF8Strings will be used: this
  279. is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
  280. option just uses PrintableStrings and T61Strings: certain software has
  281. problems with BMPStrings and UTF8Strings: in particular Netscape.
  282. =item B<req_extensions>
  283. this specifies the configuration file section containing a list of
  284. extensions to add to the certificate request. It can be overridden
  285. by the B<-reqexts> command line switch. See the
  286. L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
  287. extension section format.
  288. =item B<x509_extensions>
  289. this specifies the configuration file section containing a list of
  290. extensions to add to certificate generated when the B<-x509> switch
  291. is used. It can be overridden by the B<-extensions> command line switch.
  292. =item B<prompt>
  293. if set to the value B<no> this disables prompting of certificate fields
  294. and just takes values from the config file directly. It also changes the
  295. expected format of the B<distinguished_name> and B<attributes> sections.
  296. =item B<utf8>
  297. if set to the value B<yes> then field values to be interpreted as UTF8
  298. strings, by default they are interpreted as ASCII. This means that
  299. the field values, whether prompted from a terminal or obtained from a
  300. configuration file, must be valid UTF8 strings.
  301. =item B<attributes>
  302. this specifies the section containing any request attributes: its format
  303. is the same as B<distinguished_name>. Typically these may contain the
  304. challengePassword or unstructuredName types. They are currently ignored
  305. by OpenSSL's request signing utilities but some CAs might want them.
  306. =item B<distinguished_name>
  307. This specifies the section containing the distinguished name fields to
  308. prompt for when generating a certificate or certificate request. The format
  309. is described in the next section.
  310. =back
  311. =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
  312. There are two separate formats for the distinguished name and attribute
  313. sections. If the B<prompt> option is set to B<no> then these sections
  314. just consist of field names and values: for example,
  315. CN=My Name
  316. OU=My Organization
  317. emailAddress=someone@somewhere.org
  318. This allows external programs (e.g. GUI based) to generate a template file
  319. with all the field names and values and just pass it to B<req>. An example
  320. of this kind of configuration file is contained in the B<EXAMPLES> section.
  321. Alternatively if the B<prompt> option is absent or not set to B<no> then the
  322. file contains field prompting information. It consists of lines of the form:
  323. fieldName="prompt"
  324. fieldName_default="default field value"
  325. fieldName_min= 2
  326. fieldName_max= 4
  327. "fieldName" is the field name being used, for example commonName (or CN).
  328. The "prompt" string is used to ask the user to enter the relevant
  329. details. If the user enters nothing then the default value is used if no
  330. default value is present then the field is omitted. A field can
  331. still be omitted if a default value is present if the user just
  332. enters the '.' character.
  333. The number of characters entered must be between the fieldName_min and
  334. fieldName_max limits: there may be additional restrictions based
  335. on the field being used (for example countryName can only ever be
  336. two characters long and must fit in a PrintableString).
  337. Some fields (such as organizationName) can be used more than once
  338. in a DN. This presents a problem because configuration files will
  339. not recognize the same name occurring twice. To avoid this problem
  340. if the fieldName contains some characters followed by a full stop
  341. they will be ignored. So for example a second organizationName can
  342. be input by calling it "1.organizationName".
  343. The actual permitted field names are any object identifier short or
  344. long names. These are compiled into OpenSSL and include the usual
  345. values such as commonName, countryName, localityName, organizationName,
  346. organizationUnitName, stateOrProvinceName. Additionally emailAddress
  347. is include as well as name, surname, givenName initials and dnQualifier.
  348. Additional object identifiers can be defined with the B<oid_file> or
  349. B<oid_section> options in the configuration file. Any additional fields
  350. will be treated as though they were a DirectoryString.
  351. =head1 EXAMPLES
  352. Examine and verify certificate request:
  353. openssl req -in req.pem -text -verify -noout
  354. Create a private key and then generate a certificate request from it:
  355. openssl genrsa -out key.pem 1024
  356. openssl req -new -key key.pem -out req.pem
  357. The same but just using req:
  358. openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
  359. Generate a self signed root certificate:
  360. openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
  361. Example of a file pointed to by the B<oid_file> option:
  362. 1.2.3.4 shortName A longer Name
  363. 1.2.3.6 otherName Other longer Name
  364. Example of a section pointed to by B<oid_section> making use of variable
  365. expansion:
  366. testoid1=1.2.3.5
  367. testoid2=${testoid1}.6
  368. Sample configuration file prompting for field values:
  369. [ req ]
  370. default_bits = 1024
  371. default_keyfile = privkey.pem
  372. distinguished_name = req_distinguished_name
  373. attributes = req_attributes
  374. x509_extensions = v3_ca
  375. dirstring_type = nobmp
  376. [ req_distinguished_name ]
  377. countryName = Country Name (2 letter code)
  378. countryName_default = AU
  379. countryName_min = 2
  380. countryName_max = 2
  381. localityName = Locality Name (eg, city)
  382. organizationalUnitName = Organizational Unit Name (eg, section)
  383. commonName = Common Name (eg, YOUR name)
  384. commonName_max = 64
  385. emailAddress = Email Address
  386. emailAddress_max = 40
  387. [ req_attributes ]
  388. challengePassword = A challenge password
  389. challengePassword_min = 4
  390. challengePassword_max = 20
  391. [ v3_ca ]
  392. subjectKeyIdentifier=hash
  393. authorityKeyIdentifier=keyid:always,issuer:always
  394. basicConstraints = CA:true
  395. Sample configuration containing all field values:
  396. RANDFILE = $ENV::HOME/.rnd
  397. [ req ]
  398. default_bits = 1024
  399. default_keyfile = keyfile.pem
  400. distinguished_name = req_distinguished_name
  401. attributes = req_attributes
  402. prompt = no
  403. output_password = mypass
  404. [ req_distinguished_name ]
  405. C = GB
  406. ST = Test State or Province
  407. L = Test Locality
  408. O = Organization Name
  409. OU = Organizational Unit Name
  410. CN = Common Name
  411. emailAddress = test@email.address
  412. [ req_attributes ]
  413. challengePassword = A challenge password
  414. =head1 NOTES
  415. The header and footer lines in the B<PEM> format are normally:
  416. -----BEGIN CERTIFICATE REQUEST-----
  417. -----END CERTIFICATE REQUEST-----
  418. some software (some versions of Netscape certificate server) instead needs:
  419. -----BEGIN NEW CERTIFICATE REQUEST-----
  420. -----END NEW CERTIFICATE REQUEST-----
  421. which is produced with the B<-newhdr> option but is otherwise compatible.
  422. Either form is accepted transparently on input.
  423. The certificate requests generated by B<Xenroll> with MSIE have extensions
  424. added. It includes the B<keyUsage> extension which determines the type of
  425. key (signature only or general purpose) and any additional OIDs entered
  426. by the script in an extendedKeyUsage extension.
  427. =head1 DIAGNOSTICS
  428. The following messages are frequently asked about:
  429. Using configuration from /some/path/openssl.cnf
  430. Unable to load config info
  431. This is followed some time later by...
  432. unable to find 'distinguished_name' in config
  433. problems making Certificate Request
  434. The first error message is the clue: it can't find the configuration
  435. file! Certain operations (like examining a certificate request) don't
  436. need a configuration file so its use isn't enforced. Generation of
  437. certificates or requests however does need a configuration file. This
  438. could be regarded as a bug.
  439. Another puzzling message is this:
  440. Attributes:
  441. a0:00
  442. this is displayed when no attributes are present and the request includes
  443. the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
  444. 0x00). If you just see:
  445. Attributes:
  446. then the B<SET OF> is missing and the encoding is technically invalid (but
  447. it is tolerated). See the description of the command line option B<-asn1-kludge>
  448. for more information.
  449. =head1 ENVIRONMENT VARIABLES
  450. The variable B<OPENSSL_CONF> if defined allows an alternative configuration
  451. file location to be specified, it will be overridden by the B<-config> command
  452. line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
  453. environment variable serves the same purpose but its use is discouraged.
  454. =head1 BUGS
  455. OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
  456. treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
  457. This can cause problems if you need characters that aren't available in
  458. PrintableStrings and you don't want to or can't use BMPStrings.
  459. As a consequence of the T61String handling the only correct way to represent
  460. accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
  461. currently chokes on these. If you have to use accented characters with Netscape
  462. and MSIE then you currently need to use the invalid T61String form.
  463. The current prompting is not very friendly. It doesn't allow you to confirm what
  464. you've just entered. Other things like extensions in certificate requests are
  465. statically defined in the configuration file. Some of these: like an email
  466. address in subjectAltName should be input by the user.
  467. =head1 SEE ALSO
  468. L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
  469. L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>,
  470. L<x509v3_config(5)|x509v3_config(5)>
  471. =cut