Include some notes on basic extension usage and change openssl.cnf to…

… usually

do sensible things with extensions.

apps/openssl.cnf

@@ -42,7 +42,11 @@ private_key	= $dir/private/cakey.pem# The private key
 RANDFILE	= $dir/private/.rand	# private random number file
 
 x509_extensions	= usr_cert		# The extentions to add to the cert
-crl_extensions	= crl_ext		# Extensions to add to CRL
+
+# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
+# so this is commented out by default to leave a V1 CRL.
+# crl_extensions	= crl_ext
+
 default_days	= 365			# how long to certify for
 default_crl_days= 30			# how long before next CRL
 default_md	= md5			# which md to use.
@@ -131,31 +135,33 @@ basicConstraints=CA:FALSE
 # the certificate can be used for anything *except* object signing.
 
 # This is OK for an SSL server.
-#nsCertType			= server
+# nsCertType			= server
 
 # For an object signing certificate this would be used.
-#nsCertType = objsign
+# nsCertType = objsign
 
 # For normal client use this is typical
-#nsCertType = client, email
+# nsCertType = client, email
 
-# This is typical also
+# and for everything including object signing:
+# nsCertType = client, email, objsign
 
-keyUsage = nonRepudiation, digitalSignature, keyEncipherment
+# This is typical in keyUsage for a client certificate.
+# keyUsage = nonRepudiation, digitalSignature, keyEncipherment
 
+# This will be displayed in Netscape's comment listbox.
 nsComment			= "OpenSSL Generated Certificate"
 
-# PKIX recommendations
+# PKIX recommendations harmless if included in all certificates.
 subjectKeyIdentifier=hash
 authorityKeyIdentifier=keyid,issuer:always
 
+# This stuff is for subjectAltName and issuerAltname.
 # Import the email address.
-
-subjectAltName=email:copy
+# subjectAltName=email:copy
 
 # Copy subject details
-
-issuerAltName=issuer:copy
+# issuerAltName=issuer:copy
 
 #nsCaRevocationUrl		= http://www.domain.dom/ca-crl.pem
 #nsBaseUrl
@@ -168,8 +174,6 @@ issuerAltName=issuer:copy
 
 # Extensions for a typical CA
 
-# It's a CA certificate
-basicConstraints = CA:true
 
 # PKIX recommendation.
 
@@ -180,17 +184,21 @@ authorityKeyIdentifier=keyid:always,issuer:always
 # This is what PKIX recommends but some broken software chokes on critical
 # extensions.
 #basicConstraints = critical,CA:true
+# So we do this instead.
+basicConstraints = CA:true
 
-# Key usage: again this should really be critical.
-keyUsage = cRLSign, keyCertSign
+# Key usage: this is typical for a CA certificate. However since it will
+# prevent it being used as an test self-signed certificate it is best
+# left out by default.
+# keyUsage = cRLSign, keyCertSign
 
 # Some might want this also
-#nsCertType = sslCA, emailCA
+# nsCertType = sslCA, emailCA
 
 # Include email address in subject alt name: another PKIX recommendation
-subjectAltName=email:copy
+# subjectAltName=email:copy
 # Copy issuer details
-issuerAltName=issuer:copy
+# issuerAltName=issuer:copy
 
 # RAW DER hex encoding of an extension: beware experts only!
 # 1.2.3.5=RAW:02:03
@@ -202,5 +210,5 @@ issuerAltName=issuer:copy
 # CRL extensions.
 # Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
 
-issuerAltName=issuer:copy
+# issuerAltName=issuer:copy
 authorityKeyIdentifier=keyid:always,issuer:always

doc/openssl.txt

@@ -60,7 +60,16 @@ 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:
+BEGINNERS NOTE
+
+For most simple applications you don't need to know too much about extensions:
+the default openssl.cnf values will usually do sensible things.
+
+If you want to know more you can initially quickly look through the sections
+describing how the standard OpenSSL utilities display and add extensions and
+then the list of supported extensions.
+
+For more technical information about the meaning of extensions see:
 
 http://www.imc.org/ietf-pkix/
 http://home.netscape.com/eng/security/certs.html
@@ -74,7 +83,6 @@ openssl crl -in crl.pem -text
 
 will give information in the extension printout, for example:
 
-
         X509v3 extensions:
             X509v3 Basic Constraints: 
                 CA:TRUE
@@ -118,7 +126,7 @@ 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.
+you should not include a 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
@@ -204,6 +212,14 @@ invalid extensions unless care is taken.
 
 CURRENTLY SUPPORTED EXTENSIONS.
 
+If you aren't sure about extensions then they can be largely ignored: its only
+when you want to do things like restrict certificate usage when you need to
+worry about them. 
+
+The only extension that a beginner might want to look at is Basic Constraints.
+If in addition you want to try Netscape object signing the you should also
+look at Netscape Certificate Type.
+
 Literal String extensions.
 
 In each case the 'value' of the extension is placed directly in the
@@ -232,20 +248,67 @@ For example:
 
 nsCertType=server
 
-keyUsage=critical, digitalSignature, nonRepudiation
+keyUsage=digitalSignature, nonRepudiation
+
+Hints on Netscape Certificate Type.
+
+Other than Basic Constraints this is the only extension a beginner might
+want to use, if you want to try Netscape object signing, otherwise it can
+be ignored.
+
+If you want a certificate that can be used just for object signing then:
+
+nsCertType=objsign
+
+will do the job. If you want to use it as a normal end user and server
+certificate as well then
+
+nsCertType=objsign,email,server
 
+is more appropriate. You cannot use a self signed certificate for object
+signing (well Netscape signtool can but it cheats!) so you need to create
+a CA certificate and sign an end user certificate with it.
+
+Side note: If you want to conform to the Netscape specifications then you
+should really also set:
+
+nsCertType=objCA
+
+in the *CA* certificate for just an object signing CA and
+
+nsCertType=objCA,emailCA,sslCA
+
+for everything. Current Netscape software doesn't enforce this so it can
+be omitted.
 
 Basic Constraints.
 
+This is generally the only extension you need to worry about for simple
+applications. If you want your certificate to be usable as a CA certificate
+(in addition to an end user certificate) then you set this to:
+
+basicConstraints=CA:TRUE
+
+if you want to be certain the certificate cannot be used as a CA then do:
+
+basicConstraints=CA:FALSE
+
+The rest of this section describes more advanced usage.
+
 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.
+should be omitted. 
+
+The pathlen parameter indicates the maximum number of CAs that can appear
+below this one in a chain. So if you have a CA with a pathlen of zero it can
+only be used to sign end user certificates and not further CAs. This all
+assumes that the software correctly interprets this extension of course.
 
 Examples:
 
 basicConstraints=CA:TRUE
-basicConstraints=critical,CA:TRUE, pathlen:10
+basicConstraints=critical,CA:TRUE, pathlen:0
 
 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.