/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-02-09 23:23:26 UTC
  • Revision ID: teddy@recompile.se-20190209232326-z1z2kzpgfixz7iaj
Add support for using raw public keys in TLS (RFC 7250)

Since GnuTLS removed support for OpenPGP keys in TLS (RFC 6091), and
no other library supports it, we have to change the protocol to use
something else.  We choose to use "raw public keys" (RFC 7250).  Since
we still use OpenPGP keys to decrypt the secret password, this means
that each client will have two keys: One OpenPGP key and one TLS
public/private key, and the key ID of the latter key is used to
identify clients instead of the fingerprint of the OpenPGP key.

Note that this code is still compatible with GnuTLS before version
3.6.0 (when OpenPGP key support was removed).  This commit merely adds
support for using raw pulic keys instead with GnuTLS 3.6.6. or later.

* DBUS-API (Signals/ClientNotFound): Change name of first parameter
                                     from "Fingerprint" to "KeyID".
  (Mandos Client Interface/Properties/KeyID): New.
* INSTALL: Document conflict with GnuTLS 3.6.0 (which removed OpenPGP
           key support) up until 3.6.6, when support for raw public
           keys was added.  Also document new dependency of client on
           "gnutls-bin" package (for certtool).
* Makefile (run-client): Depend on TLS key files, and also pass them
                         as arguments to client.
  (keydir/tls-privkey.pem, keydir/tls-pubkey.pem): New.
  (confdir/clients.conf): Add dependency on TLS public key.
  (purge-client): Add removal of TLS key files.
* clients.conf ([foo]/key_id, [bar]/key_id): New.
* debian/control (Source: mandos/Build-Depends): Also allow
                                                 libgnutls30 (>= 3.6.6)
  (Package: mandos/Depends): - '' -
  (Package: mandos/Description): Alter description to match new
                                 design.
  (Package: mandos-client/Description): - '' -
  (Package: mandos-client/Depends): Move "gnutls-bin | openssl" to
                                    here from "Recommends".
* debian/mandos-client.README.Debian: Add --tls-privkey and
                                      --tls-pubkey options to test
                                      command.
* debian/mandos-client.postinst (create_key): Renamed to "create_keys"
                                             (all callers changed),
                                             and also create TLS key.
* debian/mandos-client.postrm (purge): Also remove TLS key files.
* intro.xml (DESCRIPTION): Describe new dual-key design.
* mandos (GnuTLS): Define different functions depending on whether
                   support for raw public keys is detected.
  (Client.key_id): New attribute.
  (ClientDBus.KeyID_dbus_property): New method.
  (ProxyClient.__init__): Take new "key_id" parameter.
  (ClientHandler.handle): Use key IDs when using raw public keys and
                          use fingerprints when using OpenPGP keys.
  (ClientHandler.peer_certificate): Also handle raw public keys.
  (ClientHandler.key_id): New.
  (MandosServer.handle_ipc): Pass key ID over the pipe IPC.  Also
                             check for key ID matches when looking up
                             clients.
  (main): Default GnuTLS priority string depends on whether we are
          using raw public keys or not.  When unpickling clients, set
          key_id if not set in the pickle.
  (main/MandosDBusService.ClientNotFound): Change name of first
                                           parameter from
                                           "Fingerprint" to "KeyID".
* mandos-clients.conf.xml (OPTIONS): Document new "key_id" option.
  (OPTIONS/secret): Mention new key ID matchning.
  (EXPANSION/RUNTIME EXPANSION): Add new "key_id" option.
  (EXAMPLE): - '' -
* mandos-ctl (tablewords, main/keywords): Add new "KeyID" property.
* mandos-keygen: Create TLS key files.  New "--tls-keytype" (-T)
                 option.  Alter help text to be more clear about key
                 types.  When in password mode, also output "key_id"
                 option.
* mandos-keygen.xml (SYNOPSIS): Add new "--tls-keytype" (-T) option.
  (DESCRIPTION): Alter to match new dual-key design.
  (OVERVIEW): - '' -
  (FILES): Add TLS key files.
* mandos-options.xml (priority): Document new default priority string
                                 when using raw public keys.
* mandos.xml (NETWORK PROTOCOL): Describe new protocol using key ID.
  (BUGS): Remove issue about checking expire times of OpenPGP keys,
          since TLS public keys do not have expiration times.
  (SECURITY/CLIENT): Alter description to match new design.
  (SEE ALSO/GnuTLS): - '' -
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.
* overview.xml: Alter text to match new design.
* plugin-runner.xml (EXAMPLE): Add --tls-pubkey and --tls-privkey
                               options to mandos-client options.
* plugins.d/mandos-client.c: Use raw public keys when compiling with
                             supporting GnuTLS versions. Add new
                             "--tls-pubkey" and "--tls-privkey"
                             options (which do nothing if GnuTLS
                             library does not support raw public
                             keys).  Alter text throughout to reflect
                             new design.  Only generate new DH
                             parameters (based on size of OpenPGP key)
                             when using OpenPGP in TLS.  Default
                             GnuTLS priority string depends on whether
                             we are using raw public keys or not.
* plugins.d/mandos-client.xml (SYNOPSIS): Add new "--tls-privkey" (-t)
                                          and "--tls-pubkey" (-T)
                                          options.
  (DESCRIPTION): Describe new dual-key design.
  (OPTIONS): Document new "--tls-privkey" (-t) and "--tls-pubkey" (-T)
             options.
  (OPTIONS/--dh-bits): No longer necessarily depends on OpenPGP key
                       size.
  (FILES): Add default locations for TLS public and private key files.
  (EXAMPLE): Use new --tls-pubkey and --tls-privkey options.
  (SECURITY): Alter wording slightly to reflect new dual-key design.
  (SEE ALSO/GnuTLS): Alter description to match new design.
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
6
8
]>
7
9
 
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
9
11
  <refentryinfo>
10
 
    <title>&COMMANDNAME;</title>
 
12
    <title>Mandos Manual</title>
11
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
 
    <productname>&COMMANDNAME;</productname>
13
 
    <productnumber>&VERSION;</productnumber>
 
14
    <productname>Mandos</productname>
 
15
    <productnumber>&version;</productnumber>
 
16
    <date>&TIMESTAMP;</date>
14
17
    <authorgroup>
15
18
      <author>
16
19
        <firstname>Björn</firstname>
17
20
        <surname>Påhlsson</surname>
18
21
        <address>
19
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
20
23
        </address>
21
24
      </author>
22
25
      <author>
23
26
        <firstname>Teddy</firstname>
24
27
        <surname>Hogeborn</surname>
25
28
        <address>
26
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
27
30
        </address>
28
31
      </author>
29
32
    </authorgroup>
30
33
    <copyright>
31
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
 
39
      <year>2013</year>
 
40
      <year>2014</year>
 
41
      <year>2015</year>
 
42
      <year>2016</year>
 
43
      <year>2017</year>
 
44
      <year>2018</year>
32
45
      <holder>Teddy Hogeborn</holder>
33
46
      <holder>Björn Påhlsson</holder>
34
47
    </copyright>
35
 
    <legalnotice>
36
 
      <para>
37
 
        This manual page is free software: you can redistribute it
38
 
        and/or modify it under the terms of the GNU General Public
39
 
        License as published by the Free Software Foundation,
40
 
        either version 3 of the License, or (at your option) any
41
 
        later version.
42
 
      </para>
43
 
 
44
 
      <para>
45
 
        This manual page is distributed in the hope that it will
46
 
        be useful, but WITHOUT ANY WARRANTY; without even the
47
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
48
 
        PARTICULAR PURPOSE.  See the GNU General Public License
49
 
        for more details.
50
 
      </para>
51
 
 
52
 
      <para>
53
 
        You should have received a copy of the GNU General Public
54
 
        License along with this program; If not, see
55
 
        <ulink url="http://www.gnu.org/licenses/"/>.
56
 
      </para>
57
 
    </legalnotice>
 
48
    <xi:include href="legalnotice.xml"/>
58
49
  </refentryinfo>
59
 
 
 
50
  
60
51
  <refmeta>
61
52
    <refentrytitle>&COMMANDNAME;</refentrytitle>
62
53
    <manvolnum>8</manvolnum>
65
56
  <refnamediv>
66
57
    <refname><command>&COMMANDNAME;</command></refname>
67
58
    <refpurpose>
68
 
      Generate keys for <citerefentry><refentrytitle>password-request
69
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
59
      Generate key and password for Mandos client and server.
70
60
    </refpurpose>
71
61
  </refnamediv>
72
 
 
 
62
  
73
63
  <refsynopsisdiv>
74
64
    <cmdsynopsis>
75
65
      <command>&COMMANDNAME;</command>
76
 
      <group choice="opt">
77
 
        <arg choice="plain"><option>--dir</option>
78
 
        <replaceable>directory</replaceable></arg>
79
 
      </group>
80
 
      <group choice="opt">
81
 
        <arg choice="plain"><option>--type</option>
82
 
        <replaceable>type</replaceable></arg>
83
 
      </group>
84
 
      <group choice="opt">
85
 
        <arg choice="plain"><option>--length</option>
86
 
        <replaceable>bits</replaceable></arg>
87
 
      </group>
88
 
      <group choice="opt">
89
 
        <arg choice="plain"><option>--subtype</option>
90
 
        <replaceable>type</replaceable></arg>
91
 
      </group>
92
 
      <group choice="opt">
93
 
        <arg choice="plain"><option>--sublength</option>
94
 
        <replaceable>bits</replaceable></arg>
95
 
      </group>
96
 
      <group choice="opt">
97
 
        <arg choice="plain"><option>--name</option>
98
 
        <replaceable>NAME</replaceable></arg>
99
 
      </group>
100
 
      <group choice="opt">
101
 
        <arg choice="plain"><option>--email</option>
102
 
        <replaceable>EMAIL</replaceable></arg>
103
 
      </group>
104
 
      <group choice="opt">
105
 
        <arg choice="plain"><option>--comment</option>
106
 
        <replaceable>COMMENT</replaceable></arg>
107
 
      </group>
108
 
      <group choice="opt">
109
 
        <arg choice="plain"><option>--expire</option>
110
 
        <replaceable>TIME</replaceable></arg>
111
 
      </group>
112
 
      <group choice="opt">
 
66
      <group>
 
67
        <arg choice="plain"><option>--dir
 
68
        <replaceable>DIRECTORY</replaceable></option></arg>
 
69
        <arg choice="plain"><option>-d
 
70
        <replaceable>DIRECTORY</replaceable></option></arg>
 
71
      </group>
 
72
      <sbr/>
 
73
      <group>
 
74
        <arg choice="plain"><option>--type
 
75
        <replaceable>KEYTYPE</replaceable></option></arg>
 
76
        <arg choice="plain"><option>-t
 
77
        <replaceable>KEYTYPE</replaceable></option></arg>
 
78
      </group>
 
79
      <sbr/>
 
80
      <group>
 
81
        <arg choice="plain"><option>--length
 
82
        <replaceable>BITS</replaceable></option></arg>
 
83
        <arg choice="plain"><option>-l
 
84
        <replaceable>BITS</replaceable></option></arg>
 
85
      </group>
 
86
      <sbr/>
 
87
      <group>
 
88
        <arg choice="plain"><option>--subtype
 
89
        <replaceable>KEYTYPE</replaceable></option></arg>
 
90
        <arg choice="plain"><option>-s
 
91
        <replaceable>KEYTYPE</replaceable></option></arg>
 
92
      </group>
 
93
      <sbr/>
 
94
      <group>
 
95
        <arg choice="plain"><option>--sublength
 
96
        <replaceable>BITS</replaceable></option></arg>
 
97
        <arg choice="plain"><option>-L
 
98
        <replaceable>BITS</replaceable></option></arg>
 
99
      </group>
 
100
      <sbr/>
 
101
      <group>
 
102
        <arg choice="plain"><option>--name
 
103
        <replaceable>NAME</replaceable></option></arg>
 
104
        <arg choice="plain"><option>-n
 
105
        <replaceable>NAME</replaceable></option></arg>
 
106
      </group>
 
107
      <sbr/>
 
108
      <group>
 
109
        <arg choice="plain"><option>--email
 
110
        <replaceable>ADDRESS</replaceable></option></arg>
 
111
        <arg choice="plain"><option>-e
 
112
        <replaceable>ADDRESS</replaceable></option></arg>
 
113
      </group>
 
114
      <sbr/>
 
115
      <group>
 
116
        <arg choice="plain"><option>--comment
 
117
        <replaceable>TEXT</replaceable></option></arg>
 
118
        <arg choice="plain"><option>-c
 
119
        <replaceable>TEXT</replaceable></option></arg>
 
120
      </group>
 
121
      <sbr/>
 
122
      <group>
 
123
        <arg choice="plain"><option>--expire
 
124
        <replaceable>TIME</replaceable></option></arg>
 
125
        <arg choice="plain"><option>-x
 
126
        <replaceable>TIME</replaceable></option></arg>
 
127
      </group>
 
128
      <sbr/>
 
129
      <group>
 
130
        <arg choice="plain"><option>--tls-keytype
 
131
        <replaceable>KEYTYPE</replaceable></option></arg>
 
132
        <arg choice="plain"><option>-T
 
133
        <replaceable>KEYTYPE</replaceable></option></arg>
 
134
      </group>
 
135
      <sbr/>
 
136
      <group>
113
137
        <arg choice="plain"><option>--force</option></arg>
114
 
      </group>
115
 
    </cmdsynopsis>
116
 
    <cmdsynopsis>
117
 
      <command>&COMMANDNAME;</command>
118
 
      <group choice="opt">
119
 
        <arg choice="plain"><option>-d</option>
120
 
        <replaceable>directory</replaceable></arg>
121
 
      </group>
122
 
      <group choice="opt">
123
 
        <arg choice="plain"><option>-t</option>
124
 
        <replaceable>type</replaceable></arg>
125
 
      </group>
126
 
      <group choice="opt">
127
 
        <arg choice="plain"><option>-l</option>
128
 
        <replaceable>bits</replaceable></arg>
129
 
      </group>
130
 
      <group choice="opt">
131
 
        <arg choice="plain"><option>-s</option>
132
 
        <replaceable>type</replaceable></arg>
133
 
      </group>
134
 
      <group choice="opt">
135
 
        <arg choice="plain"><option>-L</option>
136
 
        <replaceable>bits</replaceable></arg>
137
 
      </group>
138
 
      <group choice="opt">
139
 
        <arg choice="plain"><option>-n</option>
140
 
        <replaceable>NAME</replaceable></arg>
141
 
      </group>
142
 
      <group choice="opt">
143
 
        <arg choice="plain"><option>-e</option>
144
 
        <replaceable>EMAIL</replaceable></arg>
145
 
      </group>
146
 
      <group choice="opt">
147
 
        <arg choice="plain"><option>-c</option>
148
 
        <replaceable>COMMENT</replaceable></arg>
149
 
      </group>
150
 
      <group choice="opt">
151
 
        <arg choice="plain"><option>-x</option>
152
 
        <replaceable>TIME</replaceable></arg>
153
 
      </group>
154
 
      <group choice="opt">
155
138
        <arg choice="plain"><option>-f</option></arg>
156
139
      </group>
157
140
    </cmdsynopsis>
158
141
    <cmdsynopsis>
159
142
      <command>&COMMANDNAME;</command>
160
143
      <group choice="req">
 
144
        <arg choice="plain"><option>--password</option></arg>
161
145
        <arg choice="plain"><option>-p</option></arg>
162
 
        <arg choice="plain"><option>--password</option></arg>
163
 
      </group>
164
 
      <group choice="opt">
165
 
        <arg choice="plain"><option>--dir</option>
166
 
        <replaceable>directory</replaceable></arg>
167
 
      </group>
168
 
      <group choice="opt">
169
 
        <arg choice="plain"><option>--name</option>
170
 
        <replaceable>NAME</replaceable></arg>
 
146
        <arg choice="plain"><option>--passfile
 
147
        <replaceable>FILE</replaceable></option></arg>
 
148
        <arg choice="plain"><option>-F</option>
 
149
        <replaceable>FILE</replaceable></arg>
 
150
      </group>
 
151
      <sbr/>
 
152
      <group>
 
153
        <arg choice="plain"><option>--dir
 
154
        <replaceable>DIRECTORY</replaceable></option></arg>
 
155
        <arg choice="plain"><option>-d
 
156
        <replaceable>DIRECTORY</replaceable></option></arg>
 
157
      </group>
 
158
      <sbr/>
 
159
      <group>
 
160
        <arg choice="plain"><option>--name
 
161
        <replaceable>NAME</replaceable></option></arg>
 
162
        <arg choice="plain"><option>-n
 
163
        <replaceable>NAME</replaceable></option></arg>
 
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
171
168
      </group>
172
169
    </cmdsynopsis>
173
170
    <cmdsynopsis>
174
171
      <command>&COMMANDNAME;</command>
175
172
      <group choice="req">
 
173
        <arg choice="plain"><option>--help</option></arg>
176
174
        <arg choice="plain"><option>-h</option></arg>
177
 
        <arg choice="plain"><option>--help</option></arg>
178
175
      </group>
179
176
    </cmdsynopsis>
180
177
    <cmdsynopsis>
181
178
      <command>&COMMANDNAME;</command>
182
179
      <group choice="req">
 
180
        <arg choice="plain"><option>--version</option></arg>
183
181
        <arg choice="plain"><option>-v</option></arg>
184
 
        <arg choice="plain"><option>--version</option></arg>
185
182
      </group>
186
183
    </cmdsynopsis>
187
184
  </refsynopsisdiv>
188
 
 
 
185
  
189
186
  <refsect1 id="description">
190
187
    <title>DESCRIPTION</title>
191
188
    <para>
192
189
      <command>&COMMANDNAME;</command> is a program to generate the
193
 
      OpenPGP keys used by
194
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
190
      TLS and OpenPGP keys used by
 
191
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
195
192
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
196
193
      normally written to /etc/mandos for later installation into the
197
 
      initrd image, but this, like most things, can be changed with
198
 
      command line options.
 
194
      initrd image, but this, and most other things, can be changed
 
195
      with command line options.
199
196
    </para>
200
197
    <para>
201
 
      It can also be used to generate ready-made sections for
 
198
      This program can also be used with the
 
199
      <option>--password</option> or <option>--passfile</option>
 
200
      options to generate a ready-made section for
 
201
      <filename>clients.conf</filename> (see
202
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
203
 
      <manvolnum>5</manvolnum></citerefentry> using the
204
 
      <option>--password</option> option.
 
203
      <manvolnum>5</manvolnum></citerefentry>).
205
204
    </para>
206
205
  </refsect1>
207
206
  
208
207
  <refsect1 id="purpose">
209
208
    <title>PURPOSE</title>
210
 
 
211
209
    <para>
212
210
      The purpose of this is to enable <emphasis>remote and unattended
213
211
      rebooting</emphasis> of client host computer with an
214
212
      <emphasis>encrypted root file system</emphasis>.  See <xref
215
213
      linkend="overview"/> for details.
216
214
    </para>
217
 
 
218
215
  </refsect1>
219
216
  
220
217
  <refsect1 id="options">
221
218
    <title>OPTIONS</title>
222
 
 
 
219
    
223
220
    <variablelist>
224
221
      <varlistentry>
225
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
222
        <term><option>--help</option></term>
 
223
        <term><option>-h</option></term>
226
224
        <listitem>
227
225
          <para>
228
226
            Show a help message and exit
229
227
          </para>
230
228
        </listitem>
231
229
      </varlistentry>
232
 
 
 
230
      
233
231
      <varlistentry>
234
 
        <term><literal>-d</literal>, <literal>--dir
235
 
        <replaceable>directory</replaceable></literal></term>
 
232
        <term><option>--dir
 
233
        <replaceable>DIRECTORY</replaceable></option></term>
 
234
        <term><option>-d
 
235
        <replaceable>DIRECTORY</replaceable></option></term>
236
236
        <listitem>
237
237
          <para>
238
238
            Target directory for key files.  Default is
239
 
            <filename>/etc/mandos</filename>.
240
 
          </para>
241
 
        </listitem>
242
 
      </varlistentry>
243
 
 
244
 
      <varlistentry>
245
 
        <term><literal>-t</literal>, <literal>--type
246
 
        <replaceable>type</replaceable></literal></term>
247
 
        <listitem>
248
 
          <para>
249
 
            Key type.  Default is <quote>DSA</quote>.
250
 
          </para>
251
 
        </listitem>
252
 
      </varlistentry>
253
 
 
254
 
      <varlistentry>
255
 
        <term><literal>-l</literal>, <literal>--length
256
 
        <replaceable>bits</replaceable></literal></term>
257
 
        <listitem>
258
 
          <para>
259
 
            Key length in bits.  Default is 1024.
260
 
          </para>
261
 
        </listitem>
262
 
      </varlistentry>
263
 
 
264
 
      <varlistentry>
265
 
        <term><literal>-s</literal>, <literal>--subtype
266
 
        <replaceable>type</replaceable></literal></term>
267
 
        <listitem>
268
 
          <para>
269
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
270
 
            encryption-only).
271
 
          </para>
272
 
        </listitem>
273
 
      </varlistentry>
274
 
 
275
 
      <varlistentry>
276
 
        <term><literal>-L</literal>, <literal>--sublength
277
 
        <replaceable>bits</replaceable></literal></term>
278
 
        <listitem>
279
 
          <para>
280
 
            Subkey length in bits.  Default is 2048.
281
 
          </para>
282
 
        </listitem>
283
 
      </varlistentry>
284
 
 
285
 
      <varlistentry>
286
 
        <term><literal>-e</literal>, <literal>--email</literal>
287
 
        <replaceable>address</replaceable></term>
 
239
            <filename class="directory">/etc/mandos</filename>.
 
240
          </para>
 
241
        </listitem>
 
242
      </varlistentry>
 
243
      
 
244
      <varlistentry>
 
245
        <term><option>--type
 
246
        <replaceable>TYPE</replaceable></option></term>
 
247
        <term><option>-t
 
248
        <replaceable>TYPE</replaceable></option></term>
 
249
        <listitem>
 
250
          <para>
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
 
252
          </para>
 
253
        </listitem>
 
254
      </varlistentry>
 
255
      
 
256
      <varlistentry>
 
257
        <term><option>--length
 
258
        <replaceable>BITS</replaceable></option></term>
 
259
        <term><option>-l
 
260
        <replaceable>BITS</replaceable></option></term>
 
261
        <listitem>
 
262
          <para>
 
263
            OpenPGP key length in bits.  Default is 4096.
 
264
          </para>
 
265
        </listitem>
 
266
      </varlistentry>
 
267
      
 
268
      <varlistentry>
 
269
        <term><option>--subtype
 
270
        <replaceable>KEYTYPE</replaceable></option></term>
 
271
        <term><option>-s
 
272
        <replaceable>KEYTYPE</replaceable></option></term>
 
273
        <listitem>
 
274
          <para>
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
 
276
          </para>
 
277
        </listitem>
 
278
      </varlistentry>
 
279
      
 
280
      <varlistentry>
 
281
        <term><option>--sublength
 
282
        <replaceable>BITS</replaceable></option></term>
 
283
        <term><option>-L
 
284
        <replaceable>BITS</replaceable></option></term>
 
285
        <listitem>
 
286
          <para>
 
287
            OpenPGP subkey length in bits.  Default is 4096.
 
288
          </para>
 
289
        </listitem>
 
290
      </varlistentry>
 
291
      
 
292
      <varlistentry>
 
293
        <term><option>--email
 
294
        <replaceable>ADDRESS</replaceable></option></term>
 
295
        <term><option>-e
 
296
        <replaceable>ADDRESS</replaceable></option></term>
288
297
        <listitem>
289
298
          <para>
290
299
            Email address of key.  Default is empty.
291
300
          </para>
292
301
        </listitem>
293
302
      </varlistentry>
294
 
 
 
303
      
295
304
      <varlistentry>
296
 
        <term><literal>-c</literal>, <literal>--comment</literal>
297
 
        <replaceable>comment</replaceable></term>
 
305
        <term><option>--comment
 
306
        <replaceable>TEXT</replaceable></option></term>
 
307
        <term><option>-c
 
308
        <replaceable>TEXT</replaceable></option></term>
298
309
        <listitem>
299
310
          <para>
300
 
            Comment field for key.  The default value is
301
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
302
312
          </para>
303
313
        </listitem>
304
314
      </varlistentry>
305
 
 
 
315
      
306
316
      <varlistentry>
307
 
        <term><literal>-x</literal>, <literal>--expire</literal>
308
 
        <replaceable>time</replaceable></term>
 
317
        <term><option>--expire
 
318
        <replaceable>TIME</replaceable></option></term>
 
319
        <term><option>-x
 
320
        <replaceable>TIME</replaceable></option></term>
309
321
        <listitem>
310
322
          <para>
311
323
            Key expire time.  Default is no expiration.  See
314
326
          </para>
315
327
        </listitem>
316
328
      </varlistentry>
317
 
 
318
 
      <varlistentry>
319
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
320
 
        <listitem>
321
 
          <para>
322
 
            Force overwriting old keys.
323
 
          </para>
324
 
        </listitem>
325
 
      </varlistentry>
326
 
      <varlistentry>
327
 
        <term><literal>-p</literal>, <literal>--password</literal
328
 
        ></term>
 
329
      
 
330
      <varlistentry>
 
331
        <term><option>--tls-keytype
 
332
        <replaceable>KEYTYPE</replaceable></option></term>
 
333
        <term><option>-T
 
334
        <replaceable>KEYTYPE</replaceable></option></term>
 
335
        <listitem>
 
336
          <para>
 
337
            TLS key type.  Default is <quote>ed25519</quote>
 
338
          </para>
 
339
        </listitem>
 
340
      </varlistentry>
 
341
      
 
342
      <varlistentry>
 
343
        <term><option>--force</option></term>
 
344
        <term><option>-f</option></term>
 
345
        <listitem>
 
346
          <para>
 
347
            Force overwriting old key.
 
348
          </para>
 
349
        </listitem>
 
350
      </varlistentry>
 
351
      <varlistentry>
 
352
        <term><option>--password</option></term>
 
353
        <term><option>-p</option></term>
329
354
        <listitem>
330
355
          <para>
331
356
            Prompt for a password and encrypt it with the key already
337
362
            >8</manvolnum></citerefentry>.  The host name or the name
338
363
            specified with the <option>--name</option> option is used
339
364
            for the section header.  All other options are ignored,
340
 
            and no keys are created.
 
365
            and no key is created.
 
366
          </para>
 
367
        </listitem>
 
368
      </varlistentry>
 
369
      <varlistentry>
 
370
        <term><option>--passfile
 
371
        <replaceable>FILE</replaceable></option></term>
 
372
        <term><option>-F
 
373
        <replaceable>FILE</replaceable></option></term>
 
374
        <listitem>
 
375
          <para>
 
376
            The same as <option>--password</option>, but read from
 
377
            <replaceable>FILE</replaceable>, not the terminal.
 
378
          </para>
 
379
        </listitem>
 
380
      </varlistentry>
 
381
      <varlistentry>
 
382
        <term><option>--no-ssh</option></term>
 
383
        <term><option>-S</option></term>
 
384
        <listitem>
 
385
          <para>
 
386
            When <option>--password</option> or
 
387
            <option>--passfile</option> is given, this option will
 
388
            prevent <command>&COMMANDNAME;</command> from calling
 
389
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
390
            for this host and, if successful, output suitable config
 
391
            options to use this fingerprint as a
 
392
            <option>checker</option> option in the output.  This is
 
393
            otherwise the default behavior.
341
394
          </para>
342
395
        </listitem>
343
396
      </varlistentry>
344
397
    </variablelist>
345
398
  </refsect1>
346
 
 
 
399
  
347
400
  <refsect1 id="overview">
348
401
    <title>OVERVIEW</title>
349
402
    <xi:include href="overview.xml"/>
350
403
    <para>
351
 
      This program is a small utility to generate new OpenPGP keys for
352
 
      new Mandos clients.
 
404
      This program is a small utility to generate new TLS and OpenPGP
 
405
      keys for new Mandos clients, and to generate sections for
 
406
      inclusion in <filename>clients.conf</filename> on the server.
353
407
    </para>
354
408
  </refsect1>
355
 
 
 
409
  
356
410
  <refsect1 id="exit_status">
357
411
    <title>EXIT STATUS</title>
358
412
    <para>
359
 
      The exit status will be 0 if new keys were successfully created,
360
 
      otherwise not.
 
413
      The exit status will be 0 if a new key (or password, if the
 
414
      <option>--password</option> option was used) was successfully
 
415
      created, otherwise not.
361
416
    </para>
362
417
  </refsect1>
363
418
  
365
420
    <title>ENVIRONMENT</title>
366
421
    <variablelist>
367
422
      <varlistentry>
368
 
        <term><varname>TMPDIR</varname></term>
 
423
        <term><envar>TMPDIR</envar></term>
369
424
        <listitem>
370
425
          <para>
371
426
            If set, temporary files will be created here. See
377
432
    </variablelist>
378
433
  </refsect1>
379
434
  
380
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
381
436
    <title>FILES</title>
382
437
    <para>
383
438
      Use the <option>--dir</option> option to change where
404
459
        </listitem>
405
460
      </varlistentry>
406
461
      <varlistentry>
407
 
        <term><filename>/tmp</filename></term>
 
462
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
463
        <listitem>
 
464
          <para>
 
465
            Private key file which will be created or overwritten.
 
466
          </para>
 
467
        </listitem>
 
468
      </varlistentry>
 
469
      <varlistentry>
 
470
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
471
        <listitem>
 
472
          <para>
 
473
            Public key file which will be created or overwritten.
 
474
          </para>
 
475
        </listitem>
 
476
      </varlistentry>
 
477
      <varlistentry>
 
478
        <term><filename class="directory">/tmp</filename></term>
408
479
        <listitem>
409
480
          <para>
410
481
            Temporary files will be written here if
414
485
      </varlistentry>
415
486
    </variablelist>
416
487
  </refsect1>
417
 
 
 
488
  
418
489
  <refsect1 id="bugs">
419
490
    <title>BUGS</title>
420
 
    <para>
421
 
      None are known at this time.
422
 
    </para>
 
491
    <xi:include href="bugs.xml"/>
423
492
  </refsect1>
424
 
 
 
493
  
425
494
  <refsect1 id="example">
426
495
    <title>EXAMPLE</title>
427
496
    <informalexample>
429
498
        Normal invocation needs no options:
430
499
      </para>
431
500
      <para>
432
 
        <userinput>mandos-keygen</userinput>
 
501
        <userinput>&COMMANDNAME;</userinput>
433
502
      </para>
434
503
    </informalexample>
435
504
    <informalexample>
436
505
      <para>
437
 
        Create keys in another directory and of another type.  Force
 
506
        Create key in another directory and of another type.  Force
438
507
        overwriting old key files:
439
508
      </para>
440
509
      <para>
441
510
 
442
511
<!-- do not wrap this line -->
443
 
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
 
512
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
 
513
 
 
514
      </para>
 
515
    </informalexample>
 
516
    <informalexample>
 
517
      <para>
 
518
        Prompt for a password, encrypt it with the key in <filename
 
519
        class="directory">/etc/mandos</filename> and output a section
 
520
        suitable for <filename>clients.conf</filename>.
 
521
      </para>
 
522
      <para>
 
523
        <userinput>&COMMANDNAME; --password</userinput>
 
524
      </para>
 
525
    </informalexample>
 
526
    <informalexample>
 
527
      <para>
 
528
        Prompt for a password, encrypt it with the key in the
 
529
        <filename>client-key</filename> directory and output a section
 
530
        suitable for <filename>clients.conf</filename>.
 
531
      </para>
 
532
      <para>
 
533
 
 
534
<!-- do not wrap this line -->
 
535
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
444
536
 
445
537
      </para>
446
538
    </informalexample>
447
539
  </refsect1>
448
 
 
 
540
  
449
541
  <refsect1 id="security">
450
542
    <title>SECURITY</title>
451
543
    <para>
452
544
      The <option>--type</option>, <option>--length</option>,
453
545
      <option>--subtype</option>, and <option>--sublength</option>
454
 
      options can be used to create keys of insufficient security.  If
455
 
      in doubt, leave them to the default values.
 
546
      options can be used to create keys of low security.  If in
 
547
      doubt, leave them to the default values.
456
548
    </para>
457
549
    <para>
458
 
      The key expire time is not guaranteed to be honored by
459
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
550
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
551
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
460
552
      <manvolnum>8</manvolnum></citerefentry>.
461
553
    </para>
462
554
  </refsect1>
463
 
 
 
555
  
464
556
  <refsect1 id="see_also">
465
557
    <title>SEE ALSO</title>
466
558
    <para>
467
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
468
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
562
      <manvolnum>1</manvolnum></citerefentry>,
 
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
564
      <manvolnum>5</manvolnum></citerefentry>,
469
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
470
566
      <manvolnum>8</manvolnum></citerefentry>,
471
 
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
472
570
      <manvolnum>1</manvolnum></citerefentry>
473
571
    </para>
474
572
  </refsect1>
475
573
  
476
574
</refentry>
 
575
<!-- Local Variables: -->
 
576
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
577
<!-- time-stamp-end: "[\"']>" -->
 
578
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
579
<!-- End: -->