/mandos/trunk : revision 125

1

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

2

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

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "mandos">

6

<!ENTITY TIMESTAMP "2008-08-31">

7

]>

8

9

10

11

<title>Mandos Manual</title>

12

13

<productname>Mandos</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

17

18

<firstname>Björn</firstname>

19

<surname>Påhlsson</surname>

20

21

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

22

</address>

23

</author>

24

25

<firstname>Teddy</firstname>

26

<surname>Hogeborn</surname>

27

28

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

29

</address>

30

</author>

31

</authorgroup>

32

33

34

<holder>Teddy Hogeborn</holder>

35

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

36

</copyright>

37

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>

60

</refentryinfo>

61

62

63

<refentrytitle>&COMMANDNAME;</refentrytitle>

64

65

</refmeta>

66

67

68

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

69

70

Gives encrypted passwords to authenticated Mandos clients

71

</refpurpose>

72

</refnamediv>

73

74

75

76

<command>&COMMANDNAME;</command>

77

<group>

78

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

79

80

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

81

82

</group>

83

<sbr/>

84

<group>

85

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

86

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

87

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

88

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

89

</group>

90

<sbr/>

91

<group>

92

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

93

94

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

95

96

</group>

97

<sbr/>

98

<arg><option>--priority

99

<replaceable>PRIORITY</replaceable></option></arg>

100

<sbr/>

101

<arg><option>--servicename

102

103

<sbr/>

104

<arg><option>--configdir

105

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

106

<sbr/>

107

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

108

</cmdsynopsis>

109

110

<command>&COMMANDNAME;</command>

111

112

113

114

</group>

115

</cmdsynopsis>

116

117

<command>&COMMANDNAME;</command>

118

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

119

</cmdsynopsis>

120

121

<command>&COMMANDNAME;</command>

122

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

123

</cmdsynopsis>

124

</refsynopsisdiv>

125

126

127

<title>DESCRIPTION</title>

128

<para>

129

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

130

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

131

client host computers. The Mandos server uses Zeroconf to

132

announce itself on the local network, and uses TLS to

133

communicate securely with and to authenticate the clients. The

134

Mandos server uses IPv6 to allow Mandos clients to use IPv6

135

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

136

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

137

Any authenticated client is then given the stored pre-encrypted

138

password for that specific client.

139

</para>

140

141

</refsect1>

142

143

144

<title>PURPOSE</title>

145

146

<para>

147

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

148

rebooting</emphasis> of client host computer with an

149

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

150

linkend="overview"/> for details.

151

</para>

152

153

</refsect1>

154

155

156

<title>OPTIONS</title>

157

158

159

160

161

162

163

<para>

164

Show a help message and exit

165

</para>

166

</listitem>

167

</varlistentry>

168

169

170

<term><option>--interface</option>

171

172

173

174

175

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

176

</listitem>

177

</varlistentry>

178

179

180

<term><option>--address

181

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

182

<term><option>-a

183

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

184

185

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

186

</listitem>

187

</varlistentry>

188

189

190

<term><option>--port

191

192

<term><option>-p

193

194

195

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

196

</listitem>

197

</varlistentry>

198

199

200

<term><option>--check</option></term>

201

202

<para>

203

Run the server’s self-tests. This includes any unit

204

tests, etc.

205

</para>

206

</listitem>

207

</varlistentry>

208

209

210

<term><option>--debug</option></term>

211

212

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

213

</listitem>

214

</varlistentry>

215

216

217

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

218

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

219

220

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

221

</listitem>

222

</varlistentry>

223

224

225

<term><option>--servicename

226

227

228

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

229

xpointer="servicename"/>

230

</listitem>

231

</varlistentry>

232

233

234

<term><option>--configdir

235

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

236

237

<para>

238

Directory to search for configuration files. Default is

239

<quote><literal>/etc/mandos</literal></quote>. See

240

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

241

242

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

243

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

244

</para>

245

</listitem>

246

</varlistentry>

247

248

249

<term><option>--version</option></term>

250

251

<para>

252

Prints the program version and exit.

253

</para>

254

</listitem>

255

</varlistentry>

256

</variablelist>

257

</refsect1>

258

259

260

<title>OVERVIEW</title>

261

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

262

<para>

263

This program is the server part. It is a normal server program

264

and will run in a normal system environment, not in an initial

265

RAM disk environment.

266

</para>

267

</refsect1>

268

269

270

<title>NETWORK PROTOCOL</title>

271

<para>

272

The Mandos server announces itself as a Zeroconf service of type

273

<quote><literal>_mandos._tcp</literal></quote>. The Mandos

274

client connects to the announced address and port, and sends a

275

line of text where the first whitespace-separated field is the

276

protocol version, which currently is

277

<quote><literal>1</literal></quote>. The client and server then

278

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

279

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

280

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

281

The Mandos client must supply an OpenPGP certificate, and the

282

fingerprint of this certificate is used by the Mandos server to

283

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

284

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

285

authentication or authorization is done by the server.

286

</para>

287

<table>

288

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

289

<row>

290

<entry>Mandos Client</entry>

291

<entry>Direction</entry>

292

<entry>Mandos Server</entry>

293

</row>

294

</thead><tbody>

295

<row>

296

<entry>Connect</entry>

297

298

</row>

299

<row>

300

301

302

</row>

303

<row>

304

<entry>TLS handshake <emphasis>as TLS <quote>server</quote>

305

</emphasis></entry>

306

307

<entry>TLS handshake <emphasis>as TLS <quote>client</quote>

308

</emphasis></entry>

309

</row>

310

<row>

311

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

312

313

</row>

314

<row>

315

316

317

<entry>Binary blob (client will assume OpenPGP data)</entry>

318

</row>

319

<row>

320

321

322

<entry>Close</entry>

323

</row>

324

</tbody></tgroup></table>

325

</refsect1>

326

327

328

<title>CHECKING</title>

329

<para>

330

The server will, by default, continually check that the clients

331

are still up. If a client has not been confirmed as being up

332

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

333

longer eligible to receive the encrypted password. The timeout,

334

checker program, and interval between checks can be configured

335

both globally and per client; see <citerefentry>

336

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

337

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

338

</para>

339

</refsect1>

340

341

342

<title>LOGGING</title>

343

<para>

344

The server will send log message with various severity levels to

345

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

346

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

347

and also show them on the console.

348

</para>

349

</refsect1>

350

351

352

<title>EXIT STATUS</title>

353

<para>

354

The server will exit with a non-zero exit status only when a

355

critical error is encountered.

356

</para>

357

</refsect1>

358

359

360

<title>ENVIRONMENT</title>

361

362

363

364

365

<para>

366

To start the configured checker (see <xref

367

linkend="checking"/>), the server uses

368

<filename>/bin/sh</filename>, which in turn uses

369

<varname>PATH</varname> to search for matching commands if

370

an absolute path is not given. See <citerefentry>

371

372

</citerefentry>.

373

</para>

374

</listitem>

375

</varlistentry>

376

</variablelist>

377

</refsect1>

378

379

380

<title>FILES</title>

381

<para>

382

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

383

<command>&COMMANDNAME;</command> looks for its configurations

384

files. The default file names are listed here.

385

</para>

386

387

388

<term><filename>/etc/mandos/mandos.conf</filename></term>

389

390

<para>

391

Server-global settings. See

392

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

393

<manvolnum>5</manvolnum></citerefentry> for details.

394

</para>

395

</listitem>

396

</varlistentry>

397

398

<term><filename>/etc/mandos/clients.conf</filename></term>

399

400

<para>

401

List of clients and client-specific settings. See

402

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

403

<manvolnum>5</manvolnum></citerefentry> for details.

404

</para>

405

</listitem>

406

</varlistentry>

407

408

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

409

410

<para>

411

The file containing the process id of

412

<command>&COMMANDNAME;</command>.

413

</para>

414

</listitem>

415

</varlistentry>

416

417

418

419

<para>

420

The Unix domain socket to where local syslog messages are

421

sent.

422

</para>

423

</listitem>

424

</varlistentry>

425

426

427

428

<para>

429

This is used to start the configured checker command for

430

each client. See <citerefentry>

431

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

432

<manvolnum>5</manvolnum></citerefentry> for details.

433

</para>

434

</listitem>

435

</varlistentry>

436

</variablelist>

437

</refsect1>

438

439

440

441

<para>

442

This server might, on especially fatal errors, emit a Python

443

backtrace. This could be considered a feature.

444

</para>

445

<para>

446

Currently, if a client is declared <quote>invalid</quote> due to

447

having timed out, the server does not record this fact onto

448

permanent storage. This has some security implications, see

449

<xref linkend="CLIENTS"/>.

450

</para>

451

<para>

452

There is currently no way of querying the server of the current

453

status of clients, other than analyzing its <systemitem

454

class="service">syslog</systemitem> output.

455

</para>

456

<para>

457

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

458

</para>

459

<para>

460

Debug mode is conflated with running in the foreground.

461

</para>

462

<para>

463

The console log messages does not show a timestamp.

464

</para>

465

</refsect1>

466

467

468

<title>EXAMPLE</title>

469

470

<para>

471

Normal invocation needs no options:

472

</para>

473

<para>

474

<userinput>&COMMANDNAME;</userinput>

475

</para>

476

</informalexample>

477

478

<para>

479

Run the server in debug mode, read configuration files from

480

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

481

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

482

any other official Mandos server on this host:

483

</para>

484

<para>

485

486

487

<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>

488

489

</para>

490

</informalexample>

491

492

<para>

493

Run the server normally, but only listen to one interface and

494

only on the link-local address on that interface:

495

</para>

496

<para>

497

498

499

<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

500

501

</para>

502

</informalexample>

503

</refsect1>

504

505

506

<title>SECURITY</title>

507

508

<title>SERVER</title>

509

<para>

510

Running this <command>&COMMANDNAME;</command> server program

511

should not in itself present any security risk to the host

512

computer running it. The program does not need any special

513

privileges to run, and is designed to run as a non-root user.

514

</para>

515

</refsect2>

516

517

<title>CLIENTS</title>

518

<para>

519

The server only gives out its stored data to clients which

520

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

521

guaranteed by the fact that the client sends its OpenPGP

522

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

523

genuine. The server computes the fingerprint of the key

524

itself and looks up the fingerprint in its list of

525

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

526

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

527

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

528

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

529

except the user running the server.

530

</para>

531

<para>

532

As detailed in <xref linkend="checking"/>, the status of all

533

client computers will continually be checked and be assumed

534

compromised if they are gone for too long.

535

</para>

536

<para>

537

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

538

by the server which would therefore declare the client

539

invalid. But if the server was ever restarted, it would

540

re-read its client list from its configuration file and again

541

regard all clients therein as valid, and hence eligible to

542

receive their passwords. Therefore, be careful when

543

restarting servers if it is suspected that a client has, in

544

fact, been compromised by parties who may now be running a

545

fake Mandos client with the keys from the non-encrypted

546

initial RAM image of the client host. What should be done in

547

that case (if restarting the server program really is

548

necessary) is to stop the server program, edit the

549

configuration file to omit any suspect clients, and restart

550

the server program.

551

</para>

552

<para>

553

For more details on client-side security, see

554

<citerefentry><refentrytitle>password-request</refentrytitle>

555

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

556

</para>

557

</refsect2>

558

</refsect1>

559

560

561

562

<para>

563

564

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

565

566

<refentrytitle>mandos.conf</refentrytitle>

567

568

<refentrytitle>password-request</refentrytitle>

569

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

570

571

</citerefentry>

572

</para>

573

574

575

<term>

576

<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>

577

</term>

578

579

<para>

580

Zeroconf is the network protocol standard used by clients

581

for finding this Mandos server on the local network.

582

</para>

583

</listitem>

584

</varlistentry>

585

586

<term>

587

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

588

</term>

589

590

<para>

591

Avahi is the library this server calls to implement

592

Zeroconf service announcements.

593

</para>

594

</listitem>

595

</varlistentry>

596

597

<term>

598

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

599

>GnuTLS</ulink>

600

</term>

601

602

<para>

603

GnuTLS is the library this server uses to implement TLS for

604

communicating securely with the client, and at the same time

605

confidently get the client’s public OpenPGP key.

606

</para>

607

</listitem>

608

</varlistentry>

609

610

<term>

611

RFC 4291: <citetitle>IP Version 6 Addressing

612

Architecture</citetitle>

613

</term>

614

615

616

617

<term>Section 2.2: <citetitle>Text Representation of

618

Addresses</citetitle></term>

619

620

</varlistentry>

621

622

<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6

623

Address</citetitle></term>

624

625

</varlistentry>

626

627

<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast

628

Addresses</citetitle></term>

629

630

<para>

631

The clients use IPv6 link-local addresses, which are

632

immediately usable since a link-local addresses is

633

automatically assigned to a network interfaces when it

634

is brought up.

635

</para>

636

</listitem>

637

</varlistentry>

638

</variablelist>

639

</listitem>

640

</varlistentry>

641

642

<term>

643

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

644

Protocol Version 1.1</citetitle>

645

</term>

646

647

<para>

648

TLS 1.1 is the protocol implemented by GnuTLS.

649

</para>

650

</listitem>

651

</varlistentry>

652

653

<term>

654

RFC 4880: <citetitle>OpenPGP Message Format</citetitle>

655

</term>

656

657

<para>

658

The data sent to clients is binary encrypted OpenPGP data.

659

</para>

660

</listitem>

661

</varlistentry>

662

663

<term>

664

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

665

Security</citetitle>

666

</term>

667

668

<para>

669

This is implemented by GnuTLS and used by this server so

670

that OpenPGP keys can be used.

671

</para>

672

</listitem>

673

</varlistentry>

674

</variablelist>

675

</refsect1>

676

</refentry>

677

678

679

680

681