Config.h

From Crypto++ Wiki
Jump to navigation Jump to search

config.h is the primary Crypto++ header file which holds nearly all configuration information. The file is a mix of user defines and platform defines that interact to create a compile time configuration for both library and application code.

All source have the configuration information by including either config.h directly, or indirectly by including cryptlib.h. cryptlib.h is often a good choice because it also includes the base interfaces provided by the library.

At Crypto++ 8.1 the library split the monolithic config.h into several smaller files named like config_xxx.h. For example, there is a config_asm.h and config_cxx.h. config.h includes all the child config_xxx.h headers.

In general, the GNUMakefile and config.h autodetect the environment and platform well, so there should be little to no modifications required. If features are misdetected then you can use configure.sh to fix it. configure.sh performs compile tests rewrites the results of ASM and C++11 feature tests. configure.sh was added for Crypto++ 8.3 to help with mobile devices, but it applies to desktop builds as well.

Please report configuration failures on the Mailing List or the Bug Reporter.

config.h and config_xxx.h

At Crypto++ 8.1 the library changed the monolithic config.h and separated it into different config_xxx.h files, like config_asm.h and config_cxx.h. The change was made to make it easier to update a specific configuration, like updating ASM defines or updating C++11 and C++17 defines.

Sometimes config_xxx.h misdetects a feature due to using just compiler versions and preprocessor macros (the monolithic one had the problem, too). If features are not correct then you can run configure.sh, which performs compile tests rewrites the results of ASM and C++11 feature tests. configure.sh was added for Crypto++ 8.3 to help with mobile devices, but it applies to desktop builds as well.

The library and applications still include config.h. config.h includes all of the child configuration files, like config_asm.h and config_cxx.h.

General Library Defines

General library defines include preprocessor macros that determine debug, release, big endian, little endian, initialization priority and similar defines.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

General Library Defines
Define A/E/D Avail Description
NDEBUG A - Posix's standard NDEBUG macro. Since Crypto++ 5.6.5, NDEBUG is not needed and the library is in a release build if you do nothing special. Also see CVE-2016-7420 and Assertions on the wiki.
CRYPTOPP_DEBUG A 5.6.5 Signals you want a debug build with asserts. Also see CVE-2016-7420 and Assertions on the wiki.
CRYPTOPP_BIG_ENDIAN A - Defined when the processor is operated in big endian mode.
CRYPTOPP_LITTLE_ENDIAN A - Defined when the processor is operated in little endian mode.
CRYPTOPP_INIT_PRIORITY D 5.6.3 Define to control C++ static object initialization. When defined and non-0, it utilizes GCC's init_priority or Microsoft's #pragma init_seg(lib).
CRYPTOPP_USER_PRIORITY D 5.6.3 When CRYPTOPP_INIT_PRIORITY is defined, this is the first value you can use for your user or application code that's guaranteed not to conflict with values used by the Crypto++ library.
CRYPTOPP_DATA_DIR D 5.6.4 CRYPTOPP_DATA_DIR is used to define the location of TestVectors and TestData. By default, it is defined to the empty string, which means the the directories are located in $PWD. Package maintainers, like Debian, Fedora and Macports, can use it to specify an alternate location during their packaging process.
NO_OS_DEPENDENCE D - Disable all OS-dependent features, such as OS-provided random number generators and timers. Useful on some platforms, like Windows Mobile and Windows Phone.
USE_MS_CRYPTOAPI A - Use features provided by Microsoft's CryptoAPI. Used by default for Windows 8 and below. Also see USE_MS_CNGAPI.
USE_MS_CNGAPI A 5.6.4 Use features provided by Microsoft's Next Generation Crypto. Used by default for Windows 10 and above. Also see USE_MS_CRYPTOAPI.
DSA_1024_BIT_MODULUS_ONLY E 5.6.1 Define to 1 to enforce the requirement in FIPS 186-2 Change Notice 1 that only 1024 bit moduli be used.
GZIP_OS_CODE E - Identifies the type of file system on which compression took place. Set to 0 by default. Also see (RFC 1952).
IDEA_LARGECACHE D - Try this if your CPU has 256K internal cache or a slow multiply instruction, and you want to use log tables.
LCRNG_ORIGINAL_NUMBERS D - Use S.K. Park and K.W. Miller's original constants as specified in the CACM paper.
CRYPTOPP_RIJNDAEL_NAME E 5.3.0 Set the name of Rijndael cipher. Prior to version 5.3, it was "Rijndael".
WORKAROUND_MS_BUG_Q258000 E - Work around Q258000, where each call to CryptAcquireContext causes about a 100 KB memory leak.
CRYPTOPP_GCC_VERSION A - Wrapper for __GNUC__, __GNUC_MINOR__ and __GNUC_PATCHLEVEL__. GCC 4.2.1 produces 40201; GCC 4.5 produces 40500.
CRYPTOPP_APPLE_CLANG_VERSION A 5.6.3 Wrapper for Apple's __clang_major__, __clang_minor__ and __clang_patchlevel__. Apple Clang 5.1 produces 50100. Note: Apple and LLVM Clangs are mostly equivalent under different version schemes.
CRYPTOPP_LLVM_CLANG_VERSION A 5.6.3 Wrapper for __clang_major__, __clang_minor__ and __clang_patchlevel__. Clang 2.8 produces 20800; Clang 2.3 produces 30300. Note: Apple and LLVM Clangs are mostly equivalent under different version schemes.
CRYPTOPP_MSC_VERSION A 5.6.3 Wrapper for _MSC_VER and cl.exe, which is tied to Visual Studio. cl.exe 12.00 (Visual Studio 6.0) produces 1200; cl.exe 13.00 (Visual Studio 7.0) produces 1300; cl.exe 19.00 (Visual Studio 2015) produces 1900.
CRYPTOPP_INTEL_VERSION - - There is no wrapper for Intel compilers, like icc and icpc. The versioning is available in __INTEL_COMPILER and takes values like 1000 (version 10.0), 1110 (version 11.1) and 16.00 (version 16.0).

Platform and OS Defines

The following table discusses platform and OS specific defines. In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Description provides a discussion of the define.

Platform and OS Defines Defines
Define A/E/D Avail Description
CRYPTOPP_WIN32_AVAILABLE A - Defined for a Windows operating system, like Win32, Win64 or Windows Mobile. Also defined for Cygwin (but not MinGW).
CRYPTOPP_UNIX_AVAILABLE A - Defined for a Unix or Unix-like operating system, like AIX, BSD, Linux, OS X, Solaris or System V.
HIGHRES_TIMER_AVAILABLE A - Defined when a high resolution timer is available.
NONBLOCKING_RNG_AVAILABLE (Windows) A - Defined when CryptGenRandom is available, guarded by USE_MS_CRYPTOAPI. Also see Random Number Generator.
NONBLOCKING_RNG_AVAILABLE (Unix) A - Defined when /dev/random, /dev/urandom, or /dev/srandom is available, guarded by CRYPTOPP_UNIX_AVAILABLE. Also see Random Number Generator.
THREADS_AVAILABLE (Unix) A - Defined when threads are available is available, used for thread local storage, and guarded by CRYPTOPP_WIN32_AVAILABLE or CRYPTOPP_UNIX_AVAILABLE
CRYPTOPP_DISABLE_UNCAUGHT_EXCEPTION A - Disables the use of std::uncaught_exception to determine when stack unwind code is being executed. This was needed in the early days, before C++98.

Library Word Defines

The table below provides the integer related defines and typedef, which can have a dramatic effect on operations. What the library is trying to achieve is simple: a fast unsigned multiply using the largest word size available. It is usually constrained by the availability of a fast unsigned multiply (like umul128 or similar), and its reflected in the table below.

While word16, word32, word64 are always available, and word128 may be available. The real item of interest is how they are used or typedef'd. Remember, the library is trying to achieve one thing: a fast unsigned multiply using the largest word size available.

Library Word typedefs
Library Word 32-bit typedef 64-bit typedef Windows typedef
word16 hword -
word32 word hword hword
word64 dword word word
word128 - dword

If the compiler provides a synthesized int128_t or uint128_t (or equivalent), and the operations are fast, then you should have a word128 available. If CRYPTOPP_WORD128_AVAILABLE is defined, then word128 is present.

Generally speaking the advice is: (1) avoid the CRYPTOPP_BOOL_SLOW_WORD and CRYPTOPP_BOOL_SLOW_WORD64 defines, and (2) try to achieve the CRYPTOPP_WORD128_AVAILABLE define.

GCC has a define called __SIZEOF_INT128__. If its 16 or greater, then a 128-bit integer is available. However, GCC has some bugs related to the code generation surrounding their 128-bit integers (including GCC 5.1/5.2), so the Crypto++ does not enable the word128 and CRYPTOPP_WORD128_AVAILABLE machinery. We tried, but it was causing too many problems in the field.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Integer Related Defines
Define A/E/D Avail Description
CRYPTOPP_NATIVE_DWORD_AVAILABLE A - Defined when the platform provides a word64. Windows, Linux, Unix, and most other platforms.
CRYPTOPP_WORD128_AVAILABLE A - Defined when the compiler provides a word128. GCC, Clang, and Intel, but limited to Linux, Unix, and other Unix-like platforms.
CRYPTOPP_BOOL_SLOW_WORD A - Poison (as is CRYPTOPP_BOOL_SLOW_WORD64). Defined on most 32-bit platforms.

Assembly Defines

Assembly defines includes the defines related to assembly language routines, intrinsics available to the library, and information extracted from them, like alignment requirements and cache sizes. Assembly defines and intrinsics are some of the hairiest defines in the library, especially when they start interacting and overlapping in non-obvious ways.

The goal of the assembly related defines is simple: provide hand tuned assembly routines in places where the code can benefit from them. Usually, this is places when SSE2, SSE3 and AES-NI can be used. A secondary goal is to provide access to essential routines, like the CPUID instruction on X86, or the RDRAND instruction under Ivy Bridge and compatible processors.

The distinction between assembly language routines and intrinsics is important, and means you can disable nearly all assembly language with CRYPTOPP_DISABLE_ASM, but the AES-NI intrinsics will be available. Or, you can use the assembly language routines but disable the intrinsics.

When considering assembly defines and intrinsics with platforms, compilers and features, the list of potential combinations can be large:

  • X86 assembly (Windows, Unix, BSD, Linux, OS X, Solaris and other Unix-like OSes)
  • X32 assembly (Unix, BSD, Linux, OS X, Solaris and other Unix-like OSes)
  • X64 assembly (Windows, Unix, BSD, Linux, OS X, Solaris and other Unix-like OSes)
  • AT&T assembly (GCC, ICC and Clang)
  • Intel assembly (GCC and ICC)
  • MASM assembly (Microsoft, GCC and ICC)
  • AES-NI assembly (GCC, ICC and Clang)
  • MSVC AES-NI intrinsics
  • GCC AES-NI intrinsics
  • ICC AES-NI intrinsics
  • Clang AES-NI intrinsics (Apple and non-Apple)

Clang is challenging because it claims to be __GNU_C__ 4, but it cannot consume Intel syntax (with or without prefixes). Because of Clang, two additional defines have been proposed: CRYPTOPP_ATT_ASM_SYNTAX and CRYPTOPP_INTEL_ASM_SYNTAX. They have not been added yet. Also see LLVM Issue 24232: Inline assembly operands don't work with .intel_syntax for the Clang bug report.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Assembly Defines
Define A/E/D Avail Description
CRYPTOPP_BOOL_X86 A - Set for X86 platforms. CRYPTOPP_BOOL_X86 can be used as both a define and a template parameter.
CRYPTOPP_BOOL_X32 A 5.6.3 Set for X32 platforms. X32 is 32-bit integers, longs and pointers under X86_64. CRYPTOPP_BOOL_X32 can be used as both a define and a template parameter.
CRYPTOPP_BOOL_X64 A - Set for X64 platforms. CRYPTOPP_BOOL_X64 can be used as both a define and a template parameter.
CRYPTOPP_BOOL_ARM32 A 5.6.4 Set for Aarch32 platforms. CRYPTOPP_BOOL_ARM32 can be used as both a define and a template parameter.
CRYPTOPP_BOOL_ARM64 A 5.6.4 Set for Aarch64 platforms. CRYPTOPP_BOOL_ARM64 can be used as both a define and a template parameter.
CRYPTOPP_DISABLE_ASM A - Disables nearly all assembly routines. Some routines have to remain, like those related to X86 or X64 processor features.
CRYPTOPP_DISABLE_SSE2 A - Disables SSE2 and above routines. Above includes SSE3 and AES-NI.
CRYPTOPP_DISABLE_SSE3 A - Disables SSE3 and above routines. Above includes AES-NI.
CRYPTOPP_X86_ASM_AVAILABLE A - Set when X86 assembly is available.
CRYPTOPP_X32_ASM_AVAILABLE A 5.6.3 Set when X32 assembly is available under Unix, BSD, Linux, OS X, Solaris and Unix-like OSes. Also enables CRYPTOPP_X86_ASM_AVAILABLE.
CRYPTOPP_X64_ASM_AVAILABLE A - Set when X64 assembly is available under Unix, BSD, Linux, OS X, Solaris and Unix-like OSes. Also enables CRYPTOPP_X86_ASM_AVAILABLE.
CRYPTOPP_X64_MASM_AVAILABLE A - Set when X64 MASM assembly is available under Windows. Also enables CRYPTOPP_X86_ASM_AVAILABLE.
CRYPTOPP_BOOL_SSE2_ASM_AVAILABLE A - Set when SSE2 assembly is available. Disable with either CRYPTOPP_DISABLE_SSE2 or CRYPTOPP_DISABLE_ASM.
CRYPTOPP_BOOL_SSSE3_ASM_AVAILABLE A - Set when X86 assembly is available. Disable with either CRYPTOPP_DISABLE_SSE3 or CRYPTOPP_DISABLE_ASM.
CRYPTOPP_BOOL_SSE2_INTRINSICS_AVAILABLE A - Set when SSE2 intrinsics are available. Disable with either CRYPTOPP_DISABLE_SSE2 or CRYPTOPP_DISABLE_SSE2_INTRINSICS.
CRYPTOPP_BOOL_SSSSE3_INTRINSICS_AVAILABLE A - Set when SSE3 intrinsics are available. Disable with either CRYPTOPP_DISABLE_SSSE3 or CRYPTOPP_DISABLE_SSSE3_INTRINSICS.
CRYPTOPP_BOOL_AESNI_INTRINSICS_AVAILABLE A - Set when AES-NI intrinsics are available. Disable with either CRYPTOPP_DISABLE_AESNI or CRYPTOPP_DISABLE_INTRINSICS.
CRYPTOPP_BOOL_NEON_INTRINSICS_AVAILABLE A 5.6.4 Set when ARM NEON intrinsics are available, and applies to Linux, iOS, Windows Phone and Windows Store.
CRYPTOPP_BOOL_ARM_CRC32_INTRINSICS_AVAILABLE A 5.6.4 Set when ARM CRC32 intrinsics are available, and applies to Linux, iOS, Windows Phone and Windows Store.
CRYPTOPP_BOOL_ARM_CRYPTO_INTRINSICS_AVAILABLE A 5.6.4 Set when ARM Crypto intrinsics are available, and applies to Linux, iOS, Windows Phone and Windows Store. The intrinsics include AES, SHA1 and SHA2 instructions.

A define closely related to SSE2, SSE3 and AES-NI is CRYPTOPP_BOOL_ALIGN16_ENABLED:

Alignment Define
Define A/E/D Avail Description
CRYPTOPP_BOOL_ALIGN16_ENABLED A - Set when alignment requirements are 16. Platforms which require aligned access when working with SIMD data include SSE and PowerPC.

Since CRYPTOPP_BOOL_ALIGN16_ENABLED is a _BOOL_ define, the macro can be used as a define or a template parameter. SecByteBlocks use it when declaring data for SSE2 and above.

The size of the L1 cache and its line size are important to (1) ensure thrashing is minimized, and (2) guard against some timing attacks. A default value is provided using CRYPTOPP_L1_CACHE_LINE_SIZE:

L1 Cache Define
Define A/E/D Avail Description
CRYPTOPP_L1_CACHE_LINE_SIZE A/E - Set to a lower bound on the cache line size. For 64-bit CPUs, the default value is 64; and for 32-bit CPUs, the default value is 32. If the CPU allows it to be queried (say, through the x86 `cpuid` instruction), then it is updated at runtime.

If you are building on Linux, then you can perform the following to use the kernel's cache line size:

export CXXFLAGS="-DNDEBUG -g3 -O2 -Wall"
export CXXFLAGS="$CXXFLAGS -DCRYPTOPP_L1_CACHE_LINE_SIZE=`getconf LEVEL1_DCACHE_LINESIZE`"
make

If you are building on OS X, then you can perform the following to use the kernel's cache line size:

export CXXFLAGS="-DNDEBUG -g3 -O2 -Wall"
export CXXFLAGS="$CXXFLAGS -DCRYPTOPP_L1_CACHE_LINE_SIZE=`sysctl hw.cachelinesize | cut -d " " -f 2`"
make

X32 Defines

When Crypto++ was ported to the X32 platform, five source files did not port cleanly. Unique defines were added to disable assembly in the four problem source files for X32. It allowed us to disable assembly while ensuring the define did not cross-pollinate to other source files (like trying to reuse CRYPTOPP_DISABLE_ASM).

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

X32 Assembly Defines
Define A/E/D Avail Description
CRYPTOPP_DISABLE_PANAMA_ASM A 5.6.3 Disables assembly language in panama.h and panama.cpp, guarded by CRYPTOPP_BOOL_X32.
CRYPTOPP_DISABLE_RIJNDAEL_ASM A 5.6.3 Disables assembly language in rijndael.h and rijndael.cpp, guarded by CRYPTOPP_BOOL_X32.
CRYPTOPP_DISABLE_SOSEMANUK_ASM A 5.6.3 Disables assembly language in sosemanuk.h and sosemanuk.cpp, guarded by CRYPTOPP_BOOL_X32.
CRYPTOPP_DISABLE_VMAC_ASM A 5.6.3 Disables assembly language in vmac.h and vmac.cpp, guarded by CRYPTOPP_BOOL_X32.
CRYPTOPP_DISABLE_INTEGER_ASM A 5.6.3 Disables assembly language in integer.h and integer.cpp, guarded by CRYPTOPP_BOOL_X32.

X32 is a platform with 32-bit integers, longs and pointers on x86_64. SSE2 and SSE3 are available like X86, but stack interactions occur using 64-bit registers like x86_64. In addition, R9 through R15 are accessible to a program or library like x86_64. Also see Issue 32: Compile failures under X32 (32-bit integers, longs, pointers on x86_64) on the GitHub issue tracker.

C++ Defines

Crypto++ attempts to retain compatibility with C++03. C++11 is the defacto implied standard for modern compilers like GCC 4.9, GCC 5, GCC 6 and Visual Studio 2015 and 2019. Fedora is bleeding edge and often provides the newest standards, like GCC with C++17 and C++20 enabled. The library had to evolve with the platforms and compilers.

The most interesting case related to C++11 is Apple and OS X 10.8 or below. That's because Apple ships with an ancient C++ runtime library that pretends to be C++11 (even though its missing basic core classes, like unique_ptr).

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

C++ Related Defines
Define A/E/D Avail Description
CRYPTOPP_UNCAUGHT_EXCEPTION_AVAILABLE A - Defined when the compiler supports C++98 std::uncaught_exception. This is an ancient Crypto++ define. This define is the same as see CRYPTOPP_CXX98_UNCAUGHT_EXCEPTION.
CRYPTOPP_CXX98_UNCAUGHT_EXCEPTION A 8.3 Defined when the compiler supports C++98 std::uncaught_exception. This define is the same as see CRYPTOPP_UNCAUGHT_EXCEPTION_AVAILABLE.
CRYPTOPP_CXX11 A 5.6.3 Defined when the compiler claims to support C++11. The test is _MSC_VER >= 1600 on Windows and __cplusplus >= 201103L on Unix-like OSes. On Apple with Clang, the test __has_include(<forward_list>) is also used because Apple's ancient C++ standard library does not have the include.
CRYPTOPP_CXX11_NOEXCEPT A 5.6.3 Defined when the compiler support noexcept destructors under C++11. Nothing is performed for C++03. This was added due to Microsoft compiler warnings on AlgorithmParametersBase and ThreadLocalStorage classes. Both classes can throw in the destructor.
CRYPTOPP_CXX11_AUTO A 8.3 Defined when the compiler supports C++11 auto type specifier. The keyword is not currently used.
CRYPTOPP_CXX11_ATOMIC A 5.6.4 Defined when the compiler supports C++11 atomics. The Singleton class uses it for read/write memory barriers during double checked initialization.
CRYPTOPP_CXX11_SYNCHRONIZATION A 6.0 Defined when the compiler supports C++11 synchronization, like mutex and lock. The Singleton class uses it during double checked initialization.
CRYPTOPP_CXX11_STATIC_INIT A 6.0 Defined when the compiler supports "magic statics", a.k.a. Dynamic Initialization and Destruction with Concurrency. When magic statics are available the library uses them instead of the Singleton class to avoid memory leaks.
CRYPTOPP_CXX11_DELETED_FUNCTIONS A 6.0 Defined when the compiler supports defaulted and deleted functions . It is used by the NotCopyable class to remove assignment.
CRYPTOPP_CXX11_ALIGNAS A 5.6.4 Defined when the compiler supports C++11 alignas. Its planned for use with CRYPTOPP_ALIGN_DATA.
CRYPTOPP_CXX11_ALIGNOF A 5.6.4 Defined when the compiler supports C++11 alignof. Its used with GetAlignmentOf<T>.
CRYPTOPP_CXX11_INITIALIZER_LIST A 8.3 Defined when the compiler supports C++11 initializer lists.
CRYPTOPP_CXX11_LAMBDA A 8.3 Defined when the compiler supports C++11 lambda expressions.
CRYPTOPP_CXX11_VARIADIC_TEMPLATES A 5.6.4 Defined when the compiler supports C++11 variadic templates and forwarding of arguments. Its used with SecBlock<T> for the placement new operator.
CRYPTOPP_CXX11_CONSTEXPR A 6.0 Defined when the compiler supports C++11 constexpr specifier.
CRYPTOPP_CXX11_STRONG_ENUM A 6.0 Defined when the compiler supports C++11 strong typed enums. It is used in Allocator classes to derive an enum from std::size_t. Otherwise a macro is used.
CRYPTOPP_CXX11_NULLPTR A 6.0 Defined when the compiler supports C++11 nullptr_t and nullptr. nullptr is used when available to help with type safety.
CRYPTOPP_CXX11_ASSERT A 8.3 Defined when the compiler supports C++11 2-argument static assert.
CRYPTOPP_CXX14 A 7.0 Defined when the compiler claims to support C++14. There are no C++14 defines used in the library, however.
CRYPTOPP_CXX17 A 7.0 Defined when the compiler claims to support C++17.
CRYPTOPP_CXX17_UNCAUGHT_EXCEPTIONS A 7.0 Defined when the compiler supports C++17 std::uncaught_exceptions.
CRYPTOPP_CXX17_ASSERT A 7.0 Defined when the compiler supports C++17 1-argument static assert.

There are two C++ related macros, CRYPTOPP_THROW and CRYPTOPP_NO_THROW. The macros depend upon CRYPTOPP_CXX98_UNCAUGHT_EXCEPTION, CRYPTOPP_CXX17_UNCAUGHT_EXCEPTIONS and CRYPTOPP_CXX11_NOEXCEPT.

The dynamic exception specification is a moving target, but it is generally frowned upon and not used. CRYPTOPP_THROW and CRYPTOPP_NO_THROW are needed because AlgorithmParametersBase class can throw in a destructor to signal an unused parameter. Also see NameValuePairs on the wiki.

Other Defines
Define A/E/D Avail Description
CRYPTOPP_THROW A 6.0 CRYPTOPP_THROW signals a member function can throw. Under C++17 it is defined as noexcept(false). It is only applied to AlgorithmParametersBase destructor.
CRYPTOPP_NO_THROW A 6.0 CRYPTOPP_NO_THROW signals a member function will not throw. Under C++17 it is defined as noexcept(true). It is currently not used in the library.

Export and DLL Defines

Crypto++ provides preprocessor macros to help build the library as a static lib, a DLL or a shared object. Both Windows and Unix-like OSes provide visibility decorations to make symbols visible from a shared object or dynamic link library. Currently, only Windows utilizes them, and its intended for use with the FIPS 140-2 Validated DLL.

When you see CRYPTOPP_DLL in the source code, you should think FIPS 140-2 Validated DLL, and not a general purpose DLL. That's why the CRYPTOPP_DLL macro is missing from classes like Camellia and Whirlpool.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Export and DLL Defines
Define A/E/D Avail Description
CRYPTOPP_EXPORTS A - Set as a preprocessor macro under Visual Studio for project cryptdll when exporting (building) the FIPS DLL.
CRYPTOPP_IMPORTS A - Set as a preprocessor macro under Visual Studio for project dlltest when importing (linking to) the FIPS DLL. Also set in dll.h when CRYPTOPP_EXPORTS is not present in the environment.
CRYPTOPP_DLL A - When both CRYPTOPP_WIN32_AVAILABLE and CRYPTOPP_EXPORTS are defined, CRYPTOPP_DLL unrolls to __declspec(dllexport).
CRYPTOPP_DLL A - When both CRYPTOPP_WIN32_AVAILABLE and CRYPTOPP_IMPORTS are defined, CRYPTOPP_DLL unrolls to __declspec(dllimport).
CRYPTOPP_DLL_TEMPLATE_CLASS A -
CRYPTOPP_MANUALLY_INSTANTIATE_TEMPLATES A - Used to guard manual template instantiations when used in a DLL or shared object. The guard protects the definition of CRYPTOPP_EXTERN_DLL_TEMPLATE_CLASS.
CRYPTOPP_EXTERN_DLL_TEMPLATE_CLASS A - Unrolls into one of three defines depending on the compiler, but it basically the decoration extern template class. Also, see Explicit Instantiation on MSDN and 7.5 Where's the Template? in the GCC manual.

Miscellaneous Defines

config.h includes miscellaneous defines that either don't fit well elsewhere, or are situated in the file because of circular dependencies.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Miscellaneous Defines
Define A/E/D Avail Description
CRYPTOPP_API A - Used to decorate symbols with a calling convention. The Crypto++ calling convention is __cdecl.
CRYPTOPP_NO_VTABLE A - When _MSC_VER is defined, CRYPTOPP_NO_VTABLE unrolls to __declspec(novtable).
USE_PRECOMPILED_HEADERS A - Used under Windows to indicate precompiled headers should be used. The define has no effect under Unix-like OSes.
CRYPTOPP_UNUNSED A 5.6.3 Used to suppress unused parameter and variable warnings in the header and implementation files.

CRYPTOPP_NO_VTABLE is intended for Microsoft compilers. Clang defines it on Microsoft platforms, but the LLVM implementation is buggy and leads to crashes. Its one of the reasons Clang on Windows is unsupported (from config.h):

// See http://github.com/weidai11/cryptopp/issues/147
#if defined(_MSC_VER) && defined(__clang__)
# error: "Unsupported configuration"
#endif

Other Defines

As if there were not enough defines from config.h, there are other places defines are introduced and used. This section details some of those defines. For example, the Makefile detects MacPorts GCC compiler and sets a define to work around the lack of init_priority. Visual Studio defines are available below.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Other Defines
Define A/E/D Avail Description
MACPORTS_GCC_COMPILER A 5.6.3 Detects use of MacPorts GCC in the makefile because its not identifiable in preprocessor macros. It guards use of init_priority.

Visual Studio Defines

The Visual Studio project files include some defines that are only present in the Preprocessor Macros property sheet. Some of them are detailed below.

In the table below, the preprocessor macro is listed under Define. The macro's disposition is provided in A/E/D, which indicates whether it is Automatic, Enabled or Disabled by default. Avail is when the preprocessor was made available, and - means its not applicable or its been around a long time. Description provides a discussion of the define.

Miscellaneous Defines
Define A/E/D Avail Description
USE_PRECOMPILED_HEADERS A - Used under Windows to indicate precompiled headers should be used. The define has no effect under Unix-like OSes.
CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 E 5.0.4 The DLL project cryptdll.proj defines CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2. The define is consumed by osrng.h and fips140.cpp.