usr/src/cmd/ssh/doc/OVERVIEW

   1 This document is intended for those who wish to read the ssh source
   2 code.  This tries to give an overview of the structure of the code.
   3
   4 Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
   5 Updated 17 Nov 1995.
   6 Updated 19 Oct 1999 for OpenSSH-1.2
   7
   8 The software consists of ssh (client), sshd (server), scp, sdist, and
   9 the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
  10 make-ssh-known-hosts.  The main program for each of these is in a .c
  11 file with the same name.
  12
  13 There are some subsystems/abstractions that are used by a number of
  14 these programs.
  15
  16   Buffer manipulation routines
  17
  18     - These provide an arbitrary size buffer, where data can be appended.
  19       Data can be consumed from either end.  The code is used heavily
  20       throughout ssh.  The basic buffer manipulation functions are in
  21       buffer.c (header buffer.h), and additional code to manipulate specific
  22       data types is in bufaux.c.
  23
  24   Compression Library
  25
  26     - Ssh uses the GNU GZIP compression library (ZLIB).
  27
  28   Encryption/Decryption
  29
  30     - Ssh contains several encryption algorithms.  These are all
  31       accessed through the cipher.h interface.  The interface code is
  32       in cipher.c, and the implementations are in libc.
  33
  34   Multiple Precision Integer Library
  35
  36     - Uses the SSLeay BIGNUM sublibrary.
  37     - Some auxiliary functions for mp-int manipulation are in mpaux.c.
  38
  39   Random Numbers
  40
  41     - Uses arc4random() and such.
  42
  43   RSA key generation, encryption, decryption
  44
  45     - Ssh uses the RSA routines in libssl.
  46
  47   RSA key files
  48
  49     - RSA keys are stored in files with a special format.  The code to
  50       read/write these files is in authfile.c.  The files are normally
  51       encrypted with a passphrase.  The functions to read passphrases
  52       are in readpass.c (the same code is used to read passwords).
  53
  54   Binary packet protocol
  55
  56     - The ssh binary packet protocol is implemented in packet.c.  The
  57       code in packet.c does not concern itself with packet types or their
  58       execution; it contains code to build packets, to receive them and
  59       extract data from them, and the code to compress and/or encrypt
  60       packets.  CRC code comes from crc32.c.
  61
  62     - The code in packet.c calls the buffer manipulation routines
  63       (buffer.c, bufaux.c), compression routines (compress.c, zlib),
  64       and the encryption routines.
  65
  66   X11, TCP/IP, and Agent forwarding
  67
  68     - Code for various types of channel forwarding is in channels.c.
  69       The file defines a generic framework for arbitrary communication
  70       channels inside the secure channel, and uses this framework to
  71       implement X11 forwarding, TCP/IP forwarding, and authentication
  72       agent forwarding.
  73       The new, Protocol 1.5, channel close implementation is in nchan.c
  74
  75   Authentication agent
  76
  77     - Code to communicate with the authentication agent is in authfd.c.
  78
  79   Authentication methods
  80
  81     - Code for various authentication methods resides in auth-*.c
  82       (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c).  This
  83       code is linked into the server.  The routines also manipulate
  84       known hosts files using code in hostfile.c.  Code in canohost.c
  85       is used to retrieve the canonical host name of the remote host.
  86       Code in match.c is used to match host names.
  87
  88     - In the client end, authentication code is in sshconnect.c.  It
  89       reads Passwords/passphrases using code in readpass.c.  It reads
  90       RSA key files with authfile.c.  It communicates the
  91       authentication agent using authfd.c.
  92
  93   The ssh client
  94
  95     - The client main program is in ssh.c.  It first parses arguments
  96       and reads configuration (readconf.c), then calls ssh_connect (in
  97       sshconnect.c) to open a connection to the server (possibly via a
  98       proxy), and performs authentication (ssh_login in sshconnect.c).
  99       It then makes any pty, forwarding, etc. requests.  It may call
 100       code in ttymodes.c to encode current tty modes.  Finally it
 101       calls client_loop in clientloop.c.  This does the real work for
 102       the session.
 103
 104     - The client is suid root.  It tries to temporarily give up this
 105       rights while reading the configuration data.  The root
 106       privileges are only used to make the connection (from a
 107       privileged socket).  Any extra privileges are dropped before
 108       calling ssh_login.
 109
 110   Pseudo-tty manipulation and tty modes
 111
 112     - Code to allocate and use a pseudo tty is in pty.c.  Code to
 113       encode and set terminal modes is in ttymodes.c.
 114
 115   Logging in (updating utmp, lastlog, etc.)
 116
 117     - The code to do things that are done when a user logs in are in
 118       login.c.  This includes things such as updating the utmp, wtmp,
 119       and lastlog files.  Some of the code is in sshd.c.
 120
 121   Writing to the system log and terminal
 122
 123     - The programs use the functions fatal(), log(), debug(), error()
 124       in many places to write messages to system log or user's
 125       terminal.  The implementation that logs to system log is in
 126       log-server.c; it is used in the server program.  The other
 127       programs use an implementation that sends output to stderr; it
 128       is in log-client.c.  The definitions are in ssh.h.
 129
 130   The sshd server (daemon)
 131
 132     - The sshd daemon starts by processing arguments and reading the
 133       configuration file (servconf.c).  It then reads the host key,
 134       starts listening for connections, and generates the server key.
 135       The server key will be regenerated every hour by an alarm.
 136
 137     - When the server receives a connection, it forks, disables the
 138       regeneration alarm, and starts communicating with the client.
 139       They first perform identification string exchange, then
 140       negotiate encryption, then perform authentication, preparatory
 141       operations, and finally the server enters the normal session
 142       mode by calling server_loop in serverloop.c.  This does the real
 143       work, calling functions in other modules.
 144
 145     - The code for the server is in sshd.c.  It contains a lot of
 146       stuff, including:
 147         - server main program
 148         - waiting for connections
 149         - processing new connection
 150         - authentication
 151         - preparatory operations
 152         - building up the execution environment for the user program
 153         - starting the user program.
 154
 155   Auxiliary files
 156
 157     - There are several other files in the distribution that contain
 158       various auxiliary routines:
 159         ssh.h        the main header file for ssh (various definitions)
 160         getput.h     byte-order independent storage of integers
 161         includes.h   includes most system headers.  Lots of #ifdefs.
 162         tildexpand.c expand tilde in file names
 163         uidswap.c    uid-swapping
 164         xmalloc.c    "safe" malloc routines