Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 122 lines (121 sloc) 3.657 kb
32fbffb @jschauma Initial import from Yahoo!
authored
1 .\" Copyright (c) 2010,2011 Yahoo! Inc.
2 .\"
3 .\" This manual page was originally written by Jan Schaumann
4 .\" <jschauma@yahoo-inc.com> in September 2010.
e0a0295 @jschauma 2015-02-10:
authored
5 .Dd February 10, 2015
32fbffb @jschauma Initial import from Yahoo!
authored
6 .Dt SIGSH 1
7 .Os
8 .Sh NAME
9 .Nm sigsh
10 .Nd a signature verifying shell
11 .Sh SYNOPSIS
12 .Nm
e0a0295 @jschauma 2015-02-10:
authored
13 .Op Fl f Ar certs
32fbffb @jschauma Initial import from Yahoo!
authored
14 .Op Fl x
15 .Op Fl p Ar prog
16 .Sh DESCRIPTION
17 .Nm
18 is a non-interactive, signature requiring and verifying command
19 interpreter.
20 More accurately, it is a signature verification wrapper around a given
21 shell.
22 It reads input in PKCS#7 format from standard in, verifies the signature
23 and, if the signature matches, pipes the decoded input into the command
24 interpreter.
25 .Sh OPTIONS
26 .Nm
27 supports the following flags:
28 .Bl -tag -width s_shell_
e0a0295 @jschauma 2015-02-10:
authored
29 .It Fl f Ar certs
32fbffb @jschauma Initial import from Yahoo!
authored
30 Read ceritificates to trust from this file.
31 .It Fl p Ar prog
32 Pipe commands into this interpreter instead of the default
33 .Xr bash 1 .
34 .It Fl x
35 Enable debugging (mnemomic 'xtrace', as
36 .Xr sh 1 Ns ).
37 .El
38 .Sh DETAILS
39 Conceptually similar to Microsoft Windows' Powershell ExecutionPolicy (as
40 set to 'allSigned'),
41 .Nm
42 will only execute any commands from the input if a valid signature is
43 found.
44 This allows, for example, a headless user to be able to run any arbitrary
45 set of commands (if provided by trusted entities) without having to give
46 it a fully interactive login shell.
47 By specifying a different interpreter to which to pass the verified input,
48 .Nm
49 can be used for almost anything requiring input verification so long as
50 the tool invoked accepts input from standard in.
51 .Pp
52 .Nm
53 is intentionally kept as simple as possible and does not provide for a
54 whole lot of customization via either a startup file or any command-line
55 options.
56 .Sh INPUT
57 .Nm
58 reads input from standard in.
59 That is, unlike other interactive command interpreters, it cannot be
60 invoked from the terminal to read commands one at a time.
61 .Nm
62 relies on (and shells out to)
63 .Xr openssl 1
64 for signature verification.
65 In particular, it expects input to be in PKCS#7 format, containing signed
66 data to be passed to the command interpreter.
67 In order to verify the signature,
68 .Nm
69 needs to have available a matching certificate (see section FILES).
70 .Sh OUTPUT
71 By default,
72 .Nm
73 does not generate any output itself.
74 If input verification fails, it will return an error code (see section
75 EXIT STATUS) and print a brief message to STDERR; otherwise, it will pipe
76 the validated input to the given command interpreter, letting it generate
77 any and all output (both to standard out and standard error).
78 .Sh EXAMPLES
79 The following examples illustrate possible usage of this tool.
80 .Pp
81 To execute the commands in the file 'script.bash':
82 .Bd -literal -offset indent
83 openssl smime -sign -nodetach -signer mycert.pem -inkey mykey.pem \\
84 -in script.bash -outform pem | sigsh
85 .Ed
86 .Pp
87 To execute the perl code contained in the signed PKCS#7 file 'code.pem':
88 .Bd -literal -offset indent
89 sigsh -p /usr/bin/perl < code.pem
90 .Ed
91 .Sh EXIT STATUS
92 .Nm
93 will exit with the rather unusual return code of 127 if verification of
94 the input fails (for whatever reason).
95 Otherwise, it will return the exit code of the interpreter invoked.
96 .Sh ENVIRONMENT
97 .Nm
98 clears the environment before passing the verified input on to the
99 interpreter.
100 Therefor, the input must make sure to explicitly set any variables it may
101 rely on.
102 .Sh FILES
103 .Nm
104 uses the following files:
105 .Bl -tag -width _etc_sigsh_pem_
106 .It /etc/sigsh.pem
107 The file containing all certificates that
108 .Nm
109 will verify the input against.
110 .El
111 .Sh SEE ALSO
112 .Xr openssl 1 ,
113 .Xr smime 1
114 .Sh HISTORY
115 .Nm
116 was originally written by
117 .An Jan Schaumann
118 .Aq jschauma@yahoo-inc.com
119 in September 2010.
120 .Sh BUGS
121 Please report bugs and feature requests to the author.
Something went wrong with that request. Please try again.