/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos.xml

• browse files at revision 433
• compare with another revision
• download diff
• download tarball
• view history from revision 433

• reverse the comparison (433 to 1302)
• stop comparing with revision 1302

Show diffs side-by-side

added

removed

mandos.xml

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

4

<!ENTITY COMMANDNAME "mandos">

5

 

<!ENTITY TIMESTAMP "2022-04-24">

 

5

<!ENTITY TIMESTAMP "2010-09-11">

6

6

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

7

7

%common;

8

8

]>

19

19

        <firstname>Björn</firstname>

20

20

        <surname>Påhlsson</surname>

21

21

        <address>

22

 

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

 

22

          <email>belorn@fukt.bsnet.se</email>

23

23

        </address>

24

24

      </author>

25

25

      <author>

26

26

        <firstname>Teddy</firstname>

27

27

        <surname>Hogeborn</surname>

28

28

        <address>

29

 

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

 

29

          <email>teddy@fukt.bsnet.se</email>

30

30

        </address>

31

31

      </author>

32

32

    </authorgroup>

33

33

    <copyright>

34

34

      <year>2008</year>

35

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>

45

 

      <year>2019</year>

46

36

      <holder>Teddy Hogeborn</holder>

47

37

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

48

38

    </copyright>

96

86

      <sbr/>

97

87

      <arg><option>--debug</option></arg>

98

88

      <sbr/>

99

 

      <arg><option>--debuglevel

100

 

      <replaceable>LEVEL</replaceable></option></arg>

101

 

      <sbr/>

102

89

      <arg><option>--no-dbus</option></arg>

103

90

      <sbr/>

104

91

      <arg><option>--no-ipv6</option></arg>

105

 

      <sbr/>

106

 

      <arg><option>--no-restore</option></arg>

107

 

      <sbr/>

108

 

      <arg><option>--statedir

109

 

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

110

 

      <sbr/>

111

 

      <arg><option>--socket

112

 

      <replaceable>FD</replaceable></option></arg>

113

 

      <sbr/>

114

 

      <arg><option>--foreground</option></arg>

115

 

      <sbr/>

116

 

      <arg><option>--no-zeroconf</option></arg>

117

92

    </cmdsynopsis>

118

93

    <cmdsynopsis>

119

94

      <command>&COMMANDNAME;</command>

136

111

    <title>DESCRIPTION</title>

137

112

    <para>

138

113

      <command>&COMMANDNAME;</command> is a server daemon which

139

 

      handles incoming requests for passwords for a pre-defined list

140

 

      of client host computers. For an introduction, see

141

 

      <citerefentry><refentrytitle>intro</refentrytitle>

142

 

      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server

143

 

      uses Zeroconf to announce itself on the local network, and uses

144

 

      TLS to communicate securely with and to authenticate the

145

 

      clients.  The Mandos server uses IPv6 to allow Mandos clients to

146

 

      use IPv6 link-local addresses, since the clients will probably

147

 

      not have any other addresses configured (see <xref

148

 

      linkend="overview"/>).  Any authenticated client is then given

149

 

      the stored pre-encrypted password for that specific client.

 

114

      handles incoming request for passwords for a pre-defined list of

 

115

      client host computers.  The Mandos server uses Zeroconf to

 

116

      announce itself on the local network, and uses TLS to

 

117

      communicate securely with and to authenticate the clients.  The

 

118

      Mandos server uses IPv6 to allow Mandos clients to use IPv6

 

119

      link-local addresses, since the clients will probably not have

 

120

      any other addresses configured (see <xref linkend="overview"/>).

 

121

      Any authenticated client is then given the stored pre-encrypted

 

122

      password for that specific client.

150

123

    </para>

151

124

  </refsect1>

152

125

  

221

194

      </varlistentry>

222

195

      

223

196

      <varlistentry>

224

 

        <term><option>--debuglevel

225

 

        <replaceable>LEVEL</replaceable></option></term>

226

 

        <listitem>

227

 

          <para>

228

 

            Set the debugging log level.

229

 

            <replaceable>LEVEL</replaceable> is a string, one of

230

 

            <quote><literal>CRITICAL</literal></quote>,

231

 

            <quote><literal>ERROR</literal></quote>,

232

 

            <quote><literal>WARNING</literal></quote>,

233

 

            <quote><literal>INFO</literal></quote>, or

234

 

            <quote><literal>DEBUG</literal></quote>, in order of

235

 

            increasing verbosity.  The default level is

236

 

            <quote><literal>WARNING</literal></quote>.

237

 

          </para>

238

 

        </listitem>

239

 

      </varlistentry>

240

 

      

241

 

      <varlistentry>

242

197

        <term><option>--priority <replaceable>

243

198

        PRIORITY</replaceable></option></term>

244

199

        <listitem>

295

250

          <xi:include href="mandos-options.xml" xpointer="ipv6"/>

296

251

        </listitem>

297

252

      </varlistentry>

298

 

      

299

 

      <varlistentry>

300

 

        <term><option>--no-restore</option></term>

301

 

        <listitem>

302

 

          <xi:include href="mandos-options.xml" xpointer="restore"/>

303

 

          <para>

304

 

            See also <xref linkend="persistent_state"/>.

305

 

          </para>

306

 

        </listitem>

307

 

      </varlistentry>

308

 

      

309

 

      <varlistentry>

310

 

        <term><option>--statedir

311

 

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

312

 

        <listitem>

313

 

          <xi:include href="mandos-options.xml" xpointer="statedir"/>

314

 

        </listitem>

315

 

      </varlistentry>

316

 

      

317

 

      <varlistentry>

318

 

        <term><option>--socket

319

 

        <replaceable>FD</replaceable></option></term>

320

 

        <listitem>

321

 

          <xi:include href="mandos-options.xml" xpointer="socket"/>

322

 

        </listitem>

323

 

      </varlistentry>

324

 

      

325

 

      <varlistentry>

326

 

        <term><option>--foreground</option></term>

327

 

        <listitem>

328

 

          <xi:include href="mandos-options.xml"

329

 

                      xpointer="foreground"/>

330

 

        </listitem>

331

 

      </varlistentry>

332

 

      

333

 

      <varlistentry>

334

 

        <term><option>--no-zeroconf</option></term>

335

 

        <listitem>

336

 

          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>

337

 

        </listitem>

338

 

      </varlistentry>

339

 

      

340

253

    </variablelist>

341

254

  </refsect1>

342

255

  

362

275

      start a TLS protocol handshake with a slight quirk: the Mandos

363

276

      server program acts as a TLS <quote>client</quote> while the

364

277

      connecting Mandos client acts as a TLS <quote>server</quote>.

365

 

      The Mandos client must supply a TLS public key, and the key ID

366

 

      of this public key is used by the Mandos server to look up (in a

367

 

      list read from <filename>clients.conf</filename> at start time)

368

 

      which binary blob to give the client.  No other authentication

369

 

      or authorization is done by the server.

 

278

      The Mandos client must supply an OpenPGP certificate, and the

 

279

      fingerprint of this certificate is used by the Mandos server to

 

280

      look up (in a list read from <filename>clients.conf</filename>

 

281

      at start time) which binary blob to give the client.  No other

 

282

      authentication or authorization is done by the server.

370

283

    </para>

371

284

    <table>

372

285

      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>

392

305

        </emphasis></entry>

393

306

      </row>

394

307

      <row>

395

 

        <entry>Public key (part of TLS handshake)</entry>

 

308

        <entry>OpenPGP public key (part of TLS handshake)</entry>

396

309

        <entry>-><!-- &rarr; --></entry>

397

310

      </row>

398

311

      <row>

416

329

      for some time, the client is assumed to be compromised and is no

417

330

      longer eligible to receive the encrypted password.  (Manual

418

331

      intervention is required to re-enable a client.)  The timeout,

419

 

      extended timeout, checker program, and interval between checks

420

 

      can be configured both globally and per client; see

421

 

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

422

 

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

423

 

    </para>

424

 

  </refsect1>

425

 

  

426

 

  <refsect1 id="approval">

427

 

    <title>APPROVAL</title>

428

 

    <para>

429

 

      The server can be configured to require manual approval for a

430

 

      client before it is sent its secret.  The delay to wait for such

431

 

      approval and the default action (approve or deny) can be

432

 

      configured both globally and per client; see <citerefentry>

 

332

      checker program, and interval between checks can be configured

 

333

      both globally and per client; see <citerefentry>

433

334

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

434

 

      <manvolnum>5</manvolnum></citerefentry>.  By default all clients

435

 

      will be approved immediately without delay.

436

 

    </para>

437

 

    <para>

438

 

      This can be used to deny a client its secret if not manually

439

 

      approved within a specified time.  It can also be used to make

440

 

      the server delay before giving a client its secret, allowing

441

 

      optional manual denying of this specific client.

442

 

    </para>

443

 

    

 

335

      <manvolnum>5</manvolnum></citerefentry>.  A client successfully

 

336

      receiving its password will also be treated as a successful

 

337

      checker run.

 

338

    </para>

444

339

  </refsect1>

445

340

  

446

341

  <refsect1 id="logging">

447

342

    <title>LOGGING</title>

448

343

    <para>

449

344

      The server will send log message with various severity levels to

450

 

      <filename class="devicefile">/dev/log</filename>.  With the

 

345

      <filename>/dev/log</filename>.  With the

451

346

      <option>--debug</option> option, it will log even more messages,

452

347

      and also show them on the console.

453

348

    </para>

454

349

  </refsect1>

455

350

  

456

 

  <refsect1 id="persistent_state">

457

 

    <title>PERSISTENT STATE</title>

458

 

    <para>

459

 

      Client settings, initially read from

460

 

      <filename>clients.conf</filename>, are persistent across

461

 

      restarts, and run-time changes will override settings in

462

 

      <filename>clients.conf</filename>.  However, if a setting is

463

 

      <emphasis>changed</emphasis> (or a client added, or removed) in

464

 

      <filename>clients.conf</filename>, this will take precedence.

465

 

    </para>

466

 

  </refsect1>

467

 

  

468

351

  <refsect1 id="dbus_interface">

469

352

    <title>D-BUS INTERFACE</title>

470

353

    <para>

532

415

        </listitem>

533

416

      </varlistentry>

534

417

      <varlistentry>

535

 

        <term><filename>/run/mandos.pid</filename></term>

536

 

        <listitem>

537

 

          <para>

538

 

            The file containing the process id of the

539

 

            <command>&COMMANDNAME;</command> process started last.

540

 

            <emphasis >Note:</emphasis> If the <filename

541

 

            class="directory">/run</filename> directory does not

542

 

            exist, <filename>/var/run/mandos.pid</filename> will be

543

 

            used instead.

544

 

          </para>

545

 

        </listitem>

546

 

      </varlistentry>

547

 

      <varlistentry>

548

 

        <term><filename

549

 

        class="directory">/var/lib/mandos</filename></term>

550

 

        <listitem>

551

 

          <para>

552

 

            Directory where persistent state will be saved.  Change

553

 

            this with the <option>--statedir</option> option.  See

554

 

            also the <option>--no-restore</option> option.

555

 

          </para>

556

 

        </listitem>

557

 

      </varlistentry>

558

 

      <varlistentry>

559

 

        <term><filename class="devicefile">/dev/log</filename></term>

 

418

        <term><filename>/var/run/mandos.pid</filename></term>

 

419

        <listitem>

 

420

          <para>

 

421

            The file containing the process id of

 

422

            <command>&COMMANDNAME;</command>.

 

423

          </para>

 

424

        </listitem>

 

425

      </varlistentry>

 

426

      <varlistentry>

 

427

        <term><filename>/dev/log</filename></term>

560

428

        <listitem>

561

429

          <para>

562

430

            The Unix domain socket to where local syslog messages are

585

453

      backtrace.  This could be considered a feature.

586

454

    </para>

587

455

    <para>

 

456

      Currently, if a client is disabled due to having timed out, the

 

457

      server does not record this fact onto permanent storage.  This

 

458

      has some security implications, see <xref linkend="clients"/>.

 

459

    </para>

 

460

    <para>

588

461

      There is no fine-grained control over logging and debug output.

589

462

    </para>

590

 

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

 

463

    <para>

 

464

      Debug mode is conflated with running in the foreground.

 

465

    </para>

 

466

    <para>

 

467

      The console log messages do not show a time stamp.

 

468

    </para>

 

469

    <para>

 

470

      This server does not check the expire time of clients’ OpenPGP

 

471

      keys.

 

472

    </para>

591

473

  </refsect1>

592

474

  

593

475

  <refsect1 id="example">

603

485

    <informalexample>

604

486

      <para>

605

487

        Run the server in debug mode, read configuration files from

606

 

        the <filename class="directory">~/mandos</filename> directory,

607

 

        and use the Zeroconf service name <quote>Test</quote> to not

608

 

        collide with any other official Mandos server on this host:

 

488

        the <filename>~/mandos</filename> directory, and use the

 

489

        Zeroconf service name <quote>Test</quote> to not collide with

 

490

        any other official Mandos server on this host:

609

491

      </para>

610

492

      <para>

611

493

 

643

525

      <title>CLIENTS</title>

644

526

      <para>

645

527

        The server only gives out its stored data to clients which

646

 

        does have the correct key ID of the stored key ID.  This is

647

 

        guaranteed by the fact that the client sends its public key in

648

 

        the TLS handshake; this ensures it to be genuine.  The server

649

 

        computes the key ID of the key itself and looks up the key ID

650

 

        in its list of clients. The <filename>clients.conf</filename>

651

 

        file (see

 

528

        does have the OpenPGP key of the stored fingerprint.  This is

 

529

        guaranteed by the fact that the client sends its OpenPGP

 

530

        public key in the TLS handshake; this ensures it to be

 

531

        genuine.  The server computes the fingerprint of the key

 

532

        itself and looks up the fingerprint in its list of

 

533

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

652

534

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

653

535

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

654

536

        <emphasis>must</emphasis> be made non-readable by anyone

660

542

        compromised if they are gone for too long.

661

543

      </para>

662

544

      <para>

 

545

        If a client is compromised, its downtime should be duly noted

 

546

        by the server which would therefore disable the client.  But

 

547

        if the server was ever restarted, it would re-read its client

 

548

        list from its configuration file and again regard all clients

 

549

        therein as enabled, and hence eligible to receive their

 

550

        passwords.  Therefore, be careful when restarting servers if

 

551

        it is suspected that a client has, in fact, been compromised

 

552

        by parties who may now be running a fake Mandos client with

 

553

        the keys from the non-encrypted initial <acronym>RAM</acronym>

 

554

        image of the client host.  What should be done in that case

 

555

        (if restarting the server program really is necessary) is to

 

556

        stop the server program, edit the configuration file to omit

 

557

        any suspect clients, and restart the server program.

 

558

      </para>

 

559

      <para>

663

560

        For more details on client-side security, see

664

561

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

665

562

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

670

567

  <refsect1 id="see_also">

671

568

    <title>SEE ALSO</title>

672

569

    <para>

673

 

      <citerefentry><refentrytitle>intro</refentrytitle>

674

 

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

675

 

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

676

 

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

677

 

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

678

 

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

679

 

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

680

 

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

681

 

      <citerefentry><refentrytitle>sh</refentrytitle>

682

 

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

 

570

      <citerefentry>

 

571

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

 

572

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

 

573

        <refentrytitle>mandos.conf</refentrytitle>

 

574

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

 

575

        <refentrytitle>mandos-client</refentrytitle>

 

576

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

 

577

        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>

 

578

      </citerefentry>

683

579

    </para>

684

580

    <variablelist>

685

581

      <varlistentry>

695

591

      </varlistentry>

696

592

      <varlistentry>

697

593

        <term>

698

 

          <ulink url="https://www.avahi.org/">Avahi</ulink>

 

594

          <ulink url="http://www.avahi.org/">Avahi</ulink>

699

595

        </term>

700

596

      <listitem>

701

597

        <para>

706

602

      </varlistentry>

707

603

      <varlistentry>

708

604

        <term>

709

 

          <ulink url="https://gnutls.org/">GnuTLS</ulink>

 

605

          <ulink url="http://www.gnu.org/software/gnutls/"

 

606

          >GnuTLS</ulink>

710

607

        </term>

711

608

      <listitem>

712

609

        <para>

713

610

          GnuTLS is the library this server uses to implement TLS for

714

611

          communicating securely with the client, and at the same time

715

 

          confidently get the client’s public key.

 

612

          confidently get the client’s public OpenPGP key.

716

613

        </para>

717

614

      </listitem>

718

615

      </varlistentry>

739

636

            <listitem>

740

637

              <para>

741

638

                The clients use IPv6 link-local addresses, which are

742

 

                immediately usable since a link-local address is

 

639

                immediately usable since a link-local addresses is

743

640

                automatically assigned to a network interfaces when it

744

641

                is brought up.

745

642

              </para>

750

647

      </varlistentry>

751

648

      <varlistentry>

752

649

        <term>

753

 

          RFC 5246: <citetitle>The Transport Layer Security (TLS)

754

 

          Protocol Version 1.2</citetitle>

 

650

          RFC 4346: <citetitle>The Transport Layer Security (TLS)

 

651

          Protocol Version 1.1</citetitle>

755

652

        </term>

756

653

      <listitem>

757

654

        <para>

758

 

          TLS 1.2 is the protocol implemented by GnuTLS.

 

655

          TLS 1.1 is the protocol implemented by GnuTLS.

759

656

        </para>

760

657

      </listitem>

761

658

      </varlistentry>

771

668

      </varlistentry>

772

669

      <varlistentry>

773

670

        <term>

774

 

          RFC 7250: <citetitle>Using Raw Public Keys in Transport

775

 

          Layer Security (TLS) and Datagram Transport Layer Security

776

 

          (DTLS)</citetitle>

777

 

        </term>

778

 

      <listitem>

779

 

        <para>

780

 

          This is implemented by GnuTLS version 3.6.6 and is, if

781

 

          present, used by this server so that raw public keys can be

782

 

          used.

783

 

        </para>

784

 

      </listitem>

785

 

      </varlistentry>

786

 

      <varlistentry>

787

 

        <term>

788

 

          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer

789

 

          Security (TLS) Authentication</citetitle>

790

 

        </term>

791

 

      <listitem>

792

 

        <para>

793

 

          This is implemented by GnuTLS before version 3.6.0 and is,

794

 

          if present, used by this server so that OpenPGP keys can be

795

 

          used.

 

671

          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer

 

672

          Security</citetitle>

 

673

        </term>

 

674

      <listitem>

 

675

        <para>

 

676

          This is implemented by GnuTLS and used by this server so

 

677

          that OpenPGP keys can be used.

796

678

        </para>

797

679

      </listitem>

798

680

      </varlistentry>

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0