The OpenSAML V2 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

OpenSSL

Owned by Scott Cantor
Last updated: Jun 01, 2018 by Rod Widdowson
5 min read

OpenSSL is a widely used, but occasionally problematic package.

Project website: https://www.openssl.org/ 

Since it's widely used, it generally comes with many systems and builds cleanly on most others, but it can be tricky to build correctly at times, is versioned improperly and inconsistently when it comes to shared libraries, and does not support debug builds on Windows.

The trickiest issue is that on platforms where OpenSSL is not native, you may run into multiple versions and find that different pieces of software used by or with Shibboleth are linked to different versions. This will NOT work, and you will get errors or crashes.

On platforms with a version included with the OS, it is strongly suggested that you stick with that version. If you're relying on mechanisms like the Mac ports project or one of Solaris' many open source initiatives, you will have to use a uniform set of software that is provided by those channels, including things like libcurl and Apache. So it's all or nothing, essentially, don't try and mix things.

Non-Windows

OpenSSL uses a front-end to the autoconf process that sometimes has trouble detecting the right platform and compiler, particularly on Solaris. It's critical to double-check the output of the initial step to make sure it picked the right settings.

A typical command to autodetect the platform might be:

./Configure threads shared

On Solaris, you often have to specify the platform and compiler.

For Sun's compiler:

./Configure solaris-sparcv9-cc threads shared

And for gcc:

./Configure solaris-sparcv9-gcc threads shared

Windows


For the SPV3 documentation. Go to the WindowsBuild page...

To get a command line in VC14 (Visual studio 2015) there is a General Purpose batch file

c:\> C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat x64

or

c:\> C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat x86


On Windows, the docs can be a little sketchy at times, and the default build is essentially broken. It doesn't supply a proper debug build makefile, it doesn't name its libraries so as to avoid version conflicts, and doesn't support any of the native Windows assembly mechanisms for avoiding conflicts. Given that, a compromise is to modify the default makefiles during the build set up process to create versioned library names to avoid conflicts.

My system includes ActiveState Perl. The directions below are for the latest release (1.0.2c at time of writing). A given generation of lettered versions should have been able to share a set of filenames so that you can drop in patched versions at runtime, but this is not holding. They have consistently added entry points to the DLL in lettered releases, which is a violation of any rational versioning policy. So we have gone to 4 digits in the DLL name to prevent problems.

First I configure the package from source as follows (latest version at time of topic creation is shown). These steps generate starting makefiles and DEF files that are customized later.

With the changes made you can run nmake against those makefiles to generate debug and release builds with properly isolated filenames. You'll get an openssl.exe command line linked to them as well. The other big advantage is that you can stick the library path to both out32dll and out32dll.dbg directly in your Visual Studio global library directory list since the link library names are now distinct.

Win32

C:> cd \openssl-1.0.1e
perl Configure VC-WIN32
ms\do_nasm.bat
perl util\mk1mf.pl debug dll nasm VC-WIN32 1>ms\ntdlldebug.mak
copy ms\libeay32.def ms\libeay32d.def
copy ms\ssleay32.def ms\ssleay32d.def

Now edit the DEF files to adjust the module names embedded inside the libraries we're building. The module name is specified near the top in the LIBRARY command. Modify as follows:

  • ms\libeay32.def: LIBEAY32_1_0_2_4
  • ms\libeay32d.def: LIBEAY32_1_0_2_4D
  • ms\ssleay32.def: SSLEAY32_1_0_2_4
  • ms\ssleay32d.def: SSLEAY32_1_0_2_4D

Now modify the default makefiles (ms/ntdll.mak and ms/ntdlldebug.mak) to change output information and adjust some settings. If you're using VS 2005/2008, you have to remove the /WX option from CFLAGS because some warnings are being generated by the compiler.

In ms/ntdll.mak:

  • Edit the O_SSL/O_CRYPTO and L_SSL/L_CRYPTO macros around line 78 or so to reflect the corrected filenames:
    • O_SSL= $(LIB_D)\$(SSL)_1_0_2_4.dll
    • O_CRYPTO= $(LIB_D)\$(CRYPTO)_1_0_2_4.dll
    • L_SSL= $(LIB_D)\$(SSL).lib
    • L_CRYPTO= $(LIB_D)\$(CRYPTO).lib
  • Near the bottom of the file, edit the link commands to set the import library filenames by adding /implib:$(L_CRYPTO) and /implib:$(L_SSL) to the respective links.

In ms/ntdlldebug.mak:

  • Edit the O_SSL/O_CRYPTO and L_SSL/L_CRYPTO macros around line 78 or so to reflect the corrected filenames:
    • O_SSL= $(LIB_D)\$(SSL)_1_0_2_4D.dll
    • O_CRYPTO= $(LIB_D)\$(CRYPTO)_1_0_2_4D.dll
    • L_SSL= $(LIB_D)\$(SSL)D.lib
    • L_CRYPTO= $(LIB_D)\$(CRYPTO)D.lib
  • Near the bottom of the file, edit the link commands that reference the DEF files to refer to the correct debug filenames (LIBEAY32D.DEF and SSLEAY32D.DEF) and set the import library filenames by adding /implib:$(L_CRYPTO) and /implib:$(L_SSL) to the respective links.

Win64

C:> cd \openssl-1.0.1e
perl Configure VC-WIN64A
ms\do_win64a.bat
perl util\mk1mf.pl debug dll VC-WIN64A 1>ms\ntdlldebug.mak
copy ms\libeay32.def ms\libeay32d.def
copy ms\ssleay32.def ms\ssleay32d.def

Now edit the DEF files to adjust the module names embedded inside the libraries we're building. The module name is specified near the top in the LIBRARY command. Modify as follows:

  • ms\libeay32.def: LIBEAY32_1_0_2_4
  • ms\libeay32d.def: LIBEAY32_1_0_2_4D
  • ms\ssleay32.def: SSLEAY32_1_0_2_4
  • ms\ssleay32d.def: SSLEAY32_1_0_2_4D

Now modify the default makefiles (ms/ntdll.mak and ms/ntdlldebug.mak) to change output information and adjust some settings. If you're using VS 2005/2008, you have to remove the /WX option from CFLAGS because some warnings are being generated by the compiler.

In ms/ntdll.mak:

  • Modify the output directories:
    • OUT_D=out64dll
    • TMP_D=tmp64dll
    • INC_D=inc64
    • INCO_D=inc64\openssl
  • Edit the O_SSL/O_CRYPTO and L_SSL/L_CRYPTO macros around line 78 or so to reflect the corrected filenames:
    • O_SSL= $(LIB_D)\$(SSL)_1_0_2_4.dll
    • O_CRYPTO= $(LIB_D)\$(CRYPTO)_1_0_2_4.dll
    • L_SSL= $(LIB_D)\$(SSL).lib
    • L_CRYPTO= $(LIB_D)\$(CRYPTO).lib
  • Near the bottom of the file, edit the link commands to set the import library filenames by adding /implib:$(L_CRYPTO) and /implib:$(L_SSL) to the respective links.

In ms/ntdlldebug.mak:

  • Modify the output directories:
    • OUT_D=out64dll.dbg
    • TMP_D=tmp64dll.dbg
    • INC_D=inc64
    • INCO_D=inc64\openssl
  • Edit the O_SSL/O_CRYPTO and L_SSL/L_CRYPTO macros around line 78 or so to reflect the corrected filenames:
    • O_SSL= $(LIB_D)\$(SSL)_1_0_2_4D.dll
    • O_CRYPTO= $(LIB_D)\$(CRYPTO)_1_0_2_4D.dll
    • L_SSL= $(LIB_D)\$(SSL)D.lib
    • L_CRYPTO= $(LIB_D)\$(CRYPTO)D.lib
  • Near the bottom of the file, edit the link commands that reference the DEF files to refer to the correct debug filenames (LIBEAY32D.DEF and SSLEAY32D.DEF) and set the import library filenames by adding /implib:$(L_CRYPTO) and /implib:$(L_SSL) to the respective links.

Windows.  OpenSSL Versions > 1.1

This section is under construction. OpenSSL versions greater than 1.1 are not currently support by OpenSAML or Shibboleth

The Windows build in Version 1.1 is changed somewhat.  Notably

  • Configure has implicit support for debug builds by prepending 'debug-' in front of the target (VC-WIN64A or VC-WIN32)
  • The build is two step (configure, make).
  • The output LIBs and DLLs have been renamed and carry some versioning information (from SSLEAY32 and LIBEAY32 to LIBCRYPTO-<Maj>_<Min> and LIBSSL-<Maj>_<Min>)
  • The 64 bit libraries and DLLs (needlessly) carry a postfix indictaing their architecture (libcrypto-1_1-x64.dll)
  • The include directory is not created as a part of the build. Rather the include directories are always available, with the notable exception of opensslconf.h - which differs between architecture and between configuration (Debug vs Release)

It appears that this can simplify the build process.  If we copy the results and include file into an appropriate tree after each build the only intervention needed is to change the name of the debug libs and dlls.  This appears to be simply achievable with a small change to the Configure  perl script.

Building the Debug Configure script

  • Copy the Configure perl script to ConfigureD
  • Edit this new file:

  • Find where $config{shlib_minor}  is set up (from the contents of opelsslv.h):

    ($config{shlib_major}, $config{shlib_minor})
    = ($config{shlib_version_number} =~ /^([0-9]+)\.([0-9\.]+)/);

  • Add a line to append the "D" to the minor version.  

    $config{shlib_minor} = $config{shlib_minor}."D";

the .lib files do not carry any garnish, being called libssl.lib and libcrypto.lib in both the debug and release builds

WIn32

  • Perform the release build: 
c:\ cd /d h:\openssl1.1
perl Configure VC-WIN32 --prefix=h:\openssl1.1\x86
nmake install_sw


  • Clean the build and configure and build the debug build


nmake distclean
perl ConfigureD debug-VC-WIN32 --prefix=h:\openssl1.1\x86Debug
nmake install_sw


Win64

Win64 is done much as Win32, (starting from an x64 build prompt)

nmake distclean
perl ConfigureR VC-WIN64A --prefix=h:\openssl1.1\x64
nmake install_sw
nmake distclean
perl ConfigureD debug-VC-WIN64A --prefix=h:\openssl1.1\x64Debug
nmake install_sw

The build has been automated in the cpp-msbuild project.