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