beginning to add in pk12util draft

1 files changed, 181 insertions, 0 deletions

diff --git a/pk12util.xml b/pk12util.xml
new file mode 100644
index 0000000..8e83b87
--- /dev/null
+++ b/pk12util.xml
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+-->
+<refentry>
+
+  <refentryinfo>
+    <date>August 2010</date>
+<!-- this should be one word -->
+	<refentrytitle>pk12util</refentrytitle>
+<!-- end  -->
+  </refentryinfo>
+
+  <refmeta>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>pk12util</refname>
+    <refpurpose>Export and import keys and certificate to or from a PKCS #12 file and the NSS database</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>pk12util</command>
+      <arg><option>-i<replaceable>p12file</replaceable></option></arg>
+      <arg><option>-l <replaceable>p12file</replaceable></option></arg>
+      <arg><option>-o <replaceable>p12file</replaceable></option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection id="description">
+    <title>Description</title>
+    <para><command>pk12util</command> is an interactive command-line tool which can be used to export keys and certificates from an nss database to a pkcs #12 file or import from one such file into the database. It can also list the contents of a pkcs #12 file. </para>
+  </refsection>
+  
+  <refsection id="options">
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>-i </option> <replaceable>p12file</replaceable></term>
+        <listitem><simpara>Import keys and certs from p12file into the nss database.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-l </option> <replaceable>p12file</replaceable></term>
+        <listitem><simpara>List the keys and certs in p12file.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-o </option> <replaceable>p12file</replaceable></term>
+        <listitem><simpara>Export keys and certs from the nss database to 12file.</simpara></listitem>
+      </varlistentry>
+    
+      <varlistentry>
+        <term><option>-n </option> <replaceable>certname</replaceable></term>
+        <listitem><simpara>Specify the nickname of the cert and private key to export.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-d </option> <replaceable>dir</replaceable></term>
+        <listitem><simpara>Specify the database directory into which to import to or export from certificates and keys. 
+          If not specified the directory defaults to $HOME/.netscape (when $HOME exists in the environment), 
+          or to ./.netscape (when $HOME does not exist in the environment.</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-P </option> <replaceable>prefix</replaceable></term>
+        <listitem><simpara>Specify the prefix used on the cert8.db and key3.db files 
+          (for example, my_cert8.db and my_key3.db). This option is provided as a special case. 
+          Changing the names of the certificate and key databases is not recommended.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-h </option> <replaceable>tokenname</replaceable></term>
+        <listitem><simpara>Specify the name of the token to import into or export from.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-v </option></term>
+        <listitem><simpara>Enable debug logging when importing.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-k </option> <replaceable>slotPasswordFile</replaceable></term>
+        <listitem><simpara>Specify the text file containing the slot's password.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-K </option> <replaceable>slotPassword</replaceable></term>
+        <listitem><simpara>Specify the slot's password.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-w </option> <replaceable>p12filePasswordFile</replaceable></term>
+        <listitem><simpara>Specify the text file containing the pkcs #12 file password.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-W </option> <replaceable>p12filePassword</replaceable></term>
+        <listitem><simpara>Specify the pkcs #12 file password.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-c </option> <replaceable>keyCipher</replaceable></term>
+        <listitem><simpara>Specify the key encryption algorithm.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-C </option> <replaceable>certCipher</replaceable></term>
+        <listitem><simpara>Specify the key cert (overall package) encryption algorithm.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-m | --key-len</option> <replaceable>keyLength</replaceable></term>
+        <listitem><simpara>Specify the desired length of the symmetric key to be used to encrypt the private key.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-m | --cert-key-len</option> <replaceable>certKeyLength</replaceable></term>
+        <listitem><simpara>Specify the desired length of the symmetric key to be used to encrypt the certificates and other meta-data.</simpara></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection id="basic-usage">
+    <title>Basic Usage</title>
+    <para>The <option>following</option> example will do <emphasis>this</emphasis> and that
+	</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>
+		sentence #2
+	</para>
+	<para>
+		sentence #3
+	</para>
+  </refsection>
+
+  <refsection id="examples">
+    <title>Extended Examples</title>
+    <para>The following example will do this and that
+    </para>
+<programlisting>% blah blah</programlisting>
+  </refsection>
+
+  <refsection id="seealso">
+    <title>See Also</title>
+    <para> % reference to other tool here %</para>
+  </refsection>
+
+<!-- don't change -->
+  <refsection id="resources">
+    <title>Additional Resources</title>
+    <para>NSS is maintained in conjunction with PKI and security-related projects through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, with a project wiki at <ulink url="http://pki.fedoraproject.org/wiki/">http://pki.fedoraproject.org/wiki/</ulink>. </para>
+	<para>For information specifically about NSS, the NSS project wiki is located at <ulink url="http://www.mozilla.org/projects/security/pki/nss/">http://www.mozilla.org/projects/security/pki/nss/</ulink>. The NSS site relates directly to NSS code changes and releases.</para>
+	<para>Mailing lists: pki-devel@redhat.com and pki-users@redhat.com</para>
+	<para>IRC: Freenode at #dogtag-pki</para>
+  </refsection>
+
+<!-- fill in your name first; keep the other names for reference -->
+  <refsection id="authors">
+    <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>.
+	</para>
+  </refsection>
+
+<!-- don't change -->
+  <refsection id="copyright">
+    <title>Copyright</title>
+    <para>(c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2.</para>
+  </refsection>
+
+</refentry>