/mandos/trunk

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY COMMANDNAME "mandos-keygen">

<!ENTITY TIMESTAMP "2019-07-18">

<!ENTITY % common SYSTEM "common.ent">

%common;

]>

<refentry xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>

    <title>Mandos Manual</title>

    <!-- NWalsh’s docbook scripts use this to generate the footer: -->

    <productname>Mandos</productname>

    <productnumber>&version;</productnumber>

    <date>&TIMESTAMP;</date>

    <authorgroup>

      <author>

	<firstname>Björn</firstname>

	<surname>Påhlsson</surname>

	<address>

	  <email>belorn@recompile.se</email>

	</address>

      </author>

      <author>

	<firstname>Teddy</firstname>

	<surname>Hogeborn</surname>

	<address>

	  <email>teddy@recompile.se</email>

	</address>

      </author>

    </authorgroup>

    <copyright>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <year>2011</year>

      <year>2012</year>

      <year>2013</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2017</year>

      <year>2018</year>

      <year>2019</year>

      <holder>Teddy Hogeborn</holder>

      <holder>Björn Påhlsson</holder>

    </copyright>

    <xi:include href="legalnotice.xml"/>

  </refentryinfo>

  <refmeta>

    <refentrytitle>&COMMANDNAME;</refentrytitle>

    <manvolnum>8</manvolnum>

  </refmeta>

  <refnamediv>

    <refname><command>&COMMANDNAME;</command></refname>

    <refpurpose>

      Generate key and password for Mandos client and server.

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group>

	<arg choice="plain"><option>--dir

	<replaceable>DIRECTORY</replaceable></option></arg>

	<arg choice="plain"><option>-d

	<replaceable>DIRECTORY</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--type

	<replaceable>KEYTYPE</replaceable></option></arg>

	<arg choice="plain"><option>-t

	<replaceable>KEYTYPE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--length

	<replaceable>BITS</replaceable></option></arg>

	<arg choice="plain"><option>-l

	<replaceable>BITS</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--subtype

	<replaceable>KEYTYPE</replaceable></option></arg>

	<arg choice="plain"><option>-s

	<replaceable>KEYTYPE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--sublength

	<replaceable>BITS</replaceable></option></arg>

	<arg choice="plain"><option>-L

	<replaceable>BITS</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--name

	<replaceable>NAME</replaceable></option></arg>

	<arg choice="plain"><option>-n

	<replaceable>NAME</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--email

	<replaceable>ADDRESS</replaceable></option></arg>

	<arg choice="plain"><option>-e

	<replaceable>ADDRESS</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--comment

	<replaceable>TEXT</replaceable></option></arg>

	<arg choice="plain"><option>-c

	<replaceable>TEXT</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--expire

	<replaceable>TIME</replaceable></option></arg>

	<arg choice="plain"><option>-x

	<replaceable>TIME</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--tls-keytype

	<replaceable>KEYTYPE</replaceable></option></arg>

	<arg choice="plain"><option>-T

	<replaceable>KEYTYPE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--force</option></arg>

	<arg choice="plain"><option>-f</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--password</option></arg>

	<arg choice="plain"><option>-p</option></arg>

	<arg choice="plain"><option>--passfile

	<replaceable>FILE</replaceable></option></arg>

	<arg choice="plain"><option>-F</option>

	<replaceable>FILE</replaceable></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--dir

	<replaceable>DIRECTORY</replaceable></option></arg>

	<arg choice="plain"><option>-d

	<replaceable>DIRECTORY</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--name

	<replaceable>NAME</replaceable></option></arg>

	<arg choice="plain"><option>-n

	<replaceable>NAME</replaceable></option></arg>

      </group>

      <group>

	<arg choice="plain"><option>--no-ssh</option></arg>

	<arg choice="plain"><option>-S</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--help</option></arg>

	<arg choice="plain"><option>-h</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--version</option></arg>

	<arg choice="plain"><option>-v</option></arg>

      </group>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <para>

      <command>&COMMANDNAME;</command> is a program to generate the

      TLS and OpenPGP keys used by

      <citerefentry><refentrytitle>mandos-client</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are

      normally written to /etc/keys/mandos for later installation into

      the initrd image, but this, and most other things, can be

      changed with command line options.

    </para>

    <para>

      This program can also be used with the

      <option>--password</option> or <option>--passfile</option>

      options to generate a ready-made section for

      <filename>clients.conf</filename> (see

      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

      <manvolnum>5</manvolnum></citerefentry>).

    </para>

  </refsect1>

  <refsect1 id="purpose">

    <title>PURPOSE</title>

    <para>

      The purpose of this is to enable <emphasis>remote and unattended

      rebooting</emphasis> of client host computer with an

      <emphasis>encrypted root file system</emphasis>.  See <xref

      linkend="overview"/> for details.

    </para>

  </refsect1>

  <refsect1 id="options">

    <title>OPTIONS</title>

    <variablelist>

      <varlistentry>

	<term><option>--help</option></term>

	<term><option>-h</option></term>

	<listitem>

	  <para>

	    Show a help message and exit

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--dir

	<replaceable>DIRECTORY</replaceable></option></term>

	<term><option>-d

	<replaceable>DIRECTORY</replaceable></option></term>

	<listitem>

	  <para>

	    Target directory for key files.  Default is <filename

	    class="directory">/etc/keys/mandos</filename>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--type

	<replaceable>TYPE</replaceable></option></term>

	<term><option>-t

	<replaceable>TYPE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP key type.  Default is <quote>RSA</quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--length

	<replaceable>BITS</replaceable></option></term>

	<term><option>-l

	<replaceable>BITS</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP key length in bits.  Default is 4096.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--subtype

	<replaceable>KEYTYPE</replaceable></option></term>

	<term><option>-s

	<replaceable>KEYTYPE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP subkey type.  Default is <quote>RSA</quote>

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--sublength

	<replaceable>BITS</replaceable></option></term>

	<term><option>-L

	<replaceable>BITS</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP subkey length in bits.  Default is 4096.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--email

	<replaceable>ADDRESS</replaceable></option></term>

	<term><option>-e

	<replaceable>ADDRESS</replaceable></option></term>

	<listitem>

	  <para>

	    Email address of key.  Default is empty.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--comment

	<replaceable>TEXT</replaceable></option></term>

	<term><option>-c

	<replaceable>TEXT</replaceable></option></term>

	<listitem>

	  <para>

	    Comment field for key.  Default is empty.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--expire

	<replaceable>TIME</replaceable></option></term>

	<term><option>-x

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Key expire time.  Default is no expiration.  See

	    <citerefentry><refentrytitle>gpg</refentrytitle>

	    <manvolnum>1</manvolnum></citerefentry> for syntax.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--tls-keytype

	<replaceable>KEYTYPE</replaceable></option></term>

	<term><option>-T

	<replaceable>KEYTYPE</replaceable></option></term>

	<listitem>

	  <para>

	    TLS key type.  Default is <quote>ed25519</quote>

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--force</option></term>

	<term><option>-f</option></term>

	<listitem>

	  <para>

	    Force overwriting old key.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--password</option></term>

	<term><option>-p</option></term>

	<listitem>

	  <para>

	    Prompt for a password and encrypt it with the key already

	    present in either <filename>/etc/keys/mandos</filename> or

	    the directory specified with the <option>--dir</option>

	    option.  Outputs, on standard output, a section suitable

	    for inclusion in <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

	    >8</manvolnum></citerefentry>.  The host name or the name

	    specified with the <option>--name</option> option is used

	    for the section header.  All other options are ignored,

	    and no key is created.  Note: white space is stripped from

	    the beginning and from the end of the password; See <xref

	    linkend="bugs"/>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--passfile

	<replaceable>FILE</replaceable></option></term>

	<term><option>-F

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    The same as <option>--password</option>, but read from

	    <replaceable>FILE</replaceable>, not the terminal, and

	    white space is not stripped from the password in any way.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--no-ssh</option></term>

	<term><option>-S</option></term>

	<listitem>

	  <para>

	    When <option>--password</option> or

	    <option>--passfile</option> is given, this option will

	    prevent <command>&COMMANDNAME;</command> from calling

	    <command>ssh-keyscan</command> to get an SSH fingerprint

	    for this host and, if successful, output suitable config

	    options to use this fingerprint as a

	    <option>checker</option> option in the output.  This is

	    otherwise the default behavior.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="overview">

    <title>OVERVIEW</title>

    <xi:include href="overview.xml"/>

    <para>

      This program is a small utility to generate new TLS and OpenPGP

      keys for new Mandos clients, and to generate sections for

      inclusion in <filename>clients.conf</filename> on the server.

    </para>

  </refsect1>

  <refsect1 id="exit_status">

    <title>EXIT STATUS</title>

    <para>

      The exit status will be 0 if a new key (or password, if the

      <option>--password</option> option was used) was successfully

      created, otherwise not.

    </para>

  </refsect1>

  <refsect1 id="environment">

    <title>ENVIRONMENT</title>

    <variablelist>

      <varlistentry>

	<term><envar>TMPDIR</envar></term>

	<listitem>

	  <para>

	    If set, temporary files will be created here. See

	    <citerefentry><refentrytitle>mktemp</refentrytitle>

	    <manvolnum>1</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="files">

    <title>FILES</title>

    <para>

      Use the <option>--dir</option> option to change where

      <command>&COMMANDNAME;</command> will write the key files.  The

      default file names are shown here.

    </para>

    <variablelist>

      <varlistentry>

	<term><filename>/etc/keys/mandos/seckey.txt</filename></term>

	<listitem>

	  <para>

	    OpenPGP secret key file which will be created or

	    overwritten.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><filename>/etc/keys/mandos/pubkey.txt</filename></term>

	<listitem>

	  <para>

	    OpenPGP public key file which will be created or

	    overwritten.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>

	<listitem>

	  <para>

	    Private key file which will be created or overwritten.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>

	<listitem>

	  <para>

	    Public key file which will be created or overwritten.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><filename class="directory">/tmp</filename></term>

	<listitem>

	  <para>

	    Temporary files will be written here if

	    <varname>TMPDIR</varname> is not set.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

    <para>

      The <option>--password</option>/<option>-p</option> option

      strips white space from the start and from the end of the

      password before using it.  If this is a problem, use the

      <option>--passfile</option> option instead, which does not do

      this.

    </para>

    <xi:include href="bugs.xml"/>

  </refsect1>

  <refsect1 id="example">

    <title>EXAMPLE</title>

    <informalexample>

      <para>

	Normal invocation needs no options:

      </para>

      <para>

	<userinput>&COMMANDNAME;</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Create key in another directory and of another type.  Force

	overwriting old key files:

      </para>

      <para>

<!-- do not wrap this line -->

<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Prompt for a password, encrypt it with the keys in <filename

	class="directory">/etc/keys/mandos</filename> and output a

	section suitable for <filename>clients.conf</filename>.

      </para>

      <para>

	<userinput>&COMMANDNAME; --password</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Prompt for a password, encrypt it with the keys in the

	<filename>client-key</filename> directory and output a section

	suitable for <filename>clients.conf</filename>.

      </para>

      <para>

<!-- do not wrap this line -->

<userinput>&COMMANDNAME; --password --dir client-key</userinput>

      </para>

    </informalexample>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

      The <option>--type</option>, <option>--length</option>,

      <option>--subtype</option>, and <option>--sublength</option>

      options can be used to create keys of low security.  If in

      doubt, leave them to the default values.

    </para>

    <para>

      The key expire time is <emphasis>not</emphasis> guaranteed to be

      honored by <citerefentry><refentrytitle>mandos</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>.

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>intro</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>gpg</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

      <manvolnum>5</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos-client</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry>

    </para>

  </refsect1>

</refentry>

<!-- Local Variables: -->

<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->

<!-- time-stamp-end: "[\"']>" -->

<!-- time-stamp-format: "%:y-%02m-%02d" -->

<!-- End: -->