There are several different ways to build SSLeay. There is a traditional multi-level Makefile approach which generates static libraries. A second system is single Makefile which builds static libraries (or DLLs under Windows); and finally the library can be built via a single file that includes all the component files.
Building SSLeay
Before any compilation is attempted, it is generally a good idea to configure SSLeay to take maximum advantage of the compiler and the host architecture. This can be done automatically by using the Configure perl script, or manually if perl is not installed. It should be remembered that this configuration stage is optional. If it is not performed, SSLeay will still compile but the performance of CPU intensive sections will probably be far from optimal. To run the Configure script just type
perl Configure [options] <system>
If no system is specified, a list of pre-configured options is listed. Choose
the one that best suits your system. The options (which only really affect
compilation in the Unix environment) are extra -L, -l
or -D options for the compilation and linking. So to configure
SSLeay to be built using the SunC v 4 on a Solaris 2.5 ultra sparc, any of the
following options could be used:
perl Configure -lnsl -lsocket cc
perl Configure solaris-sparc-cc
perl Configure solaris-sparc-sc4
perl Configure solaris-usparc-sc4
More CPU and compiler specific options are being turned on with the increasing resolution of the target system. If for some reason you do not have perl installed or your system is not specified, the options can be configured by hand. There are also other SSLeay compilation options that you may want to add. Just edit the relevant lines at the top of the top level Makefile.ssl
The following options are set modified by the configuration script are used to tweak the various ciphers. Some options improve performance, others will reduce it. It is a bit of a black art and which options to use are normally best decided by trial and error. The best options to use are normally dependant on a combination of compiler and CPU, so just because a particular option works well when using gcc does not mean it will work well with the vendor compiler. If you are not particularly interested in changing these options, skip to the next section.
crypto/des/des_locl.h
DES_PTR
: The array lookup version of DES is the default. This option
uses pointer arithmetic to access various tables. Use this option on 64 bit
computes with care. You will probably need to use the DES_INT
option in conjunction.
DES_RISC1/DES_RISC2
: There are 3 different versions of the inner loop
logic. These two variants often produce faster code on RISC processors.
DES_RISC2 is optimal for most x86 compilers
DES_UNROLL
: Normally the DES inner loop is unrolled 4 times. This
option unrolls it to the full 16 rounds. This option causes a slow down on some
processors.
crypto/des/des.h
DES_INT
: By default, the DES algorithm uses unsigned
longs to hold 4 byte. For machines with 64 bit longs, this
sometimes it improves performance.
BN_LLONG
: The big number library has been built so that it is not
dependent on any particular machine word size. If this option is defined, it
means that there is available a data type that is two times larger than the word
size that is going to be used. The word size can be 64, 32, 16 or 8 bits.
SIXTY_FOUR_BIT_LONG
: This option should be used on machines where the
long data type is 64 bits in size and there does not exist a 128
bit data type. This is the case for the DEC Alpha.
SIXTY_FOUR_BIT
: This option should be used when there is both a 64 bit
long data type and a 128 bit 'long long'. I have not yet seen a compiler that
supports this configuration but I live in hope.
THIRTY_TWO_BIT
: This is the normal build configuration.
SIXTEEN_BIT
: When your CPU is 16bit, go with this one.
EIGHT_BIT
: This option has mostly been used for testing new algorithms
since it makes it much easier to test word overflow conditions.
Only one of the 5 possible word sizes should be defined.
crypto/md/md2.h
MD2_CHAR/MD2_LONG
: These two options are variations from the standard
'int' used to hold intermediate values in the MD2
algorithm.
crypto/idea/idea.h
IDEA_SHORT/IDEA_LONG
: Two variations on the standard 'int' used to
hold internal data values in the IDEA cipher.
crypto/rc2/rc2.h
RC2_SHORT/RC2_LONG
: Two variations on the standard 'int' used to hold
internal data values in the RC2 cipher.
crypto/rc4/rc4.h
RC4_CHAR/RC4_LONG
: Two variations on the standard 'int' used to hold
internal data values in the RC4 cipher
crypto/rc4/rc4_locl.h
.
RC4_INDEX
: This option makes the RC4 code use pointer arithmetic
instead of array lookups
crypto/bf/bf_locl.h
BF_PTR/BF_PTR2
: Two pointer arithmetic variations for the blowfish
inner loop.
For all these options, the PTR variants, which use pointer arithmetic instead of array indexing, will probably have problems moving to a 64bit environment. When experimenting with these options on a new machine, start with the default options and then start playing.
The standard way to build SSLeay on a Unix operating system is to use the multi-level makefile system. This system is designed primarily to make code development easy since a 'make' typed in any sub-directory will perform a make operation on that directory but using the options from the top level makefile.
The Makefiles for each directory are contained in the file called Makefile.ssl. Normally there will be a symbolic link so that Makefile will point at Makefile.ssl. To change various compile options, edit the top level Makefile.ssl. At the start of the makefile there are the options of interest
CC
: the C compiler to use.
CFLAG
: The C compiler flags
EX_LIBS
: Extra libraries to link with.
BN_MULW
: The file containing the inner big-number functions.
DES_ENC
: The file containing the inner DES function.
BF_ENC
: The file containing the inner Blowfish function.
DIRS
: The directories to 'walk' into when doing a make.
SDIRS
: The directories in the 'crypto' directory to 'walk' into when
doing a make.The Configuration script sets most of these options. The BN_MULW,
DES_ENC and BF_ENC options are used to replace C code with
assembler code versions. Any extra constants that need to be defined during the
build should be added to the CFLAG option.
As an example, if you wish to compile the library to use the RSAref library on a solaris box, you would set
CFLAG= -DRSAref
EX_LIBS= -lRSAglue -lrsaref -lnsl -lsocket
Options that are useful include
NOCONST
: Build without using the 'const' key-word, this is needed for
older compilers like the system compilers supplied with HP-UX and
SunOS
NOPROTO
: Build without prototypes. Old compilers often hate
them.
RSAref
: Don't use SSLeay's built in RSA implementation, rather, use
the RSAref toolkit. When built with this option, the application needs to be
linked with the RSAglue and RSAref libraries. The RSAref toolkit is not supplied
with SSLeay but it offers inferior performance and the only rational for using
it is USA software patents.
THREADS
: This key-word is used when compiling a multi-threaded version
of SSLeay for use on systems that define the gmtime_r() function.
The only system I current am aware of supplying this function is Solaris.
Basically don't worry about this option unless you are compiling for
multi-threading on solaris.
TERMIO, TERMIOS, SGTTY
: Buried down in the DES library is a function
that turns off terminal echo and reads a password from a terminal. There are
three different system in popular use on Unix system for turning off terminal
character echo. The default system is defined by SGTTY. SGI is
normally TERMIOS and everyone else seems to be TERMIO.
Don’t use these defines normally since the library make a reasonable effort to
guess the correct option. Experiment with this option if you get compile time
errors from crypto/des/read_pwd.c or you see you password on-screen
when it should no be appearing.
DEVRANDOM
: On Linux and FreeBSD systems, consider setting this option.
For Linux, -DDEVRANDOM=/dev/urandom should do the trick. The
DEVRANDOM device should be a source of random data. If it is
present, the SSLeay library will read 32 bytes from the device at startup to
seed its own internal random number state machine. On systems that contain both
/dev/random and /dev/urandom, use
/dev/urandom since this should be a non-blocking device so if the
random data is not available, the program will not wait for it to become
available.
SSL_ALLOW_ADH
: By default, the anonymous Diffie-Hellman ciphers are
not compiled into SSLeay. hey offer no authentication, only encryption, so they
are vulnerable to man in the middle attacks. If SSLeay is compiled with
NO_RSA defined, this option is automatically turned on. There is
nothing inherently wrong with these ciphers, but they have been left out by
default to protect those who just build the library without thinking about which
ciphers are present and how secure/insecure they are.
SSL_ALLOW_ENULL
: By default, the ciphers that only perform
authentication, but no encryption are disabled. To enable them, this option
needs to be defined. While authentication only ciphers have a use, this default
setup has been put in place to protect the unwary.
LOCK_DEBUG
: This option will not be used very often and is primarily
intended to help debug the SSLeay library when compiled for multi-threading.
When compiled with this option, large amounts of locking debug information are
printed to stderr. This define only affects the behaviour of
crypto/cryptlib.c.
MFUNC
: When defined, causes all malloc(),
realloc() and free() calls in the SSLeay library to
call CRYPTO_malloc(), CRYPTO_realloc() and
CRYPTO_free(). When compiling for Win32 (Windows 95 and NT), this
option is always turned on. CRYPTO_set_mem_functions() can be used
to specify application defined callbacks to be used to provide the memory
allocation functionality. This functionality is present for two reasons.
Multi-threading on Unix systems that do not have thread safe memory allocation
routines, and Win32. When compiling DLLs under WIN32, there are three possible C
libraries to link the DLLs against. If the SSLeay library is linked against a
different one to the application, data allocated inside SSLeay cannot be
deallocated without cause the application to crash. Under Win32,.the application
can call the CRYPTO_malloc_init() macro which will make the SSLeay
library use the same memory allocation functions as the application and so
avoids this problem.
CRYPTO_MDEBUG
: When this option is defined, an alternative set
of CRYPTO_malloc() functions are called by the SSLeay library.
These alternative functions keep track of memory allocation. The
CRYPTO_mem_leaks() family of function can be used to detect memory
leaks. This define is normally used during development, not in production
code.
REF_CHECK
: This option, when defined, causes additional checks to be
made when various SSLeay data structures are deallocated. Most SSLeay data
structures contain reference counts that are incremented when the structure is
shared and decremented when it is freed. If this option is defined, and an
attempt is made to free an object with a reference count of zero, an error
message is printed to stderr and abort() is called.
This will stop the program but it considering that the program was just about to
corrupt its memory, this is not a bad thing. This will not always pick up the
reference count problems, since it will only detect zero reference counts if the
freed memory has not yet been overwritten.
L_ENDIAN, B_ENDIAN
: These two defines specify the native byte order
for the host CPU. These defines are not required and are more advisory in
nature. They are used in the various digest algorithms to provide byte order
swapping optimising. For some CPU/compiler combinations, they actually slow the
digests down. Experiment to determine if they are worth using.
: Define any of these and the relevant cipher will not be
normally used. The cipher will still be compiled but will not be linked. To stop
the cipher being compiled, remove the directory entry from the SDIR
define in the top level Makefile.ssl. The application can still reinsert the
relevant cipher into the SSL library via the EVP_add_cipher()
function. Look at the 'build with one Makefile' section for details on how to
build SSLeay with unneeded ciphers completely left out of the build
process.
NO_MD2, NO_MD5, NO_SHA, NO_SHA1, NO_MDC2
: Build without these message
digests. Use EVP_add_digest() to put them back.
NO_RSA
:..Build SSLeay without RSA support.
NO_DSA
: Build SSLeay without DSA support.
NO_DH
: Build SSLeay without Diffie-Hellman (DH) support.
NO_SSL2
: Build SSLeay so that SSLv2 is not present.
NO_SSL3
: Build SSLeay so that SSLv3 is not present.
NO_ERR:
Build SSLeay so the error system is much 'lighter'. This build
the library system so that the error system does not contain the error strings,
line number or file names. It will still report the correct error number. This
means that if you have a copy of the errstr command that has not
been compiled with NO_ERR, you can still get a textual
representation of the error message.
NO_SOCK:
Build SSLeay for systems that do not support BSD
sockets.Quite a few of these options will not work correctly when it comes time to
build the ssleay application in the apps directory.
The best rule of thumb is to not use any of the NO_XXX defines when
compiling using the multi-level makefile system. Use them when compiling with a
single makefile generated via util/mk1mf.pl. The cipher and digest
disabling functions should always work.
An alternative way to build SSLeay is to use a single makefile generated by
the util/mk1mf.pl perl script. This is the primary way to build
SSLeay in the windows environment. It is actually quite simple, run the
util/mk1mf.pl perl script and redirect the output into a makefile.
The only complication is that perl is required to run the script. Options to
mk1mf.pl modify the behaviour.
The following options modify the makefile and the system being compiled for. The default mk1mf.pl output is a makefile to use on any Unix which has a C compiler called cc.
VC-WIN32: Build a makefile for Visual C (4.x or 5.0) to build for win32 (Windows 95 or NT).
VC-WIN16 or VC-W31-32: Build with Visual C 1.52c, targeted for Windows 3.x, on processors that can support 32 bit instructions (386+).
VC-W31-16: Build with Visual C 1.52c, targeted for Windows 3.x on processors that do not support 32 bit instructions (286)
VC-MSDOS: Build for MS-DOS using Visual C 1.52c.
FreeBSD: Build a makefile for FreeBSD Unix.
The following options change the way the library is build and normally specify various defines which affect the building of the library. See the section on options to conditionally compile with out various ciphers.
RSAref
: Build SSLeay to use RSA Inc's RSAref library. This is required
in the USA to avoid violating the RSA software patent.
gcc
: Build using gcc instead of cc.
debug
: Make the makefile generate a debug version of the
libraries.
dll
: Make a makefile that will generate a DLL. This currently only
works under Windows.
no-rc2, no-rc4, no-idea, no-des, no-bf, no-md2, no-md5, no-sha, no-sha1,
no-mdc2
: Disable the matching cipher/digest. These options relate very
much to the defines
specified earlier, except that when building using one makefile, the files
containing the ciphers/digests will not be compiled. There are a few
dependancies that are mostly taken care of by mk1mf.pl (mdc2 is dependant on
DES, SSLv3 requires both sha1 and md5) and there must always be at least one
message digest algorithm defined for the random number library.
no-rsa, no-dsa, no-dh
: Disable various public key
algorithms.
no-ssl2, no-ssl3
: Build without support for the relevant SSL
versions.
no-err
: This option builds the library with out the error string. It
reduces the size of DLLs but errors now report error numbers instead of
meaningful (to some) error messages. If a version of ssleay is kept
that has been compiled without this option, errstr can be used to
convert the error number to an error string. Be warned though. Due to the way
error number are generated, they can change between SSLeay versions.
no-sock
: Mostly for MS-DOS builds, compile with no socket code. The
SSL libraries will still be built since they use and IO interface that does not
depend on sockets.
no-asm
: The main reason for all the different VC_XXX machine options
is to facilitate the use of assembler functions to improve various cipher
performance. If this option is used, no assembler code will be used in the
makefile generated by the Microsoft builds.
CC=<compiler>
: This causes the generated makefile to use
<compiler> as the compiler. This function has no affect when generating a
makefile for the Microsoft platforms.
SRC=<source code directory>
: The generated makefile will have
all source code paths relative to this directory.
OUT=<output directory>
: By default, the finished programs and
libraries are placed in the out directory. This function causes them to be
placed in an alternative directory. At the end of a build, this directory
contains the ssleay program, the various testing programs, the two libraries and
the header files of interest to other programs.
TMP=<temporary directory>
: All the intermediate object and local
header files go in here. Delete this directory to cleanup.
BIN=<path>
: Where to find cc, link etc.
-L<path> -l<lib>
: When specified, these options are added
to the compiler link phase.
-<any other cc option>
: Any other option starting with a
'-' is assumed to be a C compiler option. In the Microsoft world,
these options are added to the ones mk1mf.pl has supplied, and in the Unix
world, if there are any options defined, the mk1mf.pl supplied ones are dropped and
replaced.Once a makefile has been generated in the Unix world, is assembler code is required, edit the makefile directly. It is reasonable clear where to do this. The preferred system used to build under Unix is the multi-level makefile.
The makefile generated from this step actually has one build target that is very useful in all SSLeay build environments:
make -f makefile.one headers
This will copy all the global and local headers into the relevant directories. When attempting to build SSLeay in integrated debuggers via the 3 file method, this is a useful function. The FLAT_INC define causes the removal of all relative directory references in the #include directives in the SSLeay library and should be used in conjunction with the all header files in one directory builds (automatically used by mk1mf.pl).
The last way to build SSLeay is as 3 files. One for each library and one for the ssleay program. If assembler code is being used, various options need to be defined. Have a look in the shlib directory for example code to build shared libraries for various platforms using this system. As a compiler workout, try (under Unix)
perl Configure <machine type> make -f makefile.one headers cc -O -Iout -Itmp -o ssleay crypto/crypto.c ssl/ssl.c apps/eay.c
To improve performance, assembler code is available for quite a few ciphers. Normally an assembler code file is available as a replacement for a C one. If the assembler does not work on a particular platform, just revert back to the C version. When using the multi level makefile, just edit the top level makefile to specify with assembler files to use. The configure perl script will normally do the correct configuration. There is assembler code for the inner big-number function, which improves the performance of the RSA,.DSA and DH ciphers. It is important to compile with the correct big-number word size to match the assembler code. The DES and Blowfish functions also have assembler version of their inner loops for x86 architecture machines.
crypto/bn/bn_mulw.c
: The assembler versions are found in
crypto/bn/asm. Quite a few of these are just the output from gcc -S
since often gcc produced code that was two times faster than the native compiler
(this is because when using the long long data type, gcc generates
inline code, most system compilers generate function calls).
crypto/des/des_enc.c
: The DES inner loop. The assembler is in
crypto/des/asm.
crypto/des/fcrypt_b.c
: Unix crypt(), The assembler is found in
crypto/des/asm.
crypto/bf/bf_enc.c
: The Blowfish inner loop. The assembler is found in
crypto/bf/asm.Building without RSA or RC4/RC2
To build without using any patented algorithms inside the USA, use the single makefile build system but generate the makefile with the following options:
perl util/mk1mf.pl no-rc2 no-rc4 no-idea no-rsa >no-rsa.mak
This will compile the library so that non of the rc2, rc4, idea or rsa code is compiled. Because there is no RSA code, there will also be no SSLv2.
Be warned, if the library is built with NO_RSA defined, the anonymous DH ciphers will be enabled.
Building under linx-elf
# build via the normal muli-level makefile system. perl Configure linux-elf make # Build shared libraries perl Configure linux-elf make -f makefile.one headers sh shlib/linux.sh # Build via one makefile perl Configure linux-elf perl util/mk1mf.pl gcc -O3 >linux.mak # NOTE - quite a lot of optimising flags will have been left out of the # makefile and no assember will be used unless extra editing of linux.mak # is performed. # Build a version for USA consuption perl configure linux-elf -DRSAref -L/usr/local/lib -lrsaref make # this version will still contain the SSLeay RSA functions, and the # application will be able to decided at run time which library it # uses.
To build DLLs under Windows NT using Visual C
perl Configure VC-WIN32 nmake -f ms\ntdll.mak # ms\ntdll.mak and md\w31dll.mak are pre-generated. # build a debug static library under windows 3.1 perl Configure VC-WIN16 perl util\mk1mf.pl VC-WIN16 debug OUT=debug >debug.mak nmake -f debug.mak
It is very important to either run the configuration script when building under Windows 3.1, or edit crypto/bn/bn.h to make sure the assembler big-number word size matches the C code.
After building SSLeay, one should always run the test scripts. For Unix, when using the multi-level makefile system,
make test
does the trick. Under Windows,
cd ms test
runs the test scripts. Unfortunately the windows test scripts expect the
relevant programs to be located in ..\out.
If you have a test fail, try rebuilding the library with optimising turned off. There are known bugs in some AIX compilers.