/mandos/trunk : revision 149

To get this branch, use:

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

« back to all changes in this revision

Viewing changes to plugins.d/password-request.xml

Committer: Teddy Hogeborn
Date: 2008-09-03 19:13:50 UTC
mfrom: (24.1.83 mandos)
Revision ID: teddy@fukt.bsnet.se-20080903191350-la2y2wuxt67xjslb

* mandos-keygen.xml (BUGS): Commented out.

* mandos.xml (BUGS): Note non-checking of expire time of OpenPGP keys.

files added:
legalnotice.xml

files modified:
Makefile

TODO

mandos-clients.conf.xml

mandos-keygen.xml

mandos-options.xml

mandos.conf.xml

mandos.xml

overview.xml

plugin-runner.c

plugin-runner.xml

plugins.d/password-prompt.xml

plugins.d/password-request.c

plugins.d/password-request.xml

Show diffs side-by-side

added added

removed removed

plugins.d/password-request.xml

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

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "password-request">

<!ENTITY TIMESTAMP "2008-08-31">

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

<title>Mandos Manual</title>

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

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

</refentryinfo>

146

124

147

125

<title>DESCRIPTION</title>

148

126

<para>

149

<command>&COMMANDNAME;</command> is a mandos plugin that works

150

like a client program that through avahi detects mandos servers,

151

sets up a gnutls connect and request a encrypted password. Any

152

passwords given is automaticly decrypted and passed to

153

cryptsetup.

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.

154

155

</para>

155

156

</refsect1>

156

157

158

158

159

<title>OPTIONS</title>

159

160

<para>

160

Commonly not invoked as command lines but from configuration

161

file of plugin runner.

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.

162

168

</para>

163

169

164

170

165

171

166

172

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

167

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

173

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

168

174

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

169

175

<term><option>-c

170

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

176

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

171

177

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

172

178

173

179

<para>

174

Connect directly to a specified mandos server

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.

175

189

</para>

176

190

</listitem>

177

191

</varlistentry>

178

192

179

193

180

194

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

181

195

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

183

197

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

184

198

185

199

<para>

186

Directory where the openpgp keyring is

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

187

205

</para>

188

206

</listitem>

189

207

</varlistentry>

195

213

196

214

197

215

<para>

198

Interface that Avahi will connect through

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.

199

224

</para>

200

225

</listitem>

201

226

</varlistentry>

202

227

203

228

204

229

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

205

230

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

207

232

208

233

209

234

<para>

210

Public openpgp key for gnutls authentication

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

211

239

</para>

212

240

</listitem>

213

241

</varlistentry>

219

247

220

248

221

249

<para>

222

Secret OpenPGP key for GnuTLS authentication

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

223

254

</para>

224

255

</listitem>

225

256

</varlistentry>

228

259

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

229

260

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

230

261

231

<para>

232

GnuTLS priority

233

</para>

262

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

263

xpointer="priority"/>

234

264

</listitem>

235

265

</varlistentry>

236

266

239

269

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

240

270

241

271

<para>

242

DH bits to use in gnutls communication

272

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

273

TLS Diffie-Hellman key exchange. Default is 1024.

243

274

</para>

244

275

</listitem>

245

276

</varlistentry>

248

279

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

249

280

250

281

<para>

251

Debug mode

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.

252

290

</para>

253

291

</listitem>

254

292

</varlistentry>

258

296

259

297

260

298

<para>

261

Gives a help message

299

Gives a help message about options and their meanings.

262

300

</para>

263

301

</listitem>

264

302

</varlistentry>

267

305

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

268

306

269

307

<para>

270

Gives a short usage message

308

Gives a short usage message.

271

309

</para>

272

310

</listitem>

273

311

</varlistentry>

277

315

278

316

279

317

<para>

280

Prints the program version

318

Prints the program version.

281

319

</para>

282

320

</listitem>

283

321

</varlistentry>

284

322

</variablelist>

285

323

</refsect1>

286

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

287

346

288

347

<title>EXIT STATUS</title>

289

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.

290

356

</para>

291

357

</refsect1>

292

358

293

359

294

360

<title>ENVIRONMENT</title>

295

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

296

366

</para>

297

367

</refsect1>

298

368

299

369

300

370

<title>FILES</title>

301

<para>

302

</para>

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>

303

387

</refsect1>

304

388

305

306

307

<para>

308

</para>

309

</refsect1>

389

390

391

392

393

310

394

311

395

312

396

<title>EXAMPLE</title>

313

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

314

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>

315

445

</refsect1>

316

446

317

447

318

448

<title>SECURITY</title>

319

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.

320

491

</para>

321

492

</refsect1>

322

493

323

494

324

495

325

496

<para>

497

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

498

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

499

<citerefentry><refentrytitle>crypttab</refentrytitle>

500

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

326

501

<citerefentry><refentrytitle>mandos</refentrytitle>

327

502

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

328

503

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

330

505

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

331

506

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

332

507

</para>

333

334

335

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

336

</para></listitem>

337

338

339

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

340

</para></listitem>

341

342

343

<ulink

344

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

345

</para></listitem>

346

347

348

<ulink

349

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

350

GPGME</ulink>

351

</para></listitem>

352

353

354

<citation>RFC 4880: <citetitle>OpenPGP Message

355

Format</citetitle></citation>

356

</para></listitem>

357

358

359

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

360

Transport Layer Security</citetitle></citation>

361

</para></listitem>

362

363

364

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

365

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

366

Unicast Addresses</citation>

367

</para></listitem>

368

</itemizedlist>

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>

369

623

</refsect1>

370

624

371

625

</refentry>

Older »