Rename "openssl x509" option "-config" to "-extfile", because it
[openssl.git] / doc / openssl.txt
index 76f4913..527bd97 100644 (file)
@@ -5,8 +5,8 @@ This is some preliminary documentation for OpenSSL.
                             BUFFER Library
 ==============================================================================
 
-The buffer library handles simple character arrays. Buffers are used for various
-purposes in the library, most notably memory BIOs.
+The buffer library handles simple character arrays. Buffers are used for
+various purposes in the library, most notably memory BIOs.
 
 The library uses the BUF_MEM structure defined in buffer.h:
 
@@ -98,6 +98,15 @@ indicates which section contains the extensions. In the case of 'req' the
 extension section is used when the -x509 option is present to create a
 self signed root certificate.
 
+The 'x509' utility also supports extensions when it signs a certificate.
+The -extfile option is used to set the configuration file containing the
+extensions. In this case a line with:
+
+extensions = extension_section
+
+in the nameless (default) section is used. If no such line is include then
+it uses the default section.
+
 You can also add extensions to CRLs: a line
 
 crl_extensions = crl_extension_section
@@ -108,6 +117,17 @@ issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
 CRL entry extensions can be displayed.
 
+NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
+you should comment out the crl_extensions line in the configuration file.
+
+As with all configuration files you can use the inbuilt environment expansion
+to allow the values to be passed in the environment. Therefore if you have
+several extension sections used for different purposes you can have a line:
+
+x509_extensions = $ENV::ENV_EXT
+
+and set the ENV_EXT environment variable before calling the relevant utility.
+
 EXTENSION SYNTAX.
 
 Extensions have the basic form:
@@ -180,9 +200,10 @@ CURRENTLY SUPPORTED EXTENSIONS.
 
 Literal String extensions.
 
-In each case the 'value' of the extension is placed directly in the extension.
-Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
-nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and nsComment.
+In each case the 'value' of the extension is placed directly in the
+extension. Currently supported extensions in this category are: nsBaseUrl,
+nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
+nsSslServerName and nsComment.
 
 For example:
 
@@ -298,7 +319,10 @@ This is a RAW extension. It attempts to display the contents of this extension:
 unfortuntately this extension is often improperly encoded.
 
 The certificate policies extension will rarely be used in practice: few
-software packages interpret it correctly or at all.
+software packages interpret it correctly or at all. IE5 does partially
+support this extension: but it needs the 'ia5org' option because it will
+only correctly support a broken encoding. Of the options below only the
+policy OID, explicitText and CPS options are displayed with IE5.
 
 All the fields of this extension can be set by using the appropriate syntax.
 
@@ -321,15 +345,17 @@ userNotice qualifiers can be set using the syntax:
 
 userNotice.nnn=@notice
 
-The value of the userNotice qualifier is specified in the relevant section. This
-section can include explicitText, organization and noticeNumbers options. 
-explicitText and organization are text strings, noticeNumbers is a comma
-separated list of numbers. The organization and noticeNumbers options (if
-included) must BOTH be present.
+The value of the userNotice qualifier is specified in the relevant section.
+This section can include explicitText, organization and noticeNumbers
+options. explicitText and organization are text strings, noticeNumbers is a
+comma separated list of numbers. The organization and noticeNumbers options
+(if included) must BOTH be present. If you use the userNotice option with IE5
+then you need the 'ia5org' option at the top level to modify the encoding:
+otherwise it will not be interpreted properly.
 
 Example:
 
-certificatePolicies=1.2.3.4,1.5.6.7.8,@polsect
+certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
 
 [polsect]
 
@@ -344,6 +370,10 @@ explicitText="Explicit Text Here"
 organization="Organisation Name"
 noticeNumbers=1,2,3,4
 
+TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
+according to PKIX it should be of type DisplayText but Verisign uses an 
+IA5STRING and IE5 needs this too.
+
 Display only extensions.
 
 Some extensions are only partially supported and currently are only displayed
@@ -374,7 +404,8 @@ private key and certificate pair.
 
 No special initialisation is needed for the internal PKCS#12 library: the 
 standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to
-add all algorithms then you can manually initialise the PKCS#12 library with:
+add all algorithms (you should at least add SHA1 though) then you can manually
+initialise the PKCS#12 library with:
 
 PKSC12_PBE_add();
 
@@ -445,9 +476,9 @@ PKCS12_free(p12);
 LOW LEVEL FUNCTIONS.
 
 In some cases the high level functions do not provide the necessary
-functionality. For example if you want to generate or parse more complex PKCS#12
-files. The sample pkcs12 application uses the low level functions to display
-details about the internal structure of a PKCS#12 file.
+functionality. For example if you want to generate or parse more complex
+PKCS#12 files. The sample pkcs12 application uses the low level functions
+to display details about the internal structure of a PKCS#12 file.
 
 Introduction.
 
@@ -472,14 +503,16 @@ integrity (so any unencrypted stuff below can't be tampered with).
 
 The reason for these levels is so various objects can be encrypted in various
 ways. For example you might want to encrypt a set of private keys with
-triple-DES and then include the related certificates either unencrypted or with
-lower encryption. Yes it's the dreaded crypto laws at work again which
-allow strong encryption on private keys and only weak encryption on other stuff.
+triple-DES and then include the related certificates either unencrypted or
+with lower encryption. Yes it's the dreaded crypto laws at work again which
+allow strong encryption on private keys and only weak encryption on other
+stuff.
 
 To build one of these things you turn all certificates and keys into safebags
 (with optional attributes). You collect the safebags into (one or more) STACKS
-and convert these into authsafes (encrypted or unencrypted).  The authsafes are
-collected into a STACK and added to a PKCS12 structure.  Finally a MAC inserted.
+and convert these into authsafes (encrypted or unencrypted).  The authsafes
+are collected into a STACK and added to a PKCS12 structure.  Finally a MAC
+inserted.
 
 Pulling one apart is basically the reverse process. The MAC is verified against
 the given password. The authsafes are extracted and each authsafe split into
@@ -506,9 +539,10 @@ PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey)
 
 Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure.
 Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo
-structure contains a private key data in plain text form it should be free'd up
-as soon as it has been encrypted for security reasons (freeing up the structure
-zeros out the sensitive data). This can be done with PKCS8_PRIV_KEY_INFO_free().
+structure contains a private key data in plain text form it should be free'd
+up as soon as it has been encrypted for security reasons (freeing up the
+structure zeros out the sensitive data). This can be done with
+PKCS8_PRIV_KEY_INFO_free().
 
 PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage)
 
@@ -522,9 +556,9 @@ KEY_EX is not limited and can be used for both.
 
 PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8)
 
-Convert a PKCS8 private key structure into a keybag. This routine embeds the p8
-structure in the keybag so p8 should not be freed up or used after it is called.
-The p8 structure will be freed up when the safebag is freed.
+Convert a PKCS8 private key structure into a keybag. This routine embeds the
+p8 structure in the keybag so p8 should not be freed up or used after it is
+called.  The p8 structure will be freed up when the safebag is freed.
 
 PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8)
 
@@ -671,11 +705,13 @@ NID_pbe_WithSHA1And2_Key_TripleDES_CBC
 NID_pbe_WithSHA1And128BitRC2_CBC
 NID_pbe_WithSHA1And40BitRC2_CBC
 
-Which you use depends on the implementation you are exporting to. "Export grade"(i.e. cryptograhically challenged) products cannot support all algorithms.
-Typically you may be able to use any encryption on shrouded key bags but they
-must then be placed in an unencrypted authsafe. Other authsafes may only support
-40bit encryption. Of course if you are using SSLeay throughout you can strongly
-encrypt everything and have high iteration counts on everything.
+Which you use depends on the implementation you are exporting to. "Export
+grade" (i.e. cryptograhically challenged) products cannot support all
+algorithms. Typically you may be able to use any encryption on shrouded key
+bags but they must then be placed in an unencrypted authsafe. Other authsafes
+may only support 40bit encryption. Of course if you are using SSLeay
+throughout you can strongly encrypt everything and have high iteration counts
+on everything.
 
 3. For decryption routines only the password and length are needed.