adding in more examples

1 files changed, 234 insertions, 17 deletions

diff --git a/certutil.xml b/certutil.xml
index 928951c..ab72e3e 100644
--- a/certutil.xml
+++ b/certutil.xml
@@ -558,32 +558,249 @@ the default and create a validity period of one month.</para></listitem>
   </refsection>
 
   <refsection id="basic-usage">
-    <title>Basic Usage</title>
-    <para>The <option>following</option> example will do <emphasis>this</emphasis> and that
+    <title>Usage and Examples</title>
+	<para>
+		Most of the command options in the examples listed here have more arguments available. The arguments included in these examples are the most common ones or are used to illustrate a specific scenario. Use the <option>-H</option> option to show the complete list of arguments for each command option.
 	</para>
-<programlisting>% blah blah
-     line 2
-   line 3</programlisting>
-<!-- i'm working on a decent way to do embedded subsections; for now, just use a bold tag to show a new section -->
-	<para><command>Subsection</command></para>
+	<para><command>Creating New Security Databases</command></para>
 	<para>
-		sentence #2
+		Certificates, keys, and security modules related to managing certificates are stored in three related databases:
 	</para>
 	<para>
-		sentence #3
+		* cert8.db
 	</para>
-  </refsection>
+	<para>
+		* key3.db
+	</para>
+	<para>
+		* secmod.db
+	</para>
+	<para>
+		These databases must be created before certificates or keys can be generated.
+	</para>
+<programlisting>certutil -N -d &lt;directory></programlisting>
+
+	<para><command>Creating a Certificate Request</command></para>
+	<para>
+		A certificate request contains most or all of the information that is used to generate the final certificate. This request is submitted separately to a certificate authority and is then approved by some mechanism (automatically or by human review). Once the request is approved, then the certificate is generated.
+	</para>
+<programlisting language="Bash">$ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s subject [-h tokenname] -d certdir [-p phone] [-o output-file] [-a]</programlisting>
+	<para>
+		The <option>-R</option> command options requires four arguments:
+	</para>
+	<para>
+		* <option>-k</option> to specify either the key type to generate or, when renewing a certificate, the exisitng key pair to use
+	</para>
+	<para>
+		* <option>-g</option> to set the keysize of the key to generate
+	</para>
+	<para>
+		* <option>-s</option> to set the subject name of the certificate
+	</para>
+	<para>
+		* <option>-d</option> to give the security database directory
+	</para>
+	<para>
+		The new certificate request can be output in ASCII format (<option>-a</option>) or can be written to a specified file (<option>-o</option>).
+	</para>
+	<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
+
+Generating key.  This may take a few moments...
+
+
+Certificate request generated by Netscape certutil
+Phone: 650-555-0123
+
+Common Name: John Smith
+Email: (not specified)
+Organization: Example Corp
+State: California
+Country: US
+
+-----BEGIN NEW CERTIFICATE REQUEST-----
+MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW
+MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw
+EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ
+KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J
+CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny
+qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB
+1hP9Gg==
+-----END NEW CERTIFICATE REQUEST-----</programlisting>
+
+	<para><command>Creating a Certificate</command></para>
+	<para>
+		A valid certificate must be issued by a trusted CA. This can be done by specifying a CA certificate (<option>-c</option>) that is stored in the certificate database. If a CA key pair is not available, you can create a self-signed certificate using the <option>-x</option> argument with the <option>-S</option> command option.
+	</para>
+<programlisting language="Bash">$ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer |-x] -t trustargs -d directory [-m serial-number] [-v valid-months] [-w offset-months] [-p phone] [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] [--extAIA] [--extSIA] [--extCP] [--extPM] [--extPC] [--extIA] [--extSKID]</programlisting>
+	<para>
+		The series of numbers and <option>--ext*</option> options set certificate extensions that can be added to the certificate when it is generated by the CA.
+	</para>
+	<para>
+		For example, this creates a self-signed certificate:
+	</para>
+<programlisting language="Bash">$ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650</programlisting>
+	<para>
+		From there, new certificates can reference the self-signed certificate:
+	</para>
+<programlisting language="Bash">$ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t "u,u,u" -1 -5 -6 -8 -m 730</programlisting>
+
+	<para><command>Generating a Certificate from a Certificate Request</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Generating an Email Certificate</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Generating Key Pairs</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Listing Certificates</command></para>
+	<para>
+		The <option>-L</option> command option lists all of the certificates listed in the <filename>cert8.db</filename> database. The path to the directory (<option>-d</option>) is required.
+	</para>
+<programlisting language="Bash">$ certutil -L -d .
 
-  <refsection id="examples">
-    <title>Extended Examples</title>
-    <para>The following example will do this and that
-    </para>
-<programlisting>% blah blah</programlisting>
+Certificate Nickname                                         Trust Attributes
+                                                             SSL,S/MIME,JAR/XPI
+
+CA Administrator of Instance pki-ca1's Example Domain ID     u,u,u
+TPS Administrator's Example Domain ID                        u,u,u
+Google Internet Authority                                    ,,   
+Certificate Authority - Example Domain                       CT,C,C</programlisting>
+	<para>
+		Using additional arguments with <option>-L</option> can return and print the information for a single, specific certificate. For example, the <option>-n</option> argument passes the certificate name, while the <option>-a</option> argument prints the certificate in ASCII format:
+	</para>
+<programlisting language="Bash">$ certutil -L -d . -a -n "Certificate Authority - Example Domain"
+
+-----BEGIN CERTIFICATE-----
+MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt
+cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw
+MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE
+b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI
+hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf
+Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2
+RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI
+udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2
+bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb
+3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB
+qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD
+AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/
+rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0
+LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk
+L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe
+lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX
+JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76
+bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu
+U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a
+nI7q5n1USM3eWQlVXw==
+-----END CERTIFICATE-----</programlisting>
+
+	<para><command>Listing Keys</command></para>
+	<para>
+		Keys are the orignal material used to encrypt certificate data. The keys generated for certificates are stored separately, in the <filename>key3.db</filename> database. 
+	</para>
+	<para>
+		To list all keys in the database, use the <option>-K</option> command option and the (required) <option>-d</option> argument to give the path to the directory.
+	</para>
+<programlisting language="Bash">$ certutil -K -d .
+certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services                  "
+&lt; 0> rsa      455a6673bde9375c2887ec8bf8016b3f9f35861d   Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
+&lt; 1> rsa      40defeeb522ade11090eacebaaf1196a172127df   Example Domain Administrator Cert
+&lt; 2> rsa      1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5   John Smith user cert</programlisting>
+	<para>
+		There are ways to narrow the keys listed in the search results:
+	</para>
+	<para>
+		* To return a specific key, use the <option>-n</option> <emphasis>name</emphasis> argument with the name of the key.
+	</para>
+	<para>
+		* If there are multiple security devices loaded, then the <option>-h</option> <emphasis>tokenname</emphasis> argument can search a specific token or all tokens.
+	</para>
+	<para>
+		* If there are multiple key types available, then the <option>-k</option> <emphasis>key-type</emphasis> argument can search a specific type of key, like RSA, DSA, or ECC. 
+	</para>
+
+	<para><command>Listing Security Modules</command></para>
+	<para>
+		The devices that can be used to store certificates -- both internal databases and external devices like smart cards -- are recognized and used by loading security modules. The <option>-U</option> command option lists all of the security modules listed in the <filename>secmod.db</filename> database. The path to the directory (<option>-d</option>) is required.
+	</para>
+<programlisting language="Bash">$ certutil -U -d .
+
+    slot: NSS User Private Key and Certificate Services                  
+   token: NSS Certificate DB
+
+    slot: NSS Internal Cryptographic Services                            
+   token: NSS Generic Crypto Services</programlisting>
+
+	<para><command>Adding Certificates to the Database</command></para>
+	<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>
+	<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>
+
+	<para><command>Deleting Certificates to the Database</command></para>
+	<para>
+		Certificates can be deleted from a database using the <option>-D</option> option. The only required options are to give the security database directory and to identify the certificate nickname.
+	</para>
+<programlisting language="Bash">certutil -D -d directory -n "nickname"</programlisting>
+	<para>
+		For example:
+	</para>
+<programlisting language="Bash">$ certutil -D -d . -n "my-ssl-cert"</programlisting>
+
+	<para><command>Validating Certificates</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Modifying Certificate Trust Settings</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Upgrading or Merging the Security Databases</command></para>
+	<para>
+		XXXXXXXXXXXXX
+	</para>
+<programlisting language="Bash">certutil XXXXXXXXXXXXXX</programlisting>
+
+	<para><command>Running certutil Commands from a Batch File</command></para>
+	<para>
+		A series of commands can be run sequentially from a text file with the <option>-B</option> command option. The only argument for this specifies the input file.
+	</para>
+<programlisting language="Bash">$ certutil -B -i /path/to/batch-file</programlisting>
   </refsection>
 
+
   <refsection id="seealso">
     <title>See Also</title>
-    <para> % reference to other tool here %</para>
+    <para><command>certutil</command> has arguments or operations that use features defined in several IETF RFCs.</para>
+	<para>
+		* http://tools.ietf.org/html/rfc5280
+	</para>
+	<para>
+		* http://tools.ietf.org/html/rfc1113
+	</para>
+	<para>
+		* http://tools.ietf.org/html/rfc1485
+	</para>
   </refsection>
 
 <!-- don't change -->
@@ -600,7 +817,7 @@ the default and create a validity period of one month.</para></listitem>
     <title>Authors</title>
     <para>The NSS tools were written and maintained by developers with Netscape and now with Red Hat.</para>
 	<para>
-		Authors: Elio Maldonado &lt;emaldona@redhat.com>, Deon Lackey &lt;dlackey@redhat.com>, Gerhardus Geldenhuis &lt;gerhardus.geldenhuis@gmail.com>.
+		Authors: Elio Maldonado &lt;emaldona@redhat.com>, Deon Lackey &lt;dlackey@redhat.com>.
 	</para>
   </refsection>