View source for FIPS Library and Windows Mobile 6

This document will provide instructions for building the OpenSSL FIPS Object Module and OpenSSL FIPS Capable library for Windows Mobile 6 devices. The FIPS Object Module provides validated cryptography, and the FIPS Capable Library uses the validated cryptography. As an OpenSSL developer, you will use the library the same as in the past – except you must call <tt>FIPS_mode_set</tt> to enter FIPS mode and engage the validated cryptography.

The FIPS Object Module, <tt>fipscanister.lib</tt>, is a sequestered container of object code and data built from source code. The sources, object code and data are strictly controlled by the OpenSSL FIPS 140-2 Security Policy. No changes can be made to the procedure for building the FIPS Object Module, and no changes can be made to the sources. If you need to make changes to the FIPS Object Module, you will need to engage the OpenSSL Foundation for a separate validation.

The FIPS Capable Library is comprised of <tt>libcrypto</tt> and <tt>libssl</tt>. They are the same libraries you have been using for years. The FIPS Capable Library is tolerant of changes to procedures and source code. You are allowed to modify them within reason, as long as the changes do not adversely affect the FIPS Object Module.

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 instructions that follow depend upon a properly configured Windows computer with the necessary development tools and platform specific SDK. Specifically, Visual Studio 2008 used in conjunction with the Windows Mobile 6 SDK. Also required are 7-zip, gzip, and tar programs for Windows.

==Quick Summary==

Use the following commands to build the OpenSSL FIPS Object Module and OpenSSL FIPS Capable library. 
Before running the commands
*download [https://sites.google.com/a/essemer.com.au/www/wcecompat-1.2.zip wcecompat-1.2.zip], [http://www.openssl.org/source/openssl-fips-2.0.5.tar.gz openssl-fips-2.0.5.tar.gz], and [[Media:Build_WM6_OpenSSL-FIPS.tar.gz|Build_WM6_OpenSSL-FIPS.tar.gz]]
*place all files in the same directory (the 'root' directory mentioned below)

<pre>: From the 'root' directory
> gzip -d Build_WM6_OpenSSL-FIPS.tar.gz
> tar -xvf Build_WM6_OpenSSL-FIPS.tar
</pre>

=== Prepare to build for WM6 using Visual Studio 2008 ===

<pre>: From the 'root' directory
> WM6_ARMV4I_env.bat
</pre>

The provided batch file is specific to a single target (WM6) and compiler (Visual Studio 2008).  Using this batch file as an example one could derive a process for building for another target or to use a different compiler.  Note however that the patch set provided for wcecompat only includes those changes that are required for the Windows Mobile 6 target. Additional changes may be required for other target platforms.

=== Build wcecompat for WM6 ===

<pre>> Build_wcecompat.bat</pre>

This batch file:
*extracts wcecompat-1.2 into the wcecompat folder
*creates a git repository based upon the contents of that folder
*commits a patch set to update wcecompat to support WM6
*builds wcecompat

=== Build the FIPS Object Module ===

Note: using this process the FIPS Object Module is built directly from the contents of the tar.gz file. This is important since one must neither modify the source nor the build process for this step.

<pre>: From the 'root' directory
> Build_FIPS_for_WM6.bat
</pre>

This batch file:
*creates the openssl-fips folder from a tar.gz file
 Set version=2.0.5
 if exist openssl-fips-%version%.tar.gz gzip -d openssl-fips-%version%.tar.gz
 tar -xvf openssl-fips-%version%.tar
 cd openssl-fips-%version%
*defines some environment variables:
 set FIPSDIR=..\FIPS_WM6_ARMV4I
 set FIPS_SHA1_PATH=perl util\fips_standalone_sha1
 set FIPS_SIG=perl util\msincore
 set WCECOMPAT=..\wcecompat
*builds the FIPS canister
 call ms\do_fips.bat
*builds fips_algvs.exe, a program one can use to validate the canister.
 nmake -f ms\cedll.mak build_algvs
*copies some additional files required by OpenSSL
 copy out32dll_ARMV4I\*.exe %FIPSDIR%\bin
 copy util\msincore %FIPSDIR%\bin\msincore.pl
 copy util\hmac_sha1.pl %FIPSDIR%\bin

=== Build the FIPS Capable Library (the canister) ===

This step is fraught with perils due to the fact that many branches of OpenSSL do not properly build for Windows Mobile 6 without first making changes.  As such the commands listed here will work only after those issues have been addressed.  Refer to the troubleshooting section below for details.

<pre>: From the 'root' directory
> Build_OpenSSL_for_WM6.bat
</pre>

This batch file:
*creates the openssl folder directly from the public OpenSSL repository.
 git clone git://git.openssl.org/openssl.git
*selects a branch to work on.
 git checkout origin/OpenSSL_1_0_2-stable -b OpenSSL_1_0_2
*redefines the FIPS_SIG environment variable:
 set FIPS_SIG=perl %FIPSDIR%\bin\msincore.pl
:The msincore.pl script is required to build a FIPS capable OpenSSL DLL, but it is only provided with the OpenSSL-FIPS project.
*copies header files from FIPSDIR into inc32
:Some branches of OpenSSL require this step in order to find those header files.
*configures OpenSSL to build for CE with FIPS
 perl Configure VC-CE fips --with-fipsdir=%FIPSDIR%
*creates the necessary makefiles
 call ms\do_ms
*builds static OpenSSL libraries
 nmake -f ms\ce.mak

==Checking Results==

*After building wcecompat the wcecompat\lib folder should contain wcecompat.lib and wcecompatex.lib.
*After building the canister that should be a new folder named FIPS_WM61_ARMV4I in the root folder which contains:
<pre>
>tree FIPS_WM61_ARMV4I /f
+---bin
|       fipslink.pl
|       fips_algvs.exe
|       hmac_sha1.pl
|       msincore.pl
|
+---include
|   \---openssl
|           fips.h
|           fips_rand.h
|
\---lib
        fipscanister.lib
        fipscanister.lib.sha1
        fips_premain.c
        fips_premain.c.sha1
</pre>
* As mentioned before, the OpenSSL build itself may not complete without additional work.  Once it does complete, however, you will find many executable files and PDB files in the out32_ARMV4I folder, together with a few LIB files.  Look for:
**openssl.exe
**libeaycompat32.lib
**libeayfips32.lib
**ssleay32.lib

== Troubleshooting OpenSSL builds for WM6 ==
With most branches of OpenSSL code one must make changes before a successful build is possible for Windows Mobile 6.
The first thing to try when having troubles compare files against tips.  Most issues are already solved on tips.
Some of the files likely to have issues are:
*apps\apps.c
*crypto/bio/bss_fd.c
*crypto/cryptlib.c
*crypto/o_str.c
*e_os.h
*engines/e_capi.c
*util/pl/VC-32.pl:
**With /WX defined warnings are treated like errors.
**Windows Mobile uses ws2.lib, not winsock.lib
**Windows Mobile requires crypt32.lib for e_capi.c.  Add this requirement as wcecompatex.lib is also added.
**The line that adds coredll.lib and others should not be dependent upon TARGETCPU x86.

Also note that fips_standalone_sha1.exe is required for Windows Mobile builds, but is only provided by Windows XP builds.  Building that executable as part of the FIPS canister for XP may also be a challenge if you have a 64-bit OS.

== Testing the OpenSSL Canister ==
Using ceutils programs one can test the FIPS canister build using a sequence of commands after establishing an ActiveSync connection with a device.
 >ceutils\cecopy FIPS_WM6_ARMV4I\bin\fips_algvs.exe CE:\
 >ceutils\cecopy ceutils\cerunner.dll CE:\windows
 >ceutils\cerun.exe CE:\fips_algvs.exe fips_test_suite post

== Testing the OpenSSL Libraries ==

One can use Fips-test.c to test FIPS mode operation of OpenSSL capable libraries.
Skipping the details one must:
*Create a project that includes Fips-test.c and fips_premain.c (produced by building the FIPS canister).
*Build an executable including those two files.
*Compute the SHA1-digest for that executable.
 perl msincore.pl -exe Fips-test.exe
*Modify the build to include that SHA1 digest as a pre-processor definition as fips_premain.c is built.  For example:
 HMAC_SHA1_SIG=\"89d26c23e45186b029d0bc2e67bde8a99e5a199f\"
*Rebuild the executable.
*Run the executable to test it.  For this one can use interactive debug or ceutils.

{{TODO|A more complete example might be helpful here}}

== Caveats ==

*Just because one can build a FIPS canister together with FIPS capable OpenSSL libraries in no way means that the result meets NIST requirements as a FIPS validated program. One must carefully follow additional restrictions set forth in the User's Guide in order to take advantage of validation efforts for existing certified versions.
*This document describes basic technical details required to build static libraries. Static libraries can be used by applications such as the test application so long as they are built with the proper SHA1 digest.  Applications always load at the same virtual address, which makes it easy for them to use static libraries.  Any program that does not consistently load at the same address, such as a Dynamic Link Library, cannot enable FIPS.
*With great effort one can create Dynamic Link Libraries for OpenSSL that are FIPS capable.  If in addition to that one can insure that libeay32.dll loads consistently at the same address and contains the proper FIPS digest, FIPS mode is then possible for any application that uses that solution, regardless where in memory that application may load.

== Downloads ==
*[https://sites.google.com/a/essemer.com.au/www/wcecompat-1.2.zip wcecompat-1.2.zip]: This is the original source for wcecompat.  Although there is at least one newer version available, it is not recommended for use due to unresolved issues seen with that version.
*[http://www.openssl.org/source/openssl-fips-2.0.5.tar.gz openssl-fips-2.0.5.tar.gz]: A recent version of the OpenSSL-FIPS source.
*[[Media:Build_WM6_OpenSSL-FIPS.tar.gz|Build_WM6_OpenSSL-FIPS.tar.gz]]: The set of batch files and patch files used by these instructions.
*[https://sites.google.com/a/essemer.com.au/www/ceutils.zip ceutils.zip]: This is a set of executable files useful in testing results.
*[[Media:Fips-test.c|fips-test.c]]: a test program to dump critical FIPS parameters that can also be used to test FIPS mode.

[[Category:FIPS 140]]