/mandos/release : revision 88

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-18 05:57:11 UTC
Revision ID: teddy@fukt.bsnet.se-20080818055711-2rpzat3hkbq3us62

No code or documentation changes.

files added:
COPYING

mandos-keygen.xml

overview.xml

files removed:
network-protocol.txt

files modified:
Makefile

TODO

mandos

mandos-keygen

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 OVERVIEW SYSTEM "overview.xml">

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

100

</cmdsynopsis>

101

102

<command>&COMMANDNAME;</command>

103

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

104

</cmdsynopsis>

105

106

<command>&COMMANDNAME;</command>

107

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

108

</cmdsynopsis>

109

</refsynopsisdiv>

110

111

112

<title>DESCRIPTION</title>

100

113

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

114

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

115

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

116

client host computers. The Mandos server uses Zeroconf to

117

announce itself on the local network, and uses TLS to

118

communicate securely with and to authenticate the clients. The

119

Mandos server uses IPv6 to allow Mandos clients to use IPv6

120

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

121

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

122

Any authenticated client is then given the stored pre-encrypted

123

password for that specific client.

124

</para>

125

126

</refsect1>

127

128

129

<title>PURPOSE</title>

130

131

<para>

132

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

133

rebooting</emphasis> of client host computer with an

134

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

135

linkend="overview"/> for details.

136

</para>

137

138

</refsect1>

139

140

141

<title>OPTIONS</title>

107

142

108

143

109

144

110

145

111

146

112

147

<para>

113

show a help message and exit

148

Show a help message and exit

114

149

</para>

115

150

</listitem>

116

151

</varlistentry>

120

155

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

121

156

122

157

<para>

123

Bind to interface IF

158

Only announce the server and listen to requests on network

159

interface <replaceable>IF</replaceable>. Default is to

160

use all available interfaces. <emphasis>Note:</emphasis>

161

a failure to bind to the specified interface is not

162

considered critical, and the server does not exit.

124

163

</para>

125

164

</listitem>

126

</varlistentry>

165

</varlistentry>

127

166

128

167

129

168

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

130

169

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

131

170

132

171

<para>

133

Address to listen for requests on

172

If this option is used, the server will only listen to a

173

specific address. This must currently be an IPv6 address;

174

an IPv4 address can be specified using the

175

<quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.

176

Also, if a link-local address is specified, an interface

177

should be set, since a link-local address is only valid on

178

a single interface. By default, the server will listen to

179

all available addresses.

134

180

</para>

135

181

</listitem>

136

</varlistentry>

182

</varlistentry>

137

183

138

184

139

185

140

186

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

141

187

142

188

<para>

143

Port number to receive requests on

189

If this option is used, the server to bind to that

190

port. By default, the server will listen to an arbitrary

191

port given by the operating system.

144

192

</para>

145

193

</listitem>

146

</varlistentry>

194

</varlistentry>

147

195

148

196

149

197

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

150

198

151

199

<para>

152

Run self-test on the server

200

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

201

tests, etc.

153

202

</para>

154

203

</listitem>

155

</varlistentry>

204

</varlistentry>

156

205

157

206

158

207

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

159

208

160

209

<para>

161

Debug mode

210

If the server is run in debug mode, it will run in the

211

foreground and print a lot of debugging information. The

212

default is <emphasis>not</emphasis> to run in debug mode.

162

213

</para>

163

214

</listitem>

164

215

</varlistentry>

168

219

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

169

220

170

221

<para>

171

GnuTLS priority string. See <citerefentry>

172

<refentrytitle>gnutls_priority_init</refentrytitle>

173

222

GnuTLS priority string for the TLS handshake with the

223

clients. The default is

224

<quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.

225

See <citerefentry><refentrytitle>gnutls_priority_init

226

</refentrytitle><manvolnum>3</manvolnum></citerefentry>

227

for the syntax. <emphasis>Warning</emphasis>: changing

228

this may make the TLS handshake fail, making communication

229

with clients impossible.

174

230

</para>

175

231

</listitem>

176

</varlistentry>

232

</varlistentry>

177

233

178

234

179

235

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

180

236

</literal></term>

181

237

182

238

<para>

183

Zeroconf service name

239

Zeroconf service name. The default is

240

<quote><literal>Mandos</literal></quote>. This only needs

241

to be changed this if it, for some reason, is necessary to

242

run more than one server on the same

243

<emphasis>host</emphasis>, which would not normally be

244

useful. If there are name collisions on the same

245

<emphasis>network</emphasis>, the newer server will

246

automatically rename itself to <quote><literal>Mandos

247

#2</literal></quote>, and so on; therefore, this option is

248

not needed in that case.

184

249

</para>

185

250

</listitem>

186

</varlistentry>

251

</varlistentry>

187

252

188

253

189

254

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

190

255

</literal></term>

191

256

192

257

<para>

193

Directory to search for configuration files

258

Directory to search for configuration files. Default is

259

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

260

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

261

262

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

263

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

194

264

</para>

195

265

</listitem>

196

266

</varlistentry>

199

269

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

200

270

201

271

<para>

202

Prints the program version

203

</para>

204

</listitem>

205

</varlistentry>

206

272

Prints the program version and exit.

273

</para>

274

</listitem>

275

</varlistentry>

276

</variablelist>

277

</refsect1>

278

279

280

<title>OVERVIEW</title>

281

&OVERVIEW;

282

<para>

283

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

284

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

285

RAM disk environment.

286

</para>

287

</refsect1>

288

289

290

<title>NETWORK PROTOCOL</title>

291

<para>

292

The Mandos server announces itself as a Zeroconf service of type

293

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

294

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

295

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

296

protocol version, which currently is

297

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

298

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

299

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

300

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

301

The Mandos client must supply an OpenPGP certificate, and the

302

fingerprint of this certificate is used by the Mandos server to

303

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

304

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

305

authentication or authorization is done by the server.

306

</para>

307

<table>

308

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

309

<row>

310

<entry>Mandos Client</entry>

311

<entry>Direction</entry>

312

<entry>Mandos Server</entry>

313

</row>

314

</thead><tbody>

315

<row>

316

<entry>Connect</entry>

317

318

</row>

319

<row>

320

321

322

</row>

323

<row>

324

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

325

</emphasis></entry>

326

327

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

328

</emphasis></entry>

329

</row>

330

<row>

331

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

332

333

</row>

334

<row>

335

336

337

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

338

</row>

339

<row>

340

341

342

<entry>Close</entry>

343

</row>

344

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

345

</refsect1>

346

347

348

<title>CHECKING</title>

349

<para>

350

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

351

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

352

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

353

longer eligible to receive the encrypted password. The timeout,

354

checker program, and interval between checks can be configured

355

both globally and per client; see <citerefentry>

356

<refentrytitle>mandos.conf</refentrytitle>

357

358

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

359

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

360

</para>

361

</refsect1>

362

363

364

<title>LOGGING</title>

365

<para>

366

The server will send log messaged with various severity levels

367

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

368

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

369

and also show them on the console.

370

</para>

371

</refsect1>

372

373

374

<title>EXIT STATUS</title>

375

<para>

376

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

377

critical error is encountered.

378

</para>

379

</refsect1>

380

381

382

<title>ENVIRONMENT</title>

383

384

385

386

387

<para>

388

To start the configured checker (see <xref

389

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

390

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

391

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

392

an absolute path is not given. See <citerefentry>

393

394

</citerefentry>

395

</para>

396

</listitem>

397

</varlistentry>

398

</variablelist>

399

</refsect1>

400

401

402

<title>FILES</title>

403

<para>

404

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

405

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

406

files. The default file names are listed here.

407

</para>

408

409

410

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

411

412

<para>

413

Server-global settings. See

414

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

415

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

416

</para>

417

</listitem>

418

</varlistentry>

419

420

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

421

422

<para>

423

List of clients and client-specific settings. See

424

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

425

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

426

</para>

427

</listitem>

428

</varlistentry>

429

430

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

431

432

<para>

433

The file containing the process id of

434

<command>&COMMANDNAME;</command>.

435

</para>

436

</listitem>

437

</varlistentry>

438

439

440

441

<para>

442

The Unix domain socket to where local syslog messages are

443

sent.

444

</para>

445

</listitem>

446

</varlistentry>

447

448

449

450

<para>

451

This is used to start the configured checker command for

452

each client. See <citerefentry>

453

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

454

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

455

</para>

456

</listitem>

457

</varlistentry>

458

</variablelist>

459

</refsect1>

460

461

462

463

<para>

464

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

465

backtrace. This could be considered a feature.

466

</para>

467

<para>

468

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

469

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

470

permanent storage. This has some security implications, see

471

<xref linkend="CLIENTS"/>.

472

</para>

473

<para>

474

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

475

status of clients, other than analyzing its <systemitem

476

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

477

</para>

478

<para>

479

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

480

</para>

481

<para>

482

Debug mode is conflated with running in the foreground.

483

</para>

484

<para>

485

The console log messages does not show a timestamp.

486

</para>

487

</refsect1>

488

489

490

<title>EXAMPLE</title>

491

492

<para>

493

Normal invocation needs no options:

494

</para>

495

<para>

496

<userinput>mandos</userinput>

497

</para>

498

</informalexample>

499

500

<para>

501

Run the server in debug mode, read configuration files from

502

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

503

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

504

any other official Mandos server on this host:

505

</para>

506

<para>

507

508

509

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

510

511

</para>

512

</informalexample>

513

514

<para>

515

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

516

only on the link-local address on that interface:

517

</para>

518

<para>

519

520

521

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

522

523

</para>

524

</informalexample>

525

</refsect1>

526

527

528

<title>SECURITY</title>

529

530

<title>SERVER</title>

531

<para>

532

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

533

should not in itself present any security risk to the host

534

computer running it. The program does not need any special

535

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

536

</para>

537

</refsect2>

538

539

<title>CLIENTS</title>

540

<para>

541

The server only gives out its stored data to clients which

542

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

543

guaranteed by the fact that the client sends its OpenPGP

544

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

545

genuine. The server computes the fingerprint of the key

546

itself and looks up the fingerprint in its list of

547

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

548

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

549

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

550

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

551

except the user running the server.

552

</para>

553

<para>

554

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

555

client computers will continually be checked and be assumed

556

compromised if they are gone for too long.

557

</para>

558

<para>

559

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

560

by the server which would therefore declare the client

561

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

562

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

563

regard all clients therein as valid, and hence eligible to

564

receive their passwords. Therefore, be careful when

565

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

566

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

567

fake Mandos client with the keys from the non-encrypted

568

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

569

that case (if restarting the server program really is

570

necessary) is to stop the server program, edit the

571

configuration file to omit any suspect clients, and restart

572

the server program.

573

</para>

574

<para>

575

For more details on client-side security, see

576

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

577

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

578

</para>

579

</refsect2>

580

</refsect1>

581

582

583

584

585

586

<term>

587

588

<refentrytitle>password-request</refentrytitle>

589

<manvolnum>8mandos</manvolnum>

590

</citerefentry>

591

</term>

592

593

<para>

594

This is the actual program which talks to this server.

595

Note that it is normally not invoked directly, and is only

596

run in the initial RAM disk environment, and not on a

597

fully started system.

598

</para>

599

</listitem>

600

</varlistentry>

601

602

<term>

603

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

604

</term>

605

606

<para>

607

Zeroconf is the network protocol standard used by clients

608

for finding this Mandos server on the local network.

609

</para>

610

</listitem>

611

</varlistentry>

612

613

<term>

614

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

615

</term>

616

617

<para>

618

Avahi is the library this server calls to implement

619

Zeroconf service announcements.

620

</para>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

<ulink

626

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

627

</term>

628

629

<para>

630

GnuTLS is the library this server uses to implement TLS for

631

communicating securely with the client, and at the same time

632

confidently get the client’s public OpenPGP key.

633

</para>

634

</listitem>

635

</varlistentry>

636

637

<term>

638

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

639

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

640

Unicast Addresses</citation>

641

</term>

642

643

<para>

644

The clients use IPv6 link-local addresses, which are

645

immediately usable since a link-local addresses is

646

automatically assigned to a network interfaces when it is

647

brought up.

648

</para>

649

</listitem>

650

</varlistentry>

651

652

<term>

653

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

654

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

655

</term>

656

657

<para>

658

TLS 1.1 is the protocol implemented by GnuTLS.

659

</para>

660

</listitem>

661

</varlistentry>

662

663

<term>

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

666

</term>

667

668

<para>

669

The data sent to clients is binary encrypted OpenPGP data.

670

</para>

671

</listitem>

672

</varlistentry>

673

674

<term>

675

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

676

Transport Layer Security</citetitle></citation>

677

</term>

678

679

<para>

680

This is implemented by GnuTLS and used by this server so

681

that OpenPGP keys can be used.

682

</para>

683

</listitem>

684

</varlistentry>

207

685

</variablelist>

208

686

</refsect1>

209

687

</refentry>

Older »