diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/req.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/req.1 | 768 |
1 files changed, 768 insertions, 0 deletions
diff --git a/secure/usr.bin/openssl/man/req.1 b/secure/usr.bin/openssl/man/req.1 new file mode 100644 index 0000000..d173049 --- /dev/null +++ b/secure/usr.bin/openssl/man/req.1 @@ -0,0 +1,768 @@ +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "REQ 1" +.TH REQ 1 "2015-12-03" "1.0.2e" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +req \- PKCS#10 certificate request and certificate generating utility. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBreq\fR +[\fB\-inform PEM|DER\fR] +[\fB\-outform PEM|DER\fR] +[\fB\-in filename\fR] +[\fB\-passin arg\fR] +[\fB\-out filename\fR] +[\fB\-passout arg\fR] +[\fB\-text\fR] +[\fB\-pubkey\fR] +[\fB\-noout\fR] +[\fB\-verify\fR] +[\fB\-modulus\fR] +[\fB\-new\fR] +[\fB\-rand file(s)\fR] +[\fB\-newkey rsa:bits\fR] +[\fB\-newkey alg:file\fR] +[\fB\-nodes\fR] +[\fB\-key filename\fR] +[\fB\-keyform PEM|DER\fR] +[\fB\-keyout filename\fR] +[\fB\-keygen_engine id\fR] +[\fB\-[digest]\fR] +[\fB\-config filename\fR] +[\fB\-multivalue\-rdn\fR] +[\fB\-x509\fR] +[\fB\-days n\fR] +[\fB\-set_serial n\fR] +[\fB\-asn1\-kludge\fR] +[\fB\-no\-asn1\-kludge\fR] +[\fB\-newhdr\fR] +[\fB\-extensions section\fR] +[\fB\-reqexts section\fR] +[\fB\-utf8\fR] +[\fB\-nameopt\fR] +[\fB\-reqopt\fR] +[\fB\-subject\fR] +[\fB\-subj arg\fR] +[\fB\-batch\fR] +[\fB\-verbose\fR] +[\fB\-engine id\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBreq\fR command primarily creates and processes certificate requests +in PKCS#10 format. It can additionally create self signed certificates +for use as root CAs for example. +.SH "COMMAND OPTIONS" +.IX Header "COMMAND OPTIONS" +.IP "\fB\-inform DER|PEM\fR" 4 +.IX Item "-inform DER|PEM" +This specifies the input format. The \fB\s-1DER\s0\fR option uses an \s-1ASN1 DER\s0 encoded +form compatible with the PKCS#10. The \fB\s-1PEM\s0\fR form is the default format: it +consists of the \fB\s-1DER\s0\fR format base64 encoded with additional header and +footer lines. +.IP "\fB\-outform DER|PEM\fR" 4 +.IX Item "-outform DER|PEM" +This specifies the output format, the options have the same meaning as the +\&\fB\-inform\fR option. +.IP "\fB\-in filename\fR" 4 +.IX Item "-in filename" +This specifies the input filename to read a request from or standard input +if this option is not specified. A request is only read if the creation +options (\fB\-new\fR and \fB\-newkey\fR) are not specified. +.IP "\fB\-passin arg\fR" 4 +.IX Item "-passin arg" +the input file password source. For more information about the format of \fBarg\fR +see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1). +.IP "\fB\-out filename\fR" 4 +.IX Item "-out filename" +This specifies the output filename to write to or standard output by +default. +.IP "\fB\-passout arg\fR" 4 +.IX Item "-passout arg" +the output file password source. For more information about the format of \fBarg\fR +see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1). +.IP "\fB\-text\fR" 4 +.IX Item "-text" +prints out the certificate request in text form. +.IP "\fB\-subject\fR" 4 +.IX Item "-subject" +prints out the request subject (or certificate subject if \fB\-x509\fR is +specified) +.IP "\fB\-pubkey\fR" 4 +.IX Item "-pubkey" +outputs the public key. +.IP "\fB\-noout\fR" 4 +.IX Item "-noout" +this option prevents output of the encoded version of the request. +.IP "\fB\-modulus\fR" 4 +.IX Item "-modulus" +this option prints out the value of the modulus of the public key +contained in the request. +.IP "\fB\-verify\fR" 4 +.IX Item "-verify" +verifies the signature on the request. +.IP "\fB\-new\fR" 4 +.IX Item "-new" +this option generates a new certificate request. It will prompt +the user for the relevant field values. The actual fields +prompted for and their maximum and minimum sizes are specified +in the configuration file and any requested extensions. +.Sp +If the \fB\-key\fR option is not used it will generate a new \s-1RSA\s0 private +key using information specified in the configuration file. +.IP "\fB\-subj arg\fR" 4 +.IX Item "-subj arg" +Replaces subject field of input request with specified data and outputs +modified request. The arg must be formatted as +\&\fI/type0=value0/type1=value1/type2=...\fR, +characters may be escaped by \e (backslash), no spaces are skipped. +.IP "\fB\-rand file(s)\fR" 4 +.IX Item "-rand file(s)" +a file or files containing random data used to seed the random number +generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)). +Multiple files can be specified separated by a OS-dependent character. +The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for +all others. +.IP "\fB\-newkey arg\fR" 4 +.IX Item "-newkey arg" +this option creates a new certificate request and a new private +key. The argument takes one of several forms. \fBrsa:nbits\fR, where +\&\fBnbits\fR is the number of bits, generates an \s-1RSA\s0 key \fBnbits\fR +in size. If \fBnbits\fR is omitted, i.e. \fB\-newkey rsa\fR specified, +the default key size, specified in the configuration file is used. +.Sp +All other algorithms support the \fB\-newkey alg:file\fR form, where file may be +an algorithm parameter file, created by the \fBgenpkey \-genparam\fR command +or and X.509 certificate for a key with approriate algorithm. +.Sp +\&\fBparam:file\fR generates a key using the parameter file or certificate \fBfile\fR, +the algorithm is determined by the parameters. \fBalgname:file\fR use algorithm +\&\fBalgname\fR and parameter file \fBfile\fR: the two algorithms must match or an +error occurs. \fBalgname\fR just uses algorithm \fBalgname\fR, and parameters, +if neccessary should be specified via \fB\-pkeyopt\fR parameter. +.Sp +\&\fBdsa:filename\fR generates a \s-1DSA\s0 key using the parameters +in the file \fBfilename\fR. \fBec:filename\fR generates \s-1EC\s0 key (usable both with +\&\s-1ECDSA\s0 or \s-1ECDH\s0 algorithms), \fBgost2001:filename\fR generates \s-1GOST R +34.10\-2001\s0 key (requires \fBccgost\fR engine configured in the configuration +file). If just \fBgost2001\fR is specified a parameter set should be +specified by \fB\-pkeyopt paramset:X\fR +.IP "\fB\-pkeyopt opt:value\fR" 4 +.IX Item "-pkeyopt opt:value" +set the public key algorithm option \fBopt\fR to \fBvalue\fR. The precise set of +options supported depends on the public key algorithm used and its +implementation. See \fB\s-1KEY GENERATION OPTIONS\s0\fR in the \fBgenpkey\fR manual page +for more details. +.IP "\fB\-key filename\fR" 4 +.IX Item "-key filename" +This specifies the file to read the private key from. It also +accepts PKCS#8 format private keys for \s-1PEM\s0 format files. +.IP "\fB\-keyform PEM|DER\fR" 4 +.IX Item "-keyform PEM|DER" +the format of the private key file specified in the \fB\-key\fR +argument. \s-1PEM\s0 is the default. +.IP "\fB\-keyout filename\fR" 4 +.IX Item "-keyout filename" +this gives the filename to write the newly created private key to. +If this option is not specified then the filename present in the +configuration file is used. +.IP "\fB\-nodes\fR" 4 +.IX Item "-nodes" +if this option is specified then if a private key is created it +will not be encrypted. +.IP "\fB\-[digest]\fR" 4 +.IX Item "-[digest]" +this specifies the message digest to sign the request with (such as +\&\fB\-md5\fR, \fB\-sha1\fR). This overrides the digest algorithm specified in +the configuration file. +.Sp +Some public key algorithms may override this choice. For instance, \s-1DSA\s0 +signatures always use \s-1SHA1, GOST R 34.10\s0 signatures always use +\&\s-1GOST R 34.11\-94 \s0(\fB\-md_gost94\fR). +.IP "\fB\-config filename\fR" 4 +.IX Item "-config filename" +this allows an alternative configuration file to be specified, +this overrides the compile time filename or any specified in +the \fB\s-1OPENSSL_CONF\s0\fR environment variable. +.IP "\fB\-subj arg\fR" 4 +.IX Item "-subj arg" +sets subject name for new request or supersedes the subject name +when processing a request. +The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR, +characters may be escaped by \e (backslash), no spaces are skipped. +.IP "\fB\-multivalue\-rdn\fR" 4 +.IX Item "-multivalue-rdn" +this option causes the \-subj argument to be interpreted with full +support for multivalued RDNs. Example: +.Sp +\&\fI/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\fR +.Sp +If \-multi\-rdn is not used then the \s-1UID\s0 value is \fI123456+CN=John Doe\fR. +.IP "\fB\-x509\fR" 4 +.IX Item "-x509" +this option outputs a self signed certificate instead of a certificate +request. This is typically used to generate a test certificate or +a self signed root \s-1CA.\s0 The extensions added to the certificate +(if any) are specified in the configuration file. Unless specified +using the \fBset_serial\fR option, a large random number will be used for +the serial number. +.IP "\fB\-days n\fR" 4 +.IX Item "-days n" +when the \fB\-x509\fR option is being used this specifies the number of +days to certify the certificate for. The default is 30 days. +.IP "\fB\-set_serial n\fR" 4 +.IX Item "-set_serial n" +serial number to use when outputting a self signed certificate. This +may be specified as a decimal value or a hex value if preceded by \fB0x\fR. +It is possible to use negative serial numbers but this is not recommended. +.IP "\fB\-extensions section\fR" 4 +.IX Item "-extensions section" +.PD 0 +.IP "\fB\-reqexts section\fR" 4 +.IX Item "-reqexts section" +.PD +these options specify alternative sections to include certificate +extensions (if the \fB\-x509\fR option is present) or certificate +request extensions. This allows several different sections to +be used in the same configuration file to specify requests for +a variety of purposes. +.IP "\fB\-utf8\fR" 4 +.IX Item "-utf8" +this option causes field values to be interpreted as \s-1UTF8\s0 strings, by +default they are interpreted as \s-1ASCII.\s0 This means that the field +values, whether prompted from a terminal or obtained from a +configuration file, must be valid \s-1UTF8\s0 strings. +.IP "\fB\-nameopt option\fR" 4 +.IX Item "-nameopt option" +option which determines how the subject or issuer names are displayed. The +\&\fBoption\fR argument can be a single option or multiple options separated by +commas. Alternatively the \fB\-nameopt\fR switch may be used more than once to +set multiple options. See the \fIx509\fR\|(1) manual page for details. +.IP "\fB\-reqopt\fR" 4 +.IX Item "-reqopt" +customise the output format used with \fB\-text\fR. The \fBoption\fR argument can be +a single option or multiple options separated by commas. +.Sp +See discission of the \fB\-certopt\fR parameter in the \fBx509\fR +command. +.IP "\fB\-asn1\-kludge\fR" 4 +.IX Item "-asn1-kludge" +by default the \fBreq\fR command outputs certificate requests containing +no attributes in the correct PKCS#10 format. However certain CAs will only +accept requests containing no attributes in an invalid form: this +option produces this invalid format. +.Sp +More precisely the \fBAttributes\fR in a PKCS#10 certificate request +are defined as a \fB\s-1SET OF\s0 Attribute\fR. They are \fBnot \s-1OPTIONAL\s0\fR so +if no attributes are present then they should be encoded as an +empty \fB\s-1SET OF\s0\fR. The invalid form does not include the empty +\&\fB\s-1SET OF\s0\fR whereas the correct form does. +.Sp +It should be noted that very few CAs still require the use of this option. +.IP "\fB\-no\-asn1\-kludge\fR" 4 +.IX Item "-no-asn1-kludge" +Reverses effect of \fB\-asn1\-kludge\fR +.IP "\fB\-newhdr\fR" 4 +.IX Item "-newhdr" +Adds the word \fB\s-1NEW\s0\fR to the \s-1PEM\s0 file header and footer lines on the outputted +request. Some software (Netscape certificate server) and some CAs need this. +.IP "\fB\-batch\fR" 4 +.IX Item "-batch" +non-interactive mode. +.IP "\fB\-verbose\fR" 4 +.IX Item "-verbose" +print extra details about the operations being performed. +.IP "\fB\-engine id\fR" 4 +.IX Item "-engine id" +specifying an engine (by its unique \fBid\fR string) will cause \fBreq\fR +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. +.IP "\fB\-keygen_engine id\fR" 4 +.IX Item "-keygen_engine id" +specifies an engine (by its unique \fBid\fR string) which would be used +for key generation operations. +.SH "CONFIGURATION FILE FORMAT" +.IX Header "CONFIGURATION FILE FORMAT" +The configuration options are specified in the \fBreq\fR section of +the configuration file. As with all configuration files if no +value is specified in the specific section (i.e. \fBreq\fR) then +the initial unnamed or \fBdefault\fR section is searched too. +.PP +The options available are described in detail below. +.IP "\fBinput_password output_password\fR" 4 +.IX Item "input_password output_password" +The passwords for the input private key file (if present) and +the output private key file (if one will be created). The +command line options \fBpassin\fR and \fBpassout\fR override the +configuration file values. +.IP "\fBdefault_bits\fR" 4 +.IX Item "default_bits" +This specifies the default key size in bits. If not specified then +512 is used. It is used if the \fB\-new\fR option is used. It can be +overridden by using the \fB\-newkey\fR option. +.IP "\fBdefault_keyfile\fR" 4 +.IX Item "default_keyfile" +This is the default filename to write a private key to. If not +specified the key is written to standard output. This can be +overridden by the \fB\-keyout\fR option. +.IP "\fBoid_file\fR" 4 +.IX Item "oid_file" +This specifies a file containing additional \fB\s-1OBJECT IDENTIFIERS\s0\fR. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. +.IP "\fBoid_section\fR" 4 +.IX Item "oid_section" +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by \fB=\fR and the numerical form. The short +and long names are the same when this option is used. +.IP "\fB\s-1RANDFILE\s0\fR" 4 +.IX Item "RANDFILE" +This specifies a filename in which random number seed information is +placed and read from, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)). +It is used for private key generation. +.IP "\fBencrypt_key\fR" 4 +.IX Item "encrypt_key" +If this is set to \fBno\fR then if a private key is generated it is +\&\fBnot\fR encrypted. This is equivalent to the \fB\-nodes\fR command line +option. For compatibility \fBencrypt_rsa_key\fR is an equivalent option. +.IP "\fBdefault_md\fR" 4 +.IX Item "default_md" +This option specifies the digest algorithm to use. Possible values +include \fBmd5 sha1 mdc2\fR. If not present then \s-1MD5\s0 is used. This +option can be overridden on the command line. +.IP "\fBstring_mask\fR" 4 +.IX Item "string_mask" +This option masks out the use of certain string types in certain +fields. Most users will not need to change this option. +.Sp +It can be set to several values \fBdefault\fR which is also the default +option uses PrintableStrings, T61Strings and BMPStrings if the +\&\fBpkix\fR value is used then only PrintableStrings and BMPStrings will +be used. This follows the \s-1PKIX\s0 recommendation in \s-1RFC2459.\s0 If the +\&\fButf8only\fR option is used then only UTF8Strings will be used: this +is the \s-1PKIX\s0 recommendation in \s-1RFC2459\s0 after 2003. Finally the \fBnombstr\fR +option just uses PrintableStrings and T61Strings: certain software has +problems with BMPStrings and UTF8Strings: in particular Netscape. +.IP "\fBreq_extensions\fR" 4 +.IX Item "req_extensions" +this specifies the configuration file section containing a list of +extensions to add to the certificate request. It can be overridden +by the \fB\-reqexts\fR command line switch. See the +\&\fIx509v3_config\fR\|(5) manual page for details of the +extension section format. +.IP "\fBx509_extensions\fR" 4 +.IX Item "x509_extensions" +this specifies the configuration file section containing a list of +extensions to add to certificate generated when the \fB\-x509\fR switch +is used. It can be overridden by the \fB\-extensions\fR command line switch. +.IP "\fBprompt\fR" 4 +.IX Item "prompt" +if set to the value \fBno\fR this disables prompting of certificate fields +and just takes values from the config file directly. It also changes the +expected format of the \fBdistinguished_name\fR and \fBattributes\fR sections. +.IP "\fButf8\fR" 4 +.IX Item "utf8" +if set to the value \fByes\fR then field values to be interpreted as \s-1UTF8\s0 +strings, by default they are interpreted as \s-1ASCII.\s0 This means that +the field values, whether prompted from a terminal or obtained from a +configuration file, must be valid \s-1UTF8\s0 strings. +.IP "\fBattributes\fR" 4 +.IX Item "attributes" +this specifies the section containing any request attributes: its format +is the same as \fBdistinguished_name\fR. Typically these may contain the +challengePassword or unstructuredName types. They are currently ignored +by OpenSSL's request signing utilities but some CAs might want them. +.IP "\fBdistinguished_name\fR" 4 +.IX Item "distinguished_name" +This specifies the section containing the distinguished name fields to +prompt for when generating a certificate or certificate request. The format +is described in the next section. +.SH "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT" +.IX Header "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT" +There are two separate formats for the distinguished name and attribute +sections. If the \fBprompt\fR option is set to \fBno\fR then these sections +just consist of field names and values: for example, +.PP +.Vb 3 +\& CN=My Name +\& OU=My Organization +\& emailAddress=someone@somewhere.org +.Ve +.PP +This allows external programs (e.g. \s-1GUI\s0 based) to generate a template file +with all the field names and values and just pass it to \fBreq\fR. An example +of this kind of configuration file is contained in the \fB\s-1EXAMPLES\s0\fR section. +.PP +Alternatively if the \fBprompt\fR option is absent or not set to \fBno\fR then the +file contains field prompting information. It consists of lines of the form: +.PP +.Vb 4 +\& fieldName="prompt" +\& fieldName_default="default field value" +\& fieldName_min= 2 +\& fieldName_max= 4 +.Ve +.PP +\&\*(L"fieldName\*(R" is the field name being used, for example commonName (or \s-1CN\s0). +The \*(L"prompt\*(R" string is used to ask the user to enter the relevant +details. If the user enters nothing then the default value is used if no +default value is present then the field is omitted. A field can +still be omitted if a default value is present if the user just +enters the '.' character. +.PP +The number of characters entered must be between the fieldName_min and +fieldName_max limits: there may be additional restrictions based +on the field being used (for example countryName can only ever be +two characters long and must fit in a PrintableString). +.PP +Some fields (such as organizationName) can be used more than once +in a \s-1DN.\s0 This presents a problem because configuration files will +not recognize the same name occurring twice. To avoid this problem +if the fieldName contains some characters followed by a full stop +they will be ignored. So for example a second organizationName can +be input by calling it \*(L"1.organizationName\*(R". +.PP +The actual permitted field names are any object identifier short or +long names. These are compiled into OpenSSL and include the usual +values such as commonName, countryName, localityName, organizationName, +organizationalUnitName, stateOrProvinceName. Additionally emailAddress +is include as well as name, surname, givenName initials and dnQualifier. +.PP +Additional object identifiers can be defined with the \fBoid_file\fR or +\&\fBoid_section\fR options in the configuration file. Any additional fields +will be treated as though they were a DirectoryString. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Examine and verify certificate request: +.PP +.Vb 1 +\& openssl req \-in req.pem \-text \-verify \-noout +.Ve +.PP +Create a private key and then generate a certificate request from it: +.PP +.Vb 2 +\& openssl genrsa \-out key.pem 2048 +\& openssl req \-new \-key key.pem \-out req.pem +.Ve +.PP +The same but just using req: +.PP +.Vb 1 +\& openssl req \-newkey rsa:2048 \-keyout key.pem \-out req.pem +.Ve +.PP +Generate a self signed root certificate: +.PP +.Vb 1 +\& openssl req \-x509 \-newkey rsa:2048 \-keyout key.pem \-out req.pem +.Ve +.PP +Example of a file pointed to by the \fBoid_file\fR option: +.PP +.Vb 2 +\& 1.2.3.4 shortName A longer Name +\& 1.2.3.6 otherName Other longer Name +.Ve +.PP +Example of a section pointed to by \fBoid_section\fR making use of variable +expansion: +.PP +.Vb 2 +\& testoid1=1.2.3.5 +\& testoid2=${testoid1}.6 +.Ve +.PP +Sample configuration file prompting for field values: +.PP +.Vb 6 +\& [ req ] +\& default_bits = 2048 +\& default_keyfile = privkey.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& x509_extensions = v3_ca +\& +\& dirstring_type = nobmp +\& +\& [ req_distinguished_name ] +\& countryName = Country Name (2 letter code) +\& countryName_default = AU +\& countryName_min = 2 +\& countryName_max = 2 +\& +\& localityName = Locality Name (eg, city) +\& +\& organizationalUnitName = Organizational Unit Name (eg, section) +\& +\& commonName = Common Name (eg, YOUR name) +\& commonName_max = 64 +\& +\& emailAddress = Email Address +\& emailAddress_max = 40 +\& +\& [ req_attributes ] +\& challengePassword = A challenge password +\& challengePassword_min = 4 +\& challengePassword_max = 20 +\& +\& [ v3_ca ] +\& +\& subjectKeyIdentifier=hash +\& authorityKeyIdentifier=keyid:always,issuer:always +\& basicConstraints = CA:true +.Ve +.PP +Sample configuration containing all field values: +.PP +.Vb 1 +\& RANDFILE = $ENV::HOME/.rnd +\& +\& [ req ] +\& default_bits = 2048 +\& default_keyfile = keyfile.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& prompt = no +\& output_password = mypass +\& +\& [ req_distinguished_name ] +\& C = GB +\& ST = Test State or Province +\& L = Test Locality +\& O = Organization Name +\& OU = Organizational Unit Name +\& CN = Common Name +\& emailAddress = test@email.address +\& +\& [ req_attributes ] +\& challengePassword = A challenge password +.Ve +.SH "NOTES" +.IX Header "NOTES" +The header and footer lines in the \fB\s-1PEM\s0\fR format are normally: +.PP +.Vb 2 +\& \-\-\-\-\-BEGIN CERTIFICATE REQUEST\-\-\-\-\- +\& \-\-\-\-\-END CERTIFICATE REQUEST\-\-\-\-\- +.Ve +.PP +some software (some versions of Netscape certificate server) instead needs: +.PP +.Vb 2 +\& \-\-\-\-\-BEGIN NEW CERTIFICATE REQUEST\-\-\-\-\- +\& \-\-\-\-\-END NEW CERTIFICATE REQUEST\-\-\-\-\- +.Ve +.PP +which is produced with the \fB\-newhdr\fR option but is otherwise compatible. +Either form is accepted transparently on input. +.PP +The certificate requests generated by \fBXenroll\fR with \s-1MSIE\s0 have extensions +added. It includes the \fBkeyUsage\fR extension which determines the type of +key (signature only or general purpose) and any additional OIDs entered +by the script in an extendedKeyUsage extension. +.SH "DIAGNOSTICS" +.IX Header "DIAGNOSTICS" +The following messages are frequently asked about: +.PP +.Vb 2 +\& Using configuration from /some/path/openssl.cnf +\& Unable to load config info +.Ve +.PP +This is followed some time later by... +.PP +.Vb 2 +\& unable to find \*(Aqdistinguished_name\*(Aq in config +\& problems making Certificate Request +.Ve +.PP +The first error message is the clue: it can't find the configuration +file! Certain operations (like examining a certificate request) don't +need a configuration file so its use isn't enforced. Generation of +certificates or requests however does need a configuration file. This +could be regarded as a bug. +.PP +Another puzzling message is this: +.PP +.Vb 2 +\& Attributes: +\& a0:00 +.Ve +.PP +this is displayed when no attributes are present and the request includes +the correct empty \fB\s-1SET OF\s0\fR structure (the \s-1DER\s0 encoding of which is 0xa0 +0x00). If you just see: +.PP +.Vb 1 +\& Attributes: +.Ve +.PP +then the \fB\s-1SET OF\s0\fR is missing and the encoding is technically invalid (but +it is tolerated). See the description of the command line option \fB\-asn1\-kludge\fR +for more information. +.SH "ENVIRONMENT VARIABLES" +.IX Header "ENVIRONMENT VARIABLES" +The variable \fB\s-1OPENSSL_CONF\s0\fR if defined allows an alternative configuration +file location to be specified, it will be overridden by the \fB\-config\fR command +line switch if it is present. For compatibility reasons the \fB\s-1SSLEAY_CONF\s0\fR +environment variable serves the same purpose but its use is discouraged. +.SH "BUGS" +.IX Header "BUGS" +OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively +treats them as \s-1ISO\-8859\-1 \s0(Latin 1), Netscape and \s-1MSIE\s0 have similar behaviour. +This can cause problems if you need characters that aren't available in +PrintableStrings and you don't want to or can't use BMPStrings. +.PP +As a consequence of the T61String handling the only correct way to represent +accented characters in OpenSSL is to use a BMPString: unfortunately Netscape +currently chokes on these. If you have to use accented characters with Netscape +and \s-1MSIE\s0 then you currently need to use the invalid T61String form. +.PP +The current prompting is not very friendly. It doesn't allow you to confirm what +you've just entered. Other things like extensions in certificate requests are +statically defined in the configuration file. Some of these: like an email +address in subjectAltName should be input by the user. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1), +\&\fIgendsa\fR\|(1), \fIconfig\fR\|(5), +\&\fIx509v3_config\fR\|(5) |
