Home | History | Annotate | Line # | Download | only in dist
OVERVIEW revision 1.8 
      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 (a] 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 either in libc or
     38       LibreSSL.
     39 
     40   Multiple Precision Integer Library
     41 
     42     - Uses the LibreSSL BIGNUM sublibrary.
     43 
     44   Random Numbers
     45 
     46     - Uses arc4random() and such.
     47 
     48   RSA key generation, encryption, decryption
     49 
     50     - Ssh uses the RSA routines in libssl.
     51 
     52   RSA key files
     53 
     54     - RSA keys are stored in files with a special format.  The code to
     55       read/write these files is in authfile.c.  The files are normally
     56       encrypted with a passphrase.  The functions to read passphrases
     57       are in readpass.c (the same code is used to read passwords).
     58 
     59   Binary packet protocol
     60 
     61     - The ssh binary packet protocol is implemented in packet.c.  The
     62       code in packet.c does not concern itself with packet types or their
     63       execution; it contains code to build packets, to receive them and
     64       extract data from them, and the code to compress and/or encrypt
     65       packets.
     66 
     67     - The code in packet.c calls the buffer manipulation routines
     68       (buffer.c, bufaux.c), compression routines (zlib), and the
     69       encryption routines.
     70 
     71   X11, TCP/IP, and Agent forwarding
     72 
     73     - Code for various types of channel forwarding is in channels.c.
     74       The file defines a generic framework for arbitrary communication
     75       channels inside the secure channel, and uses this framework to
     76       implement X11 forwarding, TCP/IP forwarding, and authentication
     77       agent forwarding.
     78       The new, Protocol 1.5, channel close implementation is in nchan.c
     79 
     80   Authentication agent
     81 
     82     - Code to communicate with the authentication agent is in authfd.c.
     83 
     84   Authentication methods
     85 
     86     - Code for various authentication methods resides in auth-*.c
     87       (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c).  This
     88       code is linked into the server.  The routines also manipulate
     89       known hosts files using code in hostfile.c.  Code in canohost.c
     90       is used to retrieve the canonical host name of the remote host.
     91       Code in match.c is used to match host names.
     92 
     93     - In the client end, authentication code is in sshconnect.c.  It
     94       reads Passwords/passphrases using code in readpass.c.  It reads
     95       RSA key files with authfile.c.  It communicates the
     96       authentication agent using authfd.c.
     97 
     98   The ssh client
     99 
    100     - The client main program is in ssh.c.  It first parses arguments
    101       and reads configuration (readconf.c), then calls ssh_connect (in
    102       sshconnect.c) to open a connection to the server (possibly via a
    103       proxy), and performs authentication (ssh_login in sshconnect.c).
    104       It then makes any pty, forwarding, etc. requests.  It may call
    105       code in ttymodes.c to encode current tty modes.  Finally it
    106       calls client_loop in clientloop.c.  This does the real work for
    107       the session.
    108 
    109   Pseudo-tty manipulation and tty modes
    110 
    111     - Code to allocate and use a pseudo tty is in pty.c.  Code to
    112       encode and set terminal modes is in ttymodes.c.
    113 
    114   Logging in (updating utmp, lastlog, etc.)
    115 
    116     - The code to do things that are done when a user logs in are in
    117       login.c.  This includes things such as updating the utmp, wtmp,
    118       and lastlog files.  Some of the code is in sshd.c.
    119 
    120   Writing to the system log and terminal
    121 
    122     - The programs use the functions fatal(), log(), debug(), error()
    123       in many places to write messages to system log or user's
    124       terminal.  The implementation that logs to system log is in
    125       log-server.c; it is used in the server program.  The other
    126       programs use an implementation that sends output to stderr; it
    127       is in log-client.c.  The definitions are in ssh.h.
    128 
    129   The sshd server (daemon)
    130 
    131     - The sshd daemon starts by processing arguments and reading the
    132       configuration file (servconf.c).  It then reads the host key,
    133       starts listening for connections, and generates the server key.
    134       The server key will be regenerated every hour by an alarm.
    135 
    136     - When the server receives a connection, it forks, disables the
    137       regeneration alarm, and starts communicating with the client.
    138       They first perform identification string exchange, then
    139       negotiate encryption, then perform authentication, preparatory
    140       operations, and finally the server enters the normal session
    141       mode by calling server_loop in serverloop.c.  This does the real
    142       work, calling functions in other modules.
    143 
    144     - The code for the server is in sshd.c.  It contains a lot of
    145       stuff, including:
    146 	- server main program
    147 	- waiting for connections
    148 	- processing new connection
    149 	- authentication
    150 	- preparatory operations
    151 	- building up the execution environment for the user program
    152 	- starting the user program.
    153 
    154   Auxiliary files
    155 
    156     - There are several other files in the distribution that contain
    157       various auxiliary routines:
    158 	ssh.h	     the main header file for ssh (various definitions)
    159 	uidswap.c    uid-swapping
    160 	xmalloc.c    "safe" malloc routines
    161 
    162 $OpenBSD: OVERVIEW,v 1.15 2018/10/23 05:56:35 djm Exp $
    163 $NetBSD: OVERVIEW,v 1.8 2019/04/20 17:16:40 christos Exp $
    164