/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-08-31">
 
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
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
48
    <xi:include href="legalnotice.xml"/>
60
49
  </refentryinfo>
61
 
 
 
50
  
62
51
  <refmeta>
63
52
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
53
    <manvolnum>8</manvolnum>
70
59
      Generate key and password for Mandos client and server.
71
60
    </refpurpose>
72
61
  </refnamediv>
73
 
 
 
62
  
74
63
  <refsynopsisdiv>
75
64
    <cmdsynopsis>
76
65
      <command>&COMMANDNAME;</command>
137
126
        <replaceable>TIME</replaceable></option></arg>
138
127
      </group>
139
128
      <sbr/>
140
 
      <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>
141
140
    </cmdsynopsis>
142
141
    <cmdsynopsis>
143
142
      <command>&COMMANDNAME;</command>
144
143
      <group choice="req">
145
144
        <arg choice="plain"><option>--password</option></arg>
146
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>
147
150
      </group>
148
151
      <sbr/>
149
152
      <group>
159
162
        <arg choice="plain"><option>-n
160
163
        <replaceable>NAME</replaceable></option></arg>
161
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
162
169
    </cmdsynopsis>
163
170
    <cmdsynopsis>
164
171
      <command>&COMMANDNAME;</command>
180
187
    <title>DESCRIPTION</title>
181
188
    <para>
182
189
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
184
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
190
      TLS and OpenPGP keys used by
 
191
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
192
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
186
193
      normally written to /etc/mandos for later installation into the
187
194
      initrd image, but this, and most other things, can be changed
188
195
      with command line options.
189
196
    </para>
190
197
    <para>
191
198
      This program can also be used with the
192
 
      <option>--password</option> option to generate a ready-made
193
 
      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
194
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
203
      <manvolnum>5</manvolnum></citerefentry>).
196
204
    </para>
219
227
          </para>
220
228
        </listitem>
221
229
      </varlistentry>
222
 
 
 
230
      
223
231
      <varlistentry>
224
232
        <term><option>--dir
225
233
        <replaceable>DIRECTORY</replaceable></option></term>
228
236
        <listitem>
229
237
          <para>
230
238
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
239
            <filename class="directory">/etc/mandos</filename>.
232
240
          </para>
233
241
        </listitem>
234
242
      </varlistentry>
235
 
 
 
243
      
236
244
      <varlistentry>
237
245
        <term><option>--type
238
246
        <replaceable>TYPE</replaceable></option></term>
240
248
        <replaceable>TYPE</replaceable></option></term>
241
249
        <listitem>
242
250
          <para>
243
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
244
252
          </para>
245
253
        </listitem>
246
254
      </varlistentry>
247
 
 
 
255
      
248
256
      <varlistentry>
249
257
        <term><option>--length
250
258
        <replaceable>BITS</replaceable></option></term>
252
260
        <replaceable>BITS</replaceable></option></term>
253
261
        <listitem>
254
262
          <para>
255
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
256
264
          </para>
257
265
        </listitem>
258
266
      </varlistentry>
259
 
 
 
267
      
260
268
      <varlistentry>
261
269
        <term><option>--subtype
262
270
        <replaceable>KEYTYPE</replaceable></option></term>
264
272
        <replaceable>KEYTYPE</replaceable></option></term>
265
273
        <listitem>
266
274
          <para>
267
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
268
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
269
276
          </para>
270
277
        </listitem>
271
278
      </varlistentry>
272
 
 
 
279
      
273
280
      <varlistentry>
274
281
        <term><option>--sublength
275
282
        <replaceable>BITS</replaceable></option></term>
277
284
        <replaceable>BITS</replaceable></option></term>
278
285
        <listitem>
279
286
          <para>
280
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
281
288
          </para>
282
289
        </listitem>
283
290
      </varlistentry>
284
 
 
 
291
      
285
292
      <varlistentry>
286
293
        <term><option>--email
287
294
        <replaceable>ADDRESS</replaceable></option></term>
293
300
          </para>
294
301
        </listitem>
295
302
      </varlistentry>
296
 
 
 
303
      
297
304
      <varlistentry>
298
305
        <term><option>--comment
299
306
        <replaceable>TEXT</replaceable></option></term>
301
308
        <replaceable>TEXT</replaceable></option></term>
302
309
        <listitem>
303
310
          <para>
304
 
            Comment field for key.  The default value is
305
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
306
312
          </para>
307
313
        </listitem>
308
314
      </varlistentry>
309
 
 
 
315
      
310
316
      <varlistentry>
311
317
        <term><option>--expire
312
318
        <replaceable>TIME</replaceable></option></term>
320
326
          </para>
321
327
        </listitem>
322
328
      </varlistentry>
323
 
 
 
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
      
324
342
      <varlistentry>
325
343
        <term><option>--force</option></term>
326
344
        <term><option>-f</option></term>
348
366
          </para>
349
367
        </listitem>
350
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>
351
397
    </variablelist>
352
398
  </refsect1>
353
 
 
 
399
  
354
400
  <refsect1 id="overview">
355
401
    <title>OVERVIEW</title>
356
402
    <xi:include href="overview.xml"/>
357
403
    <para>
358
 
      This program is a small utility to generate new OpenPGP keys for
359
 
      new Mandos clients, and to generate sections for inclusion in
360
 
      <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.
361
407
    </para>
362
408
  </refsect1>
363
 
 
 
409
  
364
410
  <refsect1 id="exit_status">
365
411
    <title>EXIT STATUS</title>
366
412
    <para>
386
432
    </variablelist>
387
433
  </refsect1>
388
434
  
389
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
390
436
    <title>FILES</title>
391
437
    <para>
392
438
      Use the <option>--dir</option> option to change where
413
459
        </listitem>
414
460
      </varlistentry>
415
461
      <varlistentry>
416
 
        <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>
417
479
        <listitem>
418
480
          <para>
419
481
            Temporary files will be written here if
423
485
      </varlistentry>
424
486
    </variablelist>
425
487
  </refsect1>
426
 
 
 
488
  
427
489
  <refsect1 id="bugs">
428
490
    <title>BUGS</title>
429
 
    <para>
430
 
      None are known at this time.
431
 
    </para>
 
491
    <xi:include href="bugs.xml"/>
432
492
  </refsect1>
433
 
 
 
493
  
434
494
  <refsect1 id="example">
435
495
    <title>EXAMPLE</title>
436
496
    <informalexample>
455
515
    </informalexample>
456
516
    <informalexample>
457
517
      <para>
458
 
        Prompt for a password, encrypt it with the key in
459
 
        <filename>/etc/mandos</filename> and output a section suitable
460
 
        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>.
461
521
      </para>
462
522
      <para>
463
523
        <userinput>&COMMANDNAME; --password</userinput>
477
537
      </para>
478
538
    </informalexample>
479
539
  </refsect1>
480
 
 
 
540
  
481
541
  <refsect1 id="security">
482
542
    <title>SECURITY</title>
483
543
    <para>
492
552
      <manvolnum>8</manvolnum></citerefentry>.
493
553
    </para>
494
554
  </refsect1>
495
 
 
 
555
  
496
556
  <refsect1 id="see_also">
497
557
    <title>SEE ALSO</title>
498
558
    <para>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
 
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
499
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
562
      <manvolnum>1</manvolnum></citerefentry>,
501
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
564
      <manvolnum>5</manvolnum></citerefentry>,
503
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
566
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
507
571
    </para>
508
572
  </refsect1>
509
573