/mandos/trunk : revision 146

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 13:59:58 UTC
Revision ID: teddy@fukt.bsnet.se-20080903135958-k0he2xucqmx7nz4b

* plugins.d/password-request.xml (OPTIONS): Improved wording.
  (FILES): Add text about public and secret key files.
  (BUGS): Commented out.
  (EXAMPLE): Added examples.

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

mandos.xml

overview.xml

plugin-runner.xml

plugins.d/password-prompt.xml

plugins.d/password-request.xml

plugins.d/usplash

files removed:
ca.pem

cert.pem

client-cert.pem

client-key.pem

crl.pem

key.pem

files renamed:
server.py => mandos

server.conf => mandos.conf

plugbasedclient.c => plugin-runner.c

plugins.d/passprompt.c => plugins.d/password-prompt.c

plugins.d/mandosclient.c => plugins.d/password-request.c

files modified:
Makefile

TODO

clients.conf

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

</para>

449

</refsect1>

450

451

452

453

<para>

454

<citerefentry><refentrytitle>mandos</refentrytitle>

455

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

456

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

457

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

458

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

459

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

460

</para>

461

462

463

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

464

</para></listitem>

465

466

467

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

468

</para></listitem>

469

470

471

<ulink

472

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

473

</para></listitem>

474

475

476

<ulink

477

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

478

>GPGME</ulink>

479

</para></listitem>

480

481

482

<citation>RFC 4880: <citetitle>OpenPGP Message

483

Format</citetitle></citation>

484

</para></listitem>

485

486

487

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

488

Transport Layer Security</citetitle></citation>

489

</para></listitem>

490

491

492

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

493

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

494

Unicast Addresses</citation>

495

</para></listitem>

496

</itemizedlist>

497

</refsect1>

498

499

</refentry>

500

501

502

503

504

Older »