crypto/openssh/OVERVIEW

   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
   6 This document is intended for those who wish to read the ssh source
   7 code.  This tries to give an overview of the structure of the code.
   8
   9 Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
  10 Updated 17 Nov 1995.
  11 Updated 19 Oct 1999 for OpenSSH-1.2
  12 Updated 20 May 2001 note obsolete for > OpenSSH-1.2
  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
  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 buffer manipulation functions are in
  27       sshbuf*.c (header sshbuf.h).
  28
  29   Compression Library
  30
  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.
  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.
  65
  66     - The code in packet.c calls the buffer manipulation routines
  67       (buffer.c, bufaux.c), compression routines (zlib), and the
  68       encryption routines.
  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.
  90       Code in match.c is used to match host names.
  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   Pseudo-tty manipulation and tty modes
 109
 110     - Code to allocate and use a pseudo tty is in pty.c.  Code to
 111       encode and set terminal modes is in ttymodes.c.
 112
 113   Logging in (updating utmp, lastlog, etc.)
 114
 115     - The code to do things that are done when a user logs in are in
 116       login.c.  This includes things such as updating the utmp, wtmp,
 117       and lastlog files.  Some of the code is in sshd.c.
 118
 119   Writing to the system log and terminal
 120
 121     - The programs use the functions fatal(), log(), debug(), error()
 122       in many places to write messages to system log or user's
 123       terminal.  The implementation that logs to system log is in
 124       log-server.c; it is used in the server program.  The other
 125       programs use an implementation that sends output to stderr; it
 126       is in log-client.c.  The definitions are in ssh.h.
 127
 128   The sshd server (daemon)
 129
 130     - The sshd daemon starts by processing arguments and reading the
 131       configuration file (servconf.c).  It then reads the host key,
 132       starts listening for connections, and generates the server key.
 133       The server key will be regenerated every hour by an alarm.
 134
 135     - When the server receives a connection, it forks, disables the
 136       regeneration alarm, and starts communicating with the client.
 137       They first perform identification string exchange, then
 138       negotiate encryption, then perform authentication, preparatory
 139       operations, and finally the server enters the normal session
 140       mode by calling server_loop in serverloop.c.  This does the real
 141       work, calling functions in other modules.
 142
 143     - The code for the server is in sshd.c.  It contains a lot of
 144       stuff, including:
 145         - server main program
 146         - waiting for connections
 147         - processing new connection
 148         - authentication
 149         - preparatory operations
 150         - building up the execution environment for the user program
 151         - starting the user program.
 152
 153   Auxiliary files
 154
 155     - There are several other files in the distribution that contain
 156       various auxiliary routines:
 157         ssh.h        the main header file for ssh (various definitions)
 158         uidswap.c    uid-swapping
 159         xmalloc.c    "safe" malloc routines
 160
 161 $OpenBSD: OVERVIEW,v 1.14 2018/07/27 03:55:22 dtucker Exp $