/mandos/release : revision 115

To get this branch, use:

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

« back to all changes in this revision

Viewing changes to mandos.xml

Committer: Teddy Hogeborn
Date: 2008-08-29 16:53:41 UTC
Revision ID: teddy@fukt.bsnet.se-20080829165341-xzrp0xxxfrua5kzq

* mandos.xml (SYNOPSIS): Split <term> tags for the "--help" and
"--interface" options.

files added:
.bzrignore

COPYING

mandos-keygen.xml

mandos-options.xml

overview.xml

files removed:
network-protocol.txt

files modified:
Makefile

TODO

clients.conf

initramfs-tools-hook

mandos

mandos-clients.conf.xml

mandos-keygen

mandos.conf

mandos.conf.xml

mandos.xml

plugin-runner.c

plugin-runner.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-29">

<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

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

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

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

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

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

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

<arg>--debug</arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

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

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

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

<arg>--debug</arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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>

100

114

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

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>

107

143

108

144

109

145

110

146

147

111

148

112

149

<para>

113

show a help message and exit

150

Show a help message and exit

114

151

</para>

115

152

</listitem>

116

153

</varlistentry>

117

154

118

155

119

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

120

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

156

157

158

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

159

121

160

122

<para>

123

Bind to interface IF

124

</para>

161

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

125

162

</listitem>

126

</varlistentry>

163

</varlistentry>

127

164

128

165

129

166

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

130

167

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

131

168

132

<para>

133

Address to listen for requests on

134

</para>

169

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

135

170

</listitem>

136

</varlistentry>

171

</varlistentry>

137

172

138

173

139

174

140

175

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

141

176

142

<para>

143

Port number to receive requests on

144

</para>

177

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

145

178

</listitem>

146

</varlistentry>

179

</varlistentry>

147

180

148

181

149

182

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

150

183

151

184

<para>

152

Run self-test on the server

185

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

186

tests, etc.

153

187

</para>

154

188

</listitem>

155

</varlistentry>

189

</varlistentry>

156

190

157

191

158

192

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

159

193

160

<para>

161

Debug mode

162

</para>

194

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

163

195

</listitem>

164

196

</varlistentry>

165

197

167

199

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

168

200

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

169

201

170

<para>

171

GnuTLS priority string. See <citerefentry>

172

<refentrytitle>gnutls_priority_init</refentrytitle>

173

174

</para>

202

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

175

203

</listitem>

176

</varlistentry>

204

</varlistentry>

177

205

178

206

179

207

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

180

208

</literal></term>

181

209

182

<para>

183

Zeroconf service name

184

</para>

210

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

211

xpointer="servicename"/>

185

212

</listitem>

186

</varlistentry>

213

</varlistentry>

187

214

188

215

189

216

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

190

217

</literal></term>

191

218

192

219

<para>

193

Directory to search for configuration files

220

Directory to search for configuration files. Default is

221

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

222

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

223

224

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

225

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

194

226

</para>

195

227

</listitem>

196

228

</varlistentry>

199

231

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

200

232

201

233

<para>

202

Prints the program version

203

</para>

204

</listitem>

205

</varlistentry>

206

234

Prints the program version and exit.

235

</para>

236

</listitem>

237

</varlistentry>

238

</variablelist>

239

</refsect1>

240

241

242

<title>OVERVIEW</title>

243

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

244

<para>

245

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

246

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

247

RAM disk environment.

248

</para>

249

</refsect1>

250

251

252

<title>NETWORK PROTOCOL</title>

253

<para>

254

The Mandos server announces itself as a Zeroconf service of type

255

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

256

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

257

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

258

protocol version, which currently is

259

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

260

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

261

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

262

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

263

The Mandos client must supply an OpenPGP certificate, and the

264

fingerprint of this certificate is used by the Mandos server to

265

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

266

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

267

authentication or authorization is done by the server.

268

</para>

269

<table>

270

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

271

<row>

272

<entry>Mandos Client</entry>

273

<entry>Direction</entry>

274

<entry>Mandos Server</entry>

275

</row>

276

</thead><tbody>

277

<row>

278

<entry>Connect</entry>

279

280

</row>

281

<row>

282

283

284

</row>

285

<row>

286

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

287

</emphasis></entry>

288

289

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

290

</emphasis></entry>

291

</row>

292

<row>

293

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

294

295

</row>

296

<row>

297

298

299

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

300

</row>

301

<row>

302

303

304

<entry>Close</entry>

305

</row>

306

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

307

</refsect1>

308

309

310

<title>CHECKING</title>

311

<para>

312

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

313

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

314

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

315

longer eligible to receive the encrypted password. The timeout,

316

checker program, and interval between checks can be configured

317

both globally and per client; see <citerefentry>

318

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

319

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

320

</para>

321

</refsect1>

322

323

324

<title>LOGGING</title>

325

<para>

326

The server will send log message with various severity levels to

327

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

328

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

329

and also show them on the console.

330

</para>

331

</refsect1>

332

333

334

<title>EXIT STATUS</title>

335

<para>

336

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

337

critical error is encountered.

338

</para>

339

</refsect1>

340

341

342

<title>ENVIRONMENT</title>

343

344

345

346

347

<para>

348

To start the configured checker (see <xref

349

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

350

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

351

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

352

an absolute path is not given. See <citerefentry>

353

354

</citerefentry>.

355

</para>

356

</listitem>

357

</varlistentry>

358

</variablelist>

359

</refsect1>

360

361

362

<title>FILES</title>

363

<para>

364

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

365

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

366

files. The default file names are listed here.

367

</para>

368

369

370

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

371

372

<para>

373

Server-global settings. See

374

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

375

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

376

</para>

377

</listitem>

378

</varlistentry>

379

380

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

381

382

<para>

383

List of clients and client-specific settings. See

384

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

385

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

386

</para>

387

</listitem>

388

</varlistentry>

389

390

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

391

392

<para>

393

The file containing the process id of

394

<command>&COMMANDNAME;</command>.

395

</para>

396

</listitem>

397

</varlistentry>

398

399

400

401

<para>

402

The Unix domain socket to where local syslog messages are

403

sent.

404

</para>

405

</listitem>

406

</varlistentry>

407

408

409

410

<para>

411

This is used to start the configured checker command for

412

each client. See <citerefentry>

413

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

414

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

415

</para>

416

</listitem>

417

</varlistentry>

418

</variablelist>

419

</refsect1>

420

421

422

423

<para>

424

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

425

backtrace. This could be considered a feature.

426

</para>

427

<para>

428

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

429

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

430

permanent storage. This has some security implications, see

431

<xref linkend="CLIENTS"/>.

432

</para>

433

<para>

434

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

435

status of clients, other than analyzing its <systemitem

436

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

437

</para>

438

<para>

439

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

440

</para>

441

<para>

442

Debug mode is conflated with running in the foreground.

443

</para>

444

<para>

445

The console log messages does not show a timestamp.

446

</para>

447

</refsect1>

448

449

450

<title>EXAMPLE</title>

451

452

<para>

453

Normal invocation needs no options:

454

</para>

455

<para>

456

<userinput>&COMMANDNAME;</userinput>

457

</para>

458

</informalexample>

459

460

<para>

461

Run the server in debug mode, read configuration files from

462

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

463

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

464

any other official Mandos server on this host:

465

</para>

466

<para>

467

468

469

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

470

471

</para>

472

</informalexample>

473

474

<para>

475

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

476

only on the link-local address on that interface:

477

</para>

478

<para>

479

480

481

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

482

483

</para>

484

</informalexample>

485

</refsect1>

486

487

488

<title>SECURITY</title>

489

490

<title>SERVER</title>

491

<para>

492

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

493

should not in itself present any security risk to the host

494

computer running it. The program does not need any special

495

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

496

</para>

497

</refsect2>

498

499

<title>CLIENTS</title>

500

<para>

501

The server only gives out its stored data to clients which

502

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

503

guaranteed by the fact that the client sends its OpenPGP

504

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

505

genuine. The server computes the fingerprint of the key

506

itself and looks up the fingerprint in its list of

507

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

508

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

509

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

510

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

511

except the user running the server.

512

</para>

513

<para>

514

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

515

client computers will continually be checked and be assumed

516

compromised if they are gone for too long.

517

</para>

518

<para>

519

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

520

by the server which would therefore declare the client

521

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

522

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

523

regard all clients therein as valid, and hence eligible to

524

receive their passwords. Therefore, be careful when

525

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

526

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

527

fake Mandos client with the keys from the non-encrypted

528

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

529

that case (if restarting the server program really is

530

necessary) is to stop the server program, edit the

531

configuration file to omit any suspect clients, and restart

532

the server program.

533

</para>

534

<para>

535

For more details on client-side security, see

536

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

537

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

538

</para>

539

</refsect2>

540

</refsect1>

541

542

543

544

<para>

545

546

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

547

548

<refentrytitle>mandos.conf</refentrytitle>

549

550

<refentrytitle>password-request</refentrytitle>

551

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

552

553

</citerefentry>

554

</para>

555

556

557

<term>

558

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

559

</term>

560

561

<para>

562

Zeroconf is the network protocol standard used by clients

563

for finding this Mandos server on the local network.

564

</para>

565

</listitem>

566

</varlistentry>

567

568

<term>

569

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

570

</term>

571

572

<para>

573

Avahi is the library this server calls to implement

574

Zeroconf service announcements.

575

</para>

576

</listitem>

577

</varlistentry>

578

579

<term>

580

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

581

>GnuTLS</ulink>

582

</term>

583

584

<para>

585

GnuTLS is the library this server uses to implement TLS for

586

communicating securely with the client, and at the same time

587

confidently get the client’s public OpenPGP key.

588

</para>

589

</listitem>

590

</varlistentry>

591

592

<term>

593

RFC 4291: <citetitle>IP Version 6 Addressing

594

Architecture</citetitle>

595

</term>

596

597

598

599

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

600

Addresses</citetitle></term>

601

602

</varlistentry>

603

604

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

605

Address</citetitle></term>

606

607

</varlistentry>

608

609

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

610

Addresses</citetitle></term>

611

612

<para>

613

The clients use IPv6 link-local addresses, which are

614

immediately usable since a link-local addresses is

615

automatically assigned to a network interfaces when it

616

is brought up.

617

</para>

618

</listitem>

619

</varlistentry>

620

</variablelist>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

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

626

Protocol Version 1.1</citetitle>

627

</term>

628

629

<para>

630

TLS 1.1 is the protocol implemented by GnuTLS.

631

</para>

632

</listitem>

633

</varlistentry>

634

635

<term>

636

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

637

</term>

638

639

<para>

640

The data sent to clients is binary encrypted OpenPGP data.

641

</para>

642

</listitem>

643

</varlistentry>

644

645

<term>

646

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

647

Security</citetitle>

648

</term>

649

650

<para>

651

This is implemented by GnuTLS and used by this server so

652

that OpenPGP keys can be used.

653

</para>

654

</listitem>

655

</varlistentry>

207

656

</variablelist>

208

657

</refsect1>

209

658

</refentry>

659

660

661

662

663

Older »