From Crypto++ Wiki
Jump to navigation Jump to search

DataDir is a pair of Crypto++ patches used to make the self tests run after an installation. It effectively adds an $ORIGIN bound search path on Unix and Linux to help locate test data. Prior to DataDir distros and users had to manually fix the problem. The problem was, self tests and benchmarks did not run after an installation.

The first patch was for Crypto++ 5.6.3 and earlier patch for Windows and Linux that allows the self tests and benchmarks to run after installation. Crypto++ 5.6.4 and above includes the patch and needs no special actions. Also see Issue 82, Add Debian-style Data Directory patch and Commit a0b078543abdfb5a.

The second patch was for Crypto++ 8.0 and later that allows users to forgo selecting one directory for things to work. Instead the second patch searches in the present working directory, the user's selected directory, and an origin-based location relative to Linux and Unix's bin/ and share/. Also see Issue 760, Make self-tests run after install by a typical user, and cleared at Commit 1c88fd6f5956.

Searching was avoided in the first patch because we did not want to increase attack surface by searching for data files in additional directories. However, ease of use suffered for the typical user so we traded security for usability. The data parser is resilient so it should reject most mischief. And the library does not load shared objects or execute code related to the search.

Related wiki pages are GNUmakefile and Linux (Command Line).

Search Paths

The Crypto++ library 8.0 and later use the following paths to locate its test data.

  1. $ORIGIN/../share/cryptopp
  2. $PWD

Item (1), $ORIGIN/../share/cryptopp, is for distros and staged installs. It is predicated on an install location of $ORIGIN/bin. It is the first search to avoid finding old test data from a previous install when using $DESTDIR.

You can disable path (1) by setting CRYPTOPP_DISABLE_DATA_DIR_SEARCH in config.h.

Item (2), $PWD, is for users who unpack and run in-place. This was the original use case for the library for 25 years or so. This is the use case that caused distros so much trouble.

You cannot disable path (2).

Item (3), $CRYPTOPP_DATA_DIR, is for users who wish to manually set an install directory like /usr/local. When $ORIGIN was first cut-in $CRYPTOPP_DATA_DIR was the first search path. We quickly learned this was a bad idea because a new version of the library would find old data files in $CRYPTOPP_DATA_DIR.

You can disable path (3) by leaving $CRYPTOPP_DATA_DIR undefined in config.h.

Version 5.6.3

Crypto++ 5.6.3 and earlier hard codes its TestData and TestVectors directories. After performing a make install, the tests and benchmarks no longer run because the data files are not copied during the install, and the cryptest.exe program implicitly searches for them in a different location.

After 5.6.3 you will be able to run the validation tests (cryptest.exe v and cryptest.exe tv all) or benchmarks (cryptest.exe b) after installing the library in directories like /usr and /usr/local. Existing behavior is preserved so if you do not specify a location, then the library will continue to search in the present working directory.

The issue was tracked at Issue 82, Add Debian-style Data Directory patch, and added at Commit a0b078543abdfb5a.

Version 8.0

At Crypto++ 8.0 we added data directory search to the library because it was not easy for most users to simply build, test, install, and run the library. If you are using version 8.0 of the library then you can ignore just about everything on this page except this section. The change in behavior was tracked with Issue 760, Make self-tests run after install by a typical user, and cleared at Commit 1c88fd6f5956.

The Crypto++ 8.0 change made the self tests search in the current working directory, the user's path specified with CRYPTOPP_DATA_DIR, and an origin-based search of $ORIGIN/../share/cryptopp/. The origin-based search should transparently handle distro use cases for installations that conform to Filesystem Hierarchy Standard (FHS).

For folks that don't want the search, then they can preserve existing behavior by setting CRYPTOPP_DATA_DIR to the desired directory, and then setting CRYPTOPP_DISABLE_DATA_DIR_SEARCH to disable search. Both are available in config.h.

Self Tests

As of Crypto++ 8.0 the following sequences will work as expected for users and distros.

$ make -j 5

$ ./cryptest.exe v

$ ./cryptest.exe tv all

$ sudo make install PREFIX=/opt/local

$ cd /opt/local/bin/

$ ./cryptest.exe v

$ ./cryptest.exe tv all

Prior to Crypto++ 8.0 users had to select something that ran in the build directory but not the install directory; or something that ran in the install directory but not the build directory. And to ensure the install directory worked users had to set CRYPTOPP_DATA_DIR.