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