/mandos/trunk : revision 146

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-09-02">

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

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

38

</refentryinfo>

39

40

41

<refentrytitle>&COMMANDNAME;</refentrytitle>

42

43

</refmeta>

44

45

46

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

47

48

Gives encrypted passwords to authenticated Mandos clients

49

</refpurpose>

50

</refnamediv>

51

52

53

54

<command>&COMMANDNAME;</command>

55

<group>

56

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

57

58

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

59

60

</group>

61

<sbr/>

62

<group>

63

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

64

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

65

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

66

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

67

</group>

68

<sbr/>

69

<group>

70

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

71

72

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

73

74

</group>

75

<sbr/>

76

<arg><option>--priority

77

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

78

<sbr/>

79

<arg><option>--servicename

80

81

<sbr/>

82

<arg><option>--configdir

83

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

84

<sbr/>

85

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

86

</cmdsynopsis>

87

88

<command>&COMMANDNAME;</command>

89

90

91

92

</group>

93

</cmdsynopsis>

94

95

<command>&COMMANDNAME;</command>

96

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

97

</cmdsynopsis>

98

99

<command>&COMMANDNAME;</command>

100

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

101

</cmdsynopsis>

102

</refsynopsisdiv>

103

104

105

<title>DESCRIPTION</title>

106

<para>

107

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

108

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

109

client host computers. The Mandos server uses Zeroconf to

110

announce itself on the local network, and uses TLS to

111

communicate securely with and to authenticate the clients. The

112

Mandos server uses IPv6 to allow Mandos clients to use IPv6

113

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

114

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

115

Any authenticated client is then given the stored pre-encrypted

116

password for that specific client.

117

</para>

118

</refsect1>

119

120

121

<title>PURPOSE</title>

122

<para>

123

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

124

rebooting</emphasis> of client host computer with an

125

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

126

linkend="overview"/> for details.

127

</para>

128

</refsect1>

129

130

131

<title>OPTIONS</title>

132

133

134

135

136

137

<para>

138

Show a help message and exit

139

</para>

140

</listitem>

141

</varlistentry>

142

143

144

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

145

146

147

148

149

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

150

</listitem>

151

</varlistentry>

152

153

154

<term><option>--address

155

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

156

<term><option>-a

157

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

158

159

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

160

</listitem>

161

</varlistentry>

162

163

164

<term><option>--port

165

166

<term><option>-p

167

168

169

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

170

</listitem>

171

</varlistentry>

172

173

174

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

175

176

<para>

177

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

178

tests, etc.

179

</para>

180

</listitem>

181

</varlistentry>

182

183

184

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

185

186

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

187

</listitem>

188

</varlistentry>

189

190

191

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

192

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

193

194

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

195

</listitem>

196

</varlistentry>

197

198

199

<term><option>--servicename

200

201

202

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

203

xpointer="servicename"/>

204

</listitem>

205

</varlistentry>

206

207

208

<term><option>--configdir

209

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

210

211

<para>

212

Directory to search for configuration files. Default is

213

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

214

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

215

216

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

217

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

218

</para>

219

</listitem>

220

</varlistentry>

221

222

223

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

224

225

<para>

226

Prints the program version and exit.

227

</para>

228

</listitem>

229

</varlistentry>

230

</variablelist>

231

</refsect1>

232

233

234

<title>OVERVIEW</title>

235

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

236

<para>

237

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

238

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

239

<acronym>RAM</acronym> disk environment.

240

</para>

241

</refsect1>

242

243

244

<title>NETWORK PROTOCOL</title>

245

<para>

246

The Mandos server announces itself as a Zeroconf service of type

247

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

248

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

249

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

250

protocol version, which currently is

251

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

252

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

253

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

254

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

255

The Mandos client must supply an OpenPGP certificate, and the

256

fingerprint of this certificate is used by the Mandos server to

257

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

258

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

259

authentication or authorization is done by the server.

260

</para>

261

<table>

262

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

263

<row>

264

<entry>Mandos Client</entry>

265

<entry>Direction</entry>

266

<entry>Mandos Server</entry>

267

</row>

268

</thead><tbody>

269

<row>

270

<entry>Connect</entry>

271

272

</row>

273

<row>

274

275

276

</row>

277

<row>

278

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

279

</emphasis></entry>

280

281

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

282

</emphasis></entry>

283

</row>

284

<row>

285

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

286

287

</row>

288

<row>

289

290

291

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

292

</row>

293

<row>

294

295

296

<entry>Close</entry>

297

</row>

298

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

299

</refsect1>

300

301

302

<title>CHECKING</title>

303

<para>

304

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

305

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

306

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

307

longer eligible to receive the encrypted password. The timeout,

308

checker program, and interval between checks can be configured

309

both globally and per client; see <citerefentry>

310

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

311

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

312

</para>

313

</refsect1>

314

315

316

<title>LOGGING</title>

317

<para>

318

The server will send log message with various severity levels to

319

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

320

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

321

and also show them on the console.

322

</para>

323

</refsect1>

324

325

326

<title>EXIT STATUS</title>

327

<para>

328

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

329

critical error is encountered.

330

</para>

331

</refsect1>

332

333

334

<title>ENVIRONMENT</title>

335

336

337

338

339

<para>

340

To start the configured checker (see <xref

341

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

342

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

343

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

344

an absolute path is not given. See <citerefentry>

345

346

</citerefentry>.

347

</para>

348

</listitem>

349

</varlistentry>

350

</variablelist>

351

</refsect1>

352

353

354

<title>FILES</title>

355

<para>

356

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

357

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

358

files. The default file names are listed here.

359

</para>

360

361

362

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

363

364

<para>

365

Server-global settings. See

366

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

367

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

368

</para>

369

</listitem>

370

</varlistentry>

371

372

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

373

374

<para>

375

List of clients and client-specific settings. See

376

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

377

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

378

</para>

379

</listitem>

380

</varlistentry>

381

382

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

383

384

<para>

385

The file containing the process id of

386

<command>&COMMANDNAME;</command>.

387

</para>

388

</listitem>

389

</varlistentry>

390

391

392

393

<para>

394

The Unix domain socket to where local syslog messages are

395

sent.

396

</para>

397

</listitem>

398

</varlistentry>

399

400

401

402

<para>

403

This is used to start the configured checker command for

404

each client. See <citerefentry>

405

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

406

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

407

</para>

408

</listitem>

409

</varlistentry>

410

</variablelist>

411

</refsect1>

412

413

414

415

<para>

416

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

417

backtrace. This could be considered a feature.

418

</para>

419

<para>

420

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

421

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

422

permanent storage. This has some security implications, see

423

<xref linkend="CLIENTS"/>.

424

</para>

425

<para>

426

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

427

status of clients, other than analyzing its <systemitem

428

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

429

</para>

430

<para>

431

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

432

</para>

433

<para>

434

Debug mode is conflated with running in the foreground.

435

</para>

436

<para>

437

The console log messages does not show a timestamp.

438

</para>

439

</refsect1>

440

441

442

<title>EXAMPLE</title>

443

444

<para>

445

Normal invocation needs no options:

446

</para>

447

<para>

448

<userinput>&COMMANDNAME;</userinput>

449

</para>

450

</informalexample>

451

452

<para>

453

Run the server in debug mode, read configuration files from

454

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

455

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

456

any other official Mandos server on this host:

457

</para>

458

<para>

459

460

461

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

462

463

</para>

464

</informalexample>

465

466

<para>

467

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

468

only on the link-local address on that interface:

469

</para>

470

<para>

471

472

473

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

474

475

</para>

476

</informalexample>

477

</refsect1>

478

479

480

<title>SECURITY</title>

481

482

<title>SERVER</title>

483

<para>

484

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

485

should not in itself present any security risk to the host

486

computer running it. The program does not need any special

487

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

488

</para>

489

</refsect2>

490

491

<title>CLIENTS</title>

492

<para>

493

The server only gives out its stored data to clients which

494

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

495

guaranteed by the fact that the client sends its OpenPGP

496

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

497

genuine. The server computes the fingerprint of the key

498

itself and looks up the fingerprint in its list of

499

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

500

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

501

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

502

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

503

except the user running the server.

504

</para>

505

<para>

506

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

507

client computers will continually be checked and be assumed

508

compromised if they are gone for too long.

509

</para>

510

<para>

511

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

512

by the server which would therefore declare the client

513

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

514

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

515

regard all clients therein as valid, and hence eligible to

516

receive their passwords. Therefore, be careful when

517

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

518

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

519

fake Mandos client with the keys from the non-encrypted

520

initial <acronym>RAM</acronym> image of the client host. What

521

should be done in that case (if restarting the server program

522

really is necessary) is to stop the server program, edit the

523

configuration file to omit any suspect clients, and restart

524

the server program.

525

</para>

526

<para>

527

For more details on client-side security, see

528

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

529

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

530

</para>

531

</refsect2>

532

</refsect1>

533

534

535

536

<para>

537

538

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

539

540

<refentrytitle>mandos.conf</refentrytitle>

541

542

<refentrytitle>password-request</refentrytitle>

543

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

544

545

</citerefentry>

546

</para>

547

548

549

<term>

550

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

551

</term>

552

553

<para>

554

Zeroconf is the network protocol standard used by clients

555

for finding this Mandos server on the local network.

556

</para>

557

</listitem>

558

</varlistentry>

559

560

<term>

561

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

562

</term>

563

564

<para>

565

Avahi is the library this server calls to implement

566

Zeroconf service announcements.

567

</para>

568

</listitem>

569

</varlistentry>

570

571

<term>

572

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

573

>GnuTLS</ulink>

574

</term>

575

576

<para>

577

GnuTLS is the library this server uses to implement TLS for

578

communicating securely with the client, and at the same time

579

confidently get the client’s public OpenPGP key.

580

</para>

581

</listitem>

582

</varlistentry>

583

584

<term>

585

RFC 4291: <citetitle>IP Version 6 Addressing

586

Architecture</citetitle>

587

</term>

588

589

590

591

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

592

Addresses</citetitle></term>

593

594

</varlistentry>

595

596

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

597

Address</citetitle></term>

598

599

</varlistentry>

600

601

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

602

Addresses</citetitle></term>

603

604

<para>

605

The clients use IPv6 link-local addresses, which are

606

immediately usable since a link-local addresses is

607

automatically assigned to a network interfaces when it

608

is brought up.

609

</para>

610

</listitem>

611

</varlistentry>

612

</variablelist>

613

</listitem>

614

</varlistentry>

615

616

<term>

617

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

618

Protocol Version 1.1</citetitle>

619

</term>

620

621

<para>

622

TLS 1.1 is the protocol implemented by GnuTLS.

623

</para>

624

</listitem>

625

</varlistentry>

626

627

<term>

628

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

629

</term>

630

631

<para>

632

The data sent to clients is binary encrypted OpenPGP data.

633

</para>

634

</listitem>

635

</varlistentry>

636

637

<term>

638

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

639

Security</citetitle>

640

</term>

641

642

<para>

643

This is implemented by GnuTLS and used by this server so

644

that OpenPGP keys can be used.

645

</para>

646

</listitem>

647

</varlistentry>

648

</variablelist>

649

</refsect1>

650

</refentry>

651

652

653

654

655