1[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 6This document is intended for those who wish to read the ssh source 7code. This tries to give an overview of the structure of the code. 8 9Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi> 10Updated 17 Nov 1995. 11Updated 19 Oct 1999 for OpenSSH-1.2 12Updated 20 May 2001 note obsolete for > OpenSSH-1.2 13 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 23 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 31 32 - 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. 43 - Some auxiliary functions for mp-int manipulation are in mpaux.c. 44 45 Random Numbers 46 47 - Uses arc4random() and such. 48 49 RSA key generation, encryption, decryption 50 51 - Ssh uses the RSA routines in libssl. 52 53 RSA key files 54 55 - RSA keys are stored in files with a special format. The code to 56 read/write these files is in authfile.c. The files are normally 57 encrypted with a passphrase. The functions to read passphrases 58 are in readpass.c (the same code is used to read passwords). 59 60 Binary packet protocol 61 62 - The ssh binary packet protocol is implemented in packet.c. The 63 code in packet.c does not concern itself with packet types or their 64 execution; it contains code to build packets, to receive them and 65 extract data from them, and the code to compress and/or encrypt 66 packets. CRC code comes from crc32.c. 67 68 - The code in packet.c calls the buffer manipulation routines 69 (buffer.c, bufaux.c), compression routines (compress.c, zlib), 70 and the encryption routines. 71 72 X11, TCP/IP, and Agent forwarding 73 74 - Code for various types of channel forwarding is in channels.c. 75 The file defines a generic framework for arbitrary communication 76 channels inside the secure channel, and uses this framework to 77 implement X11 forwarding, TCP/IP forwarding, and authentication 78 agent forwarding. 79 The new, Protocol 1.5, channel close implementation is in nchan.c 80 81 Authentication agent 82 83 - Code to communicate with the authentication agent is in authfd.c. 84 85 Authentication methods 86 87 - Code for various authentication methods resides in auth-*.c 88 (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c). This 89 code is linked into the server. The routines also manipulate 90 known hosts files using code in hostfile.c. Code in canohost.c 91 is used to retrieve the canonical host name of the remote host. 92 Code in match.c is used to match host names. 93 94 - In the client end, authentication code is in sshconnect.c. It 95 reads Passwords/passphrases using code in readpass.c. It reads 96 RSA key files with authfile.c. It communicates the 97 authentication agent using authfd.c. 98 99 The ssh client 100 101 - The client main program is in ssh.c. It first parses arguments 102 and reads configuration (readconf.c), then calls ssh_connect (in 103 sshconnect.c) to open a connection to the server (possibly via a 104 proxy), and performs authentication (ssh_login in sshconnect.c). 105 It then makes any pty, forwarding, etc. requests. It may call 106 code in ttymodes.c to encode current tty modes. Finally it 107 calls client_loop in clientloop.c. This does the real work for 108 the session. 109 110 - The client is suid root. It tries to temporarily give up this 111 rights while reading the configuration data. The root 112 privileges are only used to make the connection (from a 113 privileged socket). Any extra privileges are dropped before 114 calling ssh_login. 115 116 Pseudo-tty manipulation and tty modes 117 118 - Code to allocate and use a pseudo tty is in pty.c. Code to 119 encode and set terminal modes is in ttymodes.c. 120 121 Logging in (updating utmp, lastlog, etc.) 122 123 - The code to do things that are done when a user logs in are in 124 login.c. This includes things such as updating the utmp, wtmp, 125 and lastlog files. Some of the code is in sshd.c. 126 127 Writing to the system log and terminal 128 129 - The programs use the functions fatal(), log(), debug(), error() 130 in many places to write messages to system log or user's 131 terminal. The implementation that logs to system log is in 132 log-server.c; it is used in the server program. The other 133 programs use an implementation that sends output to stderr; it 134 is in log-client.c. The definitions are in ssh.h. 135 136 The sshd server (daemon) 137 138 - The sshd daemon starts by processing arguments and reading the 139 configuration file (servconf.c). It then reads the host key, 140 starts listening for connections, and generates the server key. 141 The server key will be regenerated every hour by an alarm. 142 143 - When the server receives a connection, it forks, disables the 144 regeneration alarm, and starts communicating with the client. 145 They first perform identification string exchange, then 146 negotiate encryption, then perform authentication, preparatory 147 operations, and finally the server enters the normal session 148 mode by calling server_loop in serverloop.c. This does the real 149 work, calling functions in other modules. 150 151 - The code for the server is in sshd.c. It contains a lot of 152 stuff, including: 153 - server main program 154 - waiting for connections 155 - processing new connection 156 - authentication 157 - preparatory operations 158 - building up the execution environment for the user program 159 - starting the user program. 160 161 Auxiliary files 162 163 - There are several other files in the distribution that contain 164 various auxiliary routines: 165 ssh.h the main header file for ssh (various definitions) 166 getput.h byte-order independent storage of integers 167 includes.h includes most system headers. Lots of #ifdefs. 168 tildexpand.c expand tilde in file names 169 uidswap.c uid-swapping 170 xmalloc.c "safe" malloc routines 171