/mandos/trunk : revision 26

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-01">

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

119

</refsect1>

120

121

122

<title>PURPOSE</title>

123

124

<para>

125

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

126

rebooting</emphasis> of client host computer with an

127

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

128

linkend="overview"/> for details.

129

</para>

130

131

</refsect1>

132

133

134

<title>OPTIONS</title>

135

136

137

138

139

140

141

<para>

142

Show a help message and exit

143

</para>

144

</listitem>

145

</varlistentry>

146

147

148

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

149

150

151

152

153

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

154

</listitem>

155

</varlistentry>

156

157

158

<term><option>--address

159

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

160

<term><option>-a

161

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

162

163

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

164

</listitem>

165

</varlistentry>

166

167

168

<term><option>--port

169

170

<term><option>-p

171

172

173

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

174

</listitem>

175

</varlistentry>

176

177

178

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

179

180

<para>

181

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

182

tests, etc.

183

</para>

184

</listitem>

185

</varlistentry>

186

187

188

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

189

190

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

191

</listitem>

192

</varlistentry>

193

194

195

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

196

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

197

198

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

199

</listitem>

200

</varlistentry>

201

202

203

<term><option>--servicename

204

205

206

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

207

xpointer="servicename"/>

208

</listitem>

209

</varlistentry>

210

211

212

<term><option>--configdir

213

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

214

215

<para>

216

Directory to search for configuration files. Default is

217

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

218

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

219

220

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

221

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

222

</para>

223

</listitem>

224

</varlistentry>

225

226

227

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

228

229

<para>

230

Prints the program version and exit.

231

</para>

232

</listitem>

233

</varlistentry>

234

</variablelist>

235

</refsect1>

236

237

238

<title>OVERVIEW</title>

239

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

240

<para>

241

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

242

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

243

<acronym>RAM</acronym> disk environment.

244

</para>

245

</refsect1>

246

247

248

<title>NETWORK PROTOCOL</title>

249

<para>

250

The Mandos server announces itself as a Zeroconf service of type

251

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

252

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

253

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

254

protocol version, which currently is

255

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

256

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

257

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

258

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

259

The Mandos client must supply an OpenPGP certificate, and the

260

fingerprint of this certificate is used by the Mandos server to

261

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

262

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

263

authentication or authorization is done by the server.

264

</para>

265

<table>

266

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

267

<row>

268

<entry>Mandos Client</entry>

269

<entry>Direction</entry>

270

<entry>Mandos Server</entry>

271

</row>

272

</thead><tbody>

273

<row>

274

<entry>Connect</entry>

275

276

</row>

277

<row>

278

279

280

</row>

281

<row>

282

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

283

</emphasis></entry>

284

285

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

286

</emphasis></entry>

287

</row>

288

<row>

289

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

290

291

</row>

292

<row>

293

294

295

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

296

</row>

297

<row>

298

299

300

<entry>Close</entry>

301

</row>

302

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

303

</refsect1>

304

305

306

<title>CHECKING</title>

307

<para>

308

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

309

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

310

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

311

longer eligible to receive the encrypted password. The timeout,

312

checker program, and interval between checks can be configured

313

both globally and per client; see <citerefentry>

314

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

315

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

316

</para>

317

</refsect1>

318

319

320

<title>LOGGING</title>

321

<para>

322

The server will send log message with various severity levels to

323

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

324

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

325

and also show them on the console.

326

</para>

327

</refsect1>

328

329

330

<title>EXIT STATUS</title>

331

<para>

332

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

333

critical error is encountered.

334

</para>

335

</refsect1>

336

337

338

<title>ENVIRONMENT</title>

339

340

341

342

343

<para>

344

To start the configured checker (see <xref

345

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

346

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

347

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

348

an absolute path is not given. See <citerefentry>

349

350

</citerefentry>.

351

</para>

352

</listitem>

353

</varlistentry>

354

</variablelist>

355

</refsect1>

356

357

358

<title>FILES</title>

359

<para>

360

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

361

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

362

files. The default file names are listed here.

363

</para>

364

365

366

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

367

368

<para>

369

Server-global settings. See

370

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

371

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

372

</para>

373

</listitem>

374

</varlistentry>

375

376

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

377

378

<para>

379

List of clients and client-specific settings. See

380

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

381

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

382

</para>

383

</listitem>

384

</varlistentry>

385

386

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

387

388

<para>

389

The file containing the process id of

390

<command>&COMMANDNAME;</command>.

391

</para>

392

</listitem>

393

</varlistentry>

394

395

396

397

<para>

398

The Unix domain socket to where local syslog messages are

399

sent.

400

</para>

401

</listitem>

402

</varlistentry>

403

404

405

406

<para>

407

This is used to start the configured checker command for

408

each client. See <citerefentry>

409

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

410

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

411

</para>

412

</listitem>

413

</varlistentry>

414

</variablelist>

415

</refsect1>

416

417

418

419

<para>

420

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

421

backtrace. This could be considered a feature.

422

</para>

423

<para>

424

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

425

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

426

permanent storage. This has some security implications, see

427

<xref linkend="CLIENTS"/>.

428

</para>

429

<para>

430

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

431

status of clients, other than analyzing its <systemitem

432

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

433

</para>

434

<para>

435

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

436

</para>

437

<para>

438

Debug mode is conflated with running in the foreground.

439

</para>

440

<para>

441

The console log messages does not show a timestamp.

442

</para>

443

</refsect1>

444

445

446

<title>EXAMPLE</title>

447

448

<para>

449

Normal invocation needs no options:

450

</para>

451

<para>

452

<userinput>&COMMANDNAME;</userinput>

453

</para>

454

</informalexample>

455

456

<para>

457

Run the server in debug mode, read configuration files from

458

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

459

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

460

any other official Mandos server on this host:

461

</para>

462

<para>

463

464

465

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

466

467

</para>

468

</informalexample>

469

470

<para>

471

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

472

only on the link-local address on that interface:

473

</para>

474

<para>

475

476

477

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

478

479

</para>

480

</informalexample>

481

</refsect1>

482

483

484

<title>SECURITY</title>

485

486

<title>SERVER</title>

487

<para>

488

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

489

should not in itself present any security risk to the host

490

computer running it. The program does not need any special

491

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

492

</para>

493

</refsect2>

494

495

<title>CLIENTS</title>

496

<para>

497

The server only gives out its stored data to clients which

498

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

499

guaranteed by the fact that the client sends its OpenPGP

500

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

501

genuine. The server computes the fingerprint of the key

502

itself and looks up the fingerprint in its list of

503

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

504

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

505

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

506

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

507

except the user running the server.

508

</para>

509

<para>

510

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

511

client computers will continually be checked and be assumed

512

compromised if they are gone for too long.

513

</para>

514

<para>

515

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

516

by the server which would therefore declare the client

517

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

518

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

519

regard all clients therein as valid, and hence eligible to

520

receive their passwords. Therefore, be careful when

521

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

522

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

523

fake Mandos client with the keys from the non-encrypted

524

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

525

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

526

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

527

configuration file to omit any suspect clients, and restart

528

the server program.

529

</para>

530

<para>

531

For more details on client-side security, see

532

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

533

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

534

</para>

535

</refsect2>

536

</refsect1>

537

538

539

540

<para>

541

542

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

543

544

<refentrytitle>mandos.conf</refentrytitle>

545

546

<refentrytitle>password-request</refentrytitle>

547

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

548

549

</citerefentry>

550

</para>

551

552

553

<term>

554

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

555

</term>

556

557

<para>

558

Zeroconf is the network protocol standard used by clients

559

for finding this Mandos server on the local network.

560

</para>

561

</listitem>

562

</varlistentry>

563

564

<term>

565

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

566

</term>

567

568

<para>

569

Avahi is the library this server calls to implement

570

Zeroconf service announcements.

571

</para>

572

</listitem>

573

</varlistentry>

574

575

<term>

576

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

577

>GnuTLS</ulink>

578

</term>

579

580

<para>

581

GnuTLS is the library this server uses to implement TLS for

582

communicating securely with the client, and at the same time

583

confidently get the client’s public OpenPGP key.

584

</para>

585

</listitem>

586

</varlistentry>

587

588

<term>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

591

</term>

592

593

594

595

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

596

Addresses</citetitle></term>

597

598

</varlistentry>

599

600

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

601

Address</citetitle></term>

602

603

</varlistentry>

604

605

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

606

Addresses</citetitle></term>

607

608

<para>

609

The clients use IPv6 link-local addresses, which are

610

immediately usable since a link-local addresses is

611

automatically assigned to a network interfaces when it

612

is brought up.

613

</para>

614

</listitem>

615

</varlistentry>

616

</variablelist>

617

</listitem>

618

</varlistentry>

619

620

<term>

621

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

622

Protocol Version 1.1</citetitle>

623

</term>

624

625

<para>

626

TLS 1.1 is the protocol implemented by GnuTLS.

627

</para>

628

</listitem>

629

</varlistentry>

630

631

<term>

632

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

633

</term>

634

635

<para>

636

The data sent to clients is binary encrypted OpenPGP data.

637

</para>

638

</listitem>

639

</varlistentry>

640

641

<term>

642

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

643

Security</citetitle>

644

</term>

645

646

<para>

647

This is implemented by GnuTLS and used by this server so

648

that OpenPGP keys can be used.

649

</para>

650

</listitem>

651

</varlistentry>

652

</variablelist>

653

</refsect1>

654

</refentry>

655

656

657

658

659