Find file
Fetching contributors…
Cannot retrieve contributors at this time
192 lines (145 sloc) 5.52 KB
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at -->
<title>man page(1) manual page</title>
<body bgcolor='white'>
<a href='#toc'>Table of Contents</a><p>
<h2><a name='sect0' href='#toc0'>Name</a></h2>
<b>sigsh</b> -- a signature verifying shell
<h2><a name='sect1' href='#toc1'><b>Synopsis</b></a></h2>
<b>sigsh</b> [<b>-f</b> <i>certs</i>] [<b>-x</b>] [<b>-p</b> <i>prog</i>]
<h2><a name='sect2' href='#toc2'><b>Description</b></a></h2>
<b>sigsh</b> is a non-interactive, signature requiring and verifying command
interpreter. More accurately, it is a signature verification wrapper
around a given shell. It reads input in PKCS#7 format from standard in,
verifies the signature and, if the signature matches, pipes the decoded
input into the command interpreter.
<h2><a name='sect3' href='#toc3'><b>Options</b></a></h2>
<b>sigsh</b> supports the following flags:
<dt><b>-f</b> <i>certs</i> </dt></dt>
<dd>Read ceritificates to trust from this file.
<dt><b>-p</b> <i>prog</i> </dt></dt>
<dd>Pipe commands into this interpreter instead of the default
<a href='bash.1'>bash(1)</a>
<dt><b>-x</b> </dt></dt>
<dd> Enable debugging (mnemomic &lsquo;xtrace&rsquo;, as <a href='sh.1'>sh(1)</a>
<h2><a name='sect4' href='#toc4'><b>Details</b></a></h2>
Conceptually similar to Microsoft Windows&rsquo; Powershell ExecutionPolicy (as
set to &lsquo;allSigned&rsquo;), <b>sigsh</b> will only execute any commands from the input
if a valid signature is found. This allows, for example, a headless user
to be able to run any arbitrary set of commands (if provided by trusted
entities) without having to give it a fully interactive login shell. By
specifying a different interpreter to which to pass the verified input,
<b>sigsh</b> can be used for almost anything requiring input verification so
long as the tool invoked accepts input from standard in.
<b>sigsh</b> is intentionally kept as simple as possible and does not provide
for a whole lot of customization via either a startup file or any command-line
<h2><a name='sect5' href='#toc5'><b>Input</b></a></h2>
<b>sigsh</b> reads input from standard in. That is, unlike other interactive
command interpreters, it cannot be invoked from the terminal to read commands
one at a time. <b>sigsh</b> relies on (and shells out to) <a href='openssl.1'>openssl(1)</a>
signature verification. In particular, it expects input to be in PKCS#7
format, containing signed data to be passed to the command interpreter.
In order to verify the signature, <b>sigsh</b> needs to have available a matching
certificate (see section FILES).
<h2><a name='sect6' href='#toc6'><b>Output</b></a></h2>
By default, <b>sigsh</b> does not generate any output itself. If input verification
fails, it will return an error code (see section EXIT STATUS) and
print a brief message to STDERR; otherwise, it will pipe the validated
input to the given command interpreter, letting it generate any and all
output (both to standard out and standard error).
<h2><a name='sect7' href='#toc7'><b>Examples</b></a></h2>
The following examples illustrate possible usage of this tool.
To execute the commands in the file &lsquo;script.bash&rsquo;:
openssl smime -sign -nodetach -signer mycert.pem -inkey mykey.pem \
-in script.bash -outform pem | sigsh
To execute the perl code contained in the signed PKCS#7 file &lsquo;code.pem&rsquo;:
sigsh -p /usr/bin/perl &lt; code.pem
<h2><a name='sect8' href='#toc8'><b>Exit</b> <b>Status</b></a></h2>
<b>sigsh</b> will exit with the rather unusual return code of 127 if verification
of the input fails (for whatever reason). Otherwise, it will return
the exit code of the interpreter invoked.
<h2><a name='sect9' href='#toc9'><b>Environment</b></a></h2>
<b>sigsh</b> clears the environment before passing the verified input on to the
interpreter. Therefor, the input must make sure to explicitly set any
variables it may rely on.
<h2><a name='sect10' href='#toc10'><b>Files</b></a></h2>
<b>sigsh</b> uses the following files:
<dt>/etc/sigsh.pem </dt></dt>
<dd>The file containing all certificates that <b>sigsh</b> will
verify the input against.
<h2><a name='sect11' href='#toc11'><b>See</b> <b>Also</b></a></h2>
<a href='openssl.1'>openssl(1)</a>
, <a href='smime.1'>smime(1)</a>
<h2><a name='sect12' href='#toc12'><b>History</b></a></h2>
<b>sigsh</b> was originally written by Jan Schaumann &lt;; in
September 2010.
<h2><a name='sect13' href='#toc13'><b>Bugs</b></a></h2>
Please report bugs and feature requests to the author.
<a name='toc'><b>Table of Contents</b></a><p>
<li><a name='toc0' href='#sect0'>Name</a></li>
<li><a name='toc1' href='#sect1'>Synopsis</a></li>
<li><a name='toc2' href='#sect2'>Description</a></li>
<li><a name='toc3' href='#sect3'>Options</a></li>
<li><a name='toc4' href='#sect4'>Details</a></li>
<li><a name='toc5' href='#sect5'>Input</a></li>
<li><a name='toc6' href='#sect6'>Output</a></li>
<li><a name='toc7' href='#sect7'>Examples</a></li>
<li><a name='toc8' href='#sect8'>Exit Status</a></li>
<li><a name='toc9' href='#sect9'>Environment</a></li>
<li><a name='toc10' href='#sect10'>Files</a></li>
<li><a name='toc11' href='#sect11'>See Also</a></li>
<li><a name='toc12' href='#sect12'>History</a></li>
<li><a name='toc13' href='#sect13'>Bugs</a></li>