blob: d1a768c109fdad7839e878436489e9dc4ecd3609 [file] [log] [blame]
Damien Millerd4d11932001-09-25 12:55:37 +10001[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
Damien Miller431f66b1999-11-21 18:31:57 +11006This document is intended for those who wish to read the ssh source
Damien Millerd4a8b7e1999-10-27 13:42:43 +10007code. This tries to give an overview of the structure of the code.
Damien Millera8e06ce2003-11-21 23:48:55 +11008
Damien Millerd4a8b7e1999-10-27 13:42:43 +10009Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
10Updated 17 Nov 1995.
11Updated 19 Oct 1999 for OpenSSH-1.2
Damien Millerd4d11932001-09-25 12:55:37 +100012Updated 20 May 2001 note obsolete for > OpenSSH-1.2
Damien Millerd4a8b7e1999-10-27 13:42:43 +100013
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
Damien Millera8e06ce2003-11-21 23:48:55 +110023
Damien Millerd4a8b7e1999-10-27 13:42:43 +100024 - 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
Damien Millera8e06ce2003-11-21 23:48:55 +110031
Damien Millerd4a8b7e1999-10-27 13:42:43 +100032 - 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.
Damien Millerd4a8b7e1999-10-27 13:42:43 +100043
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. CRC code comes from crc32.c.
66
67 - The code in packet.c calls the buffer manipulation routines
68 (buffer.c, bufaux.c), compression routines (compress.c, zlib),
69 and the 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.
Damien Millera8e06ce2003-11-21 23:48:55 +110091 Code in match.c is used to match host names.
Damien Millerd4a8b7e1999-10-27 13:42:43 +100092
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 - The client is suid root. It tries to temporarily give up this
110 rights while reading the configuration data. The root
111 privileges are only used to make the connection (from a
112 privileged socket). Any extra privileges are dropped before
113 calling ssh_login.
114
115 Pseudo-tty manipulation and tty modes
116
117 - Code to allocate and use a pseudo tty is in pty.c. Code to
118 encode and set terminal modes is in ttymodes.c.
119
120 Logging in (updating utmp, lastlog, etc.)
121
122 - The code to do things that are done when a user logs in are in
123 login.c. This includes things such as updating the utmp, wtmp,
124 and lastlog files. Some of the code is in sshd.c.
125
126 Writing to the system log and terminal
127
128 - The programs use the functions fatal(), log(), debug(), error()
129 in many places to write messages to system log or user's
130 terminal. The implementation that logs to system log is in
131 log-server.c; it is used in the server program. The other
132 programs use an implementation that sends output to stderr; it
133 is in log-client.c. The definitions are in ssh.h.
134
135 The sshd server (daemon)
136
137 - The sshd daemon starts by processing arguments and reading the
138 configuration file (servconf.c). It then reads the host key,
139 starts listening for connections, and generates the server key.
140 The server key will be regenerated every hour by an alarm.
141
142 - When the server receives a connection, it forks, disables the
143 regeneration alarm, and starts communicating with the client.
144 They first perform identification string exchange, then
145 negotiate encryption, then perform authentication, preparatory
146 operations, and finally the server enters the normal session
147 mode by calling server_loop in serverloop.c. This does the real
148 work, calling functions in other modules.
Damien Millera8e06ce2003-11-21 23:48:55 +1100149
Damien Millerd4a8b7e1999-10-27 13:42:43 +1000150 - The code for the server is in sshd.c. It contains a lot of
151 stuff, including:
Damien Millera8e06ce2003-11-21 23:48:55 +1100152 - server main program
Damien Millerd4a8b7e1999-10-27 13:42:43 +1000153 - waiting for connections
154 - processing new connection
155 - authentication
156 - preparatory operations
157 - building up the execution environment for the user program
158 - starting the user program.
159
160 Auxiliary files
161
162 - There are several other files in the distribution that contain
163 various auxiliary routines:
Damien Millera8e06ce2003-11-21 23:48:55 +1100164 ssh.h the main header file for ssh (various definitions)
165 getput.h byte-order independent storage of integers
166 includes.h includes most system headers. Lots of #ifdefs.
Damien Millerd4a8b7e1999-10-27 13:42:43 +1000167 tildexpand.c expand tilde in file names
168 uidswap.c uid-swapping
169 xmalloc.c "safe" malloc routines