1511b41d2SMark MurrayThis document is intended for those who wish to read the ssh source 2511b41d2SMark Murraycode. This tries to give an overview of the structure of the code. 3511b41d2SMark Murray 4511b41d2SMark MurrayCopyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi> 5511b41d2SMark MurrayUpdated 17 Nov 1995. 6511b41d2SMark MurrayUpdated 19 Oct 1999 for OpenSSH-1.2 7511b41d2SMark Murray 8511b41d2SMark MurrayThe software consists of ssh (client), sshd (server), scp, sdist, and 9511b41d2SMark Murraythe auxiliary programs ssh-keygen, ssh-agent, ssh-add, and 10511b41d2SMark Murraymake-ssh-known-hosts. The main program for each of these is in a .c 11511b41d2SMark Murrayfile with the same name. 12511b41d2SMark Murray 13511b41d2SMark MurrayThere are some subsystems/abstractions that are used by a number of 14511b41d2SMark Murraythese programs. 15511b41d2SMark Murray 16511b41d2SMark Murray Buffer manipulation routines 17511b41d2SMark Murray 18511b41d2SMark Murray - These provide an arbitrary size buffer, where data can be appended. 19511b41d2SMark Murray Data can be consumed from either end. The code is used heavily 20511b41d2SMark Murray throughout ssh. The basic buffer manipulation functions are in 21511b41d2SMark Murray buffer.c (header buffer.h), and additional code to manipulate specific 22511b41d2SMark Murray data types is in bufaux.c. 23511b41d2SMark Murray 24511b41d2SMark Murray Compression Library 25511b41d2SMark Murray 26511b41d2SMark Murray - Ssh uses the GNU GZIP compression library (ZLIB). 27511b41d2SMark Murray 28511b41d2SMark Murray Encryption/Decryption 29511b41d2SMark Murray 30511b41d2SMark Murray - Ssh contains several encryption algorithms. These are all 31511b41d2SMark Murray accessed through the cipher.h interface. The interface code is 32511b41d2SMark Murray in cipher.c, and the implementations are in libc. 33511b41d2SMark Murray 34511b41d2SMark Murray Multiple Precision Integer Library 35511b41d2SMark Murray 36511b41d2SMark Murray - Uses the SSLeay BIGNUM sublibrary. 37511b41d2SMark Murray - Some auxiliary functions for mp-int manipulation are in mpaux.c. 38511b41d2SMark Murray 39511b41d2SMark Murray Random Numbers 40511b41d2SMark Murray 41511b41d2SMark Murray - Uses arc4random() and such. 42511b41d2SMark Murray 43511b41d2SMark Murray RSA key generation, encryption, decryption 44511b41d2SMark Murray 45511b41d2SMark Murray - Ssh uses the RSA routines in libssl. 46511b41d2SMark Murray 47511b41d2SMark Murray RSA key files 48511b41d2SMark Murray 49511b41d2SMark Murray - RSA keys are stored in files with a special format. The code to 50511b41d2SMark Murray read/write these files is in authfile.c. The files are normally 51511b41d2SMark Murray encrypted with a passphrase. The functions to read passphrases 52511b41d2SMark Murray are in readpass.c (the same code is used to read passwords). 53511b41d2SMark Murray 54511b41d2SMark Murray Binary packet protocol 55511b41d2SMark Murray 56511b41d2SMark Murray - The ssh binary packet protocol is implemented in packet.c. The 57511b41d2SMark Murray code in packet.c does not concern itself with packet types or their 58511b41d2SMark Murray execution; it contains code to build packets, to receive them and 59511b41d2SMark Murray extract data from them, and the code to compress and/or encrypt 60511b41d2SMark Murray packets. CRC code comes from crc32.c. 61511b41d2SMark Murray 62511b41d2SMark Murray - The code in packet.c calls the buffer manipulation routines 63511b41d2SMark Murray (buffer.c, bufaux.c), compression routines (compress.c, zlib), 64511b41d2SMark Murray and the encryption routines. 65511b41d2SMark Murray 66511b41d2SMark Murray X11, TCP/IP, and Agent forwarding 67511b41d2SMark Murray 68511b41d2SMark Murray - Code for various types of channel forwarding is in channels.c. 69511b41d2SMark Murray The file defines a generic framework for arbitrary communication 70511b41d2SMark Murray channels inside the secure channel, and uses this framework to 71511b41d2SMark Murray implement X11 forwarding, TCP/IP forwarding, and authentication 72511b41d2SMark Murray agent forwarding. 73511b41d2SMark Murray The new, Protocol 1.5, channel close implementation is in nchan.c 74511b41d2SMark Murray 75511b41d2SMark Murray Authentication agent 76511b41d2SMark Murray 77511b41d2SMark Murray - Code to communicate with the authentication agent is in authfd.c. 78511b41d2SMark Murray 79511b41d2SMark Murray Authentication methods 80511b41d2SMark Murray 81511b41d2SMark Murray - Code for various authentication methods resides in auth-*.c 82511b41d2SMark Murray (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c). This 83511b41d2SMark Murray code is linked into the server. The routines also manipulate 84511b41d2SMark Murray known hosts files using code in hostfile.c. Code in canohost.c 85511b41d2SMark Murray is used to retrieve the canonical host name of the remote host. 86511b41d2SMark Murray Code in match.c is used to match host names. 87511b41d2SMark Murray 88511b41d2SMark Murray - In the client end, authentication code is in sshconnect.c. It 89511b41d2SMark Murray reads Passwords/passphrases using code in readpass.c. It reads 90511b41d2SMark Murray RSA key files with authfile.c. It communicates the 91511b41d2SMark Murray authentication agent using authfd.c. 92511b41d2SMark Murray 93511b41d2SMark Murray The ssh client 94511b41d2SMark Murray 95511b41d2SMark Murray - The client main program is in ssh.c. It first parses arguments 96511b41d2SMark Murray and reads configuration (readconf.c), then calls ssh_connect (in 97511b41d2SMark Murray sshconnect.c) to open a connection to the server (possibly via a 98511b41d2SMark Murray proxy), and performs authentication (ssh_login in sshconnect.c). 99511b41d2SMark Murray It then makes any pty, forwarding, etc. requests. It may call 100511b41d2SMark Murray code in ttymodes.c to encode current tty modes. Finally it 101511b41d2SMark Murray calls client_loop in clientloop.c. This does the real work for 102511b41d2SMark Murray the session. 103511b41d2SMark Murray 104511b41d2SMark Murray - The client is suid root. It tries to temporarily give up this 105511b41d2SMark Murray rights while reading the configuration data. The root 106511b41d2SMark Murray privileges are only used to make the connection (from a 107511b41d2SMark Murray privileged socket). Any extra privileges are dropped before 108511b41d2SMark Murray calling ssh_login. 109511b41d2SMark Murray 110511b41d2SMark Murray Pseudo-tty manipulation and tty modes 111511b41d2SMark Murray 112511b41d2SMark Murray - Code to allocate and use a pseudo tty is in pty.c. Code to 113511b41d2SMark Murray encode and set terminal modes is in ttymodes.c. 114511b41d2SMark Murray 115511b41d2SMark Murray Logging in (updating utmp, lastlog, etc.) 116511b41d2SMark Murray 117511b41d2SMark Murray - The code to do things that are done when a user logs in are in 118511b41d2SMark Murray login.c. This includes things such as updating the utmp, wtmp, 119511b41d2SMark Murray and lastlog files. Some of the code is in sshd.c. 120511b41d2SMark Murray 121511b41d2SMark Murray Writing to the system log and terminal 122511b41d2SMark Murray 123511b41d2SMark Murray - The programs use the functions fatal(), log(), debug(), error() 124511b41d2SMark Murray in many places to write messages to system log or user's 125511b41d2SMark Murray terminal. The implementation that logs to system log is in 126511b41d2SMark Murray log-server.c; it is used in the server program. The other 127511b41d2SMark Murray programs use an implementation that sends output to stderr; it 128511b41d2SMark Murray is in log-client.c. The definitions are in ssh.h. 129511b41d2SMark Murray 130511b41d2SMark Murray The sshd server (daemon) 131511b41d2SMark Murray 132511b41d2SMark Murray - The sshd daemon starts by processing arguments and reading the 133511b41d2SMark Murray configuration file (servconf.c). It then reads the host key, 134511b41d2SMark Murray starts listening for connections, and generates the server key. 135511b41d2SMark Murray The server key will be regenerated every hour by an alarm. 136511b41d2SMark Murray 137511b41d2SMark Murray - When the server receives a connection, it forks, disables the 138511b41d2SMark Murray regeneration alarm, and starts communicating with the client. 139511b41d2SMark Murray They first perform identification string exchange, then 140511b41d2SMark Murray negotiate encryption, then perform authentication, preparatory 141511b41d2SMark Murray operations, and finally the server enters the normal session 142511b41d2SMark Murray mode by calling server_loop in serverloop.c. This does the real 143511b41d2SMark Murray work, calling functions in other modules. 144511b41d2SMark Murray 145511b41d2SMark Murray - The code for the server is in sshd.c. It contains a lot of 146511b41d2SMark Murray stuff, including: 147511b41d2SMark Murray - server main program 148511b41d2SMark Murray - waiting for connections 149511b41d2SMark Murray - processing new connection 150511b41d2SMark Murray - authentication 151511b41d2SMark Murray - preparatory operations 152511b41d2SMark Murray - building up the execution environment for the user program 153511b41d2SMark Murray - starting the user program. 154511b41d2SMark Murray 155511b41d2SMark Murray Auxiliary files 156511b41d2SMark Murray 157511b41d2SMark Murray - There are several other files in the distribution that contain 158511b41d2SMark Murray various auxiliary routines: 159511b41d2SMark Murray ssh.h the main header file for ssh (various definitions) 160511b41d2SMark Murray getput.h byte-order independent storage of integers 161511b41d2SMark Murray includes.h includes most system headers. Lots of #ifdefs. 162511b41d2SMark Murray tildexpand.c expand tilde in file names 163511b41d2SMark Murray uidswap.c uid-swapping 164511b41d2SMark Murray xmalloc.c "safe" malloc routines 165