FIPS Library and Android - Revision history

Jwalton: Add info on sourcing.

2019-12-03T07:23:30Z

Add info on sourcing.

Jwalton: Formatting.

2016-10-03T20:48:46Z

Formatting.

Jwalton: Improved flow.

2016-10-03T20:41:25Z

Improved flow.

Jwalton: Improved flow.

2016-10-03T20:38:30Z

Improved flow.

Jwalton: Improved flow.

2016-10-03T19:33:48Z

Improved flow.

Jwalton: Added example wrapper code.

2016-10-03T19:20:56Z

Added example wrapper code.

Jwalton: Change "-no-XXX" to "no-XXX". How long has that mistake festered....

2015-01-07T20:15:20Z

Change "-no-XXX" to "no-XXX". How long has that mistake festered....

Jwalton: Finished removing references to non-FIPS workaround.

2014-07-11T23:07:18Z

Finished removing references to non-FIPS workaround.

Jwalton: Added link to Android (non-FIPS) article.

2014-07-11T23:06:08Z

Added link to Android (non-FIPS) article.

Jwalton: Added info on _ANDROID_ARCH.

2014-07-11T20:31:35Z

Added info on _ANDROID_ARCH.

← Older revision		Revision as of 07:23, 3 December 2019
Line 6:		Line 6:

	This guide is intended to be informative and easy to use. In case of discrepancies between this document and the OpenSSL FIPS Security Policy, the Security Policy will prevail. You can download the Security Policy from http://www.openssl.org/docs/fips/.		This guide is intended to be informative and easy to use. In case of discrepancies between this document and the OpenSSL FIPS Security Policy, the Security Policy will prevail. You can download the Security Policy from http://www.openssl.org/docs/fips/.
		+
		+	The script <tt>setenv-android.sh</tt> is sourced. Sourcing ensures the variables set in the script are available to other scripts that are run later in the process. If you shell does not provide the source command, then use <tt>. ./setenv-android.sh</tt> (note the leading dot).

	The instructions that follow depend upon a properly configured Android NDK and SDK. The NDK is used to compile programs and link the OpenSSL library; while SDK tools are used to push programs to a device. Be sure <tt>ANDROID_NDK_ROOT</tt> and <tt>ANDROID_SDK_ROOT</tt> are set properly, and the SDK's tools and platform-tools are available.		The instructions that follow depend upon a properly configured Android NDK and SDK. The NDK is used to compile programs and link the OpenSSL library; while SDK tools are used to push programs to a device. Be sure <tt>ANDROID_NDK_ROOT</tt> and <tt>ANDROID_SDK_ROOT</tt> are set properly, and the SDK's tools and platform-tools are available.

@@ Line 235: / Line 235: @@
 The command below compiles fips_hmac.c using ANDROID_SYSROOT and the shared object (libcrypto.so). ANDROID_SYSROOT specifies the location of Android's headers and libraries, and is set using setenv-android.sh.
-<pre>$ arm-linux-androideabi-gcc --sysroot="$ANDROID_SYSROOT" -I/usr/local/ssl/android-14/include fips_hmac.c \
+<pre>$ arm-linux-androideabi-gcc --sysroot="$ANDROID_SYSROOT" -I/usr/local/ssl/android-14/include \
-   -o fips_hmac.exe /usr/local/ssl/android-14/lib/libcrypto.so</pre>
+   fips_hmac.c -o fips_hmac.exe /usr/local/ssl/android-14/lib/libcrypto.so</pre>
 There's no need to run fipsld on a program which dynamically links to the OpenSSL library.

@@ Line 330: / Line 330: @@
 == Miscellaneous ==
 Once the FIPS Object Module and FIPS Capable Library are installed, you can safely delete the source directories. The headers, libraries and programs (such as fipsld and incore) are located in sub-directories of <tt>/usr/local/ssl/<platform></tt>.
 If you don't care about FIPS 140-2 and just want to build the library for Android, then see [[Android|OpenSSL and Android]].
 The NDK supplies headers for each major platform - for example, API 18, API 14, API 9, API 8, and API 5. If you are building for Android 4.2 (API 17), Android 4.1 (API 16) and Android 4.0 (API 14), then you would use the NDK's API 14 (android-14 platform).
@@ Line 340: / Line 346: @@
 Some versions of the Android Java system loader will load the system's version of the OpenSSL library, even though you built and included a copy with your application. In this case, you might need to write a wrapper shared object and link to the static version of the OpenSSL library. See, for example, ''[https://groups.google.com/forum/#!topic/android-ndk/rAf5tt4UEug "Unable to find native library" error in Native Activity app]''.
 If you compile with -fPIE and -pie, then you will core dump unless using Android 4.1 and above. Logcat shows the linker (/system/bin/linker) is the problem.
@@ Line 350: / Line 352: @@
 [1] - Segmentation fault   ./fips_hmac.exe -v fips_hmac.exe</pre>
-When building the FIPS Capable library for Android, take care to specify <tt>-mfloat-abi=softfp</tt>. If you specify <tt>-mfloat-abi=hard</tt> or <tt>-mhard-float</tt> (even if the hardware support a floating point unit), then the entropy estimate passed through the Java VM to <tt>RAND_add</tt> will always be 0.0f. See [https://groups.google.com/d/msg/android-ndk/NbUq9FDDZOo/TJJsAS6nM7wJ Hard-float and JNI] for details.
+When building the OpenSSL library for Android, take care to specify <tt>-mfloat-abi=softfp</tt>. If you specify <tt>-mfloat-abi=hard</tt> or <tt>-mhard-float</tt> (even if the hardware support a floating point unit), then the entropy estimate passed through the Java VM to <tt>RAND_add</tt> will always be 0.0f. See [https://groups.google.com/d/msg/android-ndk/NbUq9FDDZOo/TJJsAS6nM7wJ Hard-float and JNI] for details.
 == Downloads ==

@@ Line 291: / Line 291: @@
 == Wrapper Shared Objects ==
-Using OpenSSL on Android often involves JNI. The platform likely loaded the system's version of OpenSSL or BoringSSL's <tt>libssl.so</tt> and <tt>libcrypto.so</tt> at boot during Zygote initialization. Due to issues with the loader and symbol resolution, the LD_LIBRARY_PATH trick doesn't work for normal applications. And changing the build to output different library names to avoid clashes does not work, either.
+Using OpenSSL on Android often involves JNI and the platform's version of OpenSSL or BoringSSL. The platform likely loaded the system's version of <tt>libssl.so</tt> and <tt>libcrypto.so</tt> at boot during Zygote initialization. Due to issues with the loader and symbol resolution, customary <tt>LD_LIBRARY_PATH</tt> tricks do not work for most applications. And changing the build to output different library names, like <tt>libmyssl.so</tt> and <tt>libmycrypto.so</tt>, to avoid clashes does not work either.
-The solution to the namespace and symbol prolems is to wrap the '''''static''''' library in a separate '''''dynamic''''' library or shared object. To do so, write a short C wrapper library with references to functions you need from the OpenSSL library. You don't need to wrap all the functions.
+The solution to the namespace and symbol resolution problems is to wrap the '''''static''''' version of the OpenSSL library in a separate '''''dynamic''''' library or shared object provided by you. To do so, write a small C wrapper library with references to functions you need from the OpenSSL library. You don't need to wrap all the functions.
 Your <tt>wrapper.c</tt> might look as follows (also see GCC's [http://gcc.gnu.org/wiki/Visibility Visibility page]):
@@ Line 317: / Line 317: @@
 ...</pre>
-Then, compile with both <tt>-fvisibility=hidden</tt> and <tt>-Wl,--exclude-libs,ALL</tt> flags and link against <tt>libcrypto.a</tt> and <tt>libssl.a</tt>.
+Then, compile the source file into a shared object. A typical command line might look as follows.
 <pre>$ export OPENSSL_ANDROID = /usr/local/ssl/android-14
@@ Line 323: / Line 323: @@
 -Wl,-Bstatic -lcrypto -lssl -L$(OPENSSL_ANDROID)/lib -o wrapper.so -Wl,-Bdynamic</pre>
-<tt>-fvisibility=hidden</tt> works as you expect, and  <tt>-Wl,--exclude-libs,ALL</tt> means your library does not re-export other linked library symbols. Only the functions marked with <tt>DLL_PUBLIC</tt> will be exported and callable through JNI.
+<tt>-fvisibility=hidden</tt> works as you expect, and <tt>-Wl,--exclude-libs,ALL</tt> means your library does not re-export other linked library symbols. Only the functions marked with <tt>DLL_PUBLIC</tt> will be exported and callable through JNI.
 The <tt>-Wl,-Bstatic</tt> tells the linker to use the static version of the OpenSSL library for the Library. After it and the <tt>-Wl,-Bdynamic</tt> tells the linker to use dynamic linking for anything else it might need, like <tt>libc</tt>.
-Using <tt>-Bstatic</tt> and <tt>-Bshared</tt> can cause link problems on occasion. For example, see [http://stackoverflow.com/questions/22667953/error-when-trying-to-compile-wrapper-for-openssl-library-libcrypto-a Android: error when trying to compile wrapper for openssl library libcrypto.a]. To avoid the problem with the linker, specify the full path to the static archive (for example, <tt>/usr/local/ssl/android-14/lib/libcrypto.a</tt>). If you suspect the wrong OpenSSL library is being linked, then use the fully qualified archive path.
+Then use your shared object in place of OpenSSL.
 == Miscellaneous ==

@@ Line 291: / Line 291: @@
 == Wrapper Shared Objects ==
-In the real world, you probably aren't using C and therefore still need a dynamic library, but Android probably already has OpenSSL or BoringSSL's <tt>libssl.so</tt> and <tt>libcrypto.so</tt> loaded into memory.  Due to issues with the Android Zygote and the loader, the LD_LIBRARY_PATH trick doesn't work for normal applications. Changing the build to output different names to avoid the namespace clash does not work.
+Using OpenSSL on Android often involves JNI. The platform likely loaded the system's version of OpenSSL or BoringSSL's <tt>libssl.so</tt> and <tt>libcrypto.so</tt> at boot during Zygote initialization. Due to issues with the loader and symbol resolution, the LD_LIBRARY_PATH trick doesn't work for normal applications. And changing the build to output different library names to avoid clashes does not work, either.
-The solution to getting the code into a differently-named shared library is to wrap up the static Library into a separate dynamic library. To do this, write a short c wrapper library with references to functions in both the Library (so the linker doesn't discard them as unnecessary) and link the static Library as above.  You don't need to wrap all the functions, as the Library themselves become part of the interface. For these instructions, I'll assume your c file is called wrapper.c
+The solution to the namespace and symbol prolems is to wrap the '''''static''''' library in a separate '''''dynamic''''' library or shared object. To do so, write a short C wrapper library with references to functions you need from the OpenSSL library. You don't need to wrap all the functions.
-Your <tt>wrapper.c</tt> might look as follows to avoid shared object name and symbol clashes (also see GCC's [http://gcc.gnu.org/wiki/Visibility Visibility page]):
+Your <tt>wrapper.c</tt> might look as follows (also see GCC's [http://gcc.gnu.org/wiki/Visibility Visibility page]):
 <pre>#if __GNUC__ >= 4
@@ Line 317: / Line 317: @@
 ...</pre>
-Then, compile with the <tt>-fvisibility=hidden</tt> flag and link against <tt>libcrypto.a</tt> and <tt>libssl.a</tt>. Only the functions marked with <tt>DLL_PUBLIC</tt> will be exported and callable through JNI.
+Then, compile with both <tt>-fvisibility=hidden</tt> and <tt>-Wl,--exclude-libs,ALL</tt> flags and link against <tt>libcrypto.a</tt> and <tt>libssl.a</tt>.
 <pre>$ export OPENSSL_ANDROID = /usr/local/ssl/android-14
-$ $(CC) wrapper.c -fPIC -shared -I$(OPENSSL_ANDROID)/include -fvisibility=hidden -Wl,-Bstatic -lcrypto -lssl -L$(OPENSSL_ANDROID)/lib -o wrapper.so -Wl,-Bdynamic</pre>
+$ $(CC) wrapper.c -fPIC -shared -I$(OPENSSL_ANDROID)/include -fvisibility=hidden -Wl,--exclude-libs,ALL \
 The <tt>-Wl,-Bstatic</tt> tells the linker to use the static version of the OpenSSL library for the Library. After it and the <tt>-Wl,-Bdynamic</tt> tells the linker to use dynamic linking for anything else it might need, like <tt>libc</tt>.

@@ Line 43: / Line 43: @@
 $ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org
-$ ./config fips shared -no-ssl2 -no-ssl3 -no-comp -no-hw -no-engine --openssldir=/usr/local/ssl/$ANDROID_API \
+$ ./config fips shared no-ssl2 no-ssl3 no-comp no-hw no-engine --openssldir=/usr/local/ssl/$ANDROID_API \
    --with-fipsdir=/usr/local/ssl/$ANDROID_API --with-fipslibdir=/usr/local/ssl/$ANDROID_API/lib/
@@ Line 189: / Line 189: @@
 The FIPS Capable Makefile (and Makefile.org) needs its install rule modified. The install rule includes the all target, which causes items to be built during install. A bug in the process when running as root results in an empty signature for the shared object (the signature is a string of zeros).
-To build the FIPS Capable library, you must issue config fips, but other options are up to you. Some suggested options for configure include: shared, -no-ssl2, -no-ssl3, -no-comp, -no-hw, and -no-engine. shared will build and install both the shared object and static archive. You should specify --openssldir,  --with-fipsdir and --with-fipslibdir to ensure the FIPS Capable build system finds components from the FIPS Object Module.
+To build the FIPS Capable library, you must issue config fips, but other options are up to you. Some suggested options for configure include: shared, no-ssl2, no-ssl3, no-comp, no-hw, and no-engine. shared will build and install both the shared object and static archive. You should specify --openssldir,  --with-fipsdir and --with-fipslibdir to ensure the FIPS Capable build system finds components from the FIPS Object Module.
 Begin building the FIPS Capable library by setting the cross-compilation environment. Note the leading '.' when running the setenv-android.sh script. If you have any errors from the script, then you should fix them before proceeding.
@@ Line 199: / Line 199: @@
 <pre>$ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org
-$ ./config fips shared -no-ssl2 -no-ssl3 -no-comp -no-hw -no-engine --openssldir=/usr/local/ssl/android-14/ \
+$ ./config fips shared no-ssl2 no-ssl3 no-comp no-hw no-engine --openssldir=/usr/local/ssl/android-14/ \
    --with-fipsdir=/usr/local/ssl/android-14/ --with-fipslibdir=/usr/local/ssl/android-14/lib/</pre>

← Older revision		Revision as of 23:07, 11 July 2014
Line 307:		Line 307:

	If you don't care about FIPS 140-2 and just want to build the library for Android, then see [[Android\|OpenSSL and Android]].		If you don't care about FIPS 140-2 and just want to build the library for Android, then see [[Android\|OpenSSL and Android]].
−	* Omit the call to <tt>FIPS_mode_set</tt>

	The NDK supplies headers for each major platform - for example, API 18, API 14, API 9, API 8, and API 5. If you are building for Android 4.2 (API 17), Android 4.1 (API 16) and Android 4.0 (API 14), then you would use the NDK's API 14 (android-14 platform).		The NDK supplies headers for each major platform - for example, API 18, API 14, API 9, API 8, and API 5. If you are building for Android 4.2 (API 17), Android 4.1 (API 16) and Android 4.0 (API 14), then you would use the NDK's API 14 (android-14 platform).

@@ Line 304: / Line 304: @@
 == Miscellaneous ==
-Once the FIPS Object Module and FIPS Capable Library are installed, you can safely delete the source directories. The headers, libraries and programs (such as fipsld and incore) are located in subdirectories of /usr/local/ssl/<platform>.
+Once the FIPS Object Module and FIPS Capable Library are installed, you can safely delete the source directories. The headers, libraries and programs (such as fipsld and incore) are located in sub-directories of <tt>/usr/local/ssl/<platform></tt>.
-If you don't care about FIPS 140-2 and just want to build the library for Android, then modify the procedures as follows:
+If you don't care about FIPS 140-2 and just want to build the library for Android, then see [[Android|OpenSSL and Android]].
 * Omit the call to <tt>FIPS_mode_set</tt>

@@ Line 88: / Line 88: @@
 setenv-android.sh is used to set the cross-compilation environment. Open the script an ensure the following match your needs. If you are using android-ndk-r8e, android-14, and ANDROID_NDK_ROOT is set, then the script should be ready to use as-is.
-* _ANDROID_NDK – the version of the NDK. For example, android-ndk-r8e
+* <tt>_ANDROID_NDK</tt> – the version of the NDK. For example, android-ndk-r8e
-* _ANDROID_EABI – the version of the EABI tools. For example, arm-linux-androideabi-4.6
+* <tt>_ANDROID_ARCH</tt> – the architecture. For example, arch-arm or arch-x86
-* _ANDROID_API – the API level. For example, android-14
+* <tt>_ANDROID_EABI</tt> – the version of the EABI tools. For example, arm-linux-androideabi-4.6, arm-linux-androideabi-4.8, x86-4.6 or x86-4.8
 You should also set <tt>ANDROID_SDK_ROOT</tt> and <tt>ANDROID_NDK_ROOT</tt>. The environmental variables are used internally by the Android platform tools and scripts. For details, see [https://groups.google.com/d/msg/android-ndk/qZjhOaynHXc/2ux2ZZdxy2MJ Recommended NDK Directory?].