Visual Studio

From Crypto++ Wiki
Jump to: navigation, search

Crypto++ 5.6.4 and above provide a Visual Studio 2010 solution file with four projects. Crypto++ 5.6.3 and earlier provided a Visual Studio 2005 solution file with four projects. The four projects are Cryptlib, Cryptest, Cryptdll and Dlltest, and they are the same in VS2005 and VS2010. Broadly speaking, Cryptlib is the library you will usually use. Cryptest is the driver to exercise Cryptlib. The DLL provides a FIPS 140-2 Validated library in Cryptdll. Dlltest is the DLL driver program.

The four projects produce a cross product of 24 different configurations. The elements are Debug, Release, DLL-Import Debug, DLL-Import Release, Win32 (X86) and Win64 (X64). The mashup is detailed below at Projects and Configurations.

All the projects use static linking against the C/C++ runtime (/MT or /MTd). Sometimes you need to change the runtime library to work with other class libraries, like MFC or Qt (both of which use dynamic C++ runtime linking). See Dynamic C++ Runtime Linking below for information on the change.

Cryptest is set as the default startup project. There's no way to do it declaratively in the solution, so the project is listed first in the solution file. This suits most users needs because they are interested in Cryptlib and Cryptest projects. However, a side effect is you have to perform Build → Batch Build → Build All twice to successfully build all 24 configurations. Update: as of October, 2016, you should not need to build twice. Custom build steps were added and dependencies were updated at Commit c70c78474557fa68 to force building the prerequisites.

The four Visual Studio projects do not include notelemetry.obj. The object file is needed to suppress collection and sending user, device and application information to Microsoft. Microsoft surreptitiously added it to Visual Studio 2015, and claimed the failure to disclose was an oversight. Yeah, right...

You cannot build the FIPS DLL from sources and then claim the resulting module is validated. If you want to use the validated cryptography, then you must download the DLL from the Crypto++ website. Also see FIPS DLL on the Crypto++ wiki.

A related topic is MSBuild (Command Line), which uses MSBuild to build the project. You can also find Visual Studio related preprocessor macros and defines discussed at config.h.

Projects and Configurations

There are four projects bundled with the solution. The four projects are Cryptlib, Cryptest, Cryptdll and Dlltest. Broadly speaking, Cryptlib is the library you will usually use. Cryptest is the driver to exercise Cryptlib. The DLL provides a FIPS 140-2 Validated library in Cryptdll. The DLL exists to provide the security boundary required by the NIST program. Dlltest is the DLL driver program.

The Crypto++ library provides 24 configurations. They are a mashup of Debug, Release, Win32, x64 and DLL-Import settings. The table below shows how the mashup is constructed, and provides details of the configuration.

Projects and Configurations
Project Configuration Output Artifact C++ Runtime Output Directory Discussion
Cryptlib Win32, Debug cryptlib.lib Static (/MTd) $(Platform)\Output\$(Configuration) Library core. All classes are available.
Win32, Release Static (/MT)
Win64, Debug Static (/MTd)
Win64, Release Static (/MT)
DLL-Import, Win32, Debug Static (/MTd) $(Platform)\DLL_Output\Debug Non-DLL_EXPORT classes are available. DLL_EXPORT classes are available in the DLL

$(Configuration) is not used because it would expand to DLL-Import Debug or DLL-Import Release; and not Debug or Release.
DLL-Import, Win32, Release Static (/MT) $(Platform)\DLL_Output\Release
DLL-Import, Win64, Debug Static (/MTd) $(Platform)\DLL_Output\Debug
DLL-Import, Win64, Release Static (/MT) $(Platform)\DLL_Output\Release
Cryptest Win32, Debug cryptest.exe Static (/MTd) $(Platform)\Output\$(Configuration) Cryptlib driver program. The non-DLL-Import configurations use the Cryptlib project (cryptlib.lib).
Win32, Release Static (/MTd)
Win64, Debug Static (/MTd)
Win64, Release Static (/MTd)
DLL-Import, Win32, Debug Static (/MTd) $(Platform)\DLL_Output\Debug Cryptlib driver program. The DLL-Import configurations use the Cryptdll project (cryptopp.dll).

$(Configuration) is not used because it would expand to DLL-Import Debug or DLL-Import Release; and not Debug or Release.
DLL-Import, Win32, Release Static (/MT) $(Platform)\DLL_Output\Release
DLL-Import, Win64, Debug Static (/MTd) $(Platform)\DLL_Output\Debug
DLL-Import, Win64, Release Static (/MT) $(Platform)\DLL_Output\Release
Cryptdll Win32, Debug cryptopp.dll Static (/MTd) $(Platform)\DLL_Output\$(Configuration) FIPS 140-2 Validated library core. Only FIPS 140-2 algorithms are available.
Win32, Release Static (/MT)
Win64, Debug Static (/MTd)
Win64, Release Static (/MT)
Dlltest Win32, Debug dlltest.exe Static (/MTd) $(Platform)\DLL_Output\$(Configuration) Cryptdll driver program. Only FIPS 140-2 algorithms are available. Additionally, the FIPS power up self tests are performed.
Win32, Release Static (/MT)
Win64, Debug Static (/MTd)
Win64, Release Static (/MT)

Platform is either Win32 or x64. Configuration is Debug, Release, DLL-Import Debug or DLL-Import Release.

The list of FIPS 140-2 algorithms and classes are decorated with DLL_EXPORT, and it includes Diffie-Hellman, RSA, AES, SHA, HMAC and so forth. Algorithms and classes like Camellia, Whirlpool and MD5 are not available.

If you don't need the DLL bits, then delete them. Its OK to completely delete the Cryptdll and Dlltest projects. Then, use Configuration Manager to delete the DLL-Import configurations from Cryptlib and Cryptest projects.

Visual Studio 2005

The Crypto++ project used Visual Studio 2005 project files from about 2006 (Crypto++ 5.3.0) until 2016 (Crypto++ 5.6.3).

The project provided a Visual Studio 2005 solution primarily for five reasons:

  1. Two of the projects underwent FIPS validation, and the project wants to retain most of the operational environment as closely as possible.
  2. The project wants to give developers their choice of development environments. Developers should be able to use Crypto++ with just about any non-ancient configuration they have.
  3. The project is aware of users who support legacy software, and they require working downlevel tools. At least three of them still use VC++ 6.0 projects.
  4. The project does not want to place a barrier for entry. The project does not want to force developers to:
    1. buy an updated workstation for SLAT and virtualization.
    2. sign up and maintain a Microsoft account.
    3. subject developers to expiring trials.
    4. buy an updated version of Visual Studio.
  5. The project does not want to engage in Microsoft corporate policy enforcement, or assist in tying products and services.

Crypto++ 5.6.4

Crypto++ 5.6.4 uses a Visual Studio 2010 solution and project files by default. If you want or need VS2005, then you should unzip vs2005.zip in place. You can also delete the various *.vcxproj and *.filter files from VS2010.

Crypto++ 5.6.3

Crypto++ 5.6.3 uses a Visual Studio 2005 solution and project files by default. If you want or need VS2010, then you should unzip vs2010.zip in place. You can also delete the various *.vcproj files from VS2005.

Visual Studio 2010

At Visual Studio 2010, Microsoft made changes to the MSBuild engine and modified the way it handled project settings and dependencies. Additionally, the VCUpgrade does a rather poor job at migrating settings. Combined, the changes created a fair amount of trouble for Crypto++ and its users who attempt to upgrade. The especially troubling part to the project was the discomfort it was causing visually impaired users who needed VS2010 for its screen reader support.

To help avoid the troubles created by Microsoft and the VCUpgrade process, the project provides a pre-converted set of project files named vs2010.zip. The solution, project files and filters are for Visual Studio 2010, which should ease the troubles being experienced by users. The ZIP file is available for download at the bottom of the page.

Crypto++ 5.6.4

Crypto++ 5.6.4 uses a Visual Studio 2010 solution and project files by default. Nothing special needs to be performed to use them.

If you want or need VS2005, then you should unzip vs2005.zip in place. You can also delete the various *.vcxproj and *.filter files from VS2010.

Crypto++ 5.6.3

Crypto++ 5.6.3 uses a Visual Studio 2005 solution and project files by default. If you want or need VS2010, then you should unzip vs2010.zip in place.

vs2010.zip is created from the latest set of GitHub sources. If you encounter fatal error C1083: Cannot open source file: 'bench1.cpp': No such file or directory, then its due to renaming bench.cpp to bench1.cpp in Crypto++ 5.6.4. In this case, you should undo the rename in the project files. That is, open cryptest.vcxproj in notepad, find bench1.cpp, and then rename it to bench.cpp. Or, perform the rename of bench.cpp to bench1.cpp on the filesystem.

If you use vs2010.zip with a downlevel version of the library, then you might find references to missing source files. For example, Crypto++ 5.6.3 will be missing ChaCha and BLAKE2, which were added for Crypto++ 5.6.4. If you experience missing referecnces, then simply delete the missing source files from the project.

Dynamic Runtime Linking

From Projects and Configurations, Crypto++ uses static C/C++ runtime linking. If you need to use Crypto++ with other class libraries, like ATL, MFC or QT, then you will likely encounter problems due to mixing and matching C++ runtime libraries. To resolve the issue, you probably have to switch to dynamic C/C++ runtime linking for Crypto++. (The other option is to use other class libraries, like ATL, MFC or Qt, in a static runtime configuration).

If you want to use Crypto++ with your default-initialised project, you either need to use the ways described here to enable static linking for your library or to change the library to use dynamic linking.

If you switch to dynamic linking, there's an increased attack surface because a DLL can be changed or redirected at loadtime. Both Windows and Linux suffer the DLL tricks; see, for example, Breaking the Links: Exploiting the Linker on Linux or search for Binary Planting on Windows.

You have a few options to switch to dynamic linking. First, you can simply download vs2005-dynamic.zip or download vs2010-dynamic.zip from below. It provides the changes for you.

Second, under Visual Studio 2010, you can use MSBuild from the command line and override a configuration property. In this case, the property of interest is RuntimeLibrary.

Third, under Visual Studio 2005 and 2010, you can change all the project's settings by hand. Again, the the property of interest is RuntimeLibrary, and the settings of interest are Multi-threaded DLL (/MD) and Multi-threaded Debug DLL (/MDd).

Fourth, you can make the change in a text editor. First, list the files to determine the setting:

# Visual Studio 2005

$ grep Runtime *.vcproj | grep -v BasicRuntimeChecks
cryptdll.vcproj:      RuntimeLibrary="0"
cryptdll.vcproj:      RuntimeLibrary="1"
...
cryptest.vcproj:      RuntimeLibrary="0"
cryptest.vcproj:      RuntimeLibrary="1"
...
cryptlib.vcproj:      RuntimeLibrary="0"
cryptlib.vcproj:      RuntimeLibrary="1"
...
dlltest.vcproj:      RuntimeLibrary="0"
dlltest.vcproj:      RuntimeLibrary="1"

And:

# Visual Studio 2010

$ grep RuntimeLibrary *.vcxproj
cryptdll.vcxproj:      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
cryptdll.vcxproj:      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
...
cryptest.vcxproj:      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
cryptest.vcxproj:      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
...
cryptlib.vcxproj:      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
cryptlib.vcxproj:      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
...
dlltest.vcxproj:      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
dlltest.vcxproj:      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>

And then open them in a text editor and perform a Find/Replace:

  • RuntimeLibrary="0"RuntimeLibrary="2" (VS2005)
  • RuntimeLibrary="1"RuntimeLibrary="3" (VS2005)
  • MultiThreadedMultiThreadedDLL (VS2010)
  • MultiThreadedDebugMultiThreadedDebugDLL (VS2010)

Finally, if you have access to a Unix or Linux machine, then the following sed will work nicely:

# Visual Studio 2005

sed -i 's|RuntimeLibrary="0"|RuntimeLibrary="2"|g' *.vcproj
sed -i 's|RuntimeLibrary="1"|RuntimeLibrary="3"|g' *.vcproj
# Visual Studio 2010

sed -i 's|<RuntimeLibrary>MultiThreaded</RuntimeLibrary>|<RuntimeLibrary>MultiThreadedDLL</RuntimeLibrary>|g' *.vcxproj
sed -i 's|<RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>|<RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>|g' *.vcxproj

If you are using Mac OS X, be sure to use sed -i "" ...

VC++ 5.0 and 6.0

Crypto++ still supplies VC++ 5.0 and 6.0 workspace (*.dsw) and project (*.dsp) files. You can safely delete them if you are not using them.

VC++ 5.0 is not guaranteed to work in 2015. The project attempts to remain compatible with VC++ 6.0 because there are a handful of users and companies which support legacy implementations.

Visual C++ 5.0 and 6.0 support was removed in Crypto++ 6.0. See Issue 342, Remove VC++ 5.0/6.0 support for the details of the removal.

The DLL

The DLL project, Cryptdll, creates a DLL that is intended to provide FIPS validated cryptography. The DLL only provides FIPS validated cryptography. It is not a general purpose DLL, and it is missing many useful classes. The DLL is exercised by the Dlltest project. For those doing business in US Federal, it is a requirement. In general, you should avoid the DLL if you are not required to use it.

The DLL provides validated cryptography in accordance with FIPS 140-2, Level 1. The DLL only provides core cryptographic classes and functions, and they are limited to Skipjack, Triple-DES, AES, SHS, DSA, RSA, ECDSA, HMAC, RNG, Triple-DES MAC and Diffie-Hellman.

There are three version of the Crypto++ library that have been validated. They are Crypto++ 5.0.4, 5.2.3 and 5.3.0. Crypto++ 5.0.4 is from 2003, and Crypto++ 5.3.0 is from 2007.

The DLL has specific Operational Environment (OE) requirements. You have to use the DLL on the platform it was validated on, which means the same CPU, OS, service pack level and even C/C++ runtime library. Crypto++ has validations on three platforms - Windows 2000, Windows XP and Windows Server 2003.

In this configuration, you will set CRYPTOPP_IMPORTS to avoid duplicate symbols from both the DLL and static library. You will link to the import library at compile time (cryptopp.lib) for the FIPS approved algorithms. At runtime you will link to the DLL (cryptopp.dll). And for the missing classes, you will link to the static library at compile time (cryptlib.lib). All three of these are in the DLL_Output directory.

More information can be found at FIPS DLL and MSBuild (Command Line). The MSBuild page provides an example of running dlltest.exe from the command line to exercise the FIPS DLL.

Downloads

vs2010.zip - archive of a pre-converted solution file, project files and filters for Visual Studio 2010 and above. The files retain static runtime linking from Visual Studio 2005. Be sure to clean all old artifacts from previous builds.

vs2010-dynamic.zip - archive of a pre-converted solution file, project files and filters for Visual Studio 2010 and above. Additionally, the project files were modified to use dynamic runtime linking rather than static runtime linking. Dynamic runtime linking is needed to work with other class libraries, like MFC and Qt. Be sure to clean all old artifacts from previous builds.

vs2005.zip - archive of a Visual Studio 2005 solution and project files. The files retain static runtime linking.

vs2005-dynamic.zip - archive of a Visual Studio 2005 solution and project files modified to use dynamic runtime linking rather than static runtime linking. Dynamic runtime linking is needed to work with other class libraries, like MFC and Qt. Be sure to clean all old artifacts from previous builds.