Key Escrow Service

To Build or Not to Build?

If you have a pre-compiled Windows distribution of the escrow-enabled TrueCrypt client, then you probably do not need to compile this code from source. You can customize the XML file to suite your environment. Server name, TCP port, SSL certificate, and error messages can be modified without compiling the source. In this case, you can jump to the Configuration section.

Prerequisites

Microsoft Visual Studio 2005 should be used to build the escrow-enabled TrueCrypt Client.
OpenSSL header files and libraries are necessary for compiling and linking the Windows TrueCrypt Client. You will need to compile and install OpenSSL yourself or download a Windows-ready version.
TrueCrypt requires the Windows Driver Development Kit. This may take a while to install. (About 20 minutes on P4, 3.4 Ghz, 1 GB RAM, XP2).

Jumpstart

Microsoft Project files are available to expedite the Windows compile. This is the recommended method for the Windows build process. For documentation purposes, the Windows source page documents the changes and additions to the TrueCrypt source code.

The remainder of this page uses the Microsoft Project files to jump-start the Windows compile process.

OpenSSL

Installing OpenSSL on Windows can be challenging. Pre-compiled binaries are available, or you can build the libraries from source. If you redistribute these with your client, be sure you comply with the individual licensing agreements.

Example:

Shinning Light

Use the release recommended for software developers (not the light version).
Use the default installation directory (c:\OpenSSL\)
Copy the openssl directory from "c:\OpenSSL\include" to your Visual C++ include directory. (Copy the directory openssl, not just the contents.)
Copy the *MD.lib files from "c:\OpenSSL\lib\VC" to your Visual C++ lib directory.

Note:

Download and Extract

Create a new directory called c:\build to perform the TrueCrypt build.

Download the wfu.zip file and the escrow-enabled TrueCrypt client project (win32.zip) into the c:\build directory.
Extract or unzip these files in the c:\build directory. After this, you should have two new subdirectories.
The first directory will be named c:\build\wfu. This directory contains the code to build the library that interfaces with the escrow server.
The other directory will be named c:\build\win32. This directory contains the escrow-enabled TrueCrypt client code.

It is important that these two project directories have a common parent directory. The TrueCrypt project will expect to find the libwfu files by this relative directory.

Compile libwfu

Open the libwfu project using Microsoft Visual Studio. The project is in the c:\build\wfu\src\ directory created from the initial code extraction of the wfu.zip file.
c:\build\wfu\src\libwfu.vcproj # MS Visual Studio project file c:\build\wfu\src\libwfu.sln # MS Visual Studio Solution
You may need to update the reference to the OpenSSL library so that it references your install of OpenSSL.
Create a "Release" build of the libwfu source code.
What is a Release build?
A "Debug" build includes some Microsoft debugging features that should not be distributed with your code. A "Release" build does not include these features. The "Solution Configurations" select box should have options for "Debug," "Release," and "Configuration Manager." You should select "Release."

Compile TrueCrypt

Open the TrueCrypt solution using Microsoft Visual Studio. This solution is in the c:\build\win32 directory created from the initial code extraction of win32.zip.
Create a "Release" build of the TrueCrypt source code. This produces the TrueCrypt executable, the installer, and many other components.
What is a Release build?
A "Debug" build includes some Microsoft debugging features that should not be distributed with your code. A "Release" build does not include these features. The "Solution Configurations" select box should have options for "All," "All Debug," "Driver," "Driver Debug," and many other options. You should select "All" from this list.

Configuration

Like the Linux server and Linux client, the Windows client also uses an XML configuration file to identify the name of the escrow server, the TCP port number and the name of the SSL certificate.

The format of the XML configuration for the Windows client is different than the format of the XML configuration file for the Linux server and Linux client. Additionally, the Windows XML file allows for the customization of many of the escrow specific user interface messages.

An example of the XML file is provided in "C:\build\win32\Setup\Escrow.xml". You will need to customize the XML configuration file for your site.

NOTE: The XML file is updated each time you exit TrueCrypt. Before making changes to this file, you need to ensure you completely exit TrueCrypt. This includes exiting the TrueCrypt application from the system tray.

<?xml version="1.0" encoding="utf-8" ?>
<TrueCrypt>
    <configuration>
        <escrow key="WFUEscrowServerName">your-server.wfu.edu</escrow>
        <escrow key="WFUEscrowServerPort">1234</escrow>
        <escrow key="WFUEscrowCertPath">cacert.pem</escrow>

        <escrow key="WFUEscrowDialogTitle">Key Management System</escrow>

        <escrow key="WFUEscrowLoginText">Please enter your Wake Forest 
                     username and password to register your encryption keys in the Key Management System.</escrow>

        <escrow key="WFUEscrowLoginErrorText">Incorrect username or password, please try again.</escrow>

        <escrow key="WFUEscrowAuthFailureText">Due to authentication failure, the keys for this volume 
                     are not registred in the Key Management System. Please resolve this issue and 
                     try again. If you need assistance, contact the Help Desk at help.wfu.edu.</escrow>

        <escrow key="WFUEscrowDBErrorText">A critical escrow data base error has occured. 
                     Please contact help.wfu.edu.</escrow>

        <escrow key="WFUEscrowAuthFailreText">Due to authentication failure, the keys for this volume 
                     are not registered in the Key Management System. Please resolve this authentication 
                     issue and try again. If you need assistance, contact the Help Desk at help.wfu.edu.</escrow>

        <escrow key="WFUShowRedundantKey">0</escrow>
        <escrow key="WFUEscrowAuthAttempts">3</escrow>
        <escrow key="WFUEscrowUserName"></escrow>
    </configuration>
</TrueCrypt>

Distribution

When the user executes the Windows TrueCrypt client, the program expects to find the XML configuration file and the SSL certificate file in the same directory as the TrueCrypt executable. The default location for these files is "C:\Program Files\TrueCrypt\".

The following steps will prepare an installer for the escrow-enabled TrueCrypt Windows client.

Create a "Release Build" of TrueCrypt.
Create two new directories for our distribution files. We will use the directory "C:\WFU\" and "C:\WFU\Setup Files" as our example.

Copy the setup files into this new directory.

  REM exe files
  copy /Y "C:\build\win32\Release\TrueCrypt Setup.exe"        "C:\WFU"
  copy /Y "C:\build\win32\Release\TrueCrypt Setup.exe"        "C:\WFU\Setup Files"
  copy /Y "C:\build\win32\Mount\Release\TrueCrypt.exe"        "C:\WFU\Setup Files"
  copy /Y "C:\build\win32\Format\Release\TrueCryptFormat.exe" "C:\WFU\Setup Files\TrueCrypt Format.exe"

  REM driver files
  copy /Y "C:\build\win32\Driver\Release\TrueCrypt.sys"       "C:\WFU\Setup Files"
  copy /Y "C:\build\win32\Driver\Release64\TrueCrypt-x64.sys" "C:\WFU\Setup Files"

  REM License and documentation files
  copy /Y "C:\build\win32\Readme.txt"               "C:\WFU\Setup Files"
  copy /Y "C:\build\win32\License.txt"              "C:\WFU\Setup Files"
  copy /Y "C:\build\wfu\License-OpenSSL.txt"        "C:\WFU\Setup Files"
  copy /Y "C:\build\wfu\License-TrueCrypt.txt"      "C:\WFU\Setup Files"
  copy /Y "C:\build\wfu\License-WFU.txt"            "C:\WFU\Setup Files"
  copy /Y "C:\build\win32\Release\Setup Files\TrueCrypt User Guide.pdf" "C:\WFU\Setup Files"

Copy the supporting files into this new directory. You will need to determine the location of these files, hence the (?) in the path name.

  REM Copy your customized Escrow XML configuration file.
  copy "?\Escrow.xml" "C:\WFU\Setup Files"

  REM Copy your CA Certificate file.
  copy "?\cacert.pem" "C:\WFU\Setup Files"

  REM Copy the OpenSSL DLL files.  The location of these depends on your OpenSSL install.
  REM For example, C:\Windows\System32\*eay*.dll

  copy "?\libeay32.dll" "C:\WFU\Setup Files"
  copy "?\ssleay32.dll" "C:\WFU\Setup Files"

The directory C:\WFU can now be used to distribute your customized escrow-enabled TrueCrypt client.

Install

To install the client, one only has to acquire the contents of the C:\WFU directory and execute the "TrueCrypt Setup.exe" install program. These files may be packaged in a zip file. The following is a listing of these files:

  TrueCrypt Setup.exe
  Setup Files\TrueCrypt Setup.exe
  Setup Files\TrueCrypt.exe
  Setup Files\TrueCrypt Format.exe
  Setup Files\TrueCrypt.sys
  Setup Files\TrueCrypt-x64.sys
  Setup Files\Escrow.xml
  Setup Files\cacert.pem
  Setup Files\libeay32.dll
  Setup Files\ssleay32.dll
  Setup Files\Readme.txt
  Setup Files\License.txt
  Setup Files\License-OpenSSL.txt
  Setup Files\License-TrueCrypt.txt
  Setup Files\License-WFU.txt
  Setup Files\TrueCrypt User Guide.pdf