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