1psusan(1)                      PuTTY tool suite                      psusan(1)
2
3
4

NAME

6       psusan - pseudo-SSH for untappable, separately authenticated networks
7

SYNOPSIS

9       psusan [ options ]
10

DESCRIPTION

12       psusan is a server program that behaves like the innermost `connection'
13       layer of an SSH session, without the two outer security layers  of  en‐
14       cryption  and  authentication.  It provides all the post-authentication
15       features of an SSH connection:
16
17       choosing whether to run an interactive  terminal  session  or  a
18              single specified command
19
20       multiple  terminal  sessions  at once (or a mixture of those and
21              specified commands)
22
23       SFTP file transfer
24
25       all the standard SSH port-forwarding options
26
27       X11 forwarding
28
29       SSH agent forwarding
30
31       The catch is that, because it lacks the outer layers of SSH,  you  have
32       to  run it over some kind of data channel that is already authenticated
33       as the right user, and that is already protected to  your  satisfaction
34       against  eavesdropping  and  session hijacking. A good rule of thumb is
35       that any channel that you were prepared to run  a  bare  shell  session
36       over,  you can run psusan over instead, which adds all the above conve‐
37       niences without changing the security properties.
38
39       The protocol that psusan speaks is also spoken by PuTTY,  Plink,  PSCP,
40       and PSFTP, if you select the protocol type `Bare ssh-connection' or the
41       command-line option -ssh-connection and specify the  absolute  path  to
42       the appropriate Unix-domain socket in place of a hostname.
43

EXAMPLES

45       The  idea  of a secure, pre-authenticated data channel seems strange to
46       people thinking about network connections. But there are lots of  exam‐
47       ples  within the context of a single Unix system, and that's where psu‐
48       san is typically useful.
49
50   Docker
51       A good example is the console or standard I/O channel  leading  into  a
52       container  or  virtualisation  system. Docker is a familiar example. If
53       you want to start a Docker container and run a  shell  directly  within
54       it, you might say something like
55
56       docker run -i -t some:image
57
58       which  will  allow  you  to  run a single shell session inside the con‐
59       tainer, in the same terminal you started Docker from.
60
61       Suppose that you'd prefer to run multiple shell sessions  in  the  same
62       container  at once (perhaps so that one of them can use debugging tools
63       to poke at what another is doing). And perhaps  inside  that  container
64       you're  going to run a program that you don't trust with full access to
65       your network, but are prepared to let it make one or two specific  net‐
66       work connections of the kind you could set up with an SSH port forward‐
67       ing.
68
69       In that case, you could remove the -t option from that  Docker  command
70       line  (which  means  `allocate  a terminal device'), and tell it to run
71       psusan inside the container:
72
73       docker run -i some:image /some/path/to/psusan
74
75       (Of course, you'll need to ensure that psusan  is  installed  somewhere
76       inside the container image.)
77
78       If  you  do  that  from  a shell command line, you'll see a banner line
79       looking something like this:
80
81       SSHCONNECTION@putty.projects.tartarus.org-2.0-PSUSAN_Release_0.75
82
83       which isn't particularly helpful except that it tells you  that  psusan
84       has started up successfully.
85
86       To  talk  to this server usefully, you can set up a PuTTY saved session
87       as follows:
88
89       Set the protocol to `Bare ssh-connection' (the psusan protocol).
90
91       Write something in the hostname box. It will appear  in  PuTTY's
92              window  title (if you run GUI PuTTY), so you might want to write
93              something that will remind you what kind of window it is. If you
94              have no opinion, something generic like `dummy' will do.
95
96       In  the  `Proxy' configuration panel, set the proxy type to `Lo‐
97              cal', and enter the above `docker run' command  in  the  `Telnet
98              command, or local proxy command' edit box.
99
100       In  the  `SSH' configuration panel, you will very likely want to
101              turn on connection sharing. (See below.)
102
103       This arranges that when PuTTY starts up, it will run the Docker command
104       as  shown  above  in  place of making a network connection, and talk to
105       that command using the psusan SSH-like protocol.
106
107       The effect is that you will still get a shell session in the context of
108       a  Docker  container. But this time, it's got all the SSH amenities. If
109       you also turn on connection sharing in the `SSH'  configuration  panel,
110       then  the `Duplicate Session' option will get you a second shell in the
111       same Docker container (instead of a primary shell  in  a  separate  in‐
112       stance).  You can transfer files in and out of the container while it's
113       running using PSCP or PSFTP; you can forward network  ports,  X11  pro‐
114       grams, and/or an SSH agent to the container.
115
116       Of  course,  another way to do all of this would be to run the full SSH
117       protocol over the same channel. This involves more setup: you  have  to
118       invent  an SSH host key for the container, accept it in the client, and
119       deal with it being left behind in your client's host key cache when the
120       container  is  discarded.  And you have to set up some login details in
121       the container: either configure a password, and type it in the  client,
122       or  copy  in  the  public half of some SSH key you already had. And all
123       this inconvenience is unnecessary, because these  are  all  precautions
124       you  need to take when the connection between two systems is going over
125       a hostile network. In this case, it's only  going  over  a  kernel  IPC
126       channel  that's  guaranteed  to  go to the right place, so those safety
127       precautions are redundant, and they only add awkwardness.
128
129   User-mode Linux
130       User-mode Linux is another container type you can talk to in  the  same
131       way. Here's a small worked example.
132
133       The  easiest  way to run UML is to use its `hostfs' file system type to
134       give the guest kernel access to the same virtual filesystem as you have
135       on  the  host.  For  example, a command line like this gets you a shell
136       prompt inside a UML instance sharing your existing filesystem:
137
138       linux mem=512M rootfstype=hostfs rootflags=/ rw init=/bin/bash
139
140       If you run this at a command line  (assuming  you  have  a  UML  kernel
141       available  on  your path under the name `linux'), then you should see a
142       lot of kernel startup messages, followed by a shell  prompt  along  the
143       lines of
144
145       root@(none):/#
146
147       To  convert this into a psusan-based UML session, we need to adjust the
148       command line so that instead of running bash it runs psusan.  But  run‐
149       ning  psusan directly isn't quite enough, because psusan will depend on
150       a small amount of setup, such as having /proc mounted. So  instead,  we
151       set  the  init  process  to  a shell script which will do the necessary
152       setup and then invoke psusan.
153
154       Also, running psusan directly over the UML  console  device  is  a  bad
155       idea,  because  then the psusan binary protocol will be mixed with tex‐
156       tual console messages. So a better plan is to redirect UML's console to
157       the standard error of the linux process, and map its standard input and
158       output to a serial port. So the replacement UML command line might look
159       something like this:
160
161       linux mem=512M rootfstype=hostfs rootflags=/ rw \
162           con=fd:2,fd:2 ssl0=fd:0,fd:1 init=/some/path/to/uml-psusan.sh
163
164       And the setup script uml-psusan.sh might look like this:
165
166       #!/bin/bash
167       # Set up vital pseudo-filesystems
168       mount -t proc none /proc
169       mount -t devpts none /dev/pts
170       # Redirect I/O to the serial port, but stderr to the console
171       exec 0<>/dev/ttyS0 1>&0 2>/dev/console
172       # Set the serial port into raw mode, to run a binary protocol
173       stty raw -echo
174       # Choose what shell you want to run inside psusan
175       export SHELL=/bin/bash
176       # And now run psusan over the serial port
177       exec /home/simon/src/putty/misc/psusan
178
179       Now  set up a PuTTY saved session as in the Docker example above, using
180       that linux command as the local proxy command, and you'll have a  PuTTY
181       session  that  starts  up a clean UML instance when you run it, and (if
182       you enabled connection sharing) further instances of the  same  session
183       will connect to the same instance again.
184
185   Windows Subsystem for Linux
186       On  Windows,  the  default way to use WSL is to run the wsl program, or
187       one of its aliases, in a Windows console, either by launching  it  from
188       an  existing  command prompt, or by using a shortcut that opens it in a
189       fresh console. This gives you a Linux terminal environment,  but  in  a
190       Windows console window.
191
192       If  you'd  prefer  to interact with the same environment using PuTTY as
193       the terminal (for example, if you prefer PuTTY's  mouse  shortcuts  for
194       copy  and  paste),  you can set it up by installing psusan in the Linux
195       environment, and then setting up a PuTTY saved session  that  talks  to
196       it. A nice way to do this is to use the name of the WSL distribution as
197       the `host name':
198
199       set the local proxy command to `wsl -d %host /usr/local/bin/psu‐
200              san' (or wherever you installed psusan in the Linux system)
201
202       enter the name of a particular WSL distribution in the host name
203              box. (For example, if you installed WSL Debian in  the  standard
204              way from the Windows store, this will just be `Debian'.)
205
206       set the protocol to `Bare ssh-connection', as usual.
207
208       Like  all  the  other  examples  here, this also permits you to forward
209       ports in and out of the WSL environment (e.g.  expose  a  WSL2  network
210       service  through  the  hypervisor's internal NAT), forward Pageant into
211       it, and so on.
212
213   schroot
214       Another example of a  container-like  environment  is  the  alternative
215       filesystem layout set up by schroot(1).
216
217       schroot  is  another  program  that  defaults to running an interactive
218       shell session in the terminal you launched it from. But again, you  can
219       get  a  psusan  connection into the schroot environment by setting up a
220       PuTTY saved session whose local proxy command is along the lines of
221
222       schroot -c chroot-name /some/path/to/psusan
223
224       Depending on how much of the chroot environment  is  copied  from  your
225       main  one, you might find this makes it easier to (for example) run X11
226       programs inside the chroot that open windows on your main X display, or
227       transfer files in and out of the chroot.
228
229   Between network namespaces
230       If  you've  set  up multiple network namespaces on a Linux system, with
231       different TCP/IP configurations, then psusan can be  a  convenient  un‐
232       privileged-user  gateway between them, if you run it as a non-root user
233       in the non-default one of your namespaces, listening for connections on
234       a Unix-domain socket.
235
236       If you do that, then it gives you convenient control over which of your
237       outgoing network connections use which TCP/IP  configuration:  you  can
238       use  PuTTY to run a shell session in the context of the other namespace
239       if you want to run commands like ping, or you  can  set  up  individual
240       port  forwardings  or  even a SOCKS server so that processes running in
241       one namespace can send their network connections via the other one.
242
243       For this application, it's probably most convenient to use the --listen
244       option in psusan, which makes it run as a server and listen for connec‐
245       tions on a Unix-domain socket. Then you can enter that socket  name  in
246       PuTTY's  host name configuration field (and also still select the `Bare
247       ssh-connection' protocol option), to connect to that socket  as  if  it
248       were an SSH client.
249
250       Provided  the  Unix-domain  socket  is inside a directory that only the
251       right user has access to, this will ensure that authentication is  done
252       implicitly by the Linux kernel.
253
254   Between user ids, via GNU userv
255       If  you  use multiple user ids on the same machine, say for purposes of
256       privilege separation (running some less-trusted  program  with  limited
257       abilities to access all your stuff), then you probably have a `default'
258       or most privileged account where you run your main login  session,  and
259       sometimes need to run a shell in another account.
260
261       psusan can be used as an access channel between the accounts, using GNU
262       userv(1) as the transport. In the account you want to access,  write  a
263       userv configuration stanza along the lines of
264
265       if (glob service psusan & glob calling-user my-main-account-name)
266          reset
267          execute /some/path/to/psusan
268       fi
269
270       This gives your main account the right to run the command
271
272       userv my-sub-account-name psusan
273
274       and you can configure that command name as a PuTTY local proxy command,
275       in the same way as most of the previous examples.
276
277       Of course, there are plenty of ways already to access one local account
278       from  another, such as sudo. One advantage of doing it this way is that
279       you don't need the system administrator to intervene when you  want  to
280       change the access controls (e.g. change which of your accounts have ac‐
281       cess to another): as long as you have some means of getting  into  each
282       account  in  the first place, and userv is installed, you can make fur‐
283       ther configuration changes without having to bother root about it.
284
285       Another advantage is that it might make file transfer between  the  ac‐
286       counts  easier. If you're the kind of person who keeps your home direc‐
287       tories private, then it's awkward to copy a file from one of  your  ac‐
288       counts to another just by using the cp command, because there's nowhere
289       convenient that you can leave it in one account where the other one can
290       read it. But with psusan over userv, you don't need any shared piece of
291       filesystem: you can scp files back and forth without any difficulty.
292

OPTIONS

294       The command-line options supported by psusan are:
295
296       --listen unix-socket-name
297              Run psusan in listening mode. unix-socket-name is  the  pathname
298              of  a  Unix-domain  socket  to listen on. You should ensure that
299              this pathname is inside a directory whose read and exec  permis‐
300              sions  are restricted to only the user(s) you want to be able to
301              access the environment that psusan is running in.
302
303              The listening socket has to be a Unix-domain socket. psusan does
304              not  provide an option to run over TCP/IP, because the unauthen‐
305              ticated nature of the protocol would make  it  inherently  inse‐
306              cure.
307
308       --listen-once
309              In  listening mode, this option causes psusan to listen for only
310              one connection, and exit immediately after that connection  ter‐
311              minates.
312
313       --sessiondir pathname
314              This  option  sets the directory that shell sessions and subpro‐
315              cesses will start in. By default it is psusan's own working  di‐
316              rectory,  but in some situations it's easier to change it with a
317              command-line option than by wrapping psusan  in  a  script  that
318              changes directory before starting it.
319
320       -v, --verbose
321              This  option  causes psusan to print verbose log messages on its
322              standard error. This is probably most useful in listening mode.
323
324       -sshlog logfile
325
326
327       -sshrawlog logfile
328              These options cause psusan to log protocol details  to  a  file,
329              similarly to the logging options in PuTTY and Plink.
330
331              -sshlog logs decoded SSH packets and other events (those that -v
332              would print). -sshrawlog additionally logs the  raw  wire  data,
333              including the outer packet format and the initial greetings.
334
335
336
337PuTTY tool suite                  2020‐12‐13                         psusan(1)
Impressum