/mandos/trunk : revision 121

To get this branch, use:

bzr branch
http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos.xml

Committer: Teddy Hogeborn
Date: 2008-08-30 19:49:24 UTC
Revision ID: teddy@fukt.bsnet.se-20080830194924-f4liqq8wxajlbshn

* plugin-runner.xml (NAME): Improved wording.
  (SYNOPSIS): Use <option> and <replaceable> tags.  Unify short and
              long options.  Add "--global-envs" and "--envs-for"
              options.

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

mandos-keygen

mandos-keygen.xml

mandos-options.xml

overview.xml

plugins.d/usplash

files removed:
network-protocol.txt

files renamed:
mandos-client.c => plugin-runner.c

mandos-client.xml => plugin-runner.xml

files modified:
Makefile

TODO

clients.conf

mandos

mandos-clients.conf.xml

mandos.conf

mandos.conf.xml

mandos.xml

plugins.d/password-prompt.c

plugins.d/password-prompt.xml

plugins.d/password-request.c

plugins.d/password-request.xml

Show diffs side-by-side

added added

removed removed

mandos.xml

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

<?xml-stylesheet type="text/xsl"

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

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

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

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

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "mandos">

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

<title>&COMMANDNAME;</title>

<productname>&COMMANDNAME;</productname>

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

</authorgroup>

<holder>Teddy Hogeborn & Björn Påhlsson</holder>

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

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

Sends encrypted passwords to authenticated mandos clients

Gives encrypted passwords to authenticated Mandos clients

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>

<arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>

<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>

<arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>

<arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>

<arg choice='opt'>--debug</arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

</cmdsynopsis>

<group>

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

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

</group>

<sbr/>

<group>

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

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

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

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

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<arg><option>--priority

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

100

128

<para>

101

<command>&COMMANDNAME;</command> is a server daemon that handels

102

incomming passwords request for passwords. Mandos use avahi to

103

announce the service, and through gnutls authenticates

104

clients. Any authenticated client is then given its encrypted

105

password.

106

</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>

107

157

108

158

109

159

110

160

161

111

162

112

163

<para>

113

show a help message and exit

164

Show a help message and exit

114

165

</para>

115

166

</listitem>

116

167

</varlistentry>

117

168

118

169

119

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

120

IF</replaceable></literal></term>

170

171

172

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

173

121

174

122

<para>

123

Bind to interface IF

124

</para>

175

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

125

176

</listitem>

126

</varlistentry>

177

</varlistentry>

127

178

128

179

129

180

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

130

181

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

131

182

132

<para>

133

Address to listen for requests on

134

</para>

183

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

135

184

</listitem>

136

</varlistentry>

185

</varlistentry>

137

186

138

187

139

188

140

189

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

141

190

142

<para>

143

Port number to receive requests on

144

</para>

191

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

145

192

</listitem>

146

</varlistentry>

193

</varlistentry>

147

194

148

195

149

196

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

150

197

151

198

<para>

152

Run self-test on the server

199

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

200

tests, etc.

153

201

</para>

154

202

</listitem>

155

</varlistentry>

203

</varlistentry>

156

204

157

205

158

206

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

159

207

160

<para>

161

Debug mode

162

</para>

208

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

163

209

</listitem>

164

210

</varlistentry>

165

211

167

213

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

168

214

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

169

215

170

<para>

171

GnuTLS priority string. See <citerefentry>

172

<refentrytitle>gnutls_priority_init</refentrytitle>

173

174

</para>

216

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

175

217

</listitem>

176

</varlistentry>

218

</varlistentry>

177

219

178

220

179

221

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

180

222

</literal></term>

181

223

182

<para>

183

Zeroconf service name

184

</para>

224

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

225

xpointer="servicename"/>

185

226

</listitem>

186

</varlistentry>

227

</varlistentry>

187

228

188

229

189

230

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

190

231

</literal></term>

191

232

192

233

<para>

193

Directory to search for configuration files

234

Directory to search for configuration files. Default is

235

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

236

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

237

238

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

239

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

194

240

</para>

195

241

</listitem>

196

242

</varlistentry>

199

245

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

200

246

201

247

<para>

202

Prints the program version

203

</para>

204

</listitem>

205

</varlistentry>

206

248

Prints the program version and exit.

249

</para>

250

</listitem>

251

</varlistentry>

252

</variablelist>

253

</refsect1>

254

255

256

<title>OVERVIEW</title>

257

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

258

<para>

259

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

260

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

261

RAM disk environment.

262

</para>

263

</refsect1>

264

265

266

<title>NETWORK PROTOCOL</title>

267

<para>

268

The Mandos server announces itself as a Zeroconf service of type

269

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

270

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

271

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

272

protocol version, which currently is

273

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

274

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

275

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

276

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

277

The Mandos client must supply an OpenPGP certificate, and the

278

fingerprint of this certificate is used by the Mandos server to

279

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

280

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

281

authentication or authorization is done by the server.

282

</para>

283

<table>

284

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

285

<row>

286

<entry>Mandos Client</entry>

287

<entry>Direction</entry>

288

<entry>Mandos Server</entry>

289

</row>

290

</thead><tbody>

291

<row>

292

<entry>Connect</entry>

293

294

</row>

295

<row>

296

297

298

</row>

299

<row>

300

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

301

</emphasis></entry>

302

303

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

304

</emphasis></entry>

305

</row>

306

<row>

307

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

308

309

</row>

310

<row>

311

312

313

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

314

</row>

315

<row>

316

317

318

<entry>Close</entry>

319

</row>

320

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

321

</refsect1>

322

323

324

<title>CHECKING</title>

325

<para>

326

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

327

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

328

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

329

longer eligible to receive the encrypted password. The timeout,

330

checker program, and interval between checks can be configured

331

both globally and per client; see <citerefentry>

332

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

333

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

334

</para>

335

</refsect1>

336

337

338

<title>LOGGING</title>

339

<para>

340

The server will send log message with various severity levels to

341

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

342

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

343

and also show them on the console.

344

</para>

345

</refsect1>

346

347

348

<title>EXIT STATUS</title>

349

<para>

350

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

351

critical error is encountered.

352

</para>

353

</refsect1>

354

355

356

<title>ENVIRONMENT</title>

357

358

359

360

361

<para>

362

To start the configured checker (see <xref

363

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

364

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

365

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

366

an absolute path is not given. See <citerefentry>

367

368

</citerefentry>.

369

</para>

370

</listitem>

371

</varlistentry>

372

</variablelist>

373

</refsect1>

374

375

376

<title>FILES</title>

377

<para>

378

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

379

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

380

files. The default file names are listed here.

381

</para>

382

383

384

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

385

386

<para>

387

Server-global settings. See

388

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

389

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

390

</para>

391

</listitem>

392

</varlistentry>

393

394

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

395

396

<para>

397

List of clients and client-specific settings. See

398

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

399

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

400

</para>

401

</listitem>

402

</varlistentry>

403

404

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

405

406

<para>

407

The file containing the process id of

408

<command>&COMMANDNAME;</command>.

409

</para>

410

</listitem>

411

</varlistentry>

412

413

414

415

<para>

416

The Unix domain socket to where local syslog messages are

417

sent.

418

</para>

419

</listitem>

420

</varlistentry>

421

422

423

424

<para>

425

This is used to start the configured checker command for

426

each client. See <citerefentry>

427

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

428

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

429

</para>

430

</listitem>

431

</varlistentry>

432

</variablelist>

433

</refsect1>

434

435

436

437

<para>

438

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

439

backtrace. This could be considered a feature.

440

</para>

441

<para>

442

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

443

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

444

permanent storage. This has some security implications, see

445

<xref linkend="CLIENTS"/>.

446

</para>

447

<para>

448

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

449

status of clients, other than analyzing its <systemitem

450

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

451

</para>

452

<para>

453

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

454

</para>

455

<para>

456

Debug mode is conflated with running in the foreground.

457

</para>

458

<para>

459

The console log messages does not show a timestamp.

460

</para>

461

</refsect1>

462

463

464

<title>EXAMPLE</title>

465

466

<para>

467

Normal invocation needs no options:

468

</para>

469

<para>

470

<userinput>&COMMANDNAME;</userinput>

471

</para>

472

</informalexample>

473

474

<para>

475

Run the server in debug mode, read configuration files from

476

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

477

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

478

any other official Mandos server on this host:

479

</para>

480

<para>

481

482

483

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

484

485

</para>

486

</informalexample>

487

488

<para>

489

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

490

only on the link-local address on that interface:

491

</para>

492

<para>

493

494

495

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

496

497

</para>

498

</informalexample>

499

</refsect1>

500

501

502

<title>SECURITY</title>

503

504

<title>SERVER</title>

505

<para>

506

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

507

should not in itself present any security risk to the host

508

computer running it. The program does not need any special

509

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

510

</para>

511

</refsect2>

512

513

<title>CLIENTS</title>

514

<para>

515

The server only gives out its stored data to clients which

516

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

517

guaranteed by the fact that the client sends its OpenPGP

518

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

519

genuine. The server computes the fingerprint of the key

520

itself and looks up the fingerprint in its list of

521

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

522

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

523

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

524

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

525

except the user running the server.

526

</para>

527

<para>

528

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

529

client computers will continually be checked and be assumed

530

compromised if they are gone for too long.

531

</para>

532

<para>

533

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

534

by the server which would therefore declare the client

535

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

536

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

537

regard all clients therein as valid, and hence eligible to

538

receive their passwords. Therefore, be careful when

539

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

540

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

541

fake Mandos client with the keys from the non-encrypted

542

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

543

that case (if restarting the server program really is

544

necessary) is to stop the server program, edit the

545

configuration file to omit any suspect clients, and restart

546

the server program.

547

</para>

548

<para>

549

For more details on client-side security, see

550

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

551

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

552

</para>

553

</refsect2>

554

</refsect1>

555

556

557

558

<para>

559

560

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

561

562

<refentrytitle>mandos.conf</refentrytitle>

563

564

<refentrytitle>password-request</refentrytitle>

565

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

566

567

</citerefentry>

568

</para>

569

570

571

<term>

572

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

573

</term>

574

575

<para>

576

Zeroconf is the network protocol standard used by clients

577

for finding this Mandos server on the local network.

578

</para>

579

</listitem>

580

</varlistentry>

581

582

<term>

583

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

584

</term>

585

586

<para>

587

Avahi is the library this server calls to implement

588

Zeroconf service announcements.

589

</para>

590

</listitem>

591

</varlistentry>

592

593

<term>

594

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

595

>GnuTLS</ulink>

596

</term>

597

598

<para>

599

GnuTLS is the library this server uses to implement TLS for

600

communicating securely with the client, and at the same time

601

confidently get the client’s public OpenPGP key.

602

</para>

603

</listitem>

604

</varlistentry>

605

606

<term>

607

RFC 4291: <citetitle>IP Version 6 Addressing

608

Architecture</citetitle>

609

</term>

610

611

612

613

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

614

Addresses</citetitle></term>

615

616

</varlistentry>

617

618

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

619

Address</citetitle></term>

620

621

</varlistentry>

622

623

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

624

Addresses</citetitle></term>

625

626

<para>

627

The clients use IPv6 link-local addresses, which are

628

immediately usable since a link-local addresses is

629

automatically assigned to a network interfaces when it

630

is brought up.

631

</para>

632

</listitem>

633

</varlistentry>

634

</variablelist>

635

</listitem>

636

</varlistentry>

637

638

<term>

639

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

640

Protocol Version 1.1</citetitle>

641

</term>

642

643

<para>

644

TLS 1.1 is the protocol implemented by GnuTLS.

645

</para>

646

</listitem>

647

</varlistentry>

648

649

<term>

650

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

651

</term>

652

653

<para>

654

The data sent to clients is binary encrypted OpenPGP data.

655

</para>

656

</listitem>

657

</varlistentry>

658

659

<term>

660

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

661

Security</citetitle>

662

</term>

663

664

<para>

665

This is implemented by GnuTLS and used by this server so

666

that OpenPGP keys can be used.

667

</para>

668

</listitem>

669

</varlistentry>

207

670

</variablelist>

208

671

</refsect1>

209

672

</refentry>

673

674

675

676

677

Older »