OVERVIEW - security/openssh-library - Rivoreo Source Code Repositories

 This document is inteded for those who wish to read the ssh source
 code.  This tries to give an overview of the structure of the code.

 Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
 Updated 17 Nov 1995.
 Updated 19 Oct 1999 for OpenSSH-1.2

 The software consists of ssh (client), sshd (server), scp, sdist, and
 the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
 make-ssh-known-hosts.  The main program for each of these is in a .c
 file with the same name.

 There are some subsystems/abstractions that are used by a number of
 these programs.

   Buffer manipulation routines

     - These provide an arbitrary size buffer, where data can be appended.
       Data can be consumed from either end.  The code is used heavily
       throughout ssh.  The basic buffer manipulation functions are in
       buffer.c (header buffer.h), and additional code to manipulate specific
       data types is in bufaux.c.

   Compression Library

     - Ssh uses the GNU GZIP compression library (ZLIB).

   Encryption/Decryption

     - Ssh contains several encryption algorithms.  These are all
       accessed through the cipher.h interface.  The interface code is
       in cipher.c, and the implementations are in libc.

   Multiple Precision Integer Library

     - Uses the SSLeay BIGNUM sublibrary.
     - Some auxiliary functions for mp-int manipulation are in mpaux.c.

   Random Numbers

     - Uses arc4random() and such.

   RSA key generation, encryption, decryption

     - Ssh uses the RSA routines in libssl.

   RSA key files

     - RSA keys are stored in files with a special format.  The code to
       read/write these files is in authfile.c.  The files are normally
       encrypted with a passphrase.  The functions to read passphrases
       are in readpass.c (the same code is used to read passwords).

   Binary packet protocol

     - The ssh binary packet protocol is implemented in packet.c.  The
       code in packet.c does not concern itself with packet types or their
       execution; it contains code to build packets, to receive them and
       extract data from them, and the code to compress and/or encrypt
       packets.  CRC code comes from crc32.c.

     - The code in packet.c calls the buffer manipulation routines
       (buffer.c, bufaux.c), compression routines (compress.c, zlib),
       and the encryption routines.

   X11, TCP/IP, and Agent forwarding

     - Code for various types of channel forwarding is in channels.c.
       The file defines a generic framework for arbitrary communication
       channels inside the secure channel, and uses this framework to
       implement X11 forwarding, TCP/IP forwarding, and authentication
       agent forwarding.
       The new, Protocol 1.5, channel close implementation is in nchan.c

   Authentication agent

     - Code to communicate with the authentication agent is in authfd.c.

   Authentication methods

     - Code for various authentication methods resides in auth-*.c
       (auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c).  This
       code is linked into the server.  The routines also manipulate
       known hosts files using code in hostfile.c.  Code in canohost.c
       is used to retrieve the canonical host name of the remote host.
       Code in match.c is used to match host names.

     - In the client end, authentication code is in sshconnect.c.  It
       reads Passwords/passphrases using code in readpass.c.  It reads
       RSA key files with authfile.c.  It communicates the
       authentication agent using authfd.c.

   The ssh client

     - The client main program is in ssh.c.  It first parses arguments
       and reads configuration (readconf.c), then calls ssh_connect (in
       sshconnect.c) to open a connection to the server (possibly via a
       proxy), and performs authentication (ssh_login in sshconnect.c).
       It then makes any pty, forwarding, etc. requests.  It may call
       code in ttymodes.c to encode current tty modes.  Finally it
       calls client_loop in clientloop.c.  This does the real work for
       the session.

     - The client is suid root.  It tries to temporarily give up this
       rights while reading the configuration data.  The root
       privileges are only used to make the connection (from a
       privileged socket).  Any extra privileges are dropped before
       calling ssh_login.

   Pseudo-tty manipulation and tty modes

     - Code to allocate and use a pseudo tty is in pty.c.  Code to
       encode and set terminal modes is in ttymodes.c.

   Logging in (updating utmp, lastlog, etc.)

     - The code to do things that are done when a user logs in are in
       login.c.  This includes things such as updating the utmp, wtmp,
       and lastlog files.  Some of the code is in sshd.c.

   Writing to the system log and terminal

     - The programs use the functions fatal(), log(), debug(), error()
       in many places to write messages to system log or user's
       terminal.  The implementation that logs to system log is in
       log-server.c; it is used in the server program.  The other
       programs use an implementation that sends output to stderr; it
       is in log-client.c.  The definitions are in ssh.h.

   The sshd server (daemon)

     - The sshd daemon starts by processing arguments and reading the
       configuration file (servconf.c).  It then reads the host key,
       starts listening for connections, and generates the server key.
       The server key will be regenerated every hour by an alarm.

     - When the server receives a connection, it forks, disables the
       regeneration alarm, and starts communicating with the client.
       They first perform identification string exchange, then
       negotiate encryption, then perform authentication, preparatory
       operations, and finally the server enters the normal session
       mode by calling server_loop in serverloop.c.  This does the real
       work, calling functions in other modules.

     - The code for the server is in sshd.c.  It contains a lot of
       stuff, including:
         - server main program
 	- waiting for connections
 	- processing new connection
 	- authentication
 	- preparatory operations
 	- building up the execution environment for the user program
 	- starting the user program.

   Auxiliary files

     - There are several other files in the distribution that contain
       various auxiliary routines:
         ssh.h	     the main header file for ssh (various definitions)
         getput.h     byte-order independent storage of integers
         includes.h   includes most system headers.  Lots of #ifdefs.
 	tildexpand.c expand tilde in file names
 	uidswap.c    uid-swapping
 	xmalloc.c    "safe" malloc routines
	This document is inteded for those who wish to read the ssh source
	code. This tries to give an overview of the structure of the code.

	Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>
	Updated 17 Nov 1995.
	Updated 19 Oct 1999 for OpenSSH-1.2

	The software consists of ssh (client), sshd (server), scp, sdist, and
	the auxiliary programs ssh-keygen, ssh-agent, ssh-add, and
	make-ssh-known-hosts. The main program for each of these is in a .c
	file with the same name.

	There are some subsystems/abstractions that are used by a number of
	these programs.

	Buffer manipulation routines

	- These provide an arbitrary size buffer, where data can be appended.
	Data can be consumed from either end. The code is used heavily
	throughout ssh. The basic buffer manipulation functions are in
	buffer.c (header buffer.h), and additional code to manipulate specific
	data types is in bufaux.c.

	Compression Library

	- Ssh uses the GNU GZIP compression library (ZLIB).

	Encryption/Decryption

	- Ssh contains several encryption algorithms. These are all
	accessed through the cipher.h interface. The interface code is
	in cipher.c, and the implementations are in libc.

	Multiple Precision Integer Library

	- Uses the SSLeay BIGNUM sublibrary.
	- Some auxiliary functions for mp-int manipulation are in mpaux.c.

	Random Numbers

	- Uses arc4random() and such.

	RSA key generation, encryption, decryption

	- Ssh uses the RSA routines in libssl.

	RSA key files

	- RSA keys are stored in files with a special format. The code to
	read/write these files is in authfile.c. The files are normally
	encrypted with a passphrase. The functions to read passphrases
	are in readpass.c (the same code is used to read passwords).

	Binary packet protocol

	- The ssh binary packet protocol is implemented in packet.c. The
	code in packet.c does not concern itself with packet types or their
	execution; it contains code to build packets, to receive them and
	extract data from them, and the code to compress and/or encrypt
	packets. CRC code comes from crc32.c.

	- The code in packet.c calls the buffer manipulation routines
	(buffer.c, bufaux.c), compression routines (compress.c, zlib),
	and the encryption routines.

	X11, TCP/IP, and Agent forwarding

	- Code for various types of channel forwarding is in channels.c.
	The file defines a generic framework for arbitrary communication
	channels inside the secure channel, and uses this framework to
	implement X11 forwarding, TCP/IP forwarding, and authentication
	agent forwarding.
	The new, Protocol 1.5, channel close implementation is in nchan.c

	Authentication agent

	- Code to communicate with the authentication agent is in authfd.c.

	Authentication methods

	- Code for various authentication methods resides in auth-*.c
	(auth-passwd.c, auth-rh-rsa.c, auth-rhosts.c, auth-rsa.c). This
	code is linked into the server. The routines also manipulate
	known hosts files using code in hostfile.c. Code in canohost.c
	is used to retrieve the canonical host name of the remote host.
	Code in match.c is used to match host names.

	- In the client end, authentication code is in sshconnect.c. It
	reads Passwords/passphrases using code in readpass.c. It reads
	RSA key files with authfile.c. It communicates the
	authentication agent using authfd.c.

	The ssh client

	- The client main program is in ssh.c. It first parses arguments
	and reads configuration (readconf.c), then calls ssh_connect (in
	sshconnect.c) to open a connection to the server (possibly via a
	proxy), and performs authentication (ssh_login in sshconnect.c).
	It then makes any pty, forwarding, etc. requests. It may call
	code in ttymodes.c to encode current tty modes. Finally it
	calls client_loop in clientloop.c. This does the real work for
	the session.

	- The client is suid root. It tries to temporarily give up this
	rights while reading the configuration data. The root
	privileges are only used to make the connection (from a
	privileged socket). Any extra privileges are dropped before
	calling ssh_login.

	Pseudo-tty manipulation and tty modes

	- Code to allocate and use a pseudo tty is in pty.c. Code to
	encode and set terminal modes is in ttymodes.c.

	Logging in (updating utmp, lastlog, etc.)

	- The code to do things that are done when a user logs in are in
	login.c. This includes things such as updating the utmp, wtmp,
	and lastlog files. Some of the code is in sshd.c.

	Writing to the system log and terminal

	- The programs use the functions fatal(), log(), debug(), error()
	in many places to write messages to system log or user's
	terminal. The implementation that logs to system log is in
	log-server.c; it is used in the server program. The other
	programs use an implementation that sends output to stderr; it
	is in log-client.c. The definitions are in ssh.h.

	The sshd server (daemon)

	- The sshd daemon starts by processing arguments and reading the
	configuration file (servconf.c). It then reads the host key,
	starts listening for connections, and generates the server key.
	The server key will be regenerated every hour by an alarm.

	- When the server receives a connection, it forks, disables the
	regeneration alarm, and starts communicating with the client.
	They first perform identification string exchange, then
	negotiate encryption, then perform authentication, preparatory
	operations, and finally the server enters the normal session
	mode by calling server_loop in serverloop.c. This does the real
	work, calling functions in other modules.

	- The code for the server is in sshd.c. It contains a lot of
	stuff, including:
	- server main program
	- waiting for connections
	- processing new connection
	- authentication
	- preparatory operations
	- building up the execution environment for the user program
	- starting the user program.

	Auxiliary files

	- There are several other files in the distribution that contain
	various auxiliary routines:
	ssh.h the main header file for ssh (various definitions)
	getput.h byte-order independent storage of integers
	includes.h includes most system headers. Lots of #ifdefs.
	tildexpand.c expand tilde in file names
	uidswap.c uid-swapping
	xmalloc.c "safe" malloc routines