X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=doc%2Fman%2Freq.pod;h=e836f187acebb1cf587b54b0ad91030191319e03;hb=6e6bc352b18ae230833580018b246d9a7ce331a6;hp=d59a2dc2a2c1c09416ec41043bbf1c86460f42e1;hpb=77b47b903684020d07d16519b2a74cc58668fb20;p=openssl.git diff --git a/doc/man/req.pod b/doc/man/req.pod index d59a2dc2a2..e836f187ac 100644 --- a/doc/man/req.pod +++ b/doc/man/req.pod @@ -245,7 +245,7 @@ placed and read from. It is used for private key generation. If this is set to B then if a private key is generated it is B encrypted. This is equivalent to the B<-nodes> command line -option. For compatibility B is an equivalent option. +option. For compatibility B is an equivalent option. =item B @@ -279,24 +279,48 @@ this specifies the configuration file section containing a list of extensions to add to certificate generated when the B<-x509> switch is used. It can be overridden by the B<-extensions> command line switch. +=item B + +if set to the value B this disables prompting of certificate fields +and just takes values from the config file directly. It also changes the +expected format of the B and B sections. + =item B this specifies the section containing any request attributes: its format -is the same as B described below. 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. +is the same as B. 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. =item B This specifies the section containing the distinguished name fields to -prompt for when generating a certificate or certificate request. This -consists of lines of the form: +prompt for when generating a certificate or certificate request. The format +is described in the next section. + +=back + +=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT + +There are two separate formats for the distinguished name and attribute +sections. If the B option is set to B then these sections +just consist of field names and values: for example, - fieldName="prompt" - fieldName_default="default field value" - fieldName_min= 2 - fieldName_max= 4 + CN=My Name + OU=My Organization + emailAddress=someone@somehere.org + +This allows external programs (e.g. GUI based) to generate a template file +with all the field names and values and just pass it to B. An example +of this kind of configuration files is contained in the B section. + +Alternatively if the B option is absent or not set to B the the +file contains field prompting information. It consists of lines of the form: + + fieldName="prompt" + fieldName_default="default field value" + fieldName_min= 2 + fieldName_max= 4 "fieldName" is the field name being used, for example commonName (or CN). The "prompt" string is used to ask the user to enter the relevant @@ -312,7 +336,7 @@ two characters long and must fit in a PrintableString). Some fields (such as organizationName) can be used more than once in a DN. This presents a problem because configuration files will -not recognise the same name occurring twice. To avoid this problem +not recognize the same name occurring twice. To avoid this problem if the fieldName contains an some characters followed by a full stop they will be ignored. So for example a second organizationName can be input by calling it "1.organizationName". @@ -328,7 +352,6 @@ Additional object identifiers can be defined with the B or B options in the configuration file. Any additional fields will be treated as though they were a DirectoryString. -=back =head1 EXAMPLES @@ -360,7 +383,7 @@ expansion: testoid1=1.2.3.5 testoid2=${testoid1}.6 -Sample configuration file: +Sample configuration file prompting for field values: [ req ] default_bits = 1024 @@ -374,8 +397,8 @@ Sample configuration file: [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_default = AU - countryName_min = 2 - countryName_max = 2 + countryName_min = 2 + countryName_max = 2 localityName = Locality Name (eg, city) @@ -398,6 +421,32 @@ Sample configuration file: authorityKeyIdentifier=keyid:always,issuer:always basicConstraints = CA:true +Sample configuration containing all field values: + + + RANDFILE = $ENV::HOME/.rnd + + [ req ] + default_bits = 1024 + 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 + + =head1 NOTES The header and footer lines in the B format are respectively: @@ -469,18 +518,10 @@ 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 MSIE then you currently need to use the invalid T61String form. -The current prompting is not very friendly. It exits if you get the strings -wrong and 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. - -There should be a way to have a friendly front end (e.g. perl script or GUI) -handle all user input and then just feed a "template" file into B which -then silently creates the request or certificate. This would also shift the -responsibility for handling such problems as internationalisation of characters -onto the front end: the template could then just expect valid UTF8 character -strings for example. +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. =head1 SEE ALSO