Annotation of src/usr.bin/ssh/OVERVIEW, Revision 1.8.6.1
1.6 stevesk 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:
1.5 deraadt 6: This document is intended for those who wish to read the ssh source
1.1 deraadt 7: code. This tries to give an overview of the structure of the code.
1.7 djm 8:
1.1 deraadt 9: Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
10: Updated 17 Nov 1995.
1.3 markus 11: Updated 19 Oct 1999 for OpenSSH-1.2
1.6 stevesk 12: Updated 20 May 2001 note obsolete for > OpenSSH-1.2
1.1 deraadt 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
1.7 djm 23:
1.1 deraadt 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
1.7 djm 31:
1.4 deraadt 32: - Ssh uses the GNU GZIP compression library (ZLIB).
1.1 deraadt 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
1.4 deraadt 38: in cipher.c, and the implementations are in libc.
1.1 deraadt 39:
40: Multiple Precision Integer Library
41:
1.2 deraadt 42: - Uses the SSLeay BIGNUM sublibrary.
1.1 deraadt 43:
44: Random Numbers
45:
1.2 deraadt 46: - Uses arc4random() and such.
1.1 deraadt 47:
48: RSA key generation, encryption, decryption
49:
1.2 deraadt 50: - Ssh uses the RSA routines in libssl.
1.1 deraadt 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.
1.3 markus 78: The new, Protocol 1.5, channel close implementation is in nchan.c
1.1 deraadt 79:
80: Authentication agent
81:
1.3 markus 82: - Code to communicate with the authentication agent is in authfd.c.
1.1 deraadt 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.
1.7 djm 91: Code in match.c is used to match host names.
1.1 deraadt 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: - 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.
1.7 djm 149:
1.1 deraadt 150: - The code for the server is in sshd.c. It contains a lot of
151: stuff, including:
1.7 djm 152: - server main program
1.1 deraadt 153: - 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:
1.7 djm 164: ssh.h the main header file for ssh (various definitions)
1.1 deraadt 165: uidswap.c uid-swapping
166: xmalloc.c "safe" malloc routines
1.8.6.1 ! brad 167:
! 168: $OpenBSD: OVERVIEW,v 1.11 2006/08/03 03:34:41 deraadt Exp $