src/usr.bin/ssh/OVERVIEW - annotate

Return to OVERVIEW CVS log

Up to [local] / src / usr.bin / ssh

Annotation of src/usr.bin/ssh/OVERVIEW, Revision 1.2

1.1 deraadt 1: This document is inteded for those who wish to read the ssh source
2: code. This tries to give an overview of the structure of the code.
3:
4: Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
5: Updated 17 Nov 1995.
6:
7: The software consists of ssh (client), sshd (server), scp, sdist, and
8: the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
9: make-ssh-known-hosts. The main program for each of these is in a .c
10: file with the same name.
11:
12: There are some subsystems/abstractions that are used by a number of
13: these programs.
14:
15: Buffer manipulation routines
16:
17: - These provide an arbitrary size buffer, where data can be appended.
18: Data can be consumed from either end. The code is used heavily
19: throughout ssh. The basic buffer manipulation functions are in
20: buffer.c (header buffer.h), and additional code to manipulate specific
21: data types is in bufaux.c.
22:
23: Compression Library
24:
25: - Ssh uses the GNU GZIP compression library (ZLIB). It resides in
26: the zlib095 subdirectory.
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
1.2 ! deraadt 32: in cipher.c, and the implementations in des.c, ssh_md5.c, rc4.c.
1.1 deraadt 33:
34: Multiple Precision Integer Library
35:
1.2 ! deraadt 36: - Uses the SSLeay BIGNUM sublibrary.
1.1 deraadt 37: - Some auxiliary functions for mp-int manipulation are in mpaux.c.
38:
39: Random Numbers
40:
1.2 ! deraadt 41: - Uses arc4random() and such.
1.1 deraadt 42:
43: RSA key generation, encryption, decryption
44:
1.2 ! deraadt 45: - Ssh uses the RSA routines in libssl.
1.1 deraadt 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:
74: Authentication agent
75:
76: - Code to communicate with the authentication agent is in
77: authfd.c. The files gen-minfd.c, minfd.h, minfd.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. Code for osf C2
87: extended security is in osfc2.c.
88:
89: - In the client end, authentication code is in sshconnect.c. It
90: reads Passwords/passphrases using code in readpass.c. It reads
91: RSA key files with authfile.c. It communicates the
92: authentication agent using authfd.c.
93:
94: The ssh client
95:
96: - The client main program is in ssh.c. It first parses arguments
97: and reads configuration (readconf.c), then calls ssh_connect (in
98: sshconnect.c) to open a connection to the server (possibly via a
99: proxy), and performs authentication (ssh_login in sshconnect.c).
100: It then makes any pty, forwarding, etc. requests. It may call
101: code in ttymodes.c to encode current tty modes. Finally it
102: calls client_loop in clientloop.c. This does the real work for
103: the session.
104:
105: - The client is suid root. It tries to temporarily give up this
106: rights while reading the configuration data. The root
107: privileges are only used to make the connection (from a
108: privileged socket). Any extra privileges are dropped before
109: calling ssh_login.
110:
111: Pseudo-tty manipulation and tty modes
112:
113: - Code to allocate and use a pseudo tty is in pty.c. Code to
114: encode and set terminal modes is in ttymodes.c.
115:
116: Logging in (updating utmp, lastlog, etc.)
117:
118: - The code to do things that are done when a user logs in are in
119: login.c. This includes things such as updating the utmp, wtmp,
120: and lastlog files. Some of the code is in sshd.c.
121:
122: Writing to the system log and terminal
123:
124: - The programs use the functions fatal(), log(), debug(), error()
125: in many places to write messages to system log or user's
126: terminal. The implementation that logs to system log is in
127: log-server.c; it is used in the server program. The other
128: programs use an implementation that sends output to stderr; it
129: is in log-client.c. The definitions are in ssh.h.
130:
131: The sshd server (daemon)
132:
133: - The sshd daemon starts by processing arguments and reading the
134: configuration file (servconf.c). It then reads the host key,
135: starts listening for connections, and generates the server key.
136: The server key will be regenerated every hour by an alarm.
137:
138: - When the server receives a connection, it forks, disables the
139: regeneration alarm, and starts communicating with the client.
140: They first perform identification string exchange, then
141: negotiate encryption, then perform authentication, preparatory
142: operations, and finally the server enters the normal session
143: mode by calling server_loop in serverloop.c. This does the real
144: work, calling functions in other modules.
145:
146: - The code for the server is in sshd.c. It contains a lot of
147: stuff, including:
148: - server main program
149: - waiting for connections
150: - processing new connection
151: - authentication
152: - preparatory operations
153: - building up the execution environment for the user program
154: - starting the user program.
155:
156: Auxiliary files
157:
158: - There are several other files in the distribution that contain
159: various auxiliary routines:
160: ssh.h the main header file for ssh (various definitions)
161: getput.h byte-order independent storage of integers
162: includes.h includes most system headers. Lots of #ifdefs.
163: tildexpand.c expand tilde in file names
164: uidswap.c uid-swapping
165: xmalloc.c "safe" malloc routines