/mandos/trunk : revision 48

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

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

Sends encrypted passwords to authenticated Mandos clients

71

</refpurpose>

72

</refnamediv>

73

74

75

76

<command>&COMMANDNAME;</command>

77

<arg>--interface<arg choice="plain">NAME</arg></arg>

78

<arg>--address<arg choice="plain">ADDRESS</arg></arg>

79

80

<arg>--priority<arg choice="plain">PRIORITY</arg></arg>

81

<arg>--servicename<arg choice="plain">NAME</arg></arg>

82

<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>

83

<arg>--debug</arg>

84

</cmdsynopsis>

85

86

<command>&COMMANDNAME;</command>

87

88

<arg>-a<arg choice="plain">ADDRESS</arg></arg>

89

90

<arg>--priority<arg choice="plain">PRIORITY</arg></arg>

91

<arg>--servicename<arg choice="plain">NAME</arg></arg>

92

<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>

93

<arg>--debug</arg>

94

</cmdsynopsis>

95

96

<command>&COMMANDNAME;</command>

97

98

99

100

</group>

101

</cmdsynopsis>

102

103

<command>&COMMANDNAME;</command>

104

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

105

</cmdsynopsis>

106

107

<command>&COMMANDNAME;</command>

108

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

109

</cmdsynopsis>

110

</refsynopsisdiv>

111

112

113

<title>DESCRIPTION</title>

114

<para>

115

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

116

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

117

client host computers. The Mandos server uses Zeroconf to

118

announce itself on the local network, and uses TLS to

119

communicate securely with and to authenticate the clients. The

120

Mandos server uses IPv6 to allow Mandos clients to use IPv6

121

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

122

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

123

Any authenticated client is then given the stored pre-encrypted

124

password for that specific client.

125

</para>

126

127

</refsect1>

128

129

130

<title>PURPOSE</title>

131

132

<para>

133

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

134

rebooting</emphasis> of client host computer with an

135

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

136

linkend="overview"/> for details.

137

</para>

138

139

</refsect1>

140

141

142

<title>OPTIONS</title>

143

144

145

146

147

148

<para>

149

Show a help message and exit

150

</para>

151

</listitem>

152

</varlistentry>

153

154

155

<term><literal>-i</literal>, <literal>--interface <replaceable

156

>NAME</replaceable></literal></term>

157

158

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

159

</listitem>

160

</varlistentry>

161

162

163

<term><literal>-a</literal>, <literal>--address <replaceable>

164

ADDRESS</replaceable></literal></term>

165

166

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

167

</listitem>

168

</varlistentry>

169

170

171

172

PORT</replaceable></literal></term>

173

174

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

175

</listitem>

176

</varlistentry>

177

178

179

<term><literal>--check</literal></term>

180

181

<para>

182

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

183

tests, etc.

184

</para>

185

</listitem>

186

</varlistentry>

187

188

189

<term><literal>--debug</literal></term>

190

191

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

192

</listitem>

193

</varlistentry>

194

195

196

<term><literal>--priority <replaceable>

197

PRIORITY</replaceable></literal></term>

198

199

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

200

</listitem>

201

</varlistentry>

202

203

204

<term><literal>--servicename <replaceable>NAME</replaceable>

205

</literal></term>

206

207

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

208

xpointer="servicename"/>

209

</listitem>

210

</varlistentry>

211

212

213

<term><literal>--configdir <replaceable>DIR</replaceable>

214

</literal></term>

215

216

<para>

217

Directory to search for configuration files. Default is

218

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

219

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

220

221

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

222

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

223

</para>

224

</listitem>

225

</varlistentry>

226

227

228

<term><literal>--version</literal></term>

229

230

<para>

231

Prints the program version and exit.

232

</para>

233

</listitem>

234

</varlistentry>

235

</variablelist>

236

</refsect1>

237

238

239

<title>OVERVIEW</title>

240

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

241

<para>

242

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

243

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

244

RAM disk environment.

245

</para>

246

</refsect1>

247

248

249

<title>NETWORK PROTOCOL</title>

250

<para>

251

The Mandos server announces itself as a Zeroconf service of type

252

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

253

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

254

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

255

protocol version, which currently is

256

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

257

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

258

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

259

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

260

The Mandos client must supply an OpenPGP certificate, and the

261

fingerprint of this certificate is used by the Mandos server to

262

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

263

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

264

authentication or authorization is done by the server.

265

</para>

266

<table>

267

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

268

<row>

269

<entry>Mandos Client</entry>

270

<entry>Direction</entry>

271

<entry>Mandos Server</entry>

272

</row>

273

</thead><tbody>

274

<row>

275

<entry>Connect</entry>

276

277

</row>

278

<row>

279

280

281

</row>

282

<row>

283

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

284

</emphasis></entry>

285

286

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

287

</emphasis></entry>

288

</row>

289

<row>

290

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

291

292

</row>

293

<row>

294

295

296

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

297

</row>

298

<row>

299

300

301

<entry>Close</entry>

302

</row>

303

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

304

</refsect1>

305

306

307

<title>CHECKING</title>

308

<para>

309

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

310

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

311

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

312

longer eligible to receive the encrypted password. The timeout,

313

checker program, and interval between checks can be configured

314

both globally and per client; see <citerefentry>

315

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

316

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

317

</para>

318

</refsect1>

319

320

321

<title>LOGGING</title>

322

<para>

323

The server will send log message with various severity levels to

324

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

325

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

326

and also show them on the console.

327

</para>

328

</refsect1>

329

330

331

<title>EXIT STATUS</title>

332

<para>

333

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

334

critical error is encountered.

335

</para>

336

</refsect1>

337

338

339

<title>ENVIRONMENT</title>

340

341

342

343

344

<para>

345

To start the configured checker (see <xref

346

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

347

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

348

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

349

an absolute path is not given. See <citerefentry>

350

351

</citerefentry>.

352

</para>

353

</listitem>

354

</varlistentry>

355

</variablelist>

356

</refsect1>

357

358

359

<title>FILES</title>

360

<para>

361

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

362

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

363

files. The default file names are listed here.

364

</para>

365

366

367

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

368

369

<para>

370

Server-global settings. See

371

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

372

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

373

</para>

374

</listitem>

375

</varlistentry>

376

377

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

378

379

<para>

380

List of clients and client-specific settings. See

381

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

382

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

383

</para>

384

</listitem>

385

</varlistentry>

386

387

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

388

389

<para>

390

The file containing the process id of

391

<command>&COMMANDNAME;</command>.

392

</para>

393

</listitem>

394

</varlistentry>

395

396

397

398

<para>

399

The Unix domain socket to where local syslog messages are

400

sent.

401

</para>

402

</listitem>

403

</varlistentry>

404

405

406

407

<para>

408

This is used to start the configured checker command for

409

each client. See <citerefentry>

410

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

411

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

412

</para>

413

</listitem>

414

</varlistentry>

415

</variablelist>

416

</refsect1>

417

418

419

420

<para>

421

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

422

backtrace. This could be considered a feature.

423

</para>

424

<para>

425

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

426

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

427

permanent storage. This has some security implications, see

428

<xref linkend="CLIENTS"/>.

429

</para>

430

<para>

431

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

432

status of clients, other than analyzing its <systemitem

433

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

434

</para>

435

<para>

436

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

437

</para>

438

<para>

439

Debug mode is conflated with running in the foreground.

440

</para>

441

<para>

442

The console log messages does not show a timestamp.

443

</para>

444

</refsect1>

445

446

447

<title>EXAMPLE</title>

448

449

<para>

450

Normal invocation needs no options:

451

</para>

452

<para>

453

<userinput>&COMMANDNAME;</userinput>

454

</para>

455

</informalexample>

456

457

<para>

458

Run the server in debug mode, read configuration files from

459

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

460

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

461

any other official Mandos server on this host:

462

</para>

463

<para>

464

465

466

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

467

468

</para>

469

</informalexample>

470

471

<para>

472

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

473

only on the link-local address on that interface:

474

</para>

475

<para>

476

477

478

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

479

480

</para>

481

</informalexample>

482

</refsect1>

483

484

485

<title>SECURITY</title>

486

487

<title>SERVER</title>

488

<para>

489

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

490

should not in itself present any security risk to the host

491

computer running it. The program does not need any special

492

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

493

</para>

494

</refsect2>

495

496

<title>CLIENTS</title>

497

<para>

498

The server only gives out its stored data to clients which

499

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

500

guaranteed by the fact that the client sends its OpenPGP

501

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

502

genuine. The server computes the fingerprint of the key

503

itself and looks up the fingerprint in its list of

504

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

505

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

506

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

507

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

508

except the user running the server.

509

</para>

510

<para>

511

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

512

client computers will continually be checked and be assumed

513

compromised if they are gone for too long.

514

</para>

515

<para>

516

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

517

by the server which would therefore declare the client

518

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

519

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

520

regard all clients therein as valid, and hence eligible to

521

receive their passwords. Therefore, be careful when

522

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

523

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

524

fake Mandos client with the keys from the non-encrypted

525

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

526

that case (if restarting the server program really is

527

necessary) is to stop the server program, edit the

528

configuration file to omit any suspect clients, and restart

529

the server program.

530

</para>

531

<para>

532

For more details on client-side security, see

533

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

534

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

535

</para>

536

</refsect2>

537

</refsect1>

538

539

540

541

<para>

542

543

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

544

545

<refentrytitle>mandos.conf</refentrytitle>

546

547

<refentrytitle>password-request</refentrytitle>

548

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

549

550

</citerefentry>

551

</para>

552

553

554

<term>

555

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

556

</term>

557

558

<para>

559

Zeroconf is the network protocol standard used by clients

560

for finding this Mandos server on the local network.

561

</para>

562

</listitem>

563

</varlistentry>

564

565

<term>

566

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

567

</term>

568

569

<para>

570

Avahi is the library this server calls to implement

571

Zeroconf service announcements.

572

</para>

573

</listitem>

574

</varlistentry>

575

576

<term>

577

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

578

>GnuTLS</ulink>

579

</term>

580

581

<para>

582

GnuTLS is the library this server uses to implement TLS for

583

communicating securely with the client, and at the same time

584

confidently get the client’s public OpenPGP key.

585

</para>

586

</listitem>

587

</varlistentry>

588

589

<term>

590

RFC 4291: <citetitle>IP Version 6 Addressing

591

Architecture</citetitle>

592

</term>

593

594

595

596

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

597

Addresses</citetitle></term>

598

599

</varlistentry>

600

601

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

602

Address</citetitle></term>

603

604

</varlistentry>

605

606

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

607

Addresses</citetitle></term>

608

609

<para>

610

The clients use IPv6 link-local addresses, which are

611

immediately usable since a link-local addresses is

612

automatically assigned to a network interfaces when it

613

is brought up.

614

</para>

615

</listitem>

616

</varlistentry>

617

</variablelist>

618

</listitem>

619

</varlistentry>

620

621

<term>

622

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

623

Protocol Version 1.1</citetitle>

624

</term>

625

626

<para>

627

TLS 1.1 is the protocol implemented by GnuTLS.

628

</para>

629

</listitem>

630

</varlistentry>

631

632

<term>

633

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

634

</term>

635

636

<para>

637

The data sent to clients is binary encrypted OpenPGP data.

638

</para>

639

</listitem>

640

</varlistentry>

641

642

<term>

643

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

644

Security</citetitle>

645

</term>

646

647

<para>

648

This is implemented by GnuTLS and used by this server so

649

that OpenPGP keys can be used.

650

</para>

651

</listitem>

652

</varlistentry>

653

</variablelist>

654

</refsect1>

655

</refentry>

656

657

658

659

660