1This document is intended for those who wish to read the ssh source 2code. This tries to give an overview of the structure of the code. 3 4Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi> 5Updated 17 Nov 1995. 6Updated 19 Oct 1999 for OpenSSH-1.2 7 8The software consists of ssh (client), sshd (server), scp, sdist, and 9the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and 10make-ssh-known-hosts. The main program for each of these is in a .c 11file with the same name. 12 13There are some subsystems/abstractions that are used by a number of 14these 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 165