lsh.texinfo 54.8 KB
Newer Older
Niels Möller's avatar
Niels Möller committed
1 2 3 4 5 6 7
\input texinfo          @c -*-texinfo-*-

@c %**start of header
@setfilename lsh.info
@settitle lsh
@c %**end of header

8 9 10 11 12
@dircategory GNU Packages
@direntry
* LSH: (lsh).           Secure Shell and related utilities.
@end direntry

13
@set UPDATED-FOR 1.4
14

15 16 17 18
@c Latin-1 doesn't work with tex output.
@c Also lookout for é characters.

@set AUTHOR Niels Möller
Niels Möller's avatar
Niels Möller committed
19
@ifinfo
20 21
Draft manual for LSH. This manual corresponds to @command{lsh} version
@value{UPDATED-FOR}. 
Niels Möller's avatar
Niels Möller committed
22

23
Copyright 2000 @value{AUTHOR}
Niels Möller's avatar
Niels Möller committed
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end ifinfo

@titlepage
@sp 10
56 57 58 59
@c @center @titlefont{LSH Manual}

@title LSH Manual
@subtitle For @command{lsh} version @value{UPDATED-FOR}
Niels Möller's avatar
Niels Möller committed
60

61
@author @value{AUTHOR}
Niels Möller's avatar
Niels Möller committed
62 63 64 65

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
66
Copyright @copyright{} 2000 @value{AUTHOR}
Niels Möller's avatar
Niels Möller committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end titlepage

89 90
@contents

91
@ifnottex
92
@node     Top, Introduction, (dir), (dir)
Niels Möller's avatar
Niels Möller committed
93
@comment  node-name,  next,  previous,  up
94
@top
95

96 97 98 99 100
This document describes @command{lsh} and related programs. The
@command{lsh} suite of programs is intended as a free replacement for
the @command{ssh} suite of programs. In turn, @command{ssh} was intended
as a secure replacement for the @command{rsh} and @command{rlogin}
programs for remote login over the Internet.
Niels Möller's avatar
Niels Möller committed
101

102
@command{lsh} is a component of the @acronym{GNU} system.
103

104 105
This manual explains how to use and hack @command{lsh}; it corresponds to
@command{lsh} version @value{UPDATED-FOR}.
Niels Möller's avatar
Niels Möller committed
106

107 108
@menu
* Introduction::                
109 110 111 112
* Installation::                
* Getting started::             
* Invoking lsh::                
* Invoking lshd::               
113
* Files and environment variables::  
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
* Terminology::                 
* Concept Index::               

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Threats::                     
* Features::                    
* Related techniques::          

Related programs and techniques

* ssh1::                        SSH version 1
* ssh2::                        SSH version 2
* Kerberos::                    Kerberos
* ipsec::                       IP Sec

133 134
Getting started

Niels Möller's avatar
Niels Möller committed
135
* lsh-make-seed ::              
136 137 138 139 140
* lsh basics::                  Connection with lsh
* tcpip forwarding::            Forwarding @acronym{TCP/IP} ports
* lshd basics::                 Starting the lshd deamon
* public-key::                  Using public-keys
* srp::                         Using SRP authentication
Niels Möller's avatar
Niels Möller committed
141
* sexp::                        Examining keys and other S-exp files
142
* Converting keys::             
143 144

Invoking @command{lsh}
145

146 147 148 149 150
* Algorithms: Algorithm options.  Selecting algorithms.
* Hostauth options::            
* Userauth options::            
* Actions: Action options.      What to do after login.
* Messages: Verbosity options.  Tuning the amount of messages.
151

152 153 154
@end detailmenu
@end menu

155 156
@end ifnottex

157
@node Introduction, Installation, Top, Top
Niels Möller's avatar
Niels Möller committed
158 159 160 161
@comment  node-name,  next,  previous,  up
@chapter Introduction

What is this thing called computer security anyway? Why would you want
162
to use a program like @command{lsh}?
Niels Möller's avatar
Niels Möller committed
163

164
This chapter explains the threats @command{lsh} tries to protect you from,
Niels Möller's avatar
Niels Möller committed
165
and some of the threats that remain. It also describes some of the
166
technologies used in @command{lsh}.
Niels Möller's avatar
Niels Möller committed
167 168 169 170 171 172

From time to time in this manual, I will speak about the @dfn{enemy}.
This means anybody who is trying to eavesdrop or disturb your private
communication. This usage is technical, and it does not imply that the
enemy is somehow morally inferior to you: The enemy may be some awful
criminals trying to eavesdrop on you, or it may be the police trying to
173
eavesdrop on the same criminals.
Niels Möller's avatar
Niels Möller committed
174 175 176

The enemy can be a criminal, or a competitor, or your boss who's trying
to find out how much you tell collegues at competing firms. It may be
177
your own or somebody else's national security officials. Or your
Niels Möller's avatar
Niels Möller committed
178 179 180
ex-boyfriend who happens to be too curious.

So what can the enemy do to your communications and your privacy?
181
Remember that just because you're paranoid that doesn't mean that nobody
182
is trying to get you@dots{}
Niels Möller's avatar
Niels Möller committed
183 184


185 186 187 188 189 190 191
@menu
* Threats::                     
* Features::                    
* Related techniques::          
@end menu

@node Threats, Features, Introduction, Introduction
Niels Möller's avatar
Niels Möller committed
192 193 194
@comment  node-name,  next,  previous,  up
@section Threats

195 196
When logging in to some other machine via the Internet, either in the
same building or a few continents away, there are several things that
Niels Möller's avatar
Niels Möller committed
197 198
may be under enemy attack.

199 200
@table @dfn
@item Local attacks
201
The enemy controls your local environment. He or she may be looking over
Niels Möller's avatar
Niels Möller committed
202 203 204 205 206 207
your shoulder. Your local machine might be cracked. Or there may be some
device planted inside your keyboard transmitting everything you type to
the attacker. About the same problems occur if the attacker has taken
control over your target machine, i.e. the remote machine you have
logged in to.

208
@item Denial-of-service attacks
Niels Möller's avatar
Niels Möller committed
209 210 211
The enemy has cut your network cable, effectively stopping your
communication. Even without doing physical damage, the enemy may be able
to flood and overload computers or network equipment. Or disrupt network
212
traffic by sending fake packets to hangup your @acronym{TCP/IP}
Niels Möller's avatar
Niels Möller committed
213 214
connections.

215
@item Passive eavesdropping
Niels Möller's avatar
Niels Möller committed
216
The enemy may be able to listen to your communication somewhere along
217
its path. With the global Internet, it's difficult to predict who might
Niels Möller's avatar
Niels Möller committed
218 219 220 221 222 223 224 225 226
be able to listen. Internet traffic between buildings just a few hundred
meters apart have been observed temporarily being routed through half a
dozen countries, perhaps a few thousand kilometers.

And even without routing anomalies, it is possible that the enemy has
been able to take control of some nearby machine, and can listen in from
there. Of course, passive eavesdropping is most dangerous if you
transmit cleartext passwords. This is the main reason not to use vanilla
telnet to login to remote systems. Use a telnet with support for
227 228
@acronym{SSL} or Kerberos, or use a program like @command{lsh} or
@command{ssh}. 
Niels Möller's avatar
Niels Möller committed
229 230 231 232 233 234 235 236 237 238 239 240 241

A passive eavesdropper is assumed not to do anything nasty with your
packets beyond listening to them.

@item Name resolution attacks
The translation from symbolic @acronym{DNS} names to numeric
ip-addresses may be controlled by the attacker. In this case, you may
think that you are connecting to a friendly machine, when in fact you
are connecting somewhere else.

@item Fake packets
It is fairly easy to fake the source address of an @acronym{IP}-packet,
although it is more difficult to get hold on the replies to the faked
242
packets. But even without any replies, this can cause serious
Niels Möller's avatar
Niels Möller committed
243 244
problems. 

245
@item Man-in-the-middle attack
Niels Möller's avatar
Niels Möller committed
246 247 248 249 250 251 252 253 254 255 256
In this attack, the enemy sits between you and the target. When
communicating with you, he pretends to be the target. When communicating
with the target, he pretends to be you. He also passes all information
on more or less unmodified, so that he is invisible to you and the
target. To mount this attack, the enemy either needs physical access to
some network equipment on the path between you and the target, or he has
been able to fool you to connect to him rather than to the target, for
example by manipulating the @acronym{DNS}-system.

@end table

257
@command{lsh} makes no attempt to protect you from local attacks. You have
Niels Möller's avatar
Niels Möller committed
258 259 260
to trust the endpoint machines. It seems really difficult to uphold any
security if the local machine is compromised. This is important to keep
in mind in the ``visitor''-scenario, where you visit a friend or perhaps an
261
Internet café and want to connect to some of the machines at home or at
Niels Möller's avatar
Niels Möller committed
262 263 264
work. If the enemy has been able to compromize your friend's or the
café's equipment, you may well be in trouble.

265 266
Protection from denial-of-service attacks is also a very difficult
problem, and @command{lsh} makes no attempt to protect you from that.
Niels Möller's avatar
Niels Möller committed
267

268
Instead, the aim of @command{lsh}, and most serious tools for cryptographic
269
protection of communications across the net, is to isolate the
Niels Möller's avatar
Niels Möller committed
270
vulnerabilities to the communication endpoints. If you know that the
271
endpoints are safe, the enemy should not be able to compromize your
272
privacy or communications. Except for denial-of-service attacks (which
Niels Möller's avatar
Niels Möller committed
273 274
at least can't be performed without you noticing it).

275
First of all, @command{lsh} provides protection against passive
Niels Möller's avatar
Niels Möller committed
276
eavesdropping. In addition, if you take the appropriate steps to make
277
sure that hostkeys are properly authenticated, @command{lsh} also protects
Niels Möller's avatar
Niels Möller committed
278 279 280 281
against man-in-the-middle attacks and in particular against attacks on
the name resolution. In short, you need only trust the security at the
end points: Even if the enemy controls all other network equipment, name
resolution and routing infrastructure, etc, he can't do anything beyond
282
the denial-of-service attack.
Niels Möller's avatar
Niels Möller committed
283 284 285 286 287 288 289

And at last, remember that there is no such thing as absolute security.
You have to estimate the value of that which you are protecting, and
adjust the security measures so that your enemies will not find it worth
the effort to break them.


290
@node Features, Related techniques, Threats, Introduction
Niels Möller's avatar
Niels Möller committed
291
@comment  node-name,  next,  previous,  up
292
@section Features
Niels Möller's avatar
Niels Möller committed
293

294
@command{lsh} does not only provide more secure replacements for
295 296 297 298 299 300
@command{telnet}, @command{rsh} and @command{rlogin}, it also provides
some other features to make it convenient to communicate securely. This
section is expected to grow with time, as more features from the
wish-list are added to lsh. One goal for @command{lsh} is to make it
reasonable easy to extend it, without messing with the core security
functionality.
Niels Möller's avatar
Niels Möller committed
301

302
@command{lsh} can be configured to allow login based on a personal key-pair
Niels Möller's avatar
Niels Möller committed
303
consisting of a private and a public key, so that you can execute remote
304
commands without typing your password every time. You can also use
305
Thomas Wu's Secure Remote Password Protocol (@acronym{SRP}). Kerberos support is
306
on the wish list but not yet supported (@pxref{Kerberos}).
Niels Möller's avatar
Niels Möller committed
307

308
The public-key authentication methods should also be extended to support
309
Simple Public Key Infrastructure (@acronym{SPKI}) certificates, including some
Niels Möller's avatar
Niels Möller committed
310 311
mechanism to delegate restricted logins.

312 313 314
Forwarding of arbitrary @acronym{TCP/IP} connections is provided. This
is useful for tunneling otherwise insecure protocols, like telnet and
pop, through an encrypted @command{lsh} connection.
Niels Möller's avatar
Niels Möller committed
315

316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
Convenient tunneling of @acronym{X} was one of the most impressive
features of the original @command{ssh} programs. The current version of
@command{lsh} implements @acronym{X}-forwarding, although the
@command{lshd} server doesn't provide that service yet.

Whan @acronym{X} forwarding is in effect, the remote process is started
in an environment where the @env{DISPLAY} variable in the environment
points to a fake @acronym{X} server, connection to which are forwarded
to the @acronym{X} server in your local environment. @command{lsh} also
creates a new ``fake'' @samp{MIT-MAGIC-COOKIE-1} for controlling access
control. Your real @acronym{X} authentication data is never sent to the
remote machine.

Other kinds of tunneling that may turn out to be useful include
authentication (i.e. @command{ssh-agent}), general forwarding of
@acronym{UDP}, and why not also general @acronym{IP}-tunneling.
Niels Möller's avatar
Niels Möller committed
332 333


334
@node Related techniques,  , Features, Introduction
Niels Möller's avatar
Niels Möller committed
335 336 337 338
@comment  node-name,  next,  previous,  up
@section Related programs and techniques

This sections describes some other programs and techniques related to
339 340
@command{lsh}. The ssh family of programs use mostly the same kind of
security as @command{lsh}. Kerberos and @acronym{IPSEC} operate quite
Niels Möller's avatar
Niels Möller committed
341
differently, in particular when it comes to protection against
342
man-in-the-middle attacks.
Niels Möller's avatar
Niels Möller committed
343

344 345 346 347 348 349 350 351
@menu
* ssh1::                        SSH version 1
* ssh2::                        SSH version 2
* Kerberos::                    Kerberos
* ipsec::                       IP Sec
@end menu

@node ssh1, ssh2, Related techniques, Related techniques
Niels Möller's avatar
Niels Möller committed
352
@comment  node-name,  next,  previous,  up
353
@subsection @code{ssh-1.x}
Niels Möller's avatar
Niels Möller committed
354

355
The first of the Secure shell programs was Tatu Ylönen's @command{ssh}.
Niels Möller's avatar
Niels Möller committed
356 357
The latest of the version 1 series is @code{ssh-1.33} which speaks
version 1.5 of the protocol. The ``free'' version of @code{ssh-1.33}
358
does not allow commercial use without additional licensing, which makes
Niels Möller's avatar
Niels Möller committed
359
@code{ssh-1.33} non-free software according to Debian's Free Software
360
Guidelines and the Open Source Definition.
Niels Möller's avatar
Niels Möller committed
361 362 363 364 365

The version 1 protocol has some minor weaknesses, in particular, all
support for using stream ciphers was disabled by default a few versions
back, for security reasons.

366 367
There also exists free implementations of @code{ssh-1}, for both Unix
and Windows. @command{ossh} and later OpenSSH are derived from earlier
368
version av Tatu Ylönen's @command{ssh}, and are free software.
Niels Möller's avatar
Niels Möller committed
369

370
@node ssh2, Kerberos, ssh1, Related techniques
Niels Möller's avatar
Niels Möller committed
371
@comment  node-name,  next,  previous,  up
372
@subsection @code{ssh-2.x}
Niels Möller's avatar
Niels Möller committed
373

374
@command{ssh2} implements the next generation of the Secure Shell
Niels Möller's avatar
Niels Möller committed
375
protocol, the development of which is supervised by the @acronym{IETF}
376 377
secsh Working Group. @command{lsh} implements the required subset of
this protocol. It is intended to be compatible with the @command{ssh2}
378
series of programs distributed by F-Secure Corporation.
Niels Möller's avatar
Niels Möller committed
379

380
However, the existing versions of @command{ssh2} gets some details of the
Niels Möller's avatar
Niels Möller committed
381 382 383
protocol wrong (probably because it predates the protocol
specification), so there is some amount of bug-compatibility required.

384 385
Interoperability between independently developed implementations is one
necessary condition for the @code{ssh-2} protocol to become a Proposed
Niels Möller's avatar
Niels Möller committed
386 387
Standard.

388
The license for F-Secure's @command{ssh2} programs is similar to that
389
for recent versions of @command{ssh1}, but with a narrower definition of
Niels Möller's avatar
Niels Möller committed
390 391
``non-commercial use''.

392
Besides @command{lsh} there are few free implementations of the
393
@code{ssh-2} protocols. Since May 2000 it is supported also by
394 395 396
OpenSSH.


397
@node Kerberos, ipsec, ssh2, Related techniques
Niels Möller's avatar
Niels Möller committed
398 399 400 401 402 403 404 405 406 407 408 409 410 411
@comment  node-name,  next,  previous,  up
@subsection Kerberos

Kerberos is a key distribution system originally developed in the late
1980:s as a part of Project Athena at @acronym{MIT}. Recent development
have been done at The Royal Institute of Technology, Stockholm
(@acronym{KTH}).

Kerberos uses a central trusted ticket-granting server, and requires
less trust on the local machines in the system. It does not use
public-key technology.

Usually, Kerberos support is compiled into applications such as telnet,
ftp and X-clients. The ssh family of programs, on the other hand, tries
412
to do all needed magic, for instance to forward @acronym{X} securely, and then
413
provides general @acronym{TCP/IP} forwarding as a kitchen sink.
Niels Möller's avatar
Niels Möller committed
414

415 416
I believe Kerberos' and lsh's protection against passive eavesdropping
are mostly equivalent. The difference is in the set of machines and
417 418
assumptions you have to trust in order to be safe from a
man-in-the-middle attack.
Niels Möller's avatar
Niels Möller committed
419

420
I think the main advantage of @command{lsh} over Kerberos is that it is
Niels Möller's avatar
Niels Möller committed
421 422 423
easier to install and use for on ordinary mortal user. In order to set
up key exchange between two different Kerberos systems (or @dfn{Kerberos
realms}), the respective system operators need to exchange keys. In the
424
case of two random users at two random sites, setting up @command{lsh} or
425
some other program in the ssh family is likely easier than to get the
426 427
operators to spend time and attention. So @command{lsh} should be easier to
use in an anarchistic grass-roots environment.
Niels Möller's avatar
Niels Möller committed
428

429
Another perspective is to combine ssh features like @acronym{X} and
430 431 432
@acronym{TCP/IP} forwarding with authentication based on Kerberos. Such
an arrangement may provide the best of two worlds for those who happen
to have an account at a suitable ticket-granting server.
Niels Möller's avatar
Niels Möller committed
433

434
@node ipsec,  , Kerberos, Related techniques
Niels Möller's avatar
Niels Möller committed
435 436 437
@comment  node-name,  next,  previous,  up
@subsection @acronym{IPSEC}

438 439 440
@acronym{IPSEC} is a set of protocols for protecting general
@acronym{IP} traffic. It is developed by another @acronym{IETF} working
group, and is also a required part of @acronym{IP} version 6.
Niels Möller's avatar
Niels Möller committed
441

442
Again, the main difference between @acronym{IPSEC} and Kerberos and ssh
Niels Möller's avatar
Niels Möller committed
443
is the set of machines that have to be secure and the keys that have to
444
be exchanged in order to avoid man-in-the-middle attacks.
Niels Möller's avatar
Niels Möller committed
445 446 447 448 449 450 451 452 453 454 455 456 457 458

Current protocols and implementations of @acronym{IPSEC} only provide
authentication of machines; there's nothing analogous to the user
authentication in ssh or Kerberos.

On the other hand, @acronym{IPSEC} provides one distinct advantage over
application level encryption. Because @acronym{IP} and @acronym{TCP}
headers are authenticated, it provides protection against some
denial-of-service attacks. In particular, it makes attacks that cause
hangup of a @acronym{TCP} connection considerably more difficult.

So it makes sense to use both @acronym{IPSEC} and some application
level cryptographic protocol.

459 460 461 462 463
Also note that it is possible to use the @dfn{Point-to-Point Protocol}
(@acronym{PPP}) to tunnel arbitrary @acronym{IP} traffic accross an ssh
connection. This arrangement provides some of the functionality of
@acronym{IPSEC}, and is sometimes referred to as ``a poor man's Virtual
Private Network''.
Niels Möller's avatar
Niels Möller committed
464

465 466 467 468
@node Installation, Getting started, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

469
You install @command{lsh} with the usual @code{./configure && make &&
470
make install}. For a full listing of the options you can give to
471
@command{configure}, use @code{./configure --help}. For example, use
472 473 474 475
@option{--without-pty} to disable pty-support.

The most commonly used option is @option{--prefix}, which tells
configure where lsh should be installed. Default prefix is
476
@file{/usr/local}. The @command{lshd} server is installed in
477 478 479
@file{$prefix/sbin}, all other programs and scripts are installed in
@file{$prefix/bin}. 

480
The configure script tries to figure out if the linker needs any special
481 482
flags specifying where to find dynamically linked libraries at run time
(one case where this matters is if you have a dynamic libz.so installed
Niels Möller's avatar
Niels Möller committed
483
in a non-standard place). Usually, you can use
484

485 486 487
@example
./configure --with-lib-path=/opt/lib:/other/place
@end example
488

489
@noindent
490 491
to specify extra library directories, and the configure script should do
the right thing. If it doesn't work, or you believe that you know your
492
system better than @command{./configure}, just set LDFLAGS and/or
493
LD_LIBRARY_PATH to the right values instead.
494 495 496 497


@node Getting started, Invoking lsh, Installation, Top
@comment  node-name,  next,  previous,  up
498 499
@chapter Getting started
This section tells you how to perform some common tasks using the
500
@command{lsh} suite of programs, without covering all options and
501 502 503
possibilities.

@menu
Niels Möller's avatar
Niels Möller committed
504
* lsh-make-seed ::              
505 506 507 508 509
* lsh basics::                  Connection with lsh
* tcpip forwarding::            Forwarding @acronym{TCP/IP} ports
* lshd basics::                 Starting the lshd deamon
* public-key::                  Using public-keys
* srp::                         Using SRP authentication
Niels Möller's avatar
Niels Möller committed
510
* sexp::                        Examining keys and other S-exp files
511
* Converting keys::             
512 513
@end menu

Niels Möller's avatar
Niels Möller committed
514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537
@node lsh-make-seed , lsh basics, Getting started, Getting started
@comment  node-name,  next,  previous,  up
@section Initializing the randomness generator

Several of the lsh programs requires a good pseudorandomness generator
for secure operation. The first thing you need to do is to create a
seed file for the generator. To create a personal seed file, stored as
@file{~/.lsh/yarrow-seed-file}, run

@example
lsh-make-seed
@end example

To create a seed file for use by @command{lshd}, run

@example
lsh-make-seed --server
@end example

as root. The seed file is stored as
@file{/var/spool/lsh/yarrow-seed-file}.


@node lsh basics, tcpip forwarding, lsh-make-seed , Getting started
538 539 540 541 542 543
@comment  node-name,  next,  previous,  up
@section @command{lsh} basics

@command{lsh} is the program you use for connection to a remote machine. A
few examples are:

544 545 546
@example
lsh sara.lysator.liu.se
@end example
547

548
@noindent
549 550 551 552 553 554
Connects to @samp{sara.lysator.liu.se} and starts an interactive shell.
In this example, and in the rest of the examples in this section, lsh
will ask for your password, unless you have public-key user
authentication set up.

The first time you try to connect between two machines, @command{lsh}
555 556
typically complains about an ``unknown host key''. This is because it
has no reason to believe that it was the right machine that answered,
557 558
and not a machine controlled by the enemy (@pxref{Threats}). The default
behaviour is to never ever accept a server that is not properly
559
authenticated. A machine is considered authentic if it follows the
560 561 562 563
protocol and has its public hostkey listed in @file{~/.lsh/known_hosts}.

To make lsh less paranoid, use

564 565 566
@example
lsh --sloppy-host-authentication sara.lysator.liu.se
@end example
567

568
@noindent
569 570 571 572 573 574 575 576
Then @command{lsh} will display a @dfn{fingerprint} of the host key of the
remote machine, and ask you if it is correct. If so, the machine is
considered authentic and its key is appended to the file
@file{~/.lsh/captured_keys}. You can copy keys you have verified to
@file{~/.lsh/known_hosts}.

You can even use

577 578 579
@example
lsh --sloppy-host-authentication --capture-to ~/.lsh/known_hosts
@end example
580

581
@noindent
582 583 584 585 586
to get @command{lsh} to behave more like the traditional @command{ssh} program.

You can create fingerprints for the hostkeys you need regularly, and
keep with you (@pxref{sexp}).

587 588 589
@example
lsh -l omar sara.lysator.liu.se
@end example
590

591
@noindent
592 593
Connects, like above, but tries to log in as the user ``omar''.

594 595 596
@example
lsh sara.lysator.liu.se tar cf - some/dir | (cd /target/dir && tar -xf -)
@end example
597 598 599 600

Copies a directory from the remote machine, by executing one remote and
one local @command{tar} process and piping them together.

601
@example
602
CVS_RSH=lsh cvs -d cvs.lysator.liu.se:/cvsroot/lsh co lsh
603
@end example
604

605 606 607
@noindent
Checks out the @command{lsh} source code from the @acronym{CVS}
repository.
608 609 610 611 612 613 614 615 616 617 618 619


@node  tcpip forwarding, lshd basics, lsh basics, Getting started
@comment  node-name,  next,  previous,  up
@section Port forwarding

One useful feature of @command{lsh} and other ssh-like programs is the
ability to forward arbitrary connections inside the encrypted
connection. There are two flavors: ``local'' and ``remote'' forwarding.

An example of local forwarding is

620 621 622
@example
lsh -L 4000:kom.lysator.liu.se:4894 sara.lysator.liu.se
@end example
623

624
@noindent
625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655
This makes @command{lsh} listen on port 4000 on the @emph{local} machine. When
someone connects, @command{lsh} asks the server to open a connection from
the @emph{remote} machine (i.e. @samp{sara}) to port 4894 on another machine
(i.e. @samp{kom}). The two connections are piped together using an
encrypted channel.

There are a few things that should be noted here:

@itemize @bullet
@item
By default, @command{lsh} only listens on the loopback interface, so only
clients on the same machine can use the tunnel. To listen on all
interfaces, use the @option{-g} flag.

@item
A connection through the tunnel consists of three parts:

@enumerate
@item
From a client socket to the local port (4000 in this example) that
@command{lsh} listens on.

@item
The tunnel itself, from the local machine to the tunnel endpoint,
which is @samp{sara} in this example.

@item
The connection from the tunnel endpoint to the ultimate target, in this
example from @samp{sara} to @samp{kom}.

@end enumerate
656

657 658 659 660 661 662
Only the middle part is protected by @command{lsh}: all data flowing
through the tunnel is sent across the first and last part @emph{in the
clear}. So forwarding doesn't offer much protection unless the tunnel
endpoint and the ultimate target machine are close to eachother. They
should usually be either the same machine, or two machines connected by
a local network that is trusted.
663 664 665 666 667 668 669 670

@item
Port forwarding is very useful for traversing firewalls. Of course, you
don't need to use lsh-style forwarding just to get out, there are other
tools like HTTPTunnel for that. But @command{lsh} helps you get out through
the firewall in a secure way.

@item
671 672
Port forwarding is done in addition to anything else @command{lsh} is
doing. In the example above, a tunnel is set up, but @command{lsh} will
673 674 675
also start an interactive shell for you. Just as if the @option{-L}
option was not present. If this is not what you want, the @option{-N} or
@option{-B} option is for you (@pxref{Invoking lsh})
676 677 678 679 680
@end itemize

Remote forwarding is similar, but asks the @emph{remote} machine to
listen on a port. An example of remote forwarding is

681 682 683
@example
lsh -g -R 8080:localhost:80 sara.lysator.liu.se
@end example
684

685
@noindent
686
This asks the remote machine to listen on port 8080 (note that you are
687 688 689 690 691 692 693 694 695 696 697 698 699 700 701
probably not authorized to listen on port 80). Whenever someone
connects, the connection is tunnelled to your local machine, and
directed to port 80 on the same machine. Note the use of @option{-g};
the effect is to allow anybody in the world to use the tunnel to connect
to your local webserver.

The same considerations that apply to forwarded local ports apply also to
forwarded remote ports.

At last, you can use any number of @option{-L} and @option{-R} options
on the same command line.


@node lshd basics, public-key, tcpip forwarding, Getting started
@comment  node-name,  next,  previous,  up
702
@section @command{lshd} basics
703
There are no global configuration files for @command{lshd}; all
704
configuration is done with command line options (@pxref{Invoking lshd}).
705

706
To run @command{lshd}, you must first create a hostkey, usually stored in
707 708
@file{/etc/lsh_host_key}. To do this, run

709
@example
710
lsh-keygen | lsh-writekey -o /etc/lsh_host_key
711
@end example
712

713
@noindent
714
This will also create a file @file{/etc/lsh_host_key.pub},
715
containing the corresponding public key. 
716 717 718

A typical command line for starting lshd in daemon mode is simply

719 720 721
@example
lshd --daemonic
@end example
722

723 724 725 726
You can find init script for @command{lshd} tailored for Debian's and
RedHat's GNU/Linux systems in the @file{contrib} directory. 

It is also possible to let @command{init} start @command{lshd}, by adding it in
727 728
@file{/etc/inittab}.

729 730 731 732 733 734 735 736 737 738 739 740

@node public-key, srp, lshd basics, Getting started
@comment  node-name,  next,  previous,  up
@section Using public-key user authentication

Public-key user authentication is a way to authenticate for login,
without having to type any passwords. There are two steps: Creating a
key pair, and authorizing the public key to the systems where you want
to log in.

To create a keypair, run

741
@example
742
lsh-keygen | lsh-writekey
743
@end example
744

745
@noindent
746 747 748 749 750 751
This can take some time, but in the end it creates two files
@file{~/.lsh/identity} and @file{~/.lsh/identity.pub}.

If you want to use the key to login to some other machine, say
@samp{sara}, you can do that by first copying the key,

752 753 754
@example
lsh sara.lysator.liu.se '>my-key.pub' <~/.lsh/identity.pub
@end example
755

756
@noindent
757 758
then authorizing it by executing, on @samp{sara},

759 760 761
@example
lsh-authorize my-key.pub
@end example
762 763 764 765 766 767

For security reasons, you should keep the private key
@file{~/.lsh/identity} secret. Anybody who can read that file will be
able to login in your name to any machine where the corresponding public
key is registered as an authorized key.

768
Naturally, you should also make sure not to authorize any keys but your
769 770 771 772 773 774
own. For instance, it is inappropriate to use an insecure mechanism such
as unauthenticated email, @code{ftp} or @code{http} to transfer your
public key to the machines where you want to authorize it.

If you have accounts on several systems, you usually create a single
keypair on each of the systems, and on each system you authorize some or
775
all of your other public keys for login.
776

777 778 779 780 781
Note that @command{lsh-writekey} does @emph{not} currently encrypt your
private key in any way. That means that you can lose it if a backup tape
gets into the wrong hands, and if you use NFS it will likely be sent in
the clear across your local network. To encrypt the key using a pass
phrase, give the @option{-c 3des} option to @command{lsh-writekey}.
782 783 784 785


@node srp, sexp, public-key, Getting started
@comment  node-name,  next,  previous,  up
786
@section Using @acronym{SRP} authentication
787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802

The Secure Remote Password protocol is a fairly new protocol that
provides mutual authentication based on a password. To use it, you must
first choose a secret password. Next, you create a @dfn{password
verifier} that is derived from the password. The verifier is stored on
the target machine (i.e. the machine you want to log in to).

To create a verifier, you run the @command{srp-gen} program and type
your new password. You have to do it on either the target machine,
redirecting the output to ~/.lsh/srp-verifier, or you can generate it on
some other machine and copy it to the target.

The main advantage of using @acronym{SRP} is that you use the password
not only to get access to the remote machine, but you also use it to
authenticate the remote machine. I.e. you can use it to connect
securely, @emph{without} having to know any hostkeys or fingerprints
803
beforehand!
804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838

For instance, you could connect using @acronym{SRP} to fetch the hostkey
fingerprint for the remote machine, as a kind of bootstrapping
procedure, and then use traditional authentication methods for further
connections.

For this to work, the verifier @emph{must} be kept @emph{secret}. If the
enemy gets your verifier, he can mount some attacks:

@itemize @bullet
@item
He can mount a @dfn{dictionary attack} on your password, i.e. generate a large
list of likely password and check if any of them matches yours.

@item
He can impersonate the server. That means that if you try to connect to
the remote machine using @acronym{SRP}, and the attacker can intercept
your connection (e.g. by attacking the name resolution or routing
system) he can successfully pretend to be the real server.
@end itemize

If you use @acronym{SRP} to get the hostkey or fingerprint for the
remote machine, as outlined above, the impersonation attack destroys
security, you could just as well connect the hostkey presented by the
remote server without verifying it at all.

If you use @acronym{SRP} exclusively, the situation seems somewhat
different. As far as I can see, an attacker knowing your verifier can
not mount a traditional man-in-the-middle-attack: He can play the
server's part when talking to you, but in order to play your part when
talking to the real server, he needs to know your password as well.

@acronym{SRP} support is disabled by default, but can be enabled by the
@option{--srp-keyexchange} option to @command{lshd} and @command{lsh}
(naturally, it won't be used unless enabled on both sides). At the time
839 840 841
of this writing, @acronym{SRP} is too new to be trusted by conservative
cryptographers (and remember that conservatism is a virtue when it comes
to security).
842 843

And even if @acronym{SRP} in itself is secure, the way @command{lsh}
844
integrates it into the @code{ssh} protocol has not had much peer review.
845 846 847
The bottom line of this disclaimer is that the @acronym{SRP} support in
@command{lsh} should be considered experimental.

848 849 850 851 852
As far as I know, using @acronym{SRP} as a host authentication mechanism
is not supported by any other @code{ssh} implementation. The protocol
@command{lsh} uses is described in the @file{doc/srp-spec.txt}.
Implementations that use @acronym{SRP} only as a user authentication
mechanism are not compatible with @command{lsh}.
853

854
@node sexp, Converting keys, srp, Getting started
855
@comment  node-name,  next,  previous,  up
856
@section Examining keys and other sexp files
857 858

Keys and most other objects @command{lsh} needs to store on disk are
859
represented as so called S-expressions or @dfn{sexps} for short.
860
S-expressions have their roots in the Lisp world, and a variant of them
861
in used in the Simple Public Key Infrastructure (@acronym{SPKI}).
862 863 864
Currently, @command{lsh}'s support for @acronym{SPKI} is quite limited,
but it uses @acronym{SPKI}'s formats for keys and Access Control Lists
(@acronym{ACL}:s).
865 866 867 868 869 870 871 872 873 874 875 876 877 878 879

There are several flavours of the sexp syntax:

@itemize @bullet
@item
The canonical syntax is somewhere between a text and a binary format,
and is extremely easy for programs to read and write.

@item
The transport syntax, which is suitable when embedding sexps in text
files. It is essentially the canonical representation, encoded using
base64.

@item
The advanced syntax, which is intended for humans to read and write, and
880
bears some resemblance to Lisp expressions.
881 882 883 884
@end itemize

To see what your @file{~/.lsh/known_hosts} file really contains, try

885 886 887
@example
sexp-conv -i advanced < ~/.lsh/known_hosts
@end example
888 889 890 891 892

The @command{sexp-conv} program can also be used to computes
fingerprints. The fingerprint of a key (or any sexp, for that matter) is
simply the hash of its canonical representation. For example,

893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911
@example
sexp-conv --raw-hash </etc/lsh_host_key.pub
@end example


@node  Converting keys,  , sexp, Getting started
@comment  node-name,  next,  previous,  up
@section Converting keys from @command{ssh2} and OpenSSH

If you are already using @command{ssh2} or OpenSSH, and have creating
one or more personal keypairs, you need to convert the public keys to
@command{lsh}'s format before you can authorize them. Use the supplied
@command{ssh-conv} script,

@example
ssh-conv <openssh-key.pub >new-key.pub
@end example

You can then use the usual @command{lsh-authorize} on the converted
912
keys. @command{ssh-conv} supports both @acronym{DSA} and @command{RSA} keys.
913

Niels Möller's avatar
Niels Möller committed
914 915 916 917 918
Conversion of keys the other way is also possible, by using the
@command{lsh-export-key} program. It reads a public key in
@command{lsh}'s @acronym{SPKI} format on stdin, and writes the key in
@command{ssh2}/OpenSSH format on stdout.

919
There are currently no tools for converting private keys.
920 921


922 923
@node Invoking lsh, Invoking lshd, Getting started, Top
@comment  node-name,  next,  previous,  up
924
@chapter Invoking @command{lsh}
925
@anchor{lsh-usage}
926

927
You use @command{lsh} to login to a remote machine. Basic usage is
928 929 930 931

@samp{lsh [-p @var{port number}] sara.lysator.liu.se}

which attempts to connect, login, and start an interactive shell on the
932
remote machine. Default @var{port number} is whatever your system's
933
@file{/etc/services} lists for @command{ssh}. Usually, that is port 22.
934

935
There is a plethora of options to @command{lsh}, to let you configure where
936
and how to connect, how to authenticate, and what you want to do once
937 938 939
properly logged in to the remote host. Many options have both long and
short forms. This manual does not list all variants; for a full listing
of supported options, use @samp{lsh --help}.
940

941 942 943
Note that for many of the options to @command{lsh}, the ordering of the
options on the command line is important.

944
@c FIXME: Say something about the escape char mechanism here
945
@menu
946 947 948 949 950
* Algorithms: Algorithm options.  Selecting algorithms.
* Hostauth options::            
* Userauth options::            
* Actions: Action options.      What to do after login.
* Messages: Verbosity options.  Tuning the amount of messages.
951 952 953 954 955 956
@end menu

@node Algorithm options, Hostauth options, Invoking lsh, Invoking lsh
@comment  node-name,  next,  previous,  up
@section Algorithm options

957
Before a packet is sent, each packet can be compressed, encrypted
958 959 960 961 962 963 964 965
and authenticated, in that order. When the packet is received, it is
first decrypted, next it is checked that it is authenticated properly,
and finally it is decompressed. The algorithms used for this are
negotiated with the peer at the other end of the connection, as a part
of the initial handshake and key exchange.

Each party provides a list of supported algorithms, and the first
algorithm listed by the client, which is also found on the server's
966 967 968 969 970 971 972 973 974 975 976
list, is selected. Note that this implies that order in which algorithms
are listed on the server's list doesn't matter: if several algorithms
are present on both the server's and the client's lists, it's the
client's order that determines which algorithm is selected.

Algorithms of different types, e.g. data compression and message
authentication, are negotiated independently. Furthermore, algorithms
used for transmission from the client to the server are independent of
the algorithms used for transmission from the server to the client.
There are therefore no less than six different lists that could be
configured at each end.
977 978 979 980 981

The command line options for lsh and lshd don't let you specify
arbitrary lists. For instance, you can't specify different preferences
for sending and receiving.

982
There is a set of default algorithm preferences. When you use a command
983 984 985 986 987 988
line option to say that you want to use @var{algorithm} for one of the
algorithms, the default list is replaced with a list containing the
single element @var{algorithm}. For example, if you use @option{-c
arcfour} to say that you want to use @code{arcfour} as the encryption
algorithm, the connection will either end up using @code{arcfour}, or
algorithm negotiation will fail because the peer doesn't support
989
@code{arcfour}.
990

991
@multitable @columnfractions 0.1 0.2 0.2 0.5
992 993 994 995
@item Option
  @tab Algorithm type @tab Default @tab
@item @option{-z} @tab Data compression
  @tab @code{none}, @code{zlib}
996

997 998
  @tab The default preference list supports zlib compression, but
prefers not to use it. 
999

1000
@item @option{-c} @tab Encryption
1001
  @tab @code{aes256-cbs}, @code{3dec-cbc}, @code{blowfish-cbc}, @code{arcfour}
1002

1003
  @tab The default encryption algorithm is aes256. The default list
1004 1005 1006
includes only quite old and well studied algorithms. There is a special
algorithm name @code{all} to enable all supported encryption algorithms
(except @code{none}).
1007

1008 1009
@item @option{-m} @tab Message Authentication
  @tab @code{hmac-sha1}, @code{hmac-md5}
1010

1011
  @tab Both supported message authentication algorithms are of the
1012
@acronym{HMAC} family.
1013 1014
@end multitable

1015 1016
As a special case, @option{-z} with no argument changes the compression
algorithm list to @code{zlib}, @code{none}, which means that you want to
1017 1018 1019
use @code{zlib} if the other end supports it. This is different from
@option{-zzlib} which causes the negotiation to fail if the other end
doesn't support @code{zlib}. A somewhat unobvious consequence of
1020
@option{-z} having an @emph{optional} argument is that if you provide an
1021 1022
argument, it must follow directly after the option letter, no spaces
allowed. 
1023 1024


1025 1026 1027 1028
@node Hostauth options, Userauth options, Algorithm options, Invoking lsh
@comment  node-name,  next,  previous,  up
@section Host authentication options

1029
As described earlier (@pxref{Threats}), proper authentication of the
Niels Möller's avatar
Niels Möller committed
1030
remote host is crucial to protect the connection against
1031
man-in-the-middle attacks. By default, @command{lsh} verifies the server's
1032
claimed host key against the @dfn{Access Control Lists} in
Niels Möller's avatar
Niels Möller committed
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042
@file{~/.lsh/known_hosts}. If the remote host cannot be authenticated,
the connection is dropped.

The options that change this behaviour are

@table @option
@item --host-db
Specifies the location of the @acronym{ACL} file.

@item --sloppy-host-authentication
1043
Tell @command{lsh} not to drop the connection if the server's key can not
1044 1045
be authenticated. Instead, it displays the fingerprint of the key, and
asks if it is trusted. The received key is also appended to the file
1046
@file{~/.lsh/captured_keys}. If run in quiet mode, @samp{lsh -q
1047
--sloppy-host-authentication}, @command{lsh} connects to any host, no
1048 1049
questions asked.

Niels Möller's avatar
Niels Möller committed
1050
@item --strict-host-authentication
1051 1052
Disable sloppy operation (this is the default behaviour).

Niels Möller's avatar
Niels Möller committed
1053
@item --capture-to
1054
Use some other file than @file{~/.lsh/captured_keys}. For example,
1055 1056 1057 1058 1059 1060

@example
lsh --sloppy-host-authentication --capture-to ~/.lsh/known_hosts
@end example

@noindent
1061
makes @command{lsh} behave more like the @command{ssh} program.
Niels Möller's avatar
Niels Möller committed
1062

1063 1064 1065
@item --srp-keyexchange
Try using @acronym{SRP} for keyexchange and mutual authentication.

Niels Möller's avatar
Niels Möller committed
1066 1067
@end table

1068 1069 1070 1071
@node Userauth options, Action options, Hostauth options, Invoking lsh
@comment  node-name,  next,  previous,  up
@section User authentication options

1072 1073 1074 1075
@table @option

@item -l
Provide a name to use when logging in. By default, the value of the
1076
@env{LOGNAME} environment variable is used.
1077 1078

@item -i
1079
Try the keys from this file to log in. By default, @command{lsh} uses
1080 1081 1082 1083 1084 1085 1086 1087 1088
@file{~/.lsh/identity}, if it exists. It ought to be possible to use
several @option{-i} options to use more than one file, but that is
currently not implemented.

@item --no-publickey
Don't attempt to log in using public key authentication.

@end table

1089 1090 1091 1092
@node Action options, Verbosity options, Userauth options, Invoking lsh
@comment  node-name,  next,  previous,  up
@section Action options

1093
There are many things @command{lsh} can do once you are logged in. There
1094 1095 1096 1097 1098
are two types of options that control this: @dfn{actions} and
@dfn{action modifiers}. For short options, actions use uppercase letters
and modifiers use lowercase.

For each modifier @option{--foo} there's also a negated form
1099
@option{--no-foo}. Options can also be negated by preceding it with the
1100
special option @option{-n}. This is mainly useful for negating short
1101
options. For instance, use @option{-nt} to tell @command{lsh} not to
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113
request a remote pseudo terminal. Each modifier and its negation can be
used several times on the command line. For each action, the latest
previous modifier of each pair apply.

First, the actions:

@table @option

@item -L
Requests forwarding of a local port. This option takes mandatory
argument of the form
@var{listen-port}:@var{target-host}:@var{target-port}. This option tells
1114 1115
@command{lsh} to listen on @var{listen-port} on the local machine. When
someone conects to that port, @command{lsh} asks the remote server to open
1116 1117
a connection to @var{target-port} on @var{target-host}, and if it
succeeds, the two connections are joined together through an the
1118
@command{lsh} connection. Both port numbers should be given in decimal.
1119 1120 1121

@item -R
Requests forwarding of a remote port. It takes one mandatory argument,
1122
just like @option{-L}. But in this case @command{lsh} asks the
1123 1124
@emph{remote} server to listen on @var{listen-port}. When someone
connects to the remote hosts, the server will inform the local
1125
@command{lsh}. The local @command{lsh} then connects to @var{target-port} on
1126 1127 1128
@var{target-host}.

@item -E
1129 1130
This option takes one mandatory argument, which is a command line to be
executed on the remote machine.
1131 1132

@item -S
1133
Start an interactive shell on the remote machine. 
1134 1135 1136 1137

@item -G
Open a gateway on the local machine. A gateway is a local socket,
located under /tmp, that can be used for controlling and using the ssh
1138
connection. It is protected using the ordinary file permissions.
1139 1140 1141 1142

@item -N
This is a no-operation action. It inhibits the default action, which is
to start an interactive shell on the remote machine. It is useful if you
1143
want to set up a few forwarded tunnels or a gateway, and nothing more.
1144

Niels Möller's avatar
Niels Möller committed
1145
@item -B
1146 1147
Put the client into the background after key exchange and
user authentication. Implies @option{-N}
1148 1149 1150 1151
@end table

If there are trailing arguments after the name of the remote system,
this is equivalent to a @option{-E} option, with a command string
1152 1153 1154 1155
constructed by catenating all the remaining arguments, separated by
spaces. This implies that the arguments are usually expanded first by
the local shell, and then the resulting command string is interpreted
again by the remote system.
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166

If there are no trailing arguments after the name of the remote system,
and the @option{-N} option is not given, the default action is to start
a shell on the remote machine. I.e. this is equivalent to the
@option{-S} option.

There are a few supported modifiers:

@table @option

@item -t
1167
Request a pseudo terminal. @command{lsh} asks the remote system to allocate
1168