/mandos/trunk : revision 150

1

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

2

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

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "password-request">

6

<!ENTITY TIMESTAMP "2008-09-03">

7

]>

8

9

10

11

<title>Mandos Manual</title>

12

13

<productname>Mandos</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

17

18

<firstname>Björn</firstname>

19

<surname>Påhlsson</surname>

20

21

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

22

</address>

23

</author>

24

25

<firstname>Teddy</firstname>

26

<surname>Hogeborn</surname>

27

28

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

29

</address>

30

</author>

31

</authorgroup>

32

33

34

<holder>Teddy Hogeborn</holder>

35

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

36

</copyright>

37

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

38

</refentryinfo>

39

40

41

<refentrytitle>&COMMANDNAME;</refentrytitle>

42

<manvolnum>8mandos</manvolnum>

43

</refmeta>

44

45

46

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

47

48

Client for mandos

49

</refpurpose>

50

</refnamediv>

51

52

53

54

<command>&COMMANDNAME;</command>

55

<group>

56

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

57

<replaceable>IPADDR</replaceable><literal>:</literal

58

><replaceable>PORT</replaceable></option></arg>

59

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

60

<replaceable>IPADDR</replaceable><literal>:</literal

61

><replaceable>PORT</replaceable></option></arg>

62

</group>

63

<sbr/>

64

<group>

65

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

66

<replaceable>DIRECTORY</replaceable></option></arg>

67

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

68

<replaceable>DIRECTORY</replaceable></option></arg>

69

</group>

70

<sbr/>

71

<group>

72

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

73

74

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

75

76

</group>

77

<sbr/>

78

<group>

79

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

80

81

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

82

83

</group>

84

<sbr/>

85

<group>

86

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

87

88

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

89

90

</group>

91

<sbr/>

92

<arg>

93

<option>--priority <replaceable>STRING</replaceable></option>

94

</arg>

95

<sbr/>

96

<arg>

97

98

</arg>

99

<sbr/>

100

<arg>

101

<option>--debug</option>

102

</arg>

103

</cmdsynopsis>

104

105

<command>&COMMANDNAME;</command>

106

107

108

109

</group>

110

</cmdsynopsis>

111

112

<command>&COMMANDNAME;</command>

113

<arg choice="plain"><option>--usage</option></arg>

114

</cmdsynopsis>

115

116

<command>&COMMANDNAME;</command>

117

118

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

119

120

</group>

121

</cmdsynopsis>

122

</refsynopsisdiv>

123

124

125

<title>DESCRIPTION</title>

126

<para>

127

<command>&COMMANDNAME;</command> is a client program that

128

communicates with <citerefentry><refentrytitle

129

>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>

130

to get a password. It uses IPv6 link-local addresses to get

131

network connectivity, Zeroconf to find servers, and TLS with an

132

OpenPGP key to ensure authenticity and confidentiality. It

133

keeps running, trying all servers on the network, until it

134

receives a satisfactory reply or a TERM signal is recieved.

135

</para>

136

<para>

137

This program is not meant to be run directly; it is really meant

138

to run as a plugin of the <application>Mandos</application>

139

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

140

<manvolnum>8mandos</manvolnum></citerefentry>, which runs in the

141

initial <acronym>RAM</acronym> disk environment because it is

142

specified as a <quote>keyscript</quote> in the <citerefentry>

143

<refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>

144

</citerefentry> file.

145

</para>

146

</refsect1>

147

148

149

<title>PURPOSE</title>

150

<para>

151

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

152

rebooting</emphasis> of client host computer with an

153

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

154

linkend="overview"/> for details.

155

</para>

156

</refsect1>

157

158

159

<title>OPTIONS</title>

160

<para>

161

This program is commonly not invoked from the command line; it

162

is normally started by the <application>Mandos</application>

163

plugin runner, see <citerefentry><refentrytitle

164

>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

165

</citerefentry>. Any command line options this program accepts

166

are therefore normally provided by the plugin runner, and not

167

directly.

168

</para>

169

170

171

172

<term><option>--connect=<replaceable

173

>ADDRESS</replaceable><literal>:</literal><replaceable

174

>PORT</replaceable></option></term>

175

<term><option>-c

176

<replaceable>ADDRESS</replaceable><literal>:</literal

177

><replaceable>PORT</replaceable></option></term>

178

179

<para>

180

Do not use Zeroconf to locate servers. Connect directly

181

to only one specified <application>Mandos</application>

182

server. Note that an IPv6 address has colon characters in

183

it, so the <emphasis>last</emphasis> colon character is

184

assumed to separate the address from the port number.

185

</para>

186

<para>

187

This option is normally only useful for testing and

188

debugging.

189

</para>

190

</listitem>

191

</varlistentry>

192

193

194

<term><option>--keydir=<replaceable

195

>DIRECTORY</replaceable></option></term>

196

<term><option>-d

197

<replaceable>DIRECTORY</replaceable></option></term>

198

199

<para>

200

Directory to read the OpenPGP key files

201

<filename>pubkey.txt</filename> and

202

<filename>seckey.txt</filename> from. The default is

203

<filename>/conf/conf.d/mandos</filename> (in the initial

204

<acronym>RAM</acronym> disk environment).

205

</para>

206

</listitem>

207

</varlistentry>

208

209

210

<term><option>--interface=

211

212

<term><option>-i

213

214

215

<para>

216

Network interface that will be brought up and scanned for

217

Mandos servers to connect to. The default it

218

<quote><literal>eth0</literal></quote>.

219

</para>

220

<para>

221

If the <option>--connect</option> option is used, this

222

specifies the interface to use to connect to the address

223

given.

224

</para>

225

</listitem>

226

</varlistentry>

227

228

229

<term><option>--pubkey=<replaceable

230

>FILE</replaceable></option></term>

231

<term><option>-p

232

233

234

<para>

235

OpenPGP public key file base name. This will be combined

236

with the directory from the <option>--keydir</option>

237

option to form an absolute file name. The default name is

238

<quote><literal>pubkey.txt</literal></quote>.

239

</para>

240

</listitem>

241

</varlistentry>

242

243

244

<term><option>--seckey=<replaceable

245

>FILE</replaceable></option></term>

246

<term><option>-s

247

248

249

<para>

250

OpenPGP secret key file base name. This will be combined

251

with the directory from the <option>--keydir</option>

252

option to form an absolute file name. The default name is

253

<quote><literal>seckey.txt</literal></quote>.

254

</para>

255

</listitem>

256

</varlistentry>

257

258

259

<term><option>--priority=<replaceable

260

>STRING</replaceable></option></term>

261

262

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

263

xpointer="priority"/>

264

</listitem>

265

</varlistentry>

266

267

268

<term><option>--dh-bits=<replaceable

269

>BITS</replaceable></option></term>

270

271

<para>

272

Sets the number of bits to use for the prime number in the

273

TLS Diffie-Hellman key exchange. Default is 1024.

274

</para>

275

</listitem>

276

</varlistentry>

277

278

279

<term><option>--debug</option></term>

280

281

<para>

282

Enable debug mode. This will enable a lot of output to

283

standard error about what the program is doing. The

284

program will still perform all other functions normally.

285

</para>

286

<para>

287

It will also enable debug mode in the Avahi and GnuTLS

288

libraries, making them print large amounts of debugging

289

output.

290

</para>

291

</listitem>

292

</varlistentry>

293

294

295

296

297

298

<para>

299

Gives a help message about options and their meanings.

300

</para>

301

</listitem>

302

</varlistentry>

303

304

305

<term><option>--usage</option></term>

306

307

<para>

308

Gives a short usage message.

309

</para>

310

</listitem>

311

</varlistentry>

312

313

314

<term><option>--version</option></term>

315

316

317

<para>

318

Prints the program version.

319

</para>

320

</listitem>

321

</varlistentry>

322

</variablelist>

323

</refsect1>

324

325

326

<title>OVERVIEW</title>

327

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

328

<para>

329

This program is the client part. It is a plugin started by

330

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

331

<manvolnum>8mandos</manvolnum></citerefentry> which will run in

332

an initial <acronym>RAM</acronym> disk environment.

333

</para>

334

<para>

335

This program could, theoretically, be used as a keyscript in

336

<filename>/etc/crypttab</filename>, but it would then be

337

impossible to enter a password for the encrypted root disk at

338

the console, since this program does not read from the console

339

at all. This is why a separate plugin (<citerefentry>

340

<refentrytitle>password-prompt</refentrytitle>

341

<manvolnum>8mandos</manvolnum></citerefentry>) does that, which

342

will be run in parallell to this one by the plugin runner.

343

</para>

344

</refsect1>

345

346

347

<title>EXIT STATUS</title>

348

<para>

349

This program will exit with a successful (zero) exit status if a

350

server could be found and the password received from it could be

351

successfully decrypted and output on standard output. The

352

program will exit with a non-zero exit status only if a critical

353

error occurs. Otherwise, it will forever connect to new

354

<application>Mandos</application> servers as they appear, trying

355

to get a decryptable password.

356

</para>

357

</refsect1>

358

359

360

<title>ENVIRONMENT</title>

361

<para>

362

This program does not use any environment variables, not even

363

the ones provided by <citerefentry><refentrytitle

364

>cryptsetup</refentrytitle><manvolnum>8</manvolnum>

365

</citerefentry>.

366

</para>

367

</refsect1>

368

369

370

<title>FILES</title>

371

372

373

<term><filename>/conf/conf.d/mandos/pubkey.txt</filename

374

></term>

375

<term><filename>/conf/conf.d/mandos/seckey.txt</filename

376

></term>

377

378

<para>

379

OpenPGP public and private key files, in <quote>ASCII

380

Armor</quote> format. These are the default file names,

381

they can be changed with the <option>--pubkey</option> and

382

<option>--seckey</option> options.

383

</para>

384

</listitem>

385

</varlistentry>

386

</variablelist>

387

</refsect1>

388

389

390

391

392

393

394

395

396

<title>EXAMPLE</title>

397

<para>

398

Note that normally, command line options will not be given

399

directly, but via options for the Mandos <citerefentry

400

><refentrytitle>plugin-runner</refentrytitle>

401

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

402

</para>

403

404

<para>

405

Normal invocation needs no options, if the network interface

406

is <quote>eth0</quote>:

407

</para>

408

<para>

409

<userinput>&COMMANDNAME;</userinput>

410

</para>

411

</informalexample>

412

413

<para>

414

Search for Mandos servers on another interface:

415

</para>

416

<para>

417

418

<userinput>&COMMANDNAME; --interface eth1</userinput>

419

</para>

420

</informalexample>

421

422

<para>

423

Run in debug mode, and use a custom key directory:

424

</para>

425

<para>

426

427

<userinput>&COMMANDNAME; --debug --keydir keydir</userinput>

428

</para>

429

</informalexample>

430

431

<para>

432

Run in debug mode, with a custom key directory, and do not use

433

Zeroconf to locate a server; connect directly to the IPv6

434

address <quote><systemitem class="ipaddress"

435

>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,

436

port 4711, using interface eth2:

437

</para>

438

<para>

439

440

441

<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>

442

443

</para>

444

</informalexample>

445

</refsect1>

446

447

448

<title>SECURITY</title>

449

<para>

450

This program is set-uid to root, but will switch back to the

451

original (and presumably non-privileged) user and group after

452

bringing up the network interface.

453

</para>

454

<para>

455

To use this program for its intended purpose (see <xref

456

linkend="purpose"/>), the password for the root file system will

457

have to be given out to be stored in a server computer, after

458

having been encrypted using an OpenPGP key. This encrypted data

459

which will be stored in a server can only be decrypted by the

460

OpenPGP key, and the data will only be given out to those

461

clients who can prove they actually have that key. This key,

462

however, is stored unencrypted on the client side in its initial

463

<acronym>RAM</acronym> disk image file system. This is normally

464

readable by all, but this is normally fixed during installation

465

of this program; file permissions are set so that no-one is able

466

to read that file.

467

</para>

468

<para>

469

The only remaining weak point is that someone with physical

470

access to the client hard drive might turn off the client

471

computer, read the OpenPGP keys directly from the hard drive,

472

and communicate with the server. The defense against this is

473

that the server is supposed to notice the client disappearing

474

and will stop giving out the encrypted data. Therefore, it is

475

important to set the timeout and checker interval values tightly

476

on the server. See <citerefentry><refentrytitle

477

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

478

</para>

479

<para>

480

It will also help if the checker program on the server is

481

configured to request something from the client which can not be

482

spoofed by someone else on the network, unlike unencrypted

483

<acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.

484

</para>

485

<para>

486

<emphasis>Note</emphasis>: This makes it completely insecure to

487

have <application >Mandos</application> clients which dual-boot

488

to another operating system which is <emphasis>not</emphasis>

489

trusted to keep the initial <acronym>RAM</acronym> disk image

490

confidential.

491

</para>

492

</refsect1>

493

494

495

496

<para>

497

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

498

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

499

<citerefentry><refentrytitle>crypttab</refentrytitle>

500

<manvolnum>5</manvolnum></citerefentry>,

501

<citerefentry><refentrytitle>mandos</refentrytitle>

502

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

503

<citerefentry><refentrytitle>password-prompt</refentrytitle>

504

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

505

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

506

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

507

</para>

508

509

510

<term>

511

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

512

</term>

513

514

<para>

515

Zeroconf is the network protocol standard used for finding

516

Mandos servers on the local network.

517

</para>

518

</listitem>

519

</varlistentry>

520

521

<term>

522

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

523

</term>

524

525

<para>

526

Avahi is the library this program calls to find Zeroconf

527

services.

528

</para>

529

</listitem>

530

</varlistentry>

531

532

<term>

533

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

534

>GnuTLS</ulink>

535

</term>

536

537

<para>

538

GnuTLS is the library this client uses to implement TLS for

539

communicating securely with the server, and at the same time

540

send the public OpenPGP key to the server.

541

</para>

542

</listitem>

543

</varlistentry>

544

545

<term>

546

<ulink url="http://www.gnupg.org/related_software/gpgme/"

547

>GPGME</ulink>

548

</term>

549

550

<para>

551

GPGME is the library used to decrypt the OpenPGP data sent

552

by the server.

553

</para>

554

</listitem>

555

</varlistentry>

556

557

<term>

558

RFC 4291: <citetitle>IP Version 6 Addressing

559

Architecture</citetitle>

560

</term>

561

562

563

564

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

565

Addresses</citetitle></term>

566

567

</varlistentry>

568

569

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

570

Address</citetitle></term>

571

572

</varlistentry>

573

574

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

575

Addresses</citetitle></term>

576

577

<para>

578

This client uses IPv6 link-local addresses, which are

579

immediately usable since a link-local addresses is

580

automatically assigned to a network interfaces when it

581

is brought up.

582

</para>

583

</listitem>

584

</varlistentry>

585

</variablelist>

586

</listitem>

587

</varlistentry>

588

589

<term>

590

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

591

Protocol Version 1.1</citetitle>

592

</term>

593

594

<para>

595

TLS 1.1 is the protocol implemented by GnuTLS.

596

</para>

597

</listitem>

598

</varlistentry>

599

600

<term>

601

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

602

</term>

603

604

<para>

605

The data received from the server is binary encrypted

606

OpenPGP data.

607

</para>

608

</listitem>

609

</varlistentry>

610

611

<term>

612

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

613

Security</citetitle>

614

</term>

615

616

<para>

617

This is implemented by GnuTLS and used by this program so

618

that OpenPGP keys can be used.

619

</para>

620

</listitem>

621

</varlistentry>

622

</variablelist>

623

</refsect1>

624

625

</refentry>

626

627

628

629

630