/mandos/trunk : revision 147

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 17:11:32 UTC
Revision ID: teddy@fukt.bsnet.se-20080903171132-usevhlf0gi9rxqc3

* plugins.d/password-request.c (init_gnutls_global): Improved wording
                                                     in debug message.
                                                     Bug fix: Make
                                                     debug message
                                                     print to stderr,
                                                     not stdout.

* plugins.d/password-request.xml (SECURITY): Add text.

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

legalnotice.xml

mandos-clients.conf.xml

mandos-keygen

mandos-keygen.xml

mandos-options.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:
bad-ca.pem

bad-cert.pem

bad-client-cert.pem

bad-client-key.pem

bad-crl.pem

bad-key.pem

ca.pem

cert.pem

client-cert.pem

client-key.pem

client.cpp

clients.conf

crl.pem

key.pem

server.cpp

files renamed:
mandos-clients.conf => clients.conf

server.py => mandos

files modified:
Makefile

TODO

Show diffs side-by-side

added added

removed removed

plugins.d/password-request.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 "password-request">

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

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

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

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

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

<manvolnum>8mandos</manvolnum>

</refmeta>

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

Client for mandos

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<group>

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

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

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

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

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

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

</group>

<sbr/>

<group>

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

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

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

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

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<arg>

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

</arg>

<sbr/>

<arg>

</arg>

<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 does that, which will be

340

run in parallell to this one by the plugin runner.

341

</para>

342

</refsect1>

343

344

345

<title>EXIT STATUS</title>

346

<para>

347

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

348

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

349

successfully decrypted and output on standard output. The

350

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

351

error occurs. Otherwise, it will forever connect to new

352

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

353

to get a decryptable password.

354

</para>

355

</refsect1>

356

357

358

<title>ENVIRONMENT</title>

359

<para>

360

This program does not use any environment variables, not even

361

the ones provided by <citerefentry><refentrytitle

362

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

363

</citerefentry>.

364

</para>

365

</refsect1>

366

367

368

<title>FILES</title>

369

370

371

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

372

></term>

373

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

374

></term>

375

376

<para>

377

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

378

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

379

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

380

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

381

</para>

382

</listitem>

383

</varlistentry>

384

</variablelist>

385

</refsect1>

386

387

388

389

390

391

392

393

394

<title>EXAMPLE</title>

395

<para>

396

Note that normally, command line options will not be given

397

directly, but via options for the Mandos <citerefentry

398

><refentrytitle>plugin-runner</refentrytitle>

399

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

400

</para>

401

402

<para>

403

Normal invocation needs no options, if the network interface

404

is <quote>eth0</quote>:

405

</para>

406

<para>

407

<userinput>&COMMANDNAME;</userinput>

408

</para>

409

</informalexample>

410

411

<para>

412

Search for Mandos servers on another interface:

413

</para>

414

<para>

415

416

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

417

</para>

418

</informalexample>

419

420

<para>

421

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

422

</para>

423

<para>

424

425

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

426

</para>

427

</informalexample>

428

429

<para>

430

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

431

Zeroconf to locate a server; connect directly to the IPv6

432

address <quote><systemitem class="ipaddress"

433

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

434

port 4711, using interface eth2:

435

</para>

436

<para>

437

438

439

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

440

441

</para>

442

</informalexample>

443

</refsect1>

444

445

446

<title>SECURITY</title>

447

<para>

448

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

449

original user and group after bringing up the network interface.

450

</para>

451

<para>

452

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

453

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

454

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

455

having been encrypted using an OpenPGP key. This encrypted data

456

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

457

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

458

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

459

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

460

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

461

readable by all, but this is normally fixed during installation

462

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

463

to read that file.

464

</para>

465

<para>

466

The only remaining weak point is that someone with physical

467

access to the client hard drive might turn off the client

468

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

469

and communicate with the server. The defense against this is

470

that the server is supposed to notice the client disappearing

471

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

472

important to set the timeout and checker interval values tightly

473

on the server. See <citerefentry><refentrytitle

474

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

475

</para>

476

<para>

477

<emphasis>Note</emphasis>: This makes it impossible to have

478

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

479

another operating system which does <emphasis>not</emphasis> run

480

a <application>Mandos</application> client.

481

</para>

482

</refsect1>

483

484

485

486

<para>

487

<citerefentry><refentrytitle>mandos</refentrytitle>

488

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

489

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

490

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

491

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

492

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

493

</para>

494

495

496

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

497

</para></listitem>

498

499

500

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

501

</para></listitem>

502

503

504

<ulink

505

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

506

</para></listitem>

507

508

509

<ulink

510

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

511

>GPGME</ulink>

512

</para></listitem>

513

514

515

<citation>RFC 4880: <citetitle>OpenPGP Message

516

Format</citetitle></citation>

517

</para></listitem>

518

519

520

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

521

Transport Layer Security</citetitle></citation>

522

</para></listitem>

523

524

525

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

526

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

527

Unicast Addresses</citation>

528

</para></listitem>

529

</itemizedlist>

530

</refsect1>

531

532

</refentry>

533

534

535

536

537

Older »