[openssh.git] / OVERVIEW

[Note: This file has not been updated for OpenSSH versions after
OpenSSH-1.2 and should be considered OBSOLETE.  It has been left in
the distribution because some of its information may still be useful
to developers.]

This document is intended 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
Updated 20 May 2001 note obsolete 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.

  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)
	uidswap.c    uid-swapping
	xmalloc.c    "safe" malloc routines

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