Read Me
AdaSSH Build and Usage Instructions
This file provides instructions for compiling the AdaSSH library, and running
the AdaSSH client program. Please note that any shell commands listed in these
instructions assume the user is running a Bourne-compatible shell on a
Unix/Linux system. If you are not, make adjustments as necessary. The '$'
character is used to indicate a shell prompt.
Build Requirements
Build Environment
In order to build the software, the build environment must meet the following
requirements:
- Compiler: GCC 4.5 or later, or GNAT GPL 2009 or later
- gnatmake
- libadacrypt-dev
- GNU Make, as well as a Bourne-compatible shell (optional)
- Testgen (optional)
AdaSSH was written in Ada2005, using the GNAT compiler. GNAT is a free,
open-source Ada compiler that is part of the GNU Compiler Collection (GCC).
Due to a recent bug [1] in GCC, most versions of the compiler are currently
incompatible. Note that, at the time of this writing, GCC 4.5 has not been
released, and can only be obtained by downloading the source and compiling it
yourself. If you decide to do that, ensure that prior to building, GCC is
configured with Ada support enabled, by passing '--enable-languages=ada', and
'--enable-libada' to the configure script.
As an alternative, the open-source Ada compiler released by AdaCore [2] can be
used. The problematic bug is fixed in GNAT GPL version 2009.
AdaSSH makes heavy use of the gnatmake Ada build automation tool. It is
distributed along with any Ada-capable GCC build, as well as AdaCore's
compilers.
The Ada Crypto Library, or libadacrypt-dev is another requirement. It
can be downloaded from the library's SourceForge site [3].
In order to run the unit tests, testgen is required for test driver
generation (see below). GNU Make is not strictly necessary, but the Makefile
distributed along with the project helps automate the unit tests. It uses some
Bourne shell-specific syntax to accomplish that.
Operating System and Architecture
The SSH protocol library itself should compile on any operating system
where a GNAT-GCC compiler and the Ada Crypto Library are available. Note that
the Ada Crypto Library is currently only available for Unix systems, due to
the fact that it uses the /dev/random device for random number generation. The
AdaSSH client program makes some assumptions that probably limit it to Linux
systems.
At the time of this writing, AdaSSH has only been tested on Linux running on
an Intel 32-bit system. The author can make no guarantee that it works
anywhere else.
Project Layout
The project is laid out with the following directory structure:
/adassh/bin/
src/
test/
Makefile
ssh.gpr
ssh_test.gpr
The 'bin' directory contains all executables and object files once the
build is complete.
The source code is contained in the 'src' directory. All source files follow
the standard GNAT naming conventions, i.e. given a package called 'Foo', which
is a child package of another package called 'Bar', the package spec is found
in the file 'bar-foo.ads', and the package body (if any) is in the file
'bar-foo.adb'. The package hierarchy starting at 'SSH' contains all the code
of the protocol library, whereas the client application is in the 'AdaSSH'
hierarchy. Packages starting with 'Crypto' contain extensions to the Ada
Crypto Library.
The 'Makefile' can be used for building and testing the software, but it is
possible to produce a working build without using it. All build-related
commands are delegated to 'gnatmake' by the Makefile.
The '.gpr' files are GNAT project files, which specify a build environment for
the gnatmake build automation tool. The 'ssh.gpr' file is used for the library
and client programs, the other one is used to compile the test drivers.
Build Process
Set-up and Configuration
For the project to compile, the libadacrypt-dev must be downloaded, and its
sources must be found by the compiler. The easiest way to achieve that end is
to place the library in a directory called 'libadacrypt-dev', next to the
'adassh' directory. Alternatively, you can edit the file 'ssh.gpr', modifying
the first line to point to libadacrypt's project file.
Compiling
In order to build the SSH protocol library, change to the 'adassh'
directory. Then, simply type either
$ make
or
$ gnatmake -P ssh.gpr
The AdaSSH client program can be built using
$ make bin/adassh-client
or
$ gnatmake -P ssh.gpr adassh-client
In both cases, the resulting executable,
'adassh-client', can then be found in the 'adassh/bin' directory.
Generating Test Drivers and Running the Unit Tests
The unit tests are currently implemented in testgen, a test driver generator
for Ada. Using testgen, test cases are specified in a concise script format,
from which testgen generates the test driver, including all the boilerplate
condition-checking and logging code.
Testgen is based on tg originally written by André Spiegel, and extended into
testgen by Stefan Lucks.
A copy of the combined tg and testgen source code is
distributed along with this program. Alternatively,
tg [4] and testgen [5]
can be downloaded separately.
If you are using the source distributed here, change to the 'testgen'
directory, and use the GNAT project file provided there to compile it:
$ cd testgen && mkdir -p bin && gnatmake -P testgen.gpr
This will create a directory 'bin' that contains the testgen
executable. Once compiled, testgen needs to be on the system path in
order for test drivers to be automatically generated and run from the
AdaSSH Makefile. For instance, from a bash shell the following command would do:
$ export PATH=$PATH:/path/to/testgen/bin
Once this is done, change back to the 'adassh' directory. The command
$ make test
will generate, compile and run
all test drivers.
Running the AdaSSH Client
The AdaSSH reference client program currently features interactive shell
login, remote program execution and local port forwarding. The program is run
from the command line. From the AdaSSH
main directory, type
$ bin/adassh-client -h
to see a list of supported command line options.
Generally, all the options and parameters that are currently available have
the same syntax as the analogous OpenSSH command. As a somewhat contrived
example, in order to log in to an interactive shell on the host 'example.com',
using the SSH server running on port 2222, and the user name 'me' -- while at
the same time forwarding the local port 8080 to port 80 on 'www.google.com' --
type the following command:
$ bin/adassh-client -L 8080:www.google.com:80 me@example.com:2222
Care was taken to achieve compatibility with OpenSSH in other regards, but the
client is somewhat limited in scope, for now. For one, while it can read the
'known_hosts' file used for OpenSSH public host keys, it cannot currently add
new entries to it -- you could use the 'ssh-keyscan' program provided by
OpenSSH to do this separately. The client uses the '.ssh/known_hosts' file in
the user's home directory, and there is currently no way to change that.
The client, as well as its author, do not yet understand the OpenSSH file
format used for private keys. As such, only the password authentication
method can be used for now.
Also note that the RSA public key algorithm is currently not implemented by
AdaSSH, so that only DSA host keys can currently be used.
Summary
The following is a brief summary of the steps you need to complete in order to
compile and run the software:
1.) Install a compatible version of the GNU GCC with Ada support, or the AdaCore
GNAT compiler.
2.) Download the Ada Crypto Library source code. If necessary, edit the main
project file, 'ssh.gpr', to reflect its location.
3.) Optional: In order to run the unit tests, compile testgen, and put it on
your path. A call to 'make test' will now generate, compile and
run them.
4.) To build and link the AdaSSH client, run 'make bin/adassh-client'
(or 'gnatmake -P ssh.gpr adassh-client').
5.) You may now run the AdaSSH client, found at 'bin/adassh-client'.
Footnotes
[1] http://gcc.gnu.org/bugzilla/show_bug.cgi?id=38394
[2] GNAT GPL is downloadable from https://libre.adacore.com/libre/download/
[3] http://sourceforge.net/projects/libadacrypt-dev/
[4] tg source code available from:
http://www.free-software-consulting.com/projects/tg/
[5] testgen source code available from:
http://www.uni-weimar.de/cms/fileadmin/medien/medsicherheit/Teaching/SS07/SEfSVS07/programs/testgen.zip
Michael Voelske