/mandos/trunk : revision 85

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-18 03:25:01 UTC
Revision ID: teddy@fukt.bsnet.se-20080818032501-2cl874fi3uvsqn1b

* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
                         tags.  Also show the "-h" option.
  (OPTIONS): Note that failure to obey the "--interface" option is not
             considered critical.
  (ENVIRONMENT): New section to document the use of PATH by /bin/sh.
  (FILES): Added "/bin/sh".
  (BUGS): Add five bugs from the TODO file.
  (EXAMPLES): Renamed to "EXAMPLE", as per man-pages(7).
  (SERVER, CLIENTS): Added "id" attribute.
  (CLIENT): Document the security implications of one of the five
            bugs added to the BUGS section.

files added:
COPYING

TODO

clients.conf

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

mandos

mandos-clients.conf.xml

mandos-keygen

mandos-keygen.xml

mandos.conf

mandos.conf.xml

mandos.xml

overview.xml

plugin-runner.c

plugin-runner.xml

plugins.d

plugins.d/password-prompt.c

plugins.d/password-prompt.xml

plugins.d/password-request.c

plugins.d/password-request.xml

plugins.d/usplash

files removed:
ca.pem

cert.pem

client-cert.pem

client-key.pem

client.cpp

crl.pem

key.pem

files modified:
Makefile

Show diffs side-by-side

added added

removed removed

mandos.xml

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

<firstname>Björn</firstname>

<surname>Påhlsson</surname>

<email>belorn@fukt.bsnet.se</email>

</address>

</author>

<firstname>Teddy</firstname>

<surname>Hogeborn</surname>

<email>teddy@fukt.bsnet.se</email>

</address>

</author>

</authorgroup>

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

This manual page is free software: you can redistribute it

and/or modify it under the terms of the GNU General Public

License as published by the Free Software Foundation,

either version 3 of the License, or (at your option) any

later version.

</para>

<para>

This manual page is distributed in the hope that it will

be useful, but WITHOUT ANY WARRANTY; without even the

implied warranty of MERCHANTABILITY or FITNESS FOR A

PARTICULAR PURPOSE. See the GNU General Public License

for more details.

</para>

<para>

You should have received a copy of the GNU General Public

License along with this program; If not, see

<ulink url="http://www.gnu.org/licenses/"/>.

</para>

</legalnotice>

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

</refmeta>

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

Sends encrypted passwords to authenticated Mandos clients

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

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

113

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

142

143

144

145

146

147

<para>

148

Show a help message and exit

149

</para>

150

</listitem>

151

</varlistentry>

152

153

154

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

155

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

156

157

<para>

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.

163

</para>

164

</listitem>

165

</varlistentry>

166

167

168

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

169

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

170

171

<para>

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.

180

</para>

181

</listitem>

182

</varlistentry>

183

184

185

186

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

187

188

<para>

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.

192

</para>

193

</listitem>

194

</varlistentry>

195

196

197

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

198

199

<para>

200

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

201

tests, etc.

202

</para>

203

</listitem>

204

</varlistentry>

205

206

207

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

208

209

<para>

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.

213

</para>

214

</listitem>

215

</varlistentry>

216

217

218

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

219

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

220

221

<para>

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.

230

</para>

231

</listitem>

232

</varlistentry>

233

234

235

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

236

</literal></term>

237

238

<para>

239

Zeroconf service name. The default is

240

<quote><literal>Mandos</literal></quote>. You only need

241

to change this if you for some reason want to run more

242

than one server on the same <emphasis>host</emphasis>,

243

which would not normally be useful. If there are name

244

collisions on the same <emphasis>network</emphasis>, the

245

newer server will automatically rename itself to

246

<quote><literal>Mandos #2</literal></quote>, and so on;

247

therefore, this option is not needed in that case.

248

</para>

249

</listitem>

250

</varlistentry>

251

252

253

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

254

</literal></term>

255

256

<para>

257

Directory to search for configuration files. Default is

258

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

259

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

260

261

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

262

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

263

</para>

264

</listitem>

265

</varlistentry>

266

267

268

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

269

270

<para>

271

Prints the program version and exit.

272

</para>

273

</listitem>

274

</varlistentry>

275

</variablelist>

276

</refsect1>

277

278

279

<title>OVERVIEW</title>

280

&OVERVIEW;

281

<para>

282

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

283

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

284

RAM disk environment.

285

</para>

286

</refsect1>

287

288

289

<title>NETWORK PROTOCOL</title>

290

<para>

291

The Mandos server announces itself as a Zeroconf service of type

292

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

293

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

294

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

295

protocol version, which currently is

296

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

297

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

298

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

299

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

300

The Mandos client must supply an OpenPGP certificate, and the

301

fingerprint of this certificate is used by the Mandos server to

302

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

303

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

304

authentication or authorization is done by the server.

305

</para>

306

<table>

307

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

308

<row>

309

<entry>Mandos Client</entry>

310

<entry>Direction</entry>

311

<entry>Mandos Server</entry>

312

</row>

313

</thead><tbody>

314

<row>

315

<entry>Connect</entry>

316

317

</row>

318

<row>

319

320

321

</row>

322

<row>

323

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

324

</emphasis></entry>

325

326

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

327

</emphasis></entry>

328

</row>

329

<row>

330

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

331

332

</row>

333

<row>

334

335

336

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

337

</row>

338

<row>

339

340

341

<entry>Close</entry>

342

</row>

343

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

344

</refsect1>

345

346

347

<title>CHECKING</title>

348

<para>

349

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

350

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

351

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

352

longer eligible to receive the encrypted password. The timeout,

353

checker program, and interval between checks can be configured

354

both globally and per client; see <citerefentry>

355

<refentrytitle>mandos.conf</refentrytitle>

356

357

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

358

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

359

</para>

360

</refsect1>

361

362

363

<title>LOGGING</title>

364

<para>

365

The server will send log messaged with various severity levels

366

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

367

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

368

and also show them on the console.

369

</para>

370

</refsect1>

371

372

373

<title>EXIT STATUS</title>

374

<para>

375

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

376

critical error is encountered.

377

</para>

378

</refsect1>

379

380

381

<title>ENVIRONMENT</title>

382

383

384

385

386

<para>

387

To start the configured checker (see <xref

388

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

389

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

390

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

391

an absolute path is not given. See <citerefentry>

392

393

</citerefentry>

394

</para>

395

</listitem>

396

</varlistentry>

397

</variablelist>

398

</refsect1>

399

400

401

<title>FILES</title>

402

<para>

403

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

404

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

405

files. The default file names are listed here.

406

</para>

407

408

409

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

410

411

<para>

412

Server-global settings. See

413

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

414

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

415

</para>

416

</listitem>

417

</varlistentry>

418

419

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

420

421

<para>

422

List of clients and client-specific settings. See

423

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

424

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

425

</para>

426

</listitem>

427

</varlistentry>

428

429

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

430

431

<para>

432

The file containing the process id of

433

<command>&COMMANDNAME;</command>.

434

</para>

435

</listitem>

436

</varlistentry>

437

438

439

440

<para>

441

The Unix domain socket to where local syslog messages are

442

sent.

443

</para>

444

</listitem>

445

</varlistentry>

446

447

448

449

<para>

450

This is used to start the configured checker command for

451

each client. See <citerefentry>

452

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

453

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

454

</para>

455

</listitem>

456

</varlistentry>

457

</variablelist>

458

</refsect1>

459

460

461

462

<para>

463

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

464

backtrace. This could be considered a feature.

465

</para>

466

<para>

467

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

468

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

469

permanent storage. This has some security implications, see

470

<xref linkend="CLIENTS"/>.

471

</para>

472

<para>

473

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

474

status of clients, other than analyzing its <systemitem

475

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

476

</para>

477

<para>

478

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

479

</para>

480

<para>

481

Debug mode is conflated with running in the foreground.

482

</para>

483

<para>

484

The console log messages does not show a timestamp.

485

</para>

486

</refsect1>

487

488

489

<title>EXAMPLE</title>

490

491

<para>

492

Normal invocation needs no options:

493

</para>

494

<para>

495

<userinput>mandos</userinput>

496

</para>

497

</informalexample>

498

499

<para>

500

Run the server in debug mode, read configuration files from

501

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

502

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

503

any other official Mandos server on this host:

504

</para>

505

<para>

506

507

508

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

509

510

</para>

511

</informalexample>

512

513

<para>

514

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

515

only on the link-local address on that interface:

516

</para>

517

<para>

518

519

520

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

521

522

</para>

523

</informalexample>

524

</refsect1>

525

526

527

<title>SECURITY</title>

528

529

<title>SERVER</title>

530

<para>

531

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

532

should not in itself present any security risk to the host

533

computer running it. The program does not need any special

534

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

535

</para>

536

</refsect2>

537

538

<title>CLIENTS</title>

539

<para>

540

The server only gives out its stored data to clients which

541

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

542

guaranteed by the fact that the client sends its OpenPGP

543

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

544

genuine. The server computes the fingerprint of the key

545

itself and looks up the fingerprint in its list of

546

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

547

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

548

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

549

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

550

except the user running the server.

551

</para>

552

<para>

553

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

554

client computers will continually be checked and be assumed

555

compromised if they are gone for too long.

556

</para>

557

<para>

558

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

559

by the server which would therefore declare the client

560

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

561

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

562

regard all clients therein as valid, and hence eligible to

563

receive their passwords. Therefore, be careful when

564

restarting servers if you suspect that a client has, in fact,

565

been compromised by parties who may now be running a fake

566

Mandos client with the keys from the non-encrypted initial RAM

567

image of the client host. What should be done in that case

568

(if restarting the server program really is necessary) is to

569

stop the server program, edit the configuration file to omit

570

any suspect clients, and restart the server program.

571

</para>

572

<para>

573

For more details on client-side security, see

574

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

575

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

576

</para>

577

</refsect2>

578

</refsect1>

579

580

581

582

583

584

<term>

585

586

<refentrytitle>password-request</refentrytitle>

587

<manvolnum>8mandos</manvolnum>

588

</citerefentry>

589

</term>

590

591

<para>

592

This is the actual program which talks to this server.

593

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

594

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

595

fully started system.

596

</para>

597

</listitem>

598

</varlistentry>

599

600

<term>

601

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

602

</term>

603

604

<para>

605

Zeroconf is the network protocol standard used by clients

606

for finding this Mandos server on the local network.

607

</para>

608

</listitem>

609

</varlistentry>

610

611

<term>

612

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

613

</term>

614

615

<para>

616

Avahi is the library this server calls to implement

617

Zeroconf service announcements.

618

</para>

619

</listitem>

620

</varlistentry>

621

622

<term>

623

<ulink

624

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

625

</term>

626

627

<para>

628

GnuTLS is the library this server uses to implement TLS for

629

communicating securely with the client, and at the same time

630

confidently get the client’s public OpenPGP key.

631

</para>

632

</listitem>

633

</varlistentry>

634

635

<term>

636

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

637

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

638

Unicast Addresses</citation>

639

</term>

640

641

<para>

642

The clients use IPv6 link-local addresses, which are

643

immediately usable since a link-local addresses is

644

automatically assigned to a network interfaces when it is

645

brought up.

646

</para>

647

</listitem>

648

</varlistentry>

649

650

<term>

651

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

652

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

653

</term>

654

655

<para>

656

TLS 1.1 is the protocol implemented by GnuTLS.

657

</para>

658

</listitem>

659

</varlistentry>

660

661

<term>

662

<citation>RFC 4880: <citetitle>OpenPGP Message

663

Format</citetitle></citation>

664

</term>

665

666

<para>

667

The data sent to clients is binary encrypted OpenPGP data.

668

</para>

669

</listitem>

670

</varlistentry>

671

672

<term>

673

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

674

Transport Layer Security</citetitle></citation>

675

</term>

676

677

<para>

678

This is implemented by GnuTLS and used by this server so

679

that OpenPGP keys can be used.

680

</para>

681

</listitem>

682

</varlistentry>

683

</variablelist>

684

</refsect1>

685

</refentry>

Older »