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