192555Sdes[Note: This file has not been updated for OpenSSH versions after 292555SdesOpenSSH-1.2 and should be considered OBSOLETE. It has been left in 392555Sdesthe distribution because some of its information may still be useful 492555Sdesto developers.] 592555Sdes 657429SmarkmThis document is intended for those who wish to read the ssh source 757429Smarkmcode. This tries to give an overview of the structure of the code. 8126274Sdes 957429SmarkmCopyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi> 1057429SmarkmUpdated 17 Nov 1995. 1157429SmarkmUpdated 19 Oct 1999 for OpenSSH-1.2 1292555SdesUpdated 20 May 2001 note obsolete for > OpenSSH-1.2 1357429Smarkm 1457429SmarkmThe software consists of ssh (client), sshd (server), scp, sdist, and 1557429Smarkmthe auxiliary programs ssh-keygen, ssh-agent, ssh-add, and 1657429Smarkmmake-ssh-known-hosts. The main program for each of these is in a .c 1757429Smarkmfile with the same name. 1857429Smarkm 1957429SmarkmThere are some subsystems/abstractions that are used by a number of 2057429Smarkmthese programs. 2157429Smarkm 2257429Smarkm Buffer manipulation routines 23126274Sdes 2457429Smarkm - These provide an arbitrary size buffer, where data can be appended. 2557429Smarkm Data can be consumed from either end. The code is used heavily 2657429Smarkm throughout ssh. The basic buffer manipulation functions are in 2757429Smarkm buffer.c (header buffer.h), and additional code to manipulate specific 2857429Smarkm data types is in bufaux.c. 2957429Smarkm 3057429Smarkm Compression Library 31126274Sdes 3257429Smarkm - Ssh uses the GNU GZIP compression library (ZLIB). 3357429Smarkm 3457429Smarkm Encryption/Decryption 3557429Smarkm 3657429Smarkm - Ssh contains several encryption algorithms. These are all 3757429Smarkm accessed through the cipher.h interface. The interface code is 3857429Smarkm in cipher.c, and the implementations are in libc. 3957429Smarkm 4057429Smarkm Multiple Precision Integer Library 4157429Smarkm 4257429Smarkm - Uses the SSLeay BIGNUM sublibrary. 4357429Smarkm 4457429Smarkm Random Numbers 4557429Smarkm 4657429Smarkm - Uses arc4random() and such. 4757429Smarkm 4857429Smarkm RSA key generation, encryption, decryption 4957429Smarkm 5057429Smarkm - Ssh uses the RSA routines in libssl. 5157429Smarkm 5257429Smarkm RSA key files 5357429Smarkm 5457429Smarkm - RSA keys are stored in files with a special format. The code to 5557429Smarkm read/write these files is in authfile.c. The files are normally 5657429Smarkm encrypted with a passphrase. The functions to read passphrases 5757429Smarkm are in readpass.c (the same code is used to read passwords). 5857429Smarkm 5957429Smarkm Binary packet protocol 6057429Smarkm 6157429Smarkm - The ssh binary packet protocol is implemented in packet.c. The 6257429Smarkm code in packet.c does not concern itself with packet types or their 6357429Smarkm execution; it contains code to build packets, to receive them and 6457429Smarkm extract data from them, and the code to compress and/or encrypt 6557429Smarkm packets. CRC code comes from crc32.c. 6657429Smarkm 6757429Smarkm - The code in packet.c calls the buffer manipulation routines 6857429Smarkm (buffer.c, bufaux.c), compression routines (compress.c, zlib), 6957429Smarkm and the encryption routines. 7057429Smarkm 7157429Smarkm X11, TCP/IP, and Agent forwarding 7257429Smarkm 7357429Smarkm - Code for various types of channel forwarding is in channels.c. 7457429Smarkm The file defines a generic framework for arbitrary communication 7557429Smarkm channels inside the secure channel, and uses this framework to 7657429Smarkm implement X11 forwarding, TCP/IP forwarding, and authentication 7757429Smarkm agent forwarding. 7857429Smarkm The new, Protocol 1.5, channel close implementation is in nchan.c 7957429Smarkm 8057429Smarkm Authentication agent 8157429Smarkm 8257429Smarkm - Code to communicate with the authentication agent is in authfd.c. 8357429Smarkm 8457429Smarkm Authentication methods 8557429Smarkm 8657429Smarkm - Code for various authentication methods resides in auth-*.c 8757429Smarkm (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c). This 8857429Smarkm code is linked into the server. The routines also manipulate 8957429Smarkm known hosts files using code in hostfile.c. Code in canohost.c 9057429Smarkm is used to retrieve the canonical host name of the remote host. 91126274Sdes Code in match.c is used to match host names. 9257429Smarkm 9357429Smarkm - In the client end, authentication code is in sshconnect.c. It 9457429Smarkm reads Passwords/passphrases using code in readpass.c. It reads 9557429Smarkm RSA key files with authfile.c. It communicates the 9657429Smarkm authentication agent using authfd.c. 9757429Smarkm 9857429Smarkm The ssh client 9957429Smarkm 10057429Smarkm - The client main program is in ssh.c. It first parses arguments 10157429Smarkm and reads configuration (readconf.c), then calls ssh_connect (in 10257429Smarkm sshconnect.c) to open a connection to the server (possibly via a 10357429Smarkm proxy), and performs authentication (ssh_login in sshconnect.c). 10457429Smarkm It then makes any pty, forwarding, etc. requests. It may call 10557429Smarkm code in ttymodes.c to encode current tty modes. Finally it 10657429Smarkm calls client_loop in clientloop.c. This does the real work for 10757429Smarkm the session. 10857429Smarkm 10957429Smarkm - The client is suid root. It tries to temporarily give up this 11057429Smarkm rights while reading the configuration data. The root 11157429Smarkm privileges are only used to make the connection (from a 11257429Smarkm privileged socket). Any extra privileges are dropped before 11357429Smarkm calling ssh_login. 11457429Smarkm 11557429Smarkm Pseudo-tty manipulation and tty modes 11657429Smarkm 11757429Smarkm - Code to allocate and use a pseudo tty is in pty.c. Code to 11857429Smarkm encode and set terminal modes is in ttymodes.c. 11957429Smarkm 12057429Smarkm Logging in (updating utmp, lastlog, etc.) 12157429Smarkm 12257429Smarkm - The code to do things that are done when a user logs in are in 12357429Smarkm login.c. This includes things such as updating the utmp, wtmp, 12457429Smarkm and lastlog files. Some of the code is in sshd.c. 12557429Smarkm 12657429Smarkm Writing to the system log and terminal 12757429Smarkm 12857429Smarkm - The programs use the functions fatal(), log(), debug(), error() 12957429Smarkm in many places to write messages to system log or user's 13057429Smarkm terminal. The implementation that logs to system log is in 13157429Smarkm log-server.c; it is used in the server program. The other 13257429Smarkm programs use an implementation that sends output to stderr; it 13357429Smarkm is in log-client.c. The definitions are in ssh.h. 13457429Smarkm 13557429Smarkm The sshd server (daemon) 13657429Smarkm 13757429Smarkm - The sshd daemon starts by processing arguments and reading the 13857429Smarkm configuration file (servconf.c). It then reads the host key, 13957429Smarkm starts listening for connections, and generates the server key. 14057429Smarkm The server key will be regenerated every hour by an alarm. 14157429Smarkm 14257429Smarkm - When the server receives a connection, it forks, disables the 14357429Smarkm regeneration alarm, and starts communicating with the client. 14457429Smarkm They first perform identification string exchange, then 14557429Smarkm negotiate encryption, then perform authentication, preparatory 14657429Smarkm operations, and finally the server enters the normal session 14757429Smarkm mode by calling server_loop in serverloop.c. This does the real 14857429Smarkm work, calling functions in other modules. 149126274Sdes 15057429Smarkm - The code for the server is in sshd.c. It contains a lot of 15157429Smarkm stuff, including: 152126274Sdes - server main program 15357429Smarkm - waiting for connections 15457429Smarkm - processing new connection 15557429Smarkm - authentication 15657429Smarkm - preparatory operations 15757429Smarkm - building up the execution environment for the user program 15857429Smarkm - starting the user program. 15957429Smarkm 16057429Smarkm Auxiliary files 16157429Smarkm 16257429Smarkm - There are several other files in the distribution that contain 16357429Smarkm various auxiliary routines: 164126274Sdes ssh.h the main header file for ssh (various definitions) 16557429Smarkm uidswap.c uid-swapping 16657429Smarkm xmalloc.c "safe" malloc routines 167162852Sdes 168162852Sdes$OpenBSD: OVERVIEW,v 1.11 2006/08/03 03:34:41 deraadt Exp $ 169