modules.txt

伯克利做的SFTP安全文件传输协议

modules.txt
Description of each module in sftpd
Scott McPeak, May 31 1999
Updated: June 19, 2000

--------------
Library: extras
Has lots of self-contained library-like modules.
Contains all the modules below, up to the 'smcrypto' library.

Module: syserr
Module for portably reporting errors that result from system calls.

Module: breaker
Place to put a breakpoint; basically a debugging aid.

Module: crc
Compute a 32-bit CRC (cyclic redundancy check).

Module: datablok
Store an arbitrary-size block of binary data.

Module: exc
Base classes for exceptions.

Module: intutils
A few small utilities on top of Integer (integer.h).

Module: missing
A few random functions that sometimes aren't present, but I need them.

Module: nonport
Grab-bag of functions with portable interfaces but nonportable
implementations.  Includes file access restrictions, etc.

Module: str
A string class.

Module: warn
Module for reporting warnings to the user.  Not very well thought-out
at the moment.


--------------
Library: smcrypto (SM's crypto)
All cryptography functions for SafeTP.  Includes some stuff from Wei Dai's
crypto++, plus some stuff I (SM) wrote.
Contains all the modules below, up to 'sftp' library.

Module: crypto/ialgebra
Wei Dai's "algebra" module, modified to eliminate use of templates.
Has algebra functions, I guess.

Module: security
Protocol primitives.  SafeTP's protocol mechanisms are built as
derived classes of those that appear here.

Module: blokutil
Some utilities for DataBlocks.  Mostly these involve encoding and decoding
various data types into and out of DataBlocks.  (Kinda like a streams
interface.)

Module: gmp_si
A big-integer class, wrapped around the GNU Multi-precision integer
library implementation.  (Header is sint.h.)

Module: trans
Cryptographic primitives.  The base class for several cryptographic operations
used by SafeTP appears here.

Module: selgamal (Scott's ElGamal)
My implementation of the El Gamal public-key cipher.

Module: sdsa (Scott's DSA)
My implemenetation of the DSA (Digital Signature Algorithm) public-key
signature algorithm.

Module: shmac (Scott's HMAC)
My implementation of HMAC (Hash Message Authentication Code).

Module: ssha (Scott's SHA)
Wei Dai's "sha" module, modified to eliminate use of templates.

Module: crypto/{asn,cryptlib,des,dessp,integer,md5,misc,modes,
                nbtheory,queue,randpool,rng}
Wei Dai's crypto++ modules we needed for SafeTP.  They are largely
unchanged (maybe entirely unchanged) from his 2.3 release.  I don't
know what all of them do, but most have reasonably meaningful
names.  (E.g., des is DES (Data Encryption Standard) cipher.)


--------------
Library: sftp
This has all the modules that are common to sftpd (the server) and
sftpc (the client).  This is basically everything.
Contains all the modules listed below.

Module: hcl
Functions needed to work with the Hummingbird Inetd on NT.

Module: digt
Computes the digest of a series of messages, for implementing the
DIGT command.

Module: sftp
Small grab-bag of stuff common to sftpd and sftpc.

Module: base64
Dan's Base-64 functions.  Base-64 is an encoding for representing
8-bit data in a 6-bit code.

Module: base64t
My wrapper on Dan's stuff.

Module: cryputil
Some cryptographic utilities built on top of Wei Dai's crypto++.

Module: entropy
For gathering user-generated entropy periodically.

Module: filesrc
For reading a file as a StreamInputSource, which I use as the
basis for reading things one line at a time.

Module: keydb
Dan's module for maintaining the database of known server
public keys.

Module: keyutils
More of Dan's key stuff.

Module: globrand
Implementation of a pseudo-random number generator that is
cryptographically strong.  Includes some additional measures to
ensure that even if an attacker sees most or all of the output, it
is still insufficient to predict future output (it's unclear whether
the PRNG on which it is based has this property).

Module: lineread
Module for reading something one line at a time.  This is more
complex than you might think...

Module: memsrc
StreamInputSource for reading from a memory buffer.

Module: provider
Implemented SecurityProviders, which function as high-level
protocol managers.

Module: reply
Stores an FTP reply.

Module: request
Stores an FTP request.

Module: sec_clr
Implementation of X-CLEARTEXT and X-CLEARTEXT2 protocols.  These
are for debugging purposes only, and are NOT secure.

Module: sec_de3s
Implementation of X-SAFETP1 protocol.  This is the protocol used
in SafeTP, over the wire.

Module: sftpver
Just gives the sftpd version number string.

Module: socksrc
StreamInputSource from a communications socket.

Module: sockutil
Bunch of useful stuff I built on top of sockets.  Includes things
like automatically throwing exceptions when certain calls fail.


--------------
Miscellanous headers (no associated .cpp file)

integer.h  - just #includes sint.h; for backward compatibility with crypto++
socketd.h  - declaration of SOCKET type
stlsubst.h - all the STL that crypto++ needs, so real STL need not be dealt with
test.h     - some macros, etc., to facilitate writing test code
typ.h      - declarations of types, and a few utility macros
xassert.h  - assert() replacement that throws an exception instead of aborting


--------------
Executable: sftpd
This is the server (daemon) for SafeTP.  It acts as a proxy, doing
encryption and decryption while forwarding traffic between the
normal FTP daemon (ftpd) and the client.
Main file: sftpd.cpp


--------------
Executable: sftpc
This is the unix client for SafeTP.  It is a stand-alone program
that works in some respects like the normal FTP client, but (for
now) has a hairier interface.  Note that the client we expect
people to actually use is the 95/8/NT client, written by Dan as
a proxy client, available from:
  http://safetp.cs.berkeley.edu


--------------
Notes on reading this code.

In general, it is possible to read code either bottom-up or top-down.
In fact, I usually do a mix of both.  So I will give pointers for
both methods.  As always, read the header files (*.h) before the
code files (*.cpp).

Bottom-up:

Start with the 'extras' library.  The most interesting module is
'datablok', followed perhaps by 'str'.  'nonport' is fun if you
like seeing how unix and nt differ.

Then move to the 'smcrypto' library.  'blokutil' shows how to
encode various things, which are encodings specified by the
SafeTP protocol, X-SAFETP1.  'trans' and 'security' are the
foundations of the cryptography and security modules, respectively.
The rest are not of interest, unless you want to see how some
crypto is implemented.  In that case, 'selgamal' and 'sdsa' have
the most readable code, and are implementations of two public-key
algorithms.  (The Integer class they use is defined in
'crypto/integer'.)

Next, look at the 'sftp' library.  'request' and 'reply' show
how to store and parse FTP protocol sequences.  'lineread' and
'{mem,file,sock}src' show a nice way to break things up into lines
without knowing exactly which medium they come from (and without
reading beyond the CRLF, since that would block).  'sec_de3s' is
the X-SAFETP1 protocol itself.  It's long and hard to read; it
may be best to start with just the .h file and ignore the .cpp
for now.

Lastly, examine the executables themselves.  'sftpd' is better
structured and more fully-functioned than 'sftpc', at least for
now.  sftpd is also long, but should be mostly straightforward.

Top-down:

Basicaly the reverse of what I just said.  :)