path: root/certutil.xml

<?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>14 August, 2008</date>
<!-- this should be one word -->
	<refentrytitle>certutil</refentrytitle>
<!-- end  -->
    <manvolnum>1</manvolnum>
  </refentryinfo>

  <refnamediv>
    <refname>certutil</refname>
    <refpurpose>Manage keys and certificate in the the NSS database.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>certutil</command>
      <arg><replaceable>options</replaceable></arg>
      <arg>[<replaceable>arguments</replaceable>]</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection id="description">
    <title>Description</title>

    <para>The Certificate Database Tool, <command>certutil</command>, is a command-line utility that can create and modify <filename>cert8.db</filename> and <filename>key3.db</filename> database files. It can also list, generate, modify, or delete certificates within the <filename>cert8.db</filename> file and create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the <filename>key3.db</filename> file.
	</para>
	<para>
The key and certificate management process generally begins with creating keys in the key database, then generating and managing certificates in the certificate database. This document discusses certificate and key database management. For information security module database management, see the <command>modutil</command> manpages.
	</para>

  </refsection>
  
  <refsection id="options">
    <title>Options and Arguments</title>
	<para>
		Running <command>certutil</command> always requires one (and only one) option to specify the type of certificate operation. Each option may take arguments, anywhere from none to multiple arguments. To see the arguments available for each option, run the command option and <option>-H</option>.
	</para>
   	<para><command>Options</command></para> 
   	<para>Options specify an action and are uppercase. </para>
    <variablelist>
      <varlistentry>
        <term>-N example</term>
        <listitem><para>Create new certificate and key databases.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-S </term>
        <listitem><para>Create an individual certificate and add it to a certificate database.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-R</term>
        <listitem><para>Create a certificate request file.</para></listitem>
      </varlistentry>
    
      <varlistentry>
        <term>-C </term>
        <listitem><para>Create a new binary certificate file from a binary certificate request file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-G </term>
        <listitem><para>Generate a new public and private key pair within a key database. The key database should already exist; if one is not present, this option will initialize one by default. Some smart cards (for example, the Litronic card) can store only one key pair. If you create a new key pair for such a card, the previous pair is overwritten.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-F</term>
        <listitem><para>Delete a private key from a key database. Specify the key to delete with the -n argument. Specify the database from which to delete the key with the -d argument. Use the -k argument to specify explicitly whether to delete a DSA or an RSA key. If you don't use the -k argument, the option looks for an RSA key matching the specified nickname. When you delete keys, be sure to also remove any certificates associated with those keys from the certificate database, by using -D. Some smart cards (for example, the litronic card) do not let you remove a public key you have generated. In such a case, only the private key is deleted from the key pair. You can display the public key with the command certutil -K -h tokenname. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-K prefix</term>
        <listitem><para>List the keyID of keys in the key database. A keyID is the modulus of the RSA key or the publicValue of the DSA key. IDs are displayed in hexadecimal ("0x" is not shown).</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-A </term>
        <listitem><para>Add an existing certificate to a certificate database. The certificate database should already exist; if one is not present, this option will initialize one by default. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-D </term>
        <listitem><para>Delete a certificate from the certificate database.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-L </term>
        <listitem><para>List all the certificates, or display information about a named certificate, in a certificate database.
        Use the -h tokenname argument to specify the certificate database on a particular hardware or software token.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-V </term>
        <listitem><para>Check the validity of a certificate and its attributes.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-M </term>
        <listitem><para>Modify a certificate's trust attributes using the values of the -t argument.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-H </term>
        <listitem><para>Display a list of the options and arguments used by the Certificate Database Tool.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-W </term>
        <listitem><para>Change the password to a key database.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-U certCipher</term>
        <listitem><para>List all available modules or print a single named module.</para></listitem>
      </varlistentry>
	</variablelist>

	<para><command>Arguments</command></para>
	<para>Option arguments modify an action and are lowercase.</para>
	<variablelist>
      <varlistentry>
        <term>-a keyLength</term>
        <listitem><para>Use ASCII format or allow the use of ASCII format for input or output. This formatting follows RFC #1113. 
        For certificate requests, ASCII output defaults to standard output unless redirected.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-b validity-time</term>
        <listitem><para>Specify a time at which a certificate is required to be valid. 
        Use when checking certificate validity with the -V option. The format of the validity-time argument is 
        "YYMMDDHHMMSS[+HHMM|-HHMM|Z]". Specifying seconds (SS) is optional. When specifying an explicit time, 
        use "YYMMDDHHMMSSZ". When specifying an offset time, use "YYMMDDHHMMSS+HHMM" or "YYMMDDHHMMSS-HHMM". 
        If this option is not used, the validity check defaults to the current system time.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-c issuer</term>
        <listitem><para>Identify the certificate of the CA from which a new certificate will derive its authenticity. 
        Use the exact nickname or alias of the CA certificate, or use the CA's email address. Bracket the issuer string 
        with quotation marks if it contains spaces. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-d directory</term>
        <listitem><para>Specify the database directory containing the certificate and key database files. 
<!--
        On Unix the Certificate Database Tool defaults to $HOME/.netscape (that is, ~/.netscape). 
        On Windows NT the default is the current directory.
-->
        The cert8.db and key3.db database files must reside in the same directory. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-P dbPrefix</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-e dbprefix</term>
        <listitem><para>Check a certificate's signature during the process of validating a certificate.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-f password-file</term>
        <listitem><para>Specify a file that will automatically supply the password to include in a certificate 
        or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent 
        unauthorized access to this file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-g keysize</term>
        <listitem><para>Set a key size to use when generating new public and private key pairs. The minimum is 256 bits and the maximum is 1024 bits. The default is 1024 bits. Any size between the minimum and maximum is allowed.</para></listitem>
      </varlistentry>


      <varlistentry>
        <term>-h tokenname</term>
        <listitem><para>Specify the name of a token to use or act on. Unless specified otherwise the default token is an internal slot (specifically, internal slot 2). This slot can also be explicitly named with the string "internal". An internal slots is a virtual slot maintained in software, rather than a hardware device. Internal slot 2 is used by key and certificate services. Internal slot 1 is used by cryptographic services.</para></listitem>
      </varlistentry>

     <varlistentry>
        <term>-i cert|cert-request-file</term>
        <listitem><para>Specify a specific certificate or a certificate request file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-k rsa|dsa|all</term>
        <listitem><para>Specify the type of a key. The valid options are RSA, DSA or both. The default value is rsa. Specifying the type of key can avoid mistakes caused by duplicate nicknames.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-l </term>
        <listitem><para>Display detailed information when validating a certificate with the -V option.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-m serial-number</term>
        <listitem><para>Assign a unique serial number to a certificate being created. This operation should be performed by a CA. The default serial number is 0 (zero). Serial numbers are limited to integers. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-n nickname</term>
        <listitem><para>Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate. Bracket the nickname string with quotation marks if it contains spaces.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-o output-file</term>
        <listitem><para>Specify the output file name for new certificates or binary certificate requests. Bracket the output-file string with quotation marks if it contains spaces. If this argument is not used the output destination defaults to standard output.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-p phone</term>
        <listitem><para>Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-q pqgfile</term>
        <listitem><para>Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, the Key Database Tool generates its own PQG value. PQG files are created with a separate DSA utility.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-r </term>
        <listitem><para>Display a certificate's binary DER encoding when listing information about that certificate with the -L option.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-s subject</term>
        <listitem><para>Identify a particular certificate owner for new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces. The subject identification format follows RFC #1485.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-t trustargs</term>
        <listitem><para>Specify the trust attributes to modify in an existing certificate or to apply to a certificate when creating it or adding it to a database.
        There are three available trust categories for each certificate, expressed in the order <emphasis>SSL, email, object signing</emphasis>. In each category position, use none, any, or all
	of the attribute codes: 
	</para>
	<para>
		<command>p</command> - Valid peer
	</para>
	<para>
		<command>P</command> - Trusted peer (implies p)
	</para>
	<para>
		<command>c</command> - Valid CA
	</para>
	<para>
		<command>T</command> - Trusted CA to issue client certificates (implies c)
	</para>
	<para>
		<command>C</command> - Trusted CA to issue server certificates (SSL only) (implies c)
	</para>
	<para>
		<command>u</command> - Certificate can be used for authentication or signing
	</para>
	<para>
		<command>w</command> - Send warning (use with other attributes to include a warning when the certificate is used in that context)
	</para>
	<para>
		The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks. For example:
	</para>
<programlisting>-t "TCu,Cu,Tuw"</programlisting>
	<para>
	Use the -L option to see a list of the current certificates and trust attributes in a certificate database. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-u certusage</term>
        <listitem><para>Specify a usage context to apply when validating a certificate with the -V option.</para><para>The contexts are the following:</para><para>C (as an SSL client)</para><para>
        V (as an SSL server), 
        S (as an email signer), 
        R (as an email recipient)
         </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-v xxxxxxx</term>
        <listitem><para>Set the number of months a new certificate will be valid. 
        The validity period begins at the current system time unless an offset is added or 
        subtracted with the -w option. If this argument is not used, the default validity 
        period is three months. When this argument is used, the default three-month period 
        is automatically added to any value given in the valid-month argument. For example, 
        using this option to set a value of 3 would cause 3 to be added to the three-month 
        default, creating a validity period of six months. You can use negative values to 
        reduce the default period. For example, setting a value of -2 would subtract 2 from 
        the default and create a validity period of one month.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-w xxxxxxx</term>
        <listitem><para>Set an offset from the current system time, in months, 
        for the beginning of a certificate's validity period. Use when creating 
        the certificate or adding it to a database. Express the offset in integers, 
        using a minus sign (-) to indicate a negative offset. If this argument is 
        not used, the validity period begins at the current system time. The length 
        of the validity period is set with the -v argument. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-x </term>
        <listitem><para>Use the Certificate Database Tool to generate the signature 
        for a certificate being created or added to a database, rather than obtaining 
        a signature from a separate CA.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-y xxxxxxx</term>
        <listitem><para>Set an alternate exponent value to use in generating 
        a new RSA public key for the database, instead of the default value of 65537. 
        The available alternate values are 3 and 17.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-z noise-file</term>
        <listitem><para>Read a seed value from the specified binary file to 
        use in generating a new RSA private and public key pair. This argument 
        makes it possible to use hardware-generated seed values and unnecessary 
        to manually create a value from the keyboard. The minimum file size is 20 bytes.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-1 </term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-2 </term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-3 </term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-4 </term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-5 </term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-6 </term>
        <listitem><para>yyyyyyyy</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-7 emailAddrs</term>
        <listitem><para>yyyyyyyy.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>-8 dns-names</term>
        <listitem><para>yyyyyyyy.</para></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>