OVERVIEW

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