/mandos/trunk : revision 116

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

Committer: Teddy Hogeborn
Date: 2008-08-30 11:31:37 UTC
Revision ID: teddy@fukt.bsnet.se-20080830113137-v0inyj0limprzfwn

* mandos-options.xml (priority): Added <acronym> tags.

* mandos.xml (NAME): Improved wording.

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

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

plugins.d/password-prompt.xml

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

<?xml-stylesheet type="text/xsl"

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

<?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-prompt">

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

<title>&COMMANDNAME;</title>

<productname>&COMMANDNAME;</productname>

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

</authorgroup>

<holder>Teddy Hogeborn & Björn Påhlsson</holder>

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

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

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

</para>

</legalnotice>

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

<manvolnum>8mandos</manvolnum>

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

Passprompt for luks during boot sequence

</refpurpose>

<refpurpose>Prompt for a password and output it.</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<arg choice='opt' rep='repeat'>OPTION</arg>

</cmdsynopsis>

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

>PREFIX</replaceable></option></arg>

<arg choice="plain"><option>--prefix </option><replaceable

>PREFIX</replaceable></arg>

</group>

<arg choice="opt"><option>--debug</option></arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

</group>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

</group>

100

</cmdsynopsis>

101

</refsynopsisdiv>

102

103

104

<title>DESCRIPTION</title>

105

<para>

<command>&COMMANDNAME;</command> is a terminal program that ask for

passwords during boot sequence. It is a plugin to

<firstterm>mandos</firstterm>, and is used as a fallback and

alternative to retriving passwords from a mandos server. During

boot sequence the user is prompted for the disk password, and

when a password is given it then gets forwarded to

<acronym>LUKS</acronym>.

</para>

106

All <command>&COMMANDNAME;</command> does is prompt for a

107

password and output any given password to standard output. This

108

is not very useful on its own. This program is really meant to

109

run as a plugin in the <application>Mandos</application>

110

client-side system, where it is used as a fallback and

111

alternative to retriving passwords from a <application

112

>Mandos</application> server.

113

</para>

114

<para>

115

This program is little more than a <citerefentry><refentrytitle

116

>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>

117

wrapper, although actual use of that function is not guaranteed

118

or implied.

119

</para>

120

</refsect1>

121

122

123

<title>OPTIONS</title>

124

<para>

125

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

126

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

127

plugin runner, see <citerefentry><refentrytitle

128

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

129

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

130

are therefore normally provided by the plugin runner, and not

131

directly.

132

</para>

133

134

135

<term><literal>-p</literal>, <literal>--prefix=<replaceable>PREFIX

</replaceable></literal></term>

<para>

Prefix used before the passprompt

</para>

100

</listitem>

101

</varlistentry>

102

103

104

<term><literal>--debug</literal></term>

105

106

<para>

107

Debug mode

108

</para>

109

</listitem>

110

</varlistentry>

111

112

113

114

115

<para>

116

Gives a help message

117

</para>

118

</listitem>

119

</varlistentry>

120

121

122

<term><literal>--usage</literal></term>

123

124

<para>

125

Gives a short usage message

126

</para>

127

</listitem>

128

</varlistentry>

129

130

131

<term><literal>-V</literal>, <literal>--version</literal></term>

132

133

<para>

134

Prints the program version

136

<term><option>-p</option> <replaceable>PREFIX</replaceable

137

></term>

138

<term><option>--prefix=</option><replaceable

139

>PREFIX</replaceable></term>

140

141

<para>

142

Prefix string shown before the password prompt.

143

</para>

144

</listitem>

145

</varlistentry>

146

147

148

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

149

150

<para>

151

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

152

standard error about what the program is doing. The

153

program will still perform all other functions normally.

154

</para>

155

</listitem>

156

</varlistentry>

157

158

159

160

161

162

<para>

163

Gives a help message about options and their meanings.

164

</para>

165

</listitem>

166

</varlistentry>

167

168

169

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

170

171

<para>

172

Gives a short usage message.

173

</para>

174

</listitem>

175

</varlistentry>

176

177

178

179

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

180

181

<para>

182

Prints the program version.

135

183

</para>

136

184

</listitem>

137

185

</varlistentry>

138

186

</variablelist>

139

187

</refsect1>

188

189

190

<title>EXIT STATUS</title>

191

<para>

192

If exit status is 0, the output from the program is the password

193

as it was read. Otherwise, if exit status is other than 0, the

194

program has encountered an error, and any output so far could be

195

corrupt and/or truncated, and should therefore be ignored.

196

</para>

197

</refsect1>

198

199

200

<title>ENVIRONMENT</title>

201

202

203

<term><envar>cryptsource</envar></term>

204

<term><envar>crypttarget</envar></term>

205

206

<para>

207

If set, these environment variables will be assumed to

208

contain the source device name and the target device

209

mapper name, respectively, and will be shown as part of

210

the prompt.

211

</para>

212

<para>

213

These variables will normally be inherited from

214

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

215

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

216

normally have inherited them from

217

<filename>/scripts/local-top/cryptroot</filename> in the

218

initial RAM disk environment, which will have set them from

219

parsing kernel arguments and

220

<filename>/conf/conf.d/cryptroot</filename> (also in the

221

initial RAM disk environment), which in turn will have been

222

created when the initial RAM disk image was created by

223

<filename

224

>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by

225

extracting the information of the root file system from

226

<filename >/etc/crypttab</filename>.

227

</para>

228

<para>

229

This behavior is meant to exactly mirror the behavior of

230

<command>askpass</command>, the default password prompter.

231

</para>

232

</listitem>

233

</varlistentry>

234

</variablelist>

235

</refsect1>

236

237

238

239

<para>

240

None are known at this time.

241

</para>

242

</refsect1>

243

244

245

<title>EXAMPLE</title>

246

<para>

247

Note that normally, command line options will not be given

248

directly, but via options for the Mandos <citerefentry

249

><refentrytitle>plugin-runner</refentrytitle>

250

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

251

</para>

252

253

<para>

254

Normal invocation needs no options:

255

</para>

256

<para>

257

<userinput>&COMMANDNAME;</userinput>

258

</para>

259

</informalexample>

260

261

<para>

262

Show a prefix before the prompt; in this case, a host name.

263

It might be useful to be reminded of which host needs a

264

password, in case of KVM switches, etc.

265

</para>

266

<para>

267

268

269

<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>

270

271

</para>

272

</informalexample>

273

274

<para>

275

Run in debug mode.

276

</para>

277

<para>

278

279

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

280

</para>

281

</informalexample>

282

</refsect1>

283

284

285

<title>SECURITY</title>

286

<para>

287

On its own, this program is very simple, and does not exactly

288

present any security risks. The one thing that could be

289

considered worthy of note is this: This program is meant to be

290

run by <citerefentry><refentrytitle

291

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

292

</citerefentry>, and will, when run standalone, outside, in a

293

normal environment, immediately output on its standard output

294

any presumably secret password it just recieved. Therefore,

295

when running this program standalone (which should never

296

normally be done), take care not to type in any real secret

297

password by force of habit, since it would then immediately be

298

shown as output.

299

</para>

300

<para>

301

To further alleviate any risk of being locked out of a system,

302

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

303

<manvolnum>8mandos</manvolnum></citerefentry> has a fallback

304

mode which does the same thing as this program, only with less

305

features.

306

</para>

307

</refsect1>

308

309

310

311

<para>

312

<citerefentry><refentrytitle>crypttab</refentrytitle>

313

314

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

315

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

316

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

317

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

318

</para>

319

</refsect1>

140

320

</refentry>

321

322

323

324

325

Older »