Fipsld and C++

This wiki page will cover building a C++ executable program from the command line that statically links to libssl.a and libcrypto.a. When performing a static link against the OpenSSL library, you have to embed the expected FIPS signature in your executable after final linking. Embedding the FIPS signature in your executable is most often accomplished with fisld.

fisld will take the place of the linker (or compiler if invoking via a compiler driver). If you use fisld to compile a source file, fisld will do nothing and simply invoke the compiler you specify through FIPSLD_CC. When it comes time to link, fisld will compile fips_premain.c, add fipscanister.o, and then perform the final link of your program. Once your program is linked, fisld will then invoke incore to embed the FIPS signature in your program.

The procedure requires three minor modifications to fipsld. The modifications will produce fipsld++ that follows the exiting procedures and re-uses the existing components. After fipsld++ is modified, its copied into fips-2.0 with the other FIPS binary components. According to Dr. Henson on the OpenSSL user list, fipsld is not sequestered and can be changed within reason as long as it performs the same basic steps and does not negatively affect the FIPS Object Module or resulting binary.

The example below demonstrates the procedures on Debian 7.3 (x64) using OpenSSL FIPS Capable 1.0.1f and the FIPS Object Module 2.0.5. The example demonstrates Clang and Clang++ with -stdlib=libstdc++. However, the procedures work equally well with GCC and G++ (you omit the -stdlib=libstdc++ for GNU compilers). The modified fisld script also works on Mac OS X 10.8 (be sure to use -stdlib=libc++ rather than libstdc++).

Background

When attempting to link through the compiler driver when the compiler is C++, you will encounter at least two errors due to fips_premain.c:

/tmp/fips_premain-20db15.o: In function `FINGERPRINT_premain()':
/usr/local/ssl/fips-2.0/lib/fips_premain.c:103: undefined reference to `FIPS_text_start()'
/usr/local/ssl/fips-2.0/lib/fips_premain.c:116: undefined reference to `FIPS_incore_fingerprint(unsigned char*, unsigned int)'

If you link with the -Wl,--no-demangle linker flag, you will see the linker is looking for a C++ mangled name because fips_premain.c was compiled with a C++ compiler:

/tmp/fips_premain-be4611.o: In function `_Z19FINGERPRINT_premainv':
/usr/local/ssl/fips-2.0/lib/fips_premain.c:103: undefined reference to `_Z15FIPS_text_startv'
/usr/local/ssl/fips-2.0/lib/fips_premain.c:116: undefined reference to `_Z23FIPS_incore_fingerprintPhj'

The problem occurs because the symbols are declared extern, and not extern "C" in fips_premain.c (from around line 85):

extern const void         *FIPS_text_start(),  *FIPS_text_end();
extern const unsigned char FIPS_rodata_start[], FIPS_rodata_end[];
extern unsigned char       FIPS_signature[20];
extern unsigned int        FIPS_incore_fingerprint(unsigned char *,unsigned int);

fips_premain.c cannot be changed because it is sequestered under the FIPS process. A different method must be used to link a C++ project.

FIPS Object Module

The FIPS Object Module is built in accordance with the steps detailed in the OpenSSL FIPS 2.0 Security Policy. The OpenSSL Foundation also publishes a user guide at User Guide for the OpenSSL FIPS Object Module v2.0. A grossly simplified version is presented below, but the steps are essentially the same as detailed in the guides and on other pages in the wiki.

# Download and verify signature on openssl-fips-2.0.5.tar.gz
$ wget http://www.openssl.org/source/openssl-fips-2.0.5.tar.gz
$ wget http://www.openssl.org/source/openssl-fips-2.0.5.tar.gz.asc
$ pgp openssl-fips-2.0.5.tar.gz.asc 
pgp: Signature made Thu 20 Jun 2013 03:16:19 PM EDT using RSA key ID F295C759
...

# Build and install the FIPS Object Module
$ tar -xzf openssl-fips-2.0.5.tar.gz 
$ cd openssl-fips-2.0.5
$ ./config
$ make
$ sudo make install

# Copy required files missed by 'make install'
$ find . -iname incore
./util/incore
$ sudo cp util/incore /usr/local/ssl/fips-2.0/bin/
$ find . -iname fipsld
./fips/fipsld
$ sudo cp fips/fipsld /usr/local/ssl/fips-2.0/bin/

After the above executes, the FIPS Object Module components will be installed in /usr/local/ssl/fips-2.0 directory. The components include fipscanister.o (and integrity signature), fips_premain.c (and integrity signature), incore and fipsld.

FIPS Capable Library

The FIP Capable Library is a version of OpenSSL that uses the FIPS Object Module. The difference between building the standard library and the capable library is simply a switch to config - the fips switch.

# # Download and verify signature on openssl-1.0.1f.tar.gz
$ wget http://www.openssl.org/source/openssl-1.0.1f.tar.gz
$ wget http://www.openssl.org/source/openssl-1.0.1f.tar.gz.asc
$ pgp openssl-1.0.1f.tar.gz.asc
pgp: Signature made Mon 06 Jan 2014 09:36:10 AM EST using RSA key ID F295C759
...

# Build and install the FIPS Capable Library
$ tar -xzf openssl-1.0.1f.tar.gz
$ cd openssl-1.0.1f/
$ ./config fips shared no-ssl2 <other options>
$ make all
$ sudo make install

After the above executes, the OpenSSL library will be FIPS capable and have static archives and shared objects available. The components will be installed in /usr/local/ssl directory.

The C++ Program

The sample C++ program is named main.cpp and simply enters FIPS mode.

#include <iostream>
using std::cout;
using std::endl;

#include <openssl/evp.h>
#include <openssl/err.h>

int main(int argc, char* argv[])
{
    int rc, mode;

    mode = FIPS_mode();
    if(mode == 0)
    {
        rc = FIPS_mode_set(1);
        if(rc == 0) {
            cout << "Failed to enable FIPS mode, ";
            cout << "error: " << ERR_get_error() << endl;
        } else {
            cout << "Enabled FIPS mode" << endl;
        }
    }
    else
    {
        cout << "Already in FIPS mode" << endl;
    }

    return 0;
}

Build Script

A build script is used to build the sample program. The build script performs the following and is shown below:

• Sets OPENSSLDIR if its empty
• Sets FIPS_SIG to point to incore
• Sets FIPSLIBDIR to point to $OPENSSLDIR/fips-2.0/lib
• Collects C sources in C_SOURCES
• Collects C++ sources in CXX_SOURCES
• Invokes CC on C_SOURCES
• Invokes CXX on CXX_SOURCES
• Collects object files in PROG_OBJECTS
• Sets FIPSLD_CC to point to CXX
• Sets CXX to point to fipsld
• Links with fipsld via CXX

Compiling occurs as normal, and includes -std=c++11 (via CXXSTD) and -stdlib=libstdc++ (via CXXSTDLIB). Linking will still use the compiler driver and CXXFLAGS, but it omits -std=c++11 and -stdlib=libstdc++. Note: if you are building on Mac OS X, you will need to include -stdlib=libc++ when compiling and linking.

#! /bin/bash

################################
# OpenSSL directory

if [ -z $OPENSSLDIR ] && [ -d /usr/local/ssl ]; then
  OPENSSLDIR=/usr/local/ssl
fi

if [ -z "$OPENSSLDIR" ]; then
  echo "Could not locate OpenSSL installation directory"
fi

################################
# Standard build stuff

CC=/usr/local/bin/clang
CXX=/usr/local/bin/clang++

CFLAGS="-Os -g3 -Wall -Wextra"
CXXFLAGS="-Os -g3 -Wall -Wextra"

CXXSTD="-std=c++11"
CXXSTDLIB="-stdlib=libstdc++"

C_SOURCES=`ls *.c 2>/dev/null`
CXX_SOURCES=`ls *.cpp 2>/dev/null`

if [ ! -z "$C_SOURCES" ]; then 
  echo "Compiling C sources..."
    (set -x; $CC $CFLAGS -I$OPENSSLDIR/include $C_SOURCES -c)
fi

if [ ! -z "$CXX_SOURCES" ]; then 
  echo "Compiling C++ sources..."
    (set -x; $CXX $CXXFLAGS $CXXSTD $CXXSTDLIB -I$OPENSSLDIR/include $CXX_SOURCES -c)
fi

################################
# OpenSSL and fipsld

export FIPS_SIG=`find $OPENSSLDIR/fips-2.0 -iname incore 2>/dev/null`
export FIPSLIBDIR=`find $OPENSSLDIR/fips-2.0 -iname lib 2>/dev/null`

export FIPSLD_CC=$CXX
export CXX=`find $OPENSSLDIR/fips-2.0 -iname fipsld++ 2>/dev/null`

if [ -z "$CXX" ]; then
  echo "Could not locate 'fipsld++' in $OPENSSLDIR/fips-2.0"
fi

if [ -z "$FIPS_SIG" ]; then
  echo "Could not locate 'incore' in $OPENSSLDIR/fips-2.0"
fi

if [ -z "$FIPSLIBDIR" ]; then
  echo "Could not locate 'FIPS library directory' in $OPENSSLDIR/fips-2.0"
fi

################################
# Back to linking

PROG_OBJECTS=`ls *.o`

echo "Linking..."
  (set -x; $CXX $CXXFLAGS -o main.exe $PROG_OBJECTS $OPENSSLDIR/lib/libssl.a $OPENSSLDIR/lib/libcrypto.a -ldl)

Be wary of using -Bstatic, -lssl and -lcrypto. The Apple linker will simply ignore your request for static linking if a shared object is available. You will have to use the full archive path or delete the shared objects to ensure static linking. Apple linkers will also ignore rpath's and LD_PRELOAD_PATHs (and sometimes DYLD_INSERT_LIBRARIES), so you will silently link to their 0.9.8 version of the library and subsequently crash for mysterious reasons.

fipsld Modifications

Painting with a broad brush, there are three sections to fipsld. The first one-third or so is configuration, and it does things like locate fipscanister.o and fips_premain.c. The second one-third are steps to build a library or share object. The last one-third are steps to build a stand alone executable.

You have to make three modifications to fipsld, and the modifications generally apply to the last one-third of the fipsld since you are building a executable. If you are building a C++ shared object that statically links to OpenSSL, then you may have to fix the second one-third of fipsld too. Building a shared object that statically links to OpenSSL will encounter additional hardships due to {PREMAIN_DSO} and fips_premain_dso.

To begin, make a copy of fipsld and name it fipsld++.

First Change

Open fipsld++ and find occurrences where fips_premain.c is compiled. It is compiled through the variable {PREMAIN_C}. There are four instances around lines 125, 145, 175 and 195, and they look similar to the following.

${CC}  ${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
    "${PREMAIN_C}" \
    ${_WL_PREMAIN} "$@"

Change the lines so that -x c proceeds "${PREMAIN_C}", and -x none follows it. An example is shown below.

${CC}  ${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
    -x c "${PREMAIN_C}" -x none \
    ${_WL_PREMAIN} "$@"

Forcing C compilation on fips_premain.c applies to all configurations (libraries, shared objects, and executables), so you are safe to apply it to all sections of fipsld++.

If you build now, you will receive an error similar to main.exe is not cross-compiler aware:

:+/usr/local/ssl/fips-2.0/bin/incore ./main.exe
./main.exe is not cross-compiler aware.

The error is due to incore looking for the FIPS_text_startX and FIPS_text_endX symbols, which are not present in this configuration. incore will attempt to use the FIPS_text_start and FIPS_text_end symbols (notice the lack of X), but it needs the -exe switch. The -exe switch is discussed next.

Second Change

To fix the main.exe is not cross-compiler aware error, find occurrences where incore is invoked. incore is invoked through {FIPS_SIG}, and there are 2 instances around line 130 and 180. Fix the second instance around line 180 (you may have to fix the first instance too if building a C++ shared object, but that was not tested). The lines of interest look similar to the following.

if [ "x${FIPS_SIG}" != "x" ]; then
    # embed signature
    "${FIPS_SIG}" "${TARGET}"
    [ $? -ne 42 ] && exit $?
fi

Change the lines so the invocation includes the -exe switch:

if [ "x${FIPS_SIG}" != "x" ]; then
    # embed signature
    "${FIPS_SIG}" -exe "${TARGET}"
    [ $? -ne 42 ] && exit $?
fi

If you build now, you will calculate the expected signature using your program (main.exe below).

:+/usr/local/ssl/fips-2.0/bin/incore -exe ./main.exe
7d0e8dfc1912fca2b02e3e4cc5b0f05ee90fc67d:+[ 0 -ne 42 ]
:+exit 0

But the fipsld++ program exits early so that your compiled program only spews the expected signature:

$ ./main.exe 
669f9b0dfd1654fa0ff49574d988b8bfbd17338f

The program only outputs the expected fingerprint because the program's init was modified to execute FINGERPRINT_premain. FINGERPRINT_premain calculates the fingerprint, prints it to stdout and then exits. A second compilation of fips_premain.c and linking is required to complete the process. The second compilation and linking of fips_premain.c embeds the fingerprint calculated by the first instance and leaves init unchanged. The fingerprint is passed into fips_premain.c via -DHMAC_SHA1_SIG=... preprocessor macro.

Third Change

To fix the early exit of fipsld++, find the second occurrence of [ $? -ne 42 ] && exit $? and delete it. The second instance occurs around line 180 (you may have to fix the first instance too if building a C++ shared object, but that was not tested):

if [ "x${FIPS_SIG}" != "x" ]; then
    # embed signature
    "${FIPS_SIG}" -exe "${TARGET}"
fi

The value 42 is a magic value returned by incore that fipsld uses to determine if and how fipsld should continue. After deleting the second instance of the test, your program will build and run as expected.

Unified Diff

The unified diff between fipsld and fipsld++ is shown below. The lines around 125 and 145 are the one-third of the script that applies to libraries and shared objects. The lines around 170 and 190 are the one-third of the script that applies to executable programs. If you are building a C++ shared object, then you might need to make the changes to both sections of fipsld++ (a C++ shared object was not tested, so the guidance was not provided).

/usr/local/ssl/fips-2.0/bin$ diff -u fipsld fipsld++
--- fipsld	2014-03-09 14:24:55.868366777 -0400
+++ fipsld++	2014-03-10 01:54:26.471892960 -0400
@@ -124,7 +124,7 @@
 
 	/bin/rm -f "${TARGET}"
 	${CC}	${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
-		"${PREMAIN_C}" \
+		-x c "${PREMAIN_C}" -x none \
 		${_WL_PREMAIN} "$@"
 
 	if [ "x${FIPS_SIG}" != "x" ]; then
@@ -143,7 +143,7 @@
 
 	# recompile with signature...
 	${CC}	${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
-		-DHMAC_SHA1_SIG=\"${SIG}\" "${PREMAIN_C}" \
+		-DHMAC_SHA1_SIG=\"${SIG}\" -x c "${PREMAIN_C}" -x none \
 		${_WL_PREMAIN} "$@"
 	;;
 
@@ -172,13 +172,12 @@
 
 	/bin/rm -f "${TARGET}"
 	${CC}	${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
-		"${PREMAIN_C}" \
+		-x c "${PREMAIN_C}" -x none \
 		${_WL_PREMAIN} "$@"
 
 	if [ "x${FIPS_SIG}" != "x" ]; then
 		# embed signature
-		"${FIPS_SIG}" "${TARGET}"
-		[ $? -ne 42 ] && exit $?
+		"${FIPS_SIG}" -exe "${TARGET}"
 	fi
 
 	# generate signature...
@@ -191,7 +190,7 @@
 
 	# recompile with signature...
 	${CC}	${CANISTER_O_CMD:+"${CANISTER_O_CMD}"} \
-		-DHMAC_SHA1_SIG=\"${SIG}\" "${PREMAIN_C}" \
+		-DHMAC_SHA1_SIG=\"${SIG}\" -x c "${PREMAIN_C}" -x none \
 		${_WL_PREMAIN} "$@"
 	;;
 esac

Program Correctness

You can confirm the program executes successfully with the message Enabled FIPS mode:

$ ./main.exe 
Enabled FIPS mode

In addition, there will be no shared object dependencies on libssl or libcrypto:

$ ldd ./main.exe 
    linux-vdso.so.1 =>  (0x00007fff4d5ff000)
    libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f4a81857000)
    libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f4a81550000)
    libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f4a812cd000)
    libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f4a810b7000)
    libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f4a80d2c000)
    /lib64/ld-linux-x86-64.so.2 (0x00007f4a81a72000)

On Mac OS X, otool is the ldd equivalent:

$ otool -L main.exe
main.exe:
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 169.3.0)
    /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 65.1.0)

Downloads

fipsld++.tar.gz - The modified fipsld++ to create stand alone EXEs.