/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">
6
 
<!ENTITY TIMESTAMP "2008-09-06">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
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>
34
45
      <holder>Teddy Hogeborn</holder>
35
46
      <holder>Björn Påhlsson</holder>
36
47
    </copyright>
37
48
    <xi:include href="legalnotice.xml"/>
38
49
  </refentryinfo>
39
 
 
 
50
  
40
51
  <refmeta>
41
52
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
53
    <manvolnum>8</manvolnum>
48
59
      Generate key and password for Mandos client and server.
49
60
    </refpurpose>
50
61
  </refnamediv>
51
 
 
 
62
  
52
63
  <refsynopsisdiv>
53
64
    <cmdsynopsis>
54
65
      <command>&COMMANDNAME;</command>
115
126
        <replaceable>TIME</replaceable></option></arg>
116
127
      </group>
117
128
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
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>
 
137
        <arg choice="plain"><option>--force</option></arg>
 
138
        <arg choice="plain"><option>-f</option></arg>
 
139
      </group>
119
140
    </cmdsynopsis>
120
141
    <cmdsynopsis>
121
142
      <command>&COMMANDNAME;</command>
122
143
      <group choice="req">
123
144
        <arg choice="plain"><option>--password</option></arg>
124
145
        <arg choice="plain"><option>-p</option></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>
125
150
      </group>
126
151
      <sbr/>
127
152
      <group>
137
162
        <arg choice="plain"><option>-n
138
163
        <replaceable>NAME</replaceable></option></arg>
139
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
140
169
    </cmdsynopsis>
141
170
    <cmdsynopsis>
142
171
      <command>&COMMANDNAME;</command>
158
187
    <title>DESCRIPTION</title>
159
188
    <para>
160
189
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
190
      TLS and OpenPGP keys used by
162
191
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
192
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
193
      normally written to /etc/mandos for later installation into the
165
194
      initrd image, but this, and most other things, can be changed
166
195
      with command line options.
167
196
    </para>
168
197
    <para>
169
198
      This program can also be used with the
170
 
      <option>--password</option> option to generate a ready-made
171
 
      section for <filename>clients.conf</filename> (see
 
199
      <option>--password</option> or <option>--passfile</option>
 
200
      options to generate a ready-made section for
 
201
      <filename>clients.conf</filename> (see
172
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
203
      <manvolnum>5</manvolnum></citerefentry>).
174
204
    </para>
197
227
          </para>
198
228
        </listitem>
199
229
      </varlistentry>
200
 
 
 
230
      
201
231
      <varlistentry>
202
232
        <term><option>--dir
203
233
        <replaceable>DIRECTORY</replaceable></option></term>
206
236
        <listitem>
207
237
          <para>
208
238
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
239
            <filename class="directory">/etc/mandos</filename>.
210
240
          </para>
211
241
        </listitem>
212
242
      </varlistentry>
213
 
 
 
243
      
214
244
      <varlistentry>
215
245
        <term><option>--type
216
246
        <replaceable>TYPE</replaceable></option></term>
218
248
        <replaceable>TYPE</replaceable></option></term>
219
249
        <listitem>
220
250
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
222
252
          </para>
223
253
        </listitem>
224
254
      </varlistentry>
225
 
 
 
255
      
226
256
      <varlistentry>
227
257
        <term><option>--length
228
258
        <replaceable>BITS</replaceable></option></term>
230
260
        <replaceable>BITS</replaceable></option></term>
231
261
        <listitem>
232
262
          <para>
233
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
234
264
          </para>
235
265
        </listitem>
236
266
      </varlistentry>
237
 
 
 
267
      
238
268
      <varlistentry>
239
269
        <term><option>--subtype
240
270
        <replaceable>KEYTYPE</replaceable></option></term>
242
272
        <replaceable>KEYTYPE</replaceable></option></term>
243
273
        <listitem>
244
274
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
246
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
247
276
          </para>
248
277
        </listitem>
249
278
      </varlistentry>
250
 
 
 
279
      
251
280
      <varlistentry>
252
281
        <term><option>--sublength
253
282
        <replaceable>BITS</replaceable></option></term>
255
284
        <replaceable>BITS</replaceable></option></term>
256
285
        <listitem>
257
286
          <para>
258
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
259
288
          </para>
260
289
        </listitem>
261
290
      </varlistentry>
262
 
 
 
291
      
263
292
      <varlistentry>
264
293
        <term><option>--email
265
294
        <replaceable>ADDRESS</replaceable></option></term>
271
300
          </para>
272
301
        </listitem>
273
302
      </varlistentry>
274
 
 
 
303
      
275
304
      <varlistentry>
276
305
        <term><option>--comment
277
306
        <replaceable>TEXT</replaceable></option></term>
279
308
        <replaceable>TEXT</replaceable></option></term>
280
309
        <listitem>
281
310
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
284
312
          </para>
285
313
        </listitem>
286
314
      </varlistentry>
287
 
 
 
315
      
288
316
      <varlistentry>
289
317
        <term><option>--expire
290
318
        <replaceable>TIME</replaceable></option></term>
298
326
          </para>
299
327
        </listitem>
300
328
      </varlistentry>
301
 
 
 
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
      
302
342
      <varlistentry>
303
343
        <term><option>--force</option></term>
304
344
        <term><option>-f</option></term>
326
366
          </para>
327
367
        </listitem>
328
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.
 
394
          </para>
 
395
        </listitem>
 
396
      </varlistentry>
329
397
    </variablelist>
330
398
  </refsect1>
331
 
 
 
399
  
332
400
  <refsect1 id="overview">
333
401
    <title>OVERVIEW</title>
334
402
    <xi:include href="overview.xml"/>
335
403
    <para>
336
 
      This program is a small utility to generate new OpenPGP keys for
337
 
      new Mandos clients, and to generate sections for inclusion in
338
 
      <filename>clients.conf</filename> on the server.
 
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.
339
407
    </para>
340
408
  </refsect1>
341
 
 
 
409
  
342
410
  <refsect1 id="exit_status">
343
411
    <title>EXIT STATUS</title>
344
412
    <para>
364
432
    </variablelist>
365
433
  </refsect1>
366
434
  
367
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
368
436
    <title>FILES</title>
369
437
    <para>
370
438
      Use the <option>--dir</option> option to change where
391
459
        </listitem>
392
460
      </varlistentry>
393
461
      <varlistentry>
394
 
        <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>
395
479
        <listitem>
396
480
          <para>
397
481
            Temporary files will be written here if
401
485
      </varlistentry>
402
486
    </variablelist>
403
487
  </refsect1>
404
 
 
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
410
 
 
 
488
  
 
489
  <refsect1 id="bugs">
 
490
    <title>BUGS</title>
 
491
    <xi:include href="bugs.xml"/>
 
492
  </refsect1>
 
493
  
411
494
  <refsect1 id="example">
412
495
    <title>EXAMPLE</title>
413
496
    <informalexample>
432
515
    </informalexample>
433
516
    <informalexample>
434
517
      <para>
435
 
        Prompt for a password, encrypt it with the key in
436
 
        <filename>/etc/mandos</filename> and output a section suitable
437
 
        for <filename>clients.conf</filename>.
 
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>.
438
521
      </para>
439
522
      <para>
440
523
        <userinput>&COMMANDNAME; --password</userinput>
454
537
      </para>
455
538
    </informalexample>
456
539
  </refsect1>
457
 
 
 
540
  
458
541
  <refsect1 id="security">
459
542
    <title>SECURITY</title>
460
543
    <para>
469
552
      <manvolnum>8</manvolnum></citerefentry>.
470
553
    </para>
471
554
  </refsect1>
472
 
 
 
555
  
473
556
  <refsect1 id="see_also">
474
557
    <title>SEE ALSO</title>
475
558
    <para>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
 
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
476
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
562
      <manvolnum>1</manvolnum></citerefentry>,
478
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
480
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
566
      <manvolnum>8</manvolnum></citerefentry>,
482
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
484
571
    </para>
485
572
  </refsect1>
486
573