finishing up examples and first draft

1 files changed, 70 insertions, 20 deletions

diff --git a/certutil.xml b/certutil.xml
index ab72e3e..734003a 100644
--- a/certutil.xml
+++ b/certutil.xml
@@ -606,16 +606,15 @@ the default and create a validity period of one month.</para></listitem>
 	<para>
 		For example:
 	</para>
-<programlisting language="Bash">$ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" -d . -p 650-555-0123 -a
+<programlisting language="Bash">$ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" -d . -p 650-555-0123 -a -o cert.
 
 Generating key.  This may take a few moments...
 
 
-Certificate request generated by Netscape certutil
+Certificate request generated by Netscape 
 Phone: 650-555-0123
-
 Common Name: John Smith
-Email: (not specified)
+Email: (not ed)
 Organization: Example Corp
 State: California
 Country: US
@@ -649,21 +648,24 @@ qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB
 
 	<para><command>Generating a Certificate from a Certificate Request</command></para>
 	<para>
-		XXXXXXXXXXXXX
+		When a certificate request is created, a certificate can be generated by using the request and then referencing a certificate authority signing certificate (the <emphasis>issuer</emphasis> specified in the <option>-c</option> argument). The issuing certificate must be in the <filename>cert8.db</filename> database in the specified directory.
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
-
-	<para><command>Generating an Email Certificate</command></para>
+<programlisting language="Bash">certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] [-w offset-months] -d certdir [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names]</programlisting>
 	<para>
-		XXXXXXXXXXXXX
+		For example:
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+<programlisting language="Bash">$ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 -v 12 -w 1 -d . -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 jsmith@example.com</programlisting>
+
 
 	<para><command>Generating Key Pairs</command></para>
 	<para>
-		XXXXXXXXXXXXX
+		Key pairs are generated automatically with a certificate request or certificate, but they can also be generated independently using the <option>-G</option> command option. 
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+<programlisting language="Bash">certutil -G -d directory | -h tokenname -k key-type -g key-size [-y exponent-value] -q pgfile|curve-name</programlisting>
+	<para>
+		For example:
+	</para>
+<programlisting language="Bash">$ certutil -G -h lunasa -k ec -g 256 -q sect193r2</programlisting>
 
 	<para><command>Listing Certificates</command></para>
 	<para>
@@ -747,11 +749,15 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and
 	<para>
 		Existing certificates or certificate requests can be added manually to the <filename>cert8.db</filename> database, even if they were generated elsewhere. This uses the <option>-A</option> command option.
 	</para>
-<programlisting language="Bash">certutil -A -n certname -t trustargs -d certdir [-a] [-i cert-request-file]</programlisting>
+<programlisting language="Bash">certutil -A -n certname -t trustargs -d certdir [-a] [-i input-file]</programlisting>
 	<para>
 		For example:
 	</para>
-<programlisting language="Bash">$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d . -i /home/example-certs/ca.cer</programlisting>
+<programlisting language="Bash">$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d . -i /home/example-certs/cert.cer</programlisting>
+	<para>
+		A related command option, <option>-E</option>, is used specifically to add email certificates to the certificate database. The <option>-E</option> command has the same arguments as the <option>-A</option> command. The trust arguments for certificates have the format <emphasis>SSL,S/MIME,Code-signing</emphasis>, so the middle trust settings relate most to email certificates (though the others can be set). For example:
+	</para>
+<programlisting language="Bash">$ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d . -i /home/example-certs/email.cer</programlisting>
 
 	<para><command>Deleting Certificates to the Database</command></para>
 	<para>
@@ -765,21 +771,65 @@ certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and
 
 	<para><command>Validating Certificates</command></para>
 	<para>
-		XXXXXXXXXXXXX
+		A certificate contains an expiration date in itself, and expired certificates are easily rejected. However, certificates can also be revoked before they hit their expiration date. Checking whether a certificate has been revoked requires validating the certificate. Validation can also be used to ensure that the certificate is only used for the purposes it was initially issued for. Validation is carried out by the <option>-V</option> command option.
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+<programlisting language="Bash">certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d directory</programlisting>
+	<para>
+		For example, to validate an email certificate:
+	</para>
+<programlisting language="Bash">$ certutil -V -n "John Smith's Email Cert" -e -u S,R -d .</programlisting>
 
 	<para><command>Modifying Certificate Trust Settings</command></para>
 	<para>
-		XXXXXXXXXXXXX
+		The trust settings (which relate to the operations that a certificate is allowed to be used for) can be changed after a certificate is created or added to the database. This is especially useful for CA certificates, but it can be performed for any type of certificate.
+	</para>
+<programlisting language="Bash">certutil -M -n certificate-name -t trust-args -d directory</programlisting>
+	<para>
+		For example:
+	</para>
+<programlisting language="Bash">$ certutil -M -n "My CA Certificate" -d . -t "CTu,CTu,CTu"</programlisting>
+
+	<para><command>Printing the Certificate Chain</command></para>
+	<para>
+		Certificates can be issued in <emphasis>chains</emphasis> because every certificate authority itself has a certificate; when a CA issues a certificate, it essentially stamps that certificate with its own fingerprint. The <option>-O</option> prints the full chain of a certificate, going from the intial CA (the root CA) through ever intermediary CA to the actual certificate. For example, for an email certificate with two CAs in the chain:
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+<programlisting language="Bash">$ certutil -d . -O -n "jsmith@example.com"
+"Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA]
+
+  "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA]
+
+    "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member]</programlisting>
+
+	<para><command>Resetting a Token</command></para>
+	<para>
+		The device which stores certificates -- both external hardware devices and internal software databases -- can be blanked and reused. This operation is performed on the device which stores the data, not directly on the security databases, so the location must be referenced through the token name (<option>-h</option>) as well as any directory path. If there is no external token used, the default value is internal.
+	</para>
+<programlisting language="Bash">certutil -T -d directory -h token-name -0 security-officer-password</programlisting>
+	<para>
+		Many networks have dedicated personnel who handle changes to security tokens (the security officer). This person must supply the password to access the specified token. For example:
+	</para>
+<programlisting language="Bash">$ certutil -T -d . -h nethsm -0 secret</programlisting>
 
 	<para><command>Upgrading or Merging the Security Databases</command></para>
 	<para>
-		XXXXXXXXXXXXX
+		Some networks or applications may be using older versions of the certificate database, like a <filename>cert7.db</filename> database, or there may be multiple certificate databases in use. Databases can be upgraded to a new version using the <option>--upgrade-merge</option> command option or merged with other databases using the <option>---merge</option> command.
+	</para>
+	<para>
+		The <option>--upgrade-merge</option> command must give information about the original database and then use the standard arguments (like <option>-d</option>) to give the information about the new databases. The command also requires information that the tool uses for the process to upgrade and write over the original database.
+	</para>
+<programlisting language="Bash">certutil --upgrade-merge -d directory [-P dbprefix] --source-dir directory --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file]</programlisting>
+	<para>
+		For example:
+	</para>
+<programlisting language="Bash">$ certutil --upgrade-merge -d . --source-dir /opt/my-app/alias/ --source-prefix serverapp- --upgrade-id 1 --upgrade-token-name internal</programlisting>
+	<para>
+		The <option>--merge</option> command only requires information about the location of the original database; since it doesn't change the format of the database, it can write over information without performing interim step.
+	</para>
+<programlisting language="Bash">certutil --merge -d directory [-P dbprefix] --source-dir directory --source-prefix dbprefix [-@ password-file]</programlisting>
+	<para>
+		For example:
 	</para>
-<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+<programlisting language="Bash">$ certutil --merge -d . --source-dir /opt/my-app/alias/ --source-prefix serverapp-</programlisting>
 
 	<para><command>Running certutil Commands from a Batch File</command></para>
 	<para>