Add preliminary user level config documentation for extension stuff. Programming

info will come later...

Feel free to reformat and tidy this up...

CHANGES

@@ -5,6 +5,9 @@
 
  Changes between 0.9.1c and 0.9.2
 
+  *) Add preliminary config info for new extension code.
+     [Steve Henson]
+
   *) Make RSA_NO_PADDING really use no padding.
      [Ulf Moeller <ulf@fitug.de>]
 

doc/ext-conf.txt

+OpenSSL X509V3 extension configuration: preliminary documentation.
+
+INTRODUCTION.
+
+For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
+possible to add and print out common X509 V3 certificate and CRL extensions.
+
+For more information about the meaning of extensions see:
+
+http://www.imc.org/ietf-pkix/
+http://home.netscape.com/eng/security/certs.html
+
+PRINTING EXTENSIONS.
+
+Extension values are automatically printed out for supported extensions.
+
+x509 -in cert.pem -text
+crl -in crl.pem -text
+
+will give information in the extension printout, for example:
+
+
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:TRUE
+            X509v3 Subject Key Identifier: 
+                73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
+            X509v3 Authority Key Identifier: 
+                keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
+            X509v3 Key Usage: 
+                Certificate Sign, CRL Sign
+            X509v3 Subject Alternative Name: 
+                email:email@1.address, email:email@2.address
+
+CONFIGURATION FILES.
+
+The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
+which certificate extensions to include. In each case a line:
+
+x509_extensions = extension_section
+
+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.
+
+EXTENSION SYNTAX.
+
+Extensions have the basic form:
+
+extension_name=[critical,] extension_options
+
+the use of the critical option makes the extension critical. Extreme caution
+should be made when using the critical flag. If an extension is marked
+as critical then any client that does not understand the extension should
+reject it as invalid. Some broken software will reject certificates which
+have *any* critical extensions (these violates PKIX but we have to live
+with it).
+
+There are three main types of extension, string extensions, multi valued
+extensions, and raw extensions.
+
+String extensions simply have a string which defines the value of the or how
+it is obtained.
+
+For example:
+
+nsComment="This is a Comment"
+
+Multi valued extensions have a short form and a long form. The short form
+is a list of names and values:
+
+basicConstraints=critical,CA:true,pathlen:1
+
+The long form allows the values to be placed in a separate section:
+
+basicConstraints=critical,@bs_section
+
+[bs_section]
+
+CA=true
+pathlen=1
+
+Both forms are equivalent. However it should be noted that in some cases the
+same name can appear multiple times, for example,
+
+subjectAltName=email:steve@here,email:steve@there
+
+in this case an equivalent long form is:
+
+subjectAltName=@alt_section
+
+[alt_section]
+
+email.1=steve@here
+email.2=steve@there
+
+This is because the configuration file code cannot handle the same name
+occurring twice in the same extension.
+
+Raw extensions allow arbitrary data to be placed in an extension. For
+example
+
+1.2.3.4=critical,RAW:01:02:03:04
+1.2.3.4=RAW:01020304
+
+The value following RAW is a hex dump of the extension contents. Any extension
+can be placed in this form to override the default behaviour. For example:
+
+basicConstraints=critical,RAW:00:01:02:03
+
+WARNING: raw extensions should be used with caution. It is possible to create
+totally invalid extensions unless care is taken.
+
+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.
+
+For example:
+
+nsComment="This is a test comment"
+
+Bit Strings.
+
+Bit string extensions just consist of a list of suppported bits, currently
+two extensions are in this category: PKIX keyUsage and the Netscape specific
+nsCertType.
+
+nsCertType (netscape certificate type) takes the flags: client, server, email,
+objsign, reserved, sslCA, emailCA, objCA.
+
+keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
+keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
+encipherOnly, decipherOnly.
+
+For example:
+
+nsCertType=server
+
+keyUsage=critical, digitalSignature, nonRepudiation
+
+
+Basic Constraints.
+
+Basic constraints is a multi valued extension that supports a CA and an
+optional pathlen option. The CA option takes the values true and false and
+pathlen takes an integer. Note if the CA option is false the pathlen option
+should be omitted.
+
+Examples:
+
+basicConstraints=CA:TRUE
+basicConstraints=critical,CA:TRUE, pathlen:10
+
+NOTE: for a CA to be considered valid it must have the CA option set to
+TRUE. An end user certificate MUST NOT have the CA value set to true.
+According to PKIX recommendations it should exclude the extension entirely
+however some software may require CA set to FALSE for end entity certificates.
+
+Subject Key Identifier.
+
+This is really a string extension and can take two possible values. Either
+a hex string giving details of the extension value to include or the word
+'hash' which then automatically follow PKIX guidelines in selecting and
+appropriate key identifier. The use of the hex string is strongly discouraged.
+
+Example: subjectKeyIdentifier=hash
+
+Authority Key Identifier.
+
+The authority key identifier extension permits two options. keyid and issuer:
+both can take the optional value "always".
+
+If the keyid option is present an attempt is made to copy the subject key
+identifier from the parent certificate. If the value "always" is present
+then an error is returned if the option fails.
+
+The issuer option copies the issuer and serial number from the issuer
+certificate. Normally this will only be done if the keyid option fails or
+is not included: the "always" flag will always include the value.
+
+Subject Alternative Name.
+
+The subject alternative name extension allows various literal values to be
+included in the configuration file. These include "email" (an email address)
+"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
+registered ID: OBJECT IDENTIFIER) and IP (and IP address).
+
+Also the email option include a special 'copy' value. This will automatically
+include and email addresses contained in the certificate subject name in
+the extension.
+
+Examples:
+
+subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
+subjectAltName=email:my@other.address,RID:1.2.3.4
+
+Issuer Alternative Name.
+
+The issuer alternative name option supports all the literal options of
+subject alternative name. It does *not* support the email:copy option because
+that would not make sense. It does support and additional issuer:copy option
+that will copy all the subject alternative name values from the issuer 
+certificate (if possible).
+
+Display only extensions.
+
+Some extensions are only partially supported and currently are only displayed
+but cannot be set. These include private key usage period, CRL number, and
+CRL reason.