Compiling and Integrating Crypto++ into the Microsoft Visual C++ Environment

Compiling and Integrating Crypto++ into the Microsoft Visual C++ Environment

By Garth J Lancaster, Jeffrey Walton

Avoid common pitfalls when using Crypto++ and VC++

Introduction

The Crypto++ User Group occasionally receives questions on Crypto++ and Microsoft's Environments. The questions are usually basic such as, "VC++ can't find a header file - how [where] do I..." or more generic statements such as, "I can't compile." This article will attempt to resolve these common issues, and provide basic background information.

Source Code

The Crypto++ source code can be downloaded from the website at Crypto++ homepage. If the website is down, use the SourceForge page, or use an archiving service such as archive.org here.

Documentation

There are four sources of documentation for Crypto++. They are the Source Code, the Crypto++ Usenet Group, the Crypto++ FAQ, and the Crypto++ Wiki. Wei maintains an FAQ which can be found here. The Crypto++ users group can be found here. The Crypto++ Wiki can be found here. Finally, Dennis Bider has authored a User Guide and Help File which can be found here. My most used reference is the source code, which can be found online at the Crypto++ Library Reference Manual and Crypto++ Class Index.

Windows CE

Ugo Chirico maintains a port of Crypto++ 5.5.2 to Windows Mobile 2005 at Crypto++ 5.5.2 on Windows Mobile 2005. Dr. Chirico posts announcements to the Crypto++ user group. His initial post can be found at Crypto++ Users.

Managed Code

There are no special steps in using managed code. Note that if we are using the FIPS DLL, we might find that some functionality is missing (see the discussion below). For a well written example, see Mike Sinclair's CodeProject.com article, RSA Encryption with .NET 2.0 Cryptography Services and Crypto++ Wrapped as a Managed C++ Class Library.

FIPS Compliance

FIPS 140-2 certification means the library produces correct results and complies with certain cryptographic protocols. Protocols would include zeroing the memory of key material after the library is finished using it. When we refer to the FIPS compliant DLL, we will state FIPS DLL.

The FIPS DLL must be used in binary form as distributed by Wei (even though we have the source code and can build the same binary). This means we cannot build the Crypto++ DLL and claim it is FIPS compliant.

Version 5.5.2 is the last version of the library which Wei plans to submit for testing and validation. Details can be found here.

The module certification FAQ can be found under the Cryptographic Module Validation Program.

Single Threaded Versus Multi-threaded

In all cases, the Crypto++ library should be built using multi-threaded libraries. This was an issue with Visual C++ 6.0 and previous. At times, the Project Wizard would output a project using Singe Threaded project (/ML and /MLd).

Static Versus Dynamic Linking

C Runtime Library

When integrating Crypto++, the Crypto++ library must use the same runtime library linker setting as our Visual Studio project. The runtime library refers to the C Runtime Library. A stock Crypto++ distribution is built using static linking against the runtime (/MT and /MTd).

A default Visual Studio project created by the wizard will use dynamic runtime linking. The project would specify the /MD or /MDd linker switch for dynamic runtime linking, while the Crypto++ library would be using static linking (/MT or /MTd) from its build. This will cause a plethora of LINK2005 errors when linking. To resolve the Crypto++ library must be rebuilt. Table 1 below summarizes this discussion

Project Setting	Project Link Switch	Desired Runtime Linking	Action Required
Static Runtime Linking	/MT or /MTd	Static	None
Dynamic Runtime Linking	/MD or /MDd	Dynamic	Rebuild Crypto++ Library

Rebuild Crypto++ Library means to rebuild the Crypto++ library after changing the settings to compile and link against dynamic versions of the runtime. Also see the section Unsupported Configuration below.

Static Runtime Linking

The Crypto++ library is distributed as a statically linked library. Static linking is usually preferred (versus the DLL or FIPS DLL). According to Wei Dai:

... there should not be any problems linking a DLL against a DLL. But using the static library saves on code size and I'd suggest it unless you need to use the DLL for some reason (such as FIPS compliance).

When creating a statically linked Visual Studio project, no additional settings need to be changed.

Dynamic Runtime Linking

When dynamically linking to the C Runtime (/MD or /MDd), the Crypto++ library must be rebuilt using the same link settings are the main project. Open the Crypto++ project and change the Crypto++ project setting for both Cryptlib and CryptDll. The settings should be changed to /MD or /MDd. For good measure, the sett