xref: /openssh-portable/OVERVIEW (revision a65784c9)
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 either in libc or
38      LibreSSL.
39
40  Multiple Precision Integer Library
41
42    - Uses the LibreSSL 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.
66
67    - The code in packet.c calls the buffer manipulation routines
68      (buffer.c, bufaux.c), compression routines (zlib), and the
69      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  Pseudo-tty manipulation and tty modes
110
111    - Code to allocate and use a pseudo tty is in pty.c.  Code to
112      encode and set terminal modes is in ttymodes.c.
113
114  Logging in (updating utmp, lastlog, etc.)
115
116    - The code to do things that are done when a user logs in are in
117      login.c.  This includes things such as updating the utmp, wtmp,
118      and lastlog files.  Some of the code is in sshd.c.
119
120  Writing to the system log and terminal
121
122    - The programs use the functions fatal(), log(), debug(), error()
123      in many places to write messages to system log or user's
124      terminal.  The implementation that logs to system log is in
125      log-server.c; it is used in the server program.  The other
126      programs use an implementation that sends output to stderr; it
127      is in log-client.c.  The definitions are in ssh.h.
128
129  The sshd server (daemon)
130
131    - The sshd daemon starts by processing arguments and reading the
132      configuration file (servconf.c).  It then reads the host key,
133      starts listening for connections, and generates the server key.
134      The server key will be regenerated every hour by an alarm.
135
136    - When the server receives a connection, it forks, disables the
137      regeneration alarm, and starts communicating with the client.
138      They first perform identification string exchange, then
139      negotiate encryption, then perform authentication, preparatory
140      operations, and finally the server enters the normal session
141      mode by calling server_loop in serverloop.c.  This does the real
142      work, calling functions in other modules.
143
144    - The code for the server is in sshd.c.  It contains a lot of
145      stuff, including:
146	- server main program
147	- waiting for connections
148	- processing new connection
149	- authentication
150	- preparatory operations
151	- building up the execution environment for the user program
152	- starting the user program.
153
154  Auxiliary files
155
156    - There are several other files in the distribution that contain
157      various auxiliary routines:
158	ssh.h	     the main header file for ssh (various definitions)
159	uidswap.c    uid-swapping
160	xmalloc.c    "safe" malloc routines
161
162$OpenBSD: OVERVIEW,v 1.15 2018/10/23 05:56:35 djm Exp $
163