1This document is intended for those who wish to read the ssh source
2code.  This tries to give an overview of the structure of the code.
3      
4Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
5Updated 17 Nov 1995.
6Updated 19 Oct 1999 for OpenSSH-1.2
7
8The software consists of ssh (client), sshd (server), scp, sdist, and
9the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
10make-ssh-known-hosts.  The main program for each of these is in a .c
11file with the same name.
12
13There are some subsystems/abstractions that are used by a number of
14these 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
165