/mandos/trunk : revision 140

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

Committer: Teddy Hogeborn
Date: 2008-09-02 13:04:42 UTC
Revision ID: teddy@fukt.bsnet.se-20080902130442-ytnjsmllaph18e20

* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
  (BUGS): Commented out.  There are no bugs.
  (EXAMPLE): Added lots of examples.
  (SECURITY): Added text.
  (SEE ALSO): Added "crypttab(5)" and "execve(2)".

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

legalnotice.xml

mandos-keygen

mandos-keygen.xml

mandos-options.xml

overview.xml

plugins.d/usplash

files removed:
network-protocol.txt

files renamed:
mandos-client.c => plugin-runner.c

mandos-client.xml => plugin-runner.xml

files modified:
Makefile

TODO

clients.conf

mandos

mandos-clients.conf.xml

mandos.conf

mandos.conf.xml

mandos.xml

plugins.d/password-prompt.c

plugins.d/password-prompt.xml

plugins.d/password-request.c

plugins.d/password-request.xml

Show diffs side-by-side

added added

removed removed

mandos-keygen.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-keygen">

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

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

</refmeta>

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

Generate key and password for Mandos client and server.

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<group>

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

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

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

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

</group>

<sbr/>

<group>

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

<replaceable>KEYTYPE</replaceable></option></arg>

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

<replaceable>KEYTYPE</replaceable></option></arg>

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

<replaceable>KEYTYPE</replaceable></option></arg>

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

<replaceable>KEYTYPE</replaceable></option></arg>

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

<replaceable>ADDRESS</replaceable></option></arg>

100

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

101

<replaceable>ADDRESS</replaceable></option></arg>

102

</group>

103

<sbr/>

104

<group>

105

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

106

107

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

108

109

</group>

110

<sbr/>

111

<group>

112

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

113

114

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

115

116

</group>

117

<sbr/>

118

<arg><option>--force</option></arg>

119

</cmdsynopsis>

120

121

<command>&COMMANDNAME;</command>

122

123

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

124

125

</group>

126

<sbr/>

127

<group>

128

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

129

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

130

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

131

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

132

</group>

133

<sbr/>

134

<group>

135

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

136

137

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

138

139

</group>

140

</cmdsynopsis>

141

142

<command>&COMMANDNAME;</command>

143

144

145

146

</group>

147

</cmdsynopsis>

148

149

<command>&COMMANDNAME;</command>

150

151

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

152

153

</group>

154

</cmdsynopsis>

155

</refsynopsisdiv>

156

157

158

<title>DESCRIPTION</title>

159

<para>

160

<command>&COMMANDNAME;</command> is a program to generate the

161

OpenPGP key used by

162

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

163

<manvolnum>8mandos</manvolnum></citerefentry>. The key is

164

normally written to /etc/mandos for later installation into the

165

initrd image, but this, and most other things, can be changed

166

with command line options.

167

</para>

168

<para>

169

This program can also be used with the

170

<option>--password</option> option to generate a ready-made

171

section for <filename>clients.conf</filename> (see

172

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

173

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

174

</para>

175

</refsect1>

176

177

178

<title>PURPOSE</title>

179

<para>

180

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

181

rebooting</emphasis> of client host computer with an

182

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

183

linkend="overview"/> for details.

184

</para>

185

</refsect1>

186

187

188

<title>OPTIONS</title>

189

190

191

192

193

194

195

<para>

196

Show a help message and exit

197

</para>

198

</listitem>

199

</varlistentry>

200

201

202

<term><option>--dir

203

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

204

<term><option>-d

205

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

206

207

<para>

208

Target directory for key files. Default is

209

<filename>/etc/mandos</filename>.

210

</para>

211

</listitem>

212

</varlistentry>

213

214

215

<term><option>--type

216

217

<term><option>-t

218

219

220

<para>

221

Key type. Default is <quote>DSA</quote>.

222

</para>

223

</listitem>

224

</varlistentry>

225

226

227

<term><option>--length

228

229

<term><option>-l

230

231

232

<para>

233

Key length in bits. Default is 2048.

234

</para>

235

</listitem>

236

</varlistentry>

237

238

239

<term><option>--subtype

240

<replaceable>KEYTYPE</replaceable></option></term>

241

<term><option>-s

242

<replaceable>KEYTYPE</replaceable></option></term>

243

244

<para>

245

Subkey type. Default is <quote>ELG-E</quote> (Elgamal

246

encryption-only).

247

</para>

248

</listitem>

249

</varlistentry>

250

251

252

<term><option>--sublength

253

254

<term><option>-L

255

256

257

<para>

258

Subkey length in bits. Default is 2048.

259

</para>

260

</listitem>

261

</varlistentry>

262

263

264

<term><option>--email

265

<replaceable>ADDRESS</replaceable></option></term>

266

<term><option>-e

267

<replaceable>ADDRESS</replaceable></option></term>

268

269

<para>

270

Email address of key. Default is empty.

271

</para>

272

</listitem>

273

</varlistentry>

274

275

276

<term><option>--comment

277

278

<term><option>-c

279

280

281

<para>

282

Comment field for key. The default value is

283

<quote><literal>Mandos client key</literal></quote>.

284

</para>

285

</listitem>

286

</varlistentry>

287

288

289

<term><option>--expire

290

291

<term><option>-x

292

293

294

<para>

295

Key expire time. Default is no expiration. See

296

297

<manvolnum>1</manvolnum></citerefentry> for syntax.

298

</para>

299

</listitem>

300

</varlistentry>

301

302

303

<term><option>--force</option></term>

304

305

306

<para>

307

Force overwriting old key.

308

</para>

309

</listitem>

310

</varlistentry>

311

312

<term><option>--password</option></term>

313

314

315

<para>

316

Prompt for a password and encrypt it with the key already

317

present in either <filename>/etc/mandos</filename> or the

318

directory specified with the <option>--dir</option>

319

option. Outputs, on standard output, a section suitable

320

for inclusion in <citerefentry><refentrytitle

321

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

322

>8</manvolnum></citerefentry>. The host name or the name

323

specified with the <option>--name</option> option is used

324

for the section header. All other options are ignored,

325

and no key is created.

326

</para>

327

</listitem>

328

</varlistentry>

329

</variablelist>

330

</refsect1>

331

332

333

<title>OVERVIEW</title>

334

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

335

<para>

336

This program is a small utility to generate new OpenPGP keys for

337

new Mandos clients, and to generate sections for inclusion in

338

<filename>clients.conf</filename> on the server.

339

</para>

340

</refsect1>

341

342

343

<title>EXIT STATUS</title>

344

<para>

345

The exit status will be 0 if a new key (or password, if the

346

<option>--password</option> option was used) was successfully

347

created, otherwise not.

348

</para>

349

</refsect1>

350

351

352

<title>ENVIRONMENT</title>

353

354

355

<term><envar>TMPDIR</envar></term>

356

357

<para>

358

If set, temporary files will be created here. See

359

<citerefentry><refentrytitle>mktemp</refentrytitle>

360

<manvolnum>1</manvolnum></citerefentry>.

361

</para>

362

</listitem>

363

</varlistentry>

364

</variablelist>

365

</refsect1>

366

367

368

<title>FILES</title>

369

<para>

370

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

371

<command>&COMMANDNAME;</command> will write the key files. The

372

default file names are shown here.

373

</para>

374

375

376

<term><filename>/etc/mandos/seckey.txt</filename></term>

377

378

<para>

379

OpenPGP secret key file which will be created or

380

overwritten.

381

</para>

382

</listitem>

383

</varlistentry>

384

385

<term><filename>/etc/mandos/pubkey.txt</filename></term>

386

387

<para>

388

OpenPGP public key file which will be created or

389

overwritten.

390

</para>

391

</listitem>

392

</varlistentry>

393

394

395

396

<para>

397

Temporary files will be written here if

398

<varname>TMPDIR</varname> is not set.

399

</para>

400

</listitem>

401

</varlistentry>

402

</variablelist>

403

</refsect1>

404

405

406

407

<para>

408

None are known at this time.

409

</para>

410

</refsect1>

411

412

413

<title>EXAMPLE</title>

414

415

<para>

416

Normal invocation needs no options:

417

</para>

418

<para>

419

<userinput>&COMMANDNAME;</userinput>

420

</para>

421

</informalexample>

422

423

<para>

424

Create key in another directory and of another type. Force

425

overwriting old key files:

426

</para>

427

<para>

428

429

430

<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>

431

432

</para>

433

</informalexample>

434

435

<para>

436

Prompt for a password, encrypt it with the key in

437

<filename>/etc/mandos</filename> and output a section suitable

438

for <filename>clients.conf</filename>.

439

</para>

440

<para>

441

<userinput>&COMMANDNAME; --password</userinput>

442

</para>

443

</informalexample>

444

445

<para>

446

Prompt for a password, encrypt it with the key in the

447

<filename>client-key</filename> directory and output a section

448

suitable for <filename>clients.conf</filename>.

449

</para>

450

<para>

451

452

453

<userinput>&COMMANDNAME; --password --dir client-key</userinput>

454

455

</para>

456

</informalexample>

457

</refsect1>

458

459

460

<title>SECURITY</title>

461

<para>

462

The <option>--type</option>, <option>--length</option>,

463

<option>--subtype</option>, and <option>--sublength</option>

464

options can be used to create keys of low security. If in

465

doubt, leave them to the default values.

466

</para>

467

<para>

468

The key expire time is <emphasis>not</emphasis> guaranteed to be

469

honored by <citerefentry><refentrytitle>mandos</refentrytitle>

470

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

471

</para>

472

</refsect1>

473

474

475

476

<para>

477

478

<manvolnum>1</manvolnum></citerefentry>,

479

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

480

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

481

<citerefentry><refentrytitle>mandos</refentrytitle>

482

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

483

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

484

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

485

</para>

486

</refsect1>

487

488

</refentry>

489

490

491

492

493

Older »