<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2012  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
    <date>November 15, 2012</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-certgen</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-certgen</refname>
    <refpurpose>X509 Certificate generation tool for use with b10-cmdctl</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2012</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-certgen</command>
        <group choice="opt">
          <arg choice="[OPTION]..."><option>-</option></arg>
        </group>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-certgen</command> tool validates, creates, or
      updates a self-signed X509 certificate for use in b10-cmdctl.
    </para>

    <para>
      The connection between <command>bindctl</command> and
      <command>b10-cmdctl</command> is done over HTTPS, and therefore
      <command>b10-cmdctl</command> needs a certificate. Since these
      certificates have expiry dates, they also need to be regenerated at
      some point.

      There are many tools to do so, but for ease of use, <command>
      b10-certgen</command> can create a simple self-signed certificate.

      By default, it will not create anything, but it will merely check an
      existing certificate (if not specified, cmdctl-certfile.pem, in the
      current working directory). And print whether it is valid, and
      whether it would update if the option '-w' is given.

      With that option, the certificate could then be replaced by a newly
      created one. If the certificate is still valid, it would still not
      be overwritten (however, if it is found to be invalid, for example
      because it has expired, it would create a new one).

      A new certificate is always created if the certificate file does
      not exist, or if creation is forced (with the -f option).
    </para>
  </refsect1>

  <refsect1>
    <title>ARGUMENTS</title>

    <para>The arguments are as follows:</para>

    <variablelist>

      <varlistentry>
        <term>
          <option>-c <replaceable>file</replaceable></option>,
          <option>--certfile=<replaceable>file</replaceable></option>
        </term>
        <listitem>
          <para>
            File to read the certificate from, or write the certificate to.
            If <option>-w</option> and <option>-c</option> are used,
            <option>-k</option> is mandatory as well.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-f</option>,
          <option>--force</option>
        </term>
        <listitem>
          <para>
            Force updating of certificate when <option>-w</option> is used,
            even if the existing certificate is still valid.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-h</option>,
          <option>--help</option>
        </term>
        <listitem>
          <para>
            Print the command line arguments and exit.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-k <replaceable>file</replaceable></option>,
          <option>--keyfile=<replaceable>file</replaceable></option>
        </term>
        <listitem>
          <para>
            File to write the private key to. This option is only valid when <option>-w</option> is used, and if this option is used, <option>-c</option> is mandatory as well.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-w</option>,
          <option>--write</option>
        </term>
        <listitem>
          <para>
            Check the given certificate file. If it does not exist, a new
            private key and certificate are created. If it does exist, the
            certificate is validated. If it is not valid (for instance
            because it has expired), it is overwritten with a newly created
            certificate. If it is valid, nothing happens (use
            <option>-f</option> to force an update in that case).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-q</option>,
          <option>--quiet</option>
        </term>
        <listitem>
          <para>
            Don't print informational messages (only command-line errors are
            printed). Useful in scripts when only the return code is needed.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>b10-certgen</command> tool was first implemented
      in November 2012 for the ISC BIND 10 project.
    </para>
  </refsect1>

  <refsect1>
    <title>EXAMPLE</title>
    <para>
      To update an expired certificate in BIND 10 that has been installed to
      /usr/local:
      <screen>
$> cd /usr/local/etc/bind10-devel/

$> b10-certgen
cmdctl-certfile.pem failed to verify: certificate has expired
Running with -w would overwrite the certificate

$> b10-certgen --write
cmdctl-certfile.pem failed to verify: certificate has expired
Creating key file cmdctl-keyfile.pem
Creating certificate file cmdctl-certfile.pem

$> b10-certgen --write
cmdctl-certfile.pem is valid
Not creating a new certificate (use -f to force)
      </screen>
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->
