Crypto++ Documentation

Use the included makefile with GNU Make and GNU ld.

Default Build Flags: The makefile uses -DNDEBUG -g2 -O2 for CXXFLAGS by default.

Production Builds: If using an alternate build system (like Autotools or CMake), ensure you include -DNDEBUG for production/release builds to prevent asserts from leaking sensitive information via error reporting.

Linker Order for Custom Build Systems: If collecting source files manually, ensure these files are at the head of the list to avoid static initialization issues:

1. cryptlib.cpp
2. cpu.cpp
3. integer.cpp
4. <other sources>

They should be linked in this order: cryptlib.o, cpu.o, integer.o, <other objects>.

To build Crypto++ using Microsoft Visual Studio, open cryptest.sln (compatible with MSVC 2003 - 2015) and build the following projects as needed:

• cryptest Non-DLL-Import Configuration: Builds the full static library and a full test driver.
• cryptest DLL-Import Configuration: Builds a static library (containing only algorithms not in the DLL) and a test driver using both the DLL and static library.
• cryptdll: Builds the DLL.
• dlltest: Builds a sample application that uses only the DLL.

Note on DLL usage: To use the Crypto++ DLL, #include "dll.h" before any other Crypto++ headers. Place the DLL in the same directory as your .exe. The dll.h header includes #pragma comment(lib, "cryptopp") to handle the import library automatically.

Test data files are ASCII text files composed of independent sections separated by blank lines. Each section contains one or more tests and must include the following mandatory fields:

• AlgorithmType
• Name
• Source
• Test

Field Syntax Rules

• Field Structure: Each field consists of a fieldName: fieldBody.
• Multi-line Fields: If a field spans multiple lines, every line except the last must end with a backslash (\).
• Comments: Any text following a hash mark (#) on a line is treated as a comment and ignored.
• Multiple Tests: A section can contain multiple Test fields. The order is significant; a test uses the most recent occurrence of any given field name appearing before the Test field.

When using Crypto++ constructors, follow these ownership rules to avoid memory leaks or double-frees:

1. Pointer Constructors: If a constructor for class A takes a pointer to an object B (excluding primitive types like int or char), class A takes ownership of B and will delete it during its own destruction.
2. Reference Constructors: If a constructor for class A takes a reference to an object B, the caller retains ownership of B and must ensure B is not destroyed until A no longer requires it.

The Test field identifies which operation to perform. Common test types include:

• KeyPairValidAndConsistent: Validates that public and private keys are both valid and consistent with each other.
• PublicKeyInvalid: Validates that public key validation fails.
• PrivateKeyInvalid: Validates that private key validation fails.
• Verify: Validates that signature/digest/MAC verification passes.
• VerifyTruncated: Validates that truncated digest/MAC verification passes.
• NotVerify: Validates that signature/digest/MAC verification fails.
• DeterministicSign: Signs a message using a given seed; the resulting signature must match the provided signature.
• Encrypt: Validates that plaintext encrypts to the provided ciphertext.
• DecryptMatch: Validates that ciphertext decrypts back to the provided plaintext.

When defining field bodies, you can use the following data types:

• signed int: Small integers (less than 2^32) in decimal representation.
• unsigned long: Large integers (less than 2^64) compatible with strtoul or strtoull.
• string: Human-readable text.
• encoded string:
  • quoted string: "message" evaluates to message (without quotes or null terminator).
  • hex encoded string: 0x74657374 or 74657374 (e.g., evaluates to test).
  • repeated string: r<count> <value> (e.g., r100 "message" repeats the string 100 times, or r256 0x0011 repeats the hex value 256 times).