xref: /freebsd/crypto/openssh/OVERVIEW (revision 511b41d2a18c00a5f0db1a67a87ef8d831b19f2a)
1511b41d2SMark MurrayThis document is intended for those who wish to read the ssh source
2511b41d2SMark Murraycode.  This tries to give an overview of the structure of the code.
3511b41d2SMark Murray
4511b41d2SMark MurrayCopyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
5511b41d2SMark MurrayUpdated 17 Nov 1995.
6511b41d2SMark MurrayUpdated 19 Oct 1999 for OpenSSH-1.2
7511b41d2SMark Murray
8511b41d2SMark MurrayThe software consists of ssh (client), sshd (server), scp, sdist, and
9511b41d2SMark Murraythe auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
10511b41d2SMark Murraymake-ssh-known-hosts.  The main program for each of these is in a .c
11511b41d2SMark Murrayfile with the same name.
12511b41d2SMark Murray
13511b41d2SMark MurrayThere are some subsystems/abstractions that are used by a number of
14511b41d2SMark Murraythese programs.
15511b41d2SMark Murray
16511b41d2SMark Murray  Buffer manipulation routines
17511b41d2SMark Murray
18511b41d2SMark Murray    - These provide an arbitrary size buffer, where data can be appended.
19511b41d2SMark Murray      Data can be consumed from either end.  The code is used heavily
20511b41d2SMark Murray      throughout ssh.  The basic buffer manipulation functions are in
21511b41d2SMark Murray      buffer.c (header buffer.h), and additional code to manipulate specific
22511b41d2SMark Murray      data types is in bufaux.c.
23511b41d2SMark Murray
24511b41d2SMark Murray  Compression Library
25511b41d2SMark Murray
26511b41d2SMark Murray    - Ssh uses the GNU GZIP compression library (ZLIB).
27511b41d2SMark Murray
28511b41d2SMark Murray  Encryption/Decryption
29511b41d2SMark Murray
30511b41d2SMark Murray    - Ssh contains several encryption algorithms.  These are all
31511b41d2SMark Murray      accessed through the cipher.h interface.  The interface code is
32511b41d2SMark Murray      in cipher.c, and the implementations are in libc.
33511b41d2SMark Murray
34511b41d2SMark Murray  Multiple Precision Integer Library
35511b41d2SMark Murray
36511b41d2SMark Murray    - Uses the SSLeay BIGNUM sublibrary.
37511b41d2SMark Murray    - Some auxiliary functions for mp-int manipulation are in mpaux.c.
38511b41d2SMark Murray
39511b41d2SMark Murray  Random Numbers
40511b41d2SMark Murray
41511b41d2SMark Murray    - Uses arc4random() and such.
42511b41d2SMark Murray
43511b41d2SMark Murray  RSA key generation, encryption, decryption
44511b41d2SMark Murray
45511b41d2SMark Murray    - Ssh uses the RSA routines in libssl.
46511b41d2SMark Murray
47511b41d2SMark Murray  RSA key files
48511b41d2SMark Murray
49511b41d2SMark Murray    - RSA keys are stored in files with a special format.  The code to
50511b41d2SMark Murray      read/write these files is in authfile.c.  The files are normally
51511b41d2SMark Murray      encrypted with a passphrase.  The functions to read passphrases
52511b41d2SMark Murray      are in readpass.c (the same code is used to read passwords).
53511b41d2SMark Murray
54511b41d2SMark Murray  Binary packet protocol
55511b41d2SMark Murray
56511b41d2SMark Murray    - The ssh binary packet protocol is implemented in packet.c.  The
57511b41d2SMark Murray      code in packet.c does not concern itself with packet types or their
58511b41d2SMark Murray      execution; it contains code to build packets, to receive them and
59511b41d2SMark Murray      extract data from them, and the code to compress and/or encrypt
60511b41d2SMark Murray      packets.  CRC code comes from crc32.c.
61511b41d2SMark Murray
62511b41d2SMark Murray    - The code in packet.c calls the buffer manipulation routines
63511b41d2SMark Murray      (buffer.c, bufaux.c), compression routines (compress.c, zlib),
64511b41d2SMark Murray      and the encryption routines.
65511b41d2SMark Murray
66511b41d2SMark Murray  X11, TCP/IP, and Agent forwarding
67511b41d2SMark Murray
68511b41d2SMark Murray    - Code for various types of channel forwarding is in channels.c.
69511b41d2SMark Murray      The file defines a generic framework for arbitrary communication
70511b41d2SMark Murray      channels inside the secure channel, and uses this framework to
71511b41d2SMark Murray      implement X11 forwarding, TCP/IP forwarding, and authentication
72511b41d2SMark Murray      agent forwarding.
73511b41d2SMark Murray      The new, Protocol 1.5, channel close implementation is in nchan.c
74511b41d2SMark Murray
75511b41d2SMark Murray  Authentication agent
76511b41d2SMark Murray
77511b41d2SMark Murray    - Code to communicate with the authentication agent is in authfd.c.
78511b41d2SMark Murray
79511b41d2SMark Murray  Authentication methods
80511b41d2SMark Murray
81511b41d2SMark Murray    - Code for various authentication methods resides in auth-*.c
82511b41d2SMark Murray      (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c).  This
83511b41d2SMark Murray      code is linked into the server.  The routines also manipulate
84511b41d2SMark Murray      known hosts files using code in hostfile.c.  Code in canohost.c
85511b41d2SMark Murray      is used to retrieve the canonical host name of the remote host.
86511b41d2SMark Murray      Code in match.c is used to match host names.
87511b41d2SMark Murray
88511b41d2SMark Murray    - In the client end, authentication code is in sshconnect.c.  It
89511b41d2SMark Murray      reads Passwords/passphrases using code in readpass.c.  It reads
90511b41d2SMark Murray      RSA key files with authfile.c.  It communicates the
91511b41d2SMark Murray      authentication agent using authfd.c.
92511b41d2SMark Murray
93511b41d2SMark Murray  The ssh client
94511b41d2SMark Murray
95511b41d2SMark Murray    - The client main program is in ssh.c.  It first parses arguments
96511b41d2SMark Murray      and reads configuration (readconf.c), then calls ssh_connect (in
97511b41d2SMark Murray      sshconnect.c) to open a connection to the server (possibly via a
98511b41d2SMark Murray      proxy), and performs authentication (ssh_login in sshconnect.c).
99511b41d2SMark Murray      It then makes any pty, forwarding, etc. requests.  It may call
100511b41d2SMark Murray      code in ttymodes.c to encode current tty modes.  Finally it
101511b41d2SMark Murray      calls client_loop in clientloop.c.  This does the real work for
102511b41d2SMark Murray      the session.
103511b41d2SMark Murray
104511b41d2SMark Murray    - The client is suid root.  It tries to temporarily give up this
105511b41d2SMark Murray      rights while reading the configuration data.  The root
106511b41d2SMark Murray      privileges are only used to make the connection (from a
107511b41d2SMark Murray      privileged socket).  Any extra privileges are dropped before
108511b41d2SMark Murray      calling ssh_login.
109511b41d2SMark Murray
110511b41d2SMark Murray  Pseudo-tty manipulation and tty modes
111511b41d2SMark Murray
112511b41d2SMark Murray    - Code to allocate and use a pseudo tty is in pty.c.  Code to
113511b41d2SMark Murray      encode and set terminal modes is in ttymodes.c.
114511b41d2SMark Murray
115511b41d2SMark Murray  Logging in (updating utmp, lastlog, etc.)
116511b41d2SMark Murray
117511b41d2SMark Murray    - The code to do things that are done when a user logs in are in
118511b41d2SMark Murray      login.c.  This includes things such as updating the utmp, wtmp,
119511b41d2SMark Murray      and lastlog files.  Some of the code is in sshd.c.
120511b41d2SMark Murray
121511b41d2SMark Murray  Writing to the system log and terminal
122511b41d2SMark Murray
123511b41d2SMark Murray    - The programs use the functions fatal(), log(), debug(), error()
124511b41d2SMark Murray      in many places to write messages to system log or user's
125511b41d2SMark Murray      terminal.  The implementation that logs to system log is in
126511b41d2SMark Murray      log-server.c; it is used in the server program.  The other
127511b41d2SMark Murray      programs use an implementation that sends output to stderr; it
128511b41d2SMark Murray      is in log-client.c.  The definitions are in ssh.h.
129511b41d2SMark Murray
130511b41d2SMark Murray  The sshd server (daemon)
131511b41d2SMark Murray
132511b41d2SMark Murray    - The sshd daemon starts by processing arguments and reading the
133511b41d2SMark Murray      configuration file (servconf.c).  It then reads the host key,
134511b41d2SMark Murray      starts listening for connections, and generates the server key.
135511b41d2SMark Murray      The server key will be regenerated every hour by an alarm.
136511b41d2SMark Murray
137511b41d2SMark Murray    - When the server receives a connection, it forks, disables the
138511b41d2SMark Murray      regeneration alarm, and starts communicating with the client.
139511b41d2SMark Murray      They first perform identification string exchange, then
140511b41d2SMark Murray      negotiate encryption, then perform authentication, preparatory
141511b41d2SMark Murray      operations, and finally the server enters the normal session
142511b41d2SMark Murray      mode by calling server_loop in serverloop.c.  This does the real
143511b41d2SMark Murray      work, calling functions in other modules.
144511b41d2SMark Murray
145511b41d2SMark Murray    - The code for the server is in sshd.c.  It contains a lot of
146511b41d2SMark Murray      stuff, including:
147511b41d2SMark Murray        - server main program
148511b41d2SMark Murray	- waiting for connections
149511b41d2SMark Murray	- processing new connection
150511b41d2SMark Murray	- authentication
151511b41d2SMark Murray	- preparatory operations
152511b41d2SMark Murray	- building up the execution environment for the user program
153511b41d2SMark Murray	- starting the user program.
154511b41d2SMark Murray
155511b41d2SMark Murray  Auxiliary files
156511b41d2SMark Murray
157511b41d2SMark Murray    - There are several other files in the distribution that contain
158511b41d2SMark Murray      various auxiliary routines:
159511b41d2SMark Murray        ssh.h	     the main header file for ssh (various definitions)
160511b41d2SMark Murray        getput.h     byte-order independent storage of integers
161511b41d2SMark Murray        includes.h   includes most system headers.  Lots of #ifdefs.
162511b41d2SMark Murray	tildexpand.c expand tilde in file names
163511b41d2SMark Murray	uidswap.c    uid-swapping
164511b41d2SMark Murray	xmalloc.c    "safe" malloc routines
165