/mandos/trunk : revision 226

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

Committer: Teddy Hogeborn
Date: 2008-10-04 20:09:53 UTC
Revision ID: teddy@fukt.bsnet.se-20081004200953-7j0fjlq6fqsxs9t2

* Makefile (DOCS): Added "plugins.d/askpass-fifo.8mandos".
  (install-client-nokey): Also install
                          "plugins.d/askpass-fifo.8mandos".
  (uninstall-client): Also uninstall "plugins.d/askpass-fifo.8mandos".

* plugins.d/askpass-fifo.xml: New.

files added:
plugins.d/askpass-fifo.xml

plugins.d/splashy.xml

plugins.d/usplash.xml

files modified:
Makefile

Show diffs side-by-side

added added

removed removed

plugins.d/splashy.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 COMMANDNAME "splashy">

<!ENTITY TIMESTAMP "2008-10-04">

<!ENTITY % common SYSTEM "../common.ent">

%common;

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

<refpurpose>Mandos plugin to use splashy to get a

password.</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

</cmdsynopsis>

</refsynopsisdiv>

<title>DESCRIPTION</title>

<para>

This program prompts for a password using <citerefentry>

<refentrytitle>splashy_update</refentrytitle>

<manvolnum>8</manvolnum></citerefentry> and outputs any given

password to standard output. If no <citerefentry><refentrytitle

>splashy</refentrytitle><manvolnum>8</manvolnum></citerefentry>

process can be found, this program will immediately exit with an

exit code indicating failure.

</para>

<para>

This program is not very useful on its own. This program is

really meant to run as a plugin in the <application

>Mandos</application> client-side system, where it is used as a

fallback and alternative to retrieving passwords from a

<application >Mandos</application> server.

</para>

<para>

If this program is killed (presumably by

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

<manvolnum>8mandos</manvolnum></citerefentry> because some other

plugin provided the password), it cannot tell <citerefentry>

<refentrytitle>splashy</refentrytitle><manvolnum>8</manvolnum>

</citerefentry> to abort requesting a password, because

<citerefentry><refentrytitle>splashy</refentrytitle>

<manvolnum>8</manvolnum></citerefentry> does not support this.

Therefore, this program will then <emphasis>kill</emphasis> the

running <citerefentry><refentrytitle>splashy</refentrytitle>

<manvolnum>8</manvolnum></citerefentry> process and start a

<emphasis>new</emphasis> one, using <quote><literal

>boot</literal></quote> as the only argument.

</para>

</refsect1>

<title>OPTIONS</title>

<para>

This program takes no options.

</para>

</refsect1>

100

101

<title>EXIT STATUS</title>

102

<para>

103

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

104

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

105

program was interrupted or encountered an error, and any output

106

so far could be corrupt and/or truncated, and should therefore

107

be ignored.

108

</para>

109

</refsect1>

110

111

112

<title>ENVIRONMENT</title>

113

114

115

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

116

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

117

118

<para>

119

If set, these environment variables will be assumed to

120

contain the source device name and the target device

121

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

122

the prompt.

123

</para>

124

<para>

125

These variables will normally be inherited from

126

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

127

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

128

normally have inherited them from

129

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

130

initial <acronym>RAM</acronym> disk environment, which will

131

have set them from parsing kernel arguments and

132

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

133

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

134

created when the initial RAM disk image was created by

135

<filename

136

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

137

extracting the information of the root file system from

138

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

139

</para>

140

<para>

141

This behavior is meant to exactly mirror the behavior of

142

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

143

</para>

144

</listitem>

145

</varlistentry>

146

</variablelist>

147

</refsect1>

148

149

150

<title>FILES</title>

151

152

153

<term><filename>/sbin/splashy_update</filename></term>

154

155

<para>

156

This is the command run to retrieve a password from

157

<citerefentry><refentrytitle>splashy</refentrytitle>

158

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

159

<citerefentry><refentrytitle

160

>splashy_update</refentrytitle><manvolnum>8</manvolnum>

161

</citerefentry>.

162

</para>

163

</listitem>

164

</varlistentry>

165

166

167

168

<para>

169

To find the running <citerefentry><refentrytitle

170

>splashy</refentrytitle><manvolnum>8</manvolnum>

171

</citerefentry>, this directory will be searched for

172

numeric entries which will be assumed to be directories.

173

In all those directories, the <filename>exe</filename>

174

entry will be used to determine the name of the running

175

binary and the effective user and group

176

<abbrev>ID</abbrev> of the process. See <citerefentry>

177

<refentrytitle>proc</refentrytitle><manvolnum

178

>5</manvolnum></citerefentry>.

179

</para>

180

</listitem>

181

</varlistentry>

182

183

<term><filename>/sbin/splashy</filename></term>

184

185

<para>

186

This is the name of the binary which will be searched for

187

in the process list. See <citerefentry><refentrytitle

188

>splashy</refentrytitle><manvolnum>8</manvolnum>

189

</citerefentry>.

190

</para>

191

</listitem>

192

</varlistentry>

193

</variablelist>

194

</refsect1>

195

196

197

198

<para>

199

Killing <citerefentry><refentrytitle>splashy</refentrytitle>

200

<manvolnum>8</manvolnum></citerefentry> and starting a new one

201

is ugly, but necessary as long as it does not support aborting a

202

password request.

203

</para>

204

</refsect1>

205

206

207

<title>EXAMPLE</title>

208

<para>

209

Note that normally, this program will not be invoked directly,

210

but instead started by the Mandos <citerefentry><refentrytitle

211

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

212

</citerefentry>.

213

</para>

214

215

<para>

216

This program takes no options.

217

</para>

218

<para>

219

<userinput>&COMMANDNAME;</userinput>

220

</para>

221

</informalexample>

222

</refsect1>

223

224

225

<title>SECURITY</title>

226

<para>

227

If this program is killed by a signal, it will kill the process

228

<abbrev>ID</abbrev> which at the start of this program was

229

determined to run <citerefentry><refentrytitle

230

>splashy</refentrytitle><manvolnum>8</manvolnum></citerefentry>

231

as root (see also <xref linkend="files"/>). There is a very

232

slight risk that, in the time between those events, that process

233

<abbrev>ID</abbrev> was freed and then taken up by another

234

process; the wrong process would then be killed. Now, this

235

program can only be killed by the user who started it; see

236

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

237

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

238

should therefore be started by a completely separate

239

non-privileged user, and no other programs should be allowed to

240

run as that special user. This means that it is not recommended

241

to use the user "nobody" to start this program, as other

242

possibly less trusted programs could be running as "nobody", and

243

they would then be able to kill this program, triggering the

244

killing of the process <abbrev>ID</abbrev> which may or may not

245

be <citerefentry><refentrytitle>splashy</refentrytitle>

246

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

247

</para>

248

<para>

249

The only other thing that could be considered worthy of note is

250

this: This program is meant to be run by <citerefentry>

251

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

252

>8mandos</manvolnum></citerefentry>, and will, when run

253

standalone, outside, in a normal environment, immediately output

254

on its standard output any presumably secret password it just

255

received. Therefore, when running this program standalone

256

(which should never normally be done), take care not to type in

257

any real secret password by force of habit, since it would then

258

immediately be shown as output.

259

</para>

260

</refsect1>

261

262

263

264

<para>

265

<citerefentry><refentrytitle>crypttab</refentrytitle>

266

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

267

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

268

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

269

270

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

271

<citerefentry><refentrytitle>splashy</refentrytitle>

272

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

273

<citerefentry><refentrytitle>splashy_update</refentrytitle>

274

275

</para>

276

</refsect1>

277

</refentry>

278

279

280

281

282

Older »