FIPS Library and Windows Mobile 6

From OpenSSLWiki
Jump to navigationJump to search

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 FIPS_mode_set to enter FIPS mode and engage the validated cryptography.

The FIPS Object Module, fipscanister.lib, 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 libcrypto and libssl. 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 

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

Prepare to build for WM6 using Visual Studio 2008

: From the 'root' directory
> WM6_ARMV4I_env.bat

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

> Build_wcecompat.bat

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. 

: From the 'root' directory
> Build_FIPS_for_WM6.bat

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. 

: From the 'root' directory
> Build_OpenSSL_for_WM6.bat

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:
>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
  • 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

Sticky.png
 TODO
This is incomplete.

Downloads

  • 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.
  • openssl-fips-2.0.5.tar.gz: A recent version of the OpenSSL-FIPS source.
  • Build_WM6_OpenSSL-FIPS.tar.gz: The set of batch files and patch files used by these instructions.
  • ceutils.zip: This is a set of executable files useful in testing results.
Retrieved from "https://wiki.openssl.org/index.php?title=FIPS_Library_and_Windows_Mobile_6&oldid=1459"