/mandos/trunk : revision 102

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-24 23:33:02 UTC
mfrom: (24.1.65 mandos)
Revision ID: teddy@fukt.bsnet.se-20080824233302-kfu4g2pkozg7xrmz

* plugin-runner.c (process): Set "completed" and "status" as volatile.
(handle_sigchld): Bug fix: reset proc to process_list every time.

files added:
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">

<title>&COMMANDNAME;</title>

<productname>&COMMANDNAME;</productname>

<productnumber>&VERSION;</productnumber>

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

</group>

</cmdsynopsis>

100

101

<command>&COMMANDNAME;</command>

102

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

103

</cmdsynopsis>

104

105

<command>&COMMANDNAME;</command>

106

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

107

</cmdsynopsis>

108

</refsynopsisdiv>

109

110

111

<title>DESCRIPTION</title>

100

112

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

113

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

114

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

115

client host computers. The Mandos server uses Zeroconf to

116

announce itself on the local network, and uses TLS to

117

communicate securely with and to authenticate the clients. The

118

Mandos server uses IPv6 to allow Mandos clients to use IPv6

119

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

120

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

121

Any authenticated client is then given the stored pre-encrypted

122

password for that specific client.

123

</para>

124

125

</refsect1>

126

127

128

<title>PURPOSE</title>

129

130

<para>

131

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

132

rebooting</emphasis> of client host computer with an

133

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

134

linkend="overview"/> for details.

135

</para>

136

137

</refsect1>

138

139

140

<title>OPTIONS</title>

107

141

108

142

109

143

110

144

111

145

112

146

<para>

113

show a help message and exit

147

Show a help message and exit

114

148

</para>

115

149

</listitem>

116

150

</varlistentry>

119

153

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

120

154

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

121

155

122

<para>

123

Bind to interface IF

124

</para>

156

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

125

157

</listitem>

126

</varlistentry>

158

</varlistentry>

127

159

128

160

129

161

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

130

162

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

131

163

132

<para>

133

Address to listen for requests on

134

</para>

164

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

135

165

</listitem>

136

</varlistentry>

166

</varlistentry>

137

167

138

168

139

169

140

170

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

141

171

142

<para>

143

Port number to receive requests on

144

</para>

172

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

145

173

</listitem>

146

</varlistentry>

174

</varlistentry>

147

175

148

176

149

177

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

150

178

151

179

<para>

152

Run self-test on the server

180

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

181

tests, etc.

153

182

</para>

154

183

</listitem>

155

</varlistentry>

184

</varlistentry>

156

185

157

186

158

187

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

159

188

160

<para>

161

Debug mode

162

</para>

189

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

163

190

</listitem>

164

191

</varlistentry>

165

192

167

194

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

168

195

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

169

196

170

<para>

171

GnuTLS priority string. See <citerefentry>

172

<refentrytitle>gnutls_priority_init</refentrytitle>

173

174

</para>

197

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

175

198

</listitem>

176

</varlistentry>

199

</varlistentry>

177

200

178

201

179

202

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

180

203

</literal></term>

181

204

182

<para>

183

Zeroconf service name

184

</para>

205

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

206

xpointer="servicename"/>

185

207

</listitem>

186

</varlistentry>

208

</varlistentry>

187

209

188

210

189

211

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

190

212

</literal></term>

191

213

192

214

<para>

193

Directory to search for configuration files

215

Directory to search for configuration files. Default is

216

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

217

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

218

219

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

220

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

194

221

</para>

195

222

</listitem>

196

223

</varlistentry>

199

226

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

200

227

201

228

<para>

202

Prints the program version

203

</para>

204

</listitem>

205

</varlistentry>

206

229

Prints the program version and exit.

230

</para>

231

</listitem>

232

</varlistentry>

233

</variablelist>

234

</refsect1>

235

236

237

<title>OVERVIEW</title>

238

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

239

<para>

240

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

241

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

242

RAM disk environment.

243

</para>

244

</refsect1>

245

246

247

<title>NETWORK PROTOCOL</title>

248

<para>

249

The Mandos server announces itself as a Zeroconf service of type

250

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

251

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

252

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

253

protocol version, which currently is

254

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

255

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

256

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

257

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

258

The Mandos client must supply an OpenPGP certificate, and the

259

fingerprint of this certificate is used by the Mandos server to

260

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

261

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

262

authentication or authorization is done by the server.

263

</para>

264

<table>

265

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

266

<row>

267

<entry>Mandos Client</entry>

268

<entry>Direction</entry>

269

<entry>Mandos Server</entry>

270

</row>

271

</thead><tbody>

272

<row>

273

<entry>Connect</entry>

274

275

</row>

276

<row>

277

278

279

</row>

280

<row>

281

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

282

</emphasis></entry>

283

284

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

285

</emphasis></entry>

286

</row>

287

<row>

288

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

289

290

</row>

291

<row>

292

293

294

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

295

</row>

296

<row>

297

298

299

<entry>Close</entry>

300

</row>

301

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

302

</refsect1>

303

304

305

<title>CHECKING</title>

306

<para>

307

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

308

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

309

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

310

longer eligible to receive the encrypted password. The timeout,

311

checker program, and interval between checks can be configured

312

both globally and per client; see <citerefentry>

313

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

314

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

315

</para>

316

</refsect1>

317

318

319

<title>LOGGING</title>

320

<para>

321

The server will send log message with various severity levels to

322

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

323

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

324

and also show them on the console.

325

</para>

326

</refsect1>

327

328

329

<title>EXIT STATUS</title>

330

<para>

331

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

332

critical error is encountered.

333

</para>

334

</refsect1>

335

336

337

<title>ENVIRONMENT</title>

338

339

340

341

342

<para>

343

To start the configured checker (see <xref

344

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

345

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

346

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

347

an absolute path is not given. See <citerefentry>

348

349

</citerefentry>.

350

</para>

351

</listitem>

352

</varlistentry>

353

</variablelist>

354

</refsect1>

355

356

357

<title>FILES</title>

358

<para>

359

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

360

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

361

files. The default file names are listed here.

362

</para>

363

364

365

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

366

367

<para>

368

Server-global settings. See

369

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

370

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

371

</para>

372

</listitem>

373

</varlistentry>

374

375

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

376

377

<para>

378

List of clients and client-specific settings. See

379

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

380

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

381

</para>

382

</listitem>

383

</varlistentry>

384

385

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

386

387

<para>

388

The file containing the process id of

389

<command>&COMMANDNAME;</command>.

390

</para>

391

</listitem>

392

</varlistentry>

393

394

395

396

<para>

397

The Unix domain socket to where local syslog messages are

398

sent.

399

</para>

400

</listitem>

401

</varlistentry>

402

403

404

405

<para>

406

This is used to start the configured checker command for

407

each client. See <citerefentry>

408

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

409

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

410

</para>

411

</listitem>

412

</varlistentry>

413

</variablelist>

414

</refsect1>

415

416

417

418

<para>

419

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

420

backtrace. This could be considered a feature.

421

</para>

422

<para>

423

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

424

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

425

permanent storage. This has some security implications, see

426

<xref linkend="CLIENTS"/>.

427

</para>

428

<para>

429

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

430

status of clients, other than analyzing its <systemitem

431

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

432

</para>

433

<para>

434

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

435

</para>

436

<para>

437

Debug mode is conflated with running in the foreground.

438

</para>

439

<para>

440

The console log messages does not show a timestamp.

441

</para>

442

</refsect1>

443

444

445

<title>EXAMPLE</title>

446

447

<para>

448

Normal invocation needs no options:

449

</para>

450

<para>

451

<userinput>mandos</userinput>

452

</para>

453

</informalexample>

454

455

<para>

456

Run the server in debug mode, read configuration files from

457

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

458

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

459

any other official Mandos server on this host:

460

</para>

461

<para>

462

463

464

<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>

465

466

</para>

467

</informalexample>

468

469

<para>

470

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

471

only on the link-local address on that interface:

472

</para>

473

<para>

474

475

476

<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

477

478

</para>

479

</informalexample>

480

</refsect1>

481

482

483

<title>SECURITY</title>

484

485

<title>SERVER</title>

486

<para>

487

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

488

should not in itself present any security risk to the host

489

computer running it. The program does not need any special

490

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

491

</para>

492

</refsect2>

493

494

<title>CLIENTS</title>

495

<para>

496

The server only gives out its stored data to clients which

497

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

498

guaranteed by the fact that the client sends its OpenPGP

499

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

500

genuine. The server computes the fingerprint of the key

501

itself and looks up the fingerprint in its list of

502

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

503

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

504

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

505

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

506

except the user running the server.

507

</para>

508

<para>

509

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

510

client computers will continually be checked and be assumed

511

compromised if they are gone for too long.

512

</para>

513

<para>

514

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

515

by the server which would therefore declare the client

516

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

517

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

518

regard all clients therein as valid, and hence eligible to

519

receive their passwords. Therefore, be careful when

520

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

521

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

522

fake Mandos client with the keys from the non-encrypted

523

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

524

that case (if restarting the server program really is

525

necessary) is to stop the server program, edit the

526

configuration file to omit any suspect clients, and restart

527

the server program.

528

</para>

529

<para>

530

For more details on client-side security, see

531

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

532

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

533

</para>

534

</refsect2>

535

</refsect1>

536

537

538

539

<para>

540

541

<refentrytitle>mandos.conf</refentrytitle>

542

543

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

544

545

<refentrytitle>password-request</refentrytitle>

546

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

547

548

</citerefentry>

549

</para>

550

551

552

<term>

553

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

554

</term>

555

556

<para>

557

Zeroconf is the network protocol standard used by clients

558

for finding this Mandos server on the local network.

559

</para>

560

</listitem>

561

</varlistentry>

562

563

<term>

564

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

565

</term>

566

567

<para>

568

Avahi is the library this server calls to implement

569

Zeroconf service announcements.

570

</para>

571

</listitem>

572

</varlistentry>

573

574

<term>

575

<ulink

576

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

577

</term>

578

579

<para>

580

GnuTLS is the library this server uses to implement TLS for

581

communicating securely with the client, and at the same time

582

confidently get the client’s public OpenPGP key.

583

</para>

584

</listitem>

585

</varlistentry>

586

587

<term>

588

<citation>RFC 4291: <citetitle>IP Version 6 Addressing

589

Architecture</citetitle>, section 2.5.6, Link-Local IPv6

590

Unicast Addresses</citation>

591

</term>

592

593

<para>

594

The clients use IPv6 link-local addresses, which are

595

immediately usable since a link-local addresses is

596

automatically assigned to a network interfaces when it is

597

brought up.

598

</para>

599

</listitem>

600

</varlistentry>

601

602

<term>

603

<citation>RFC 4346: <citetitle>The Transport Layer Security

604

(TLS) Protocol Version 1.1</citetitle></citation>

605

</term>

606

607

<para>

608

TLS 1.1 is the protocol implemented by GnuTLS.

609

</para>

610

</listitem>

611

</varlistentry>

612

613

<term>

614

<citation>RFC 4880: <citetitle>OpenPGP Message

615

Format</citetitle></citation>

616

</term>

617

618

<para>

619

The data sent to clients is binary encrypted OpenPGP data.

620

</para>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

<citation>RFC 5081: <citetitle>Using OpenPGP Keys for

626

Transport Layer Security</citetitle></citation>

627

</term>

628

629

<para>

630

This is implemented by GnuTLS and used by this server so

631

that OpenPGP keys can be used.

632

</para>

633

</listitem>

634

</varlistentry>

207

635

</variablelist>

208

636

</refsect1>

209

637

</refentry>

Older »