Migration from Crypto++ 8.9.0

cryptopp-modern is designed to be a drop-in replacement for Crypto++ 8.9.0. Most existing code will work without changes, but there are a few important differences to be aware of.

What’s Changed?

Version Numbering

The most significant change is the switch from traditional versioning to calendar versioning.

Crypto++ 8.9.0:

// Old version format: MAJOR.MINOR.PATCH
// Encoded as: (MAJOR * 100) + (MINOR * 10) + PATCH
int version = CRYPTOPP_VERSION;  // 890 for version 8.9.0
int major = version / 100;        // 8
int minor = (version / 10) % 10;  // 9
int patch = version % 10;         // 0

cryptopp-modern 2026.3.0:

// New version format: YEAR.MONTH.INCREMENT
// Encoded as: (YEAR * 10000) + (MONTH * 100) + INCREMENT
int version = CRYPTOPP_VERSION;   // 20260300 for 2026.3.0
int year = version / 10000;       // 2026
int month = (version / 100) % 100; // 3
int increment = version % 100;    // 0

Why Calendar Versioning?

The upstream Crypto++ project’s versioning scheme created a technical limitation:

Version 8.9.0 encodes to 890
Version 8.10.0 would theoretically encode to 8100, but the current system can’t represent it
Calendar versioning removes this limitation and provides clear release timing

Migration Impact

If your code checks the library version, you’ll need to update the parsing logic:

// Before (Crypto++ 8.9.0)
#if CRYPTOPP_VERSION >= 890
    // Use features from 8.9.0
#endif

// After (cryptopp-modern)
#if CRYPTOPP_VERSION >= 20260300  // 2026.3.0
    // Use features from 2026.3.0
#endif

// Better approach: Check for feature availability
#ifdef CRYPTOPP_BLAKE3_H
    // BLAKE3 is available
#endif

What Hasn’t Changed?

Namespace

The CryptoPP namespace remains unchanged:

// Still works exactly the same
CryptoPP::SHA256 hash;
CryptoPP::AES::Encryption enc;
CryptoPP::AutoSeededRandomPool prng;

Header Structure

All headers remain in the same location:

#include <cryptopp/sha.h>
#include <cryptopp/aes.h>
#include <cryptopp/rsa.h>
#include <cryptopp/osrng.h>
// All existing includes work unchanged

API Compatibility

All existing Crypto++ 8.9.0 APIs work identically:

// Encryption code from Crypto++ 8.9.0 works unchanged
CryptoPP::AutoSeededRandomPool prng;
CryptoPP::SecByteBlock key(CryptoPP::AES::DEFAULT_KEYLENGTH);
prng.GenerateBlock(key, key.size());

CryptoPP::GCM<CryptoPP::AES>::Encryption enc;
enc.SetKeyWithIV(key, key.size(), iv, iv.size());
// ... continues exactly the same

Build Process

The same build commands work:

# Linux/macOS
make
make install

# Windows (MinGW)
mingw32-make.exe

# Windows (Visual Studio)
# Open cryptest.sln and build

New Features

Post-Quantum Cryptography (2026.3.0)

cryptopp-modern includes NIST-standardized post-quantum algorithms:

ML-KEM (FIPS 203) — Module-Lattice Key Encapsulation (512/768/1024)
ML-DSA (FIPS 204) — Module-Lattice Digital Signatures (44/65/87)
SLH-DSA (FIPS 205) — Stateless Hash-Based Signatures (all 12 parameter sets)
X-Wing — Hybrid KEM combining X25519 + ML-KEM-768 (IETF draft)

#include <cryptopp/mlkem.h>

// Generate a key pair
CryptoPP::AutoSeededRandomPool rng;
CryptoPP::MLKEM768::Decapsulator decapsulator(rng);

// Encapsulate using the public key
CryptoPP::MLKEM768::Encapsulator encapsulator(
    decapsulator.GetKey().GetPublicKeyBytePtr(),
    decapsulator.GetKey().GetPublicKeySize());

CryptoPP::SecByteBlock ciphertext(encapsulator.CiphertextLength());
CryptoPP::SecByteBlock sharedSecret(encapsulator.SharedSecretLength());
encapsulator.Encapsulate(rng, ciphertext.begin(), sharedSecret.begin());

See the Post-Quantum documentation for details.

XAES-256-GCM (2026.1.0)

Extended-nonce AES-GCM with 256-bit nonces safe for random generation:

#include <cryptopp/xaes_256_gcm.h>

CryptoPP::XAES_256_GCM::Encryption enc;
enc.SetKeyWithIV(key, key.size(), nonce, 32);  // 32-byte nonce

AES-CTR-HMAC (2026.1.0)

Encrypt-then-MAC authenticated encryption with HKDF key derivation:

#include <cryptopp/aes_ctr_hmac.h>

CryptoPP::AES_CTR_HMAC<CryptoPP::AES, CryptoPP::SHA256>::Encryption enc;
enc.SetKeyWithIV(key, key.size(), iv, iv.size());

BLAKE3 Hash Function

#include <cryptopp/blake3.h>

CryptoPP::BLAKE3 hash;
std::string message = "Hello, cryptopp-modern!";
std::string digest;

CryptoPP::StringSource(message, true,
    new CryptoPP::HashFilter(hash,
        new CryptoPP::HexEncoder(
            new CryptoPP::StringSink(digest))));

See the BLAKE3 documentation for details.

Argon2 Password Hashing

#include <cryptopp/argon2.h>

CryptoPP::Argon2 argon2;
CryptoPP::SecByteBlock hash(32);

argon2.DeriveKey(
    hash, hash.size(),
    (const CryptoPP::byte*)password.data(), password.size(),
    salt, salt.size(),
    nullptr, 0, nullptr, 0,
    2,      // Time cost
    65536   // Memory cost (64 MB)
);

See the Argon2 documentation for details.

Security Fixes

CVE-2024-28285 (2026.2.0) — Hardened hybrid DL decryption against fault injection
DSA/ECDSA Fix (2026.2.1) — Fixed invalid signature generation in release builds

Source Code Organisation

The source code structure has been improved in cryptopp-modern:

Before (Crypto++ 8.9.0):

All 204+ source files in root directory
Difficult to navigate
No logical grouping

After (cryptopp-modern):

Files organized in src/ subdirectories:
- src/core/ - Core functionality
- src/hash/ - Hash functions
- src/symmetric/ - Symmetric encryption
- src/pubkey/ - Public key cryptography
- src/pqc/ - Post-quantum cryptography
- src/kdf/ - Key derivation
- And more…

Impact: None for library users. The include structure remains flat:

// Still use flat includes
#include <cryptopp/sha.h>      // Not <cryptopp/hash/sha.h>
#include <cryptopp/aes.h>      // Not <cryptopp/symmetric/aes.h>

Migration Checklist

For All Projects

Update version checking code (if any)
Test build with cryptopp-modern
Run existing test suite
Update dependencies in build files

Optional Enhancements

Consider using BLAKE3 instead of older hash functions
Upgrade password hashing to Argon2
Adopt post-quantum algorithms (ML-KEM, ML-DSA, SLH-DSA) for quantum resistance
Review and update deprecated algorithm usage

Step-by-Step Migration

1. Replace the Library

Linux/macOS:

# Remove old Crypto++ (if installed)
sudo make uninstall  # In Crypto++ directory

# Install cryptopp-modern
cd /tmp
wget https://github.com/cryptopp-modern/cryptopp-modern/releases/download/2026.3.0/cryptopp-modern-2026.3.0.zip
unzip cryptopp-modern-2026.3.0.zip -d cryptopp-modern
cd cryptopp-modern
make -j$(nproc)
sudo make install PREFIX=/usr/local
sudo ldconfig

Windows (MinGW):

# Download and extract cryptopp-modern-2026.3.0.zip
# Build
mingw32-make.exe -j$(nproc)

2. Update Version Checks

Before:

#if CRYPTOPP_VERSION >= 890
    // Feature available in 8.9.0+
#endif

After:

// Option 1: Update version number
#if CRYPTOPP_VERSION >= 20251100
    // Feature available in cryptopp-modern 2025.11.0+
#endif

// Option 2: Feature detection (better)
#ifdef CRYPTOPP_BLAKE3_H
    // BLAKE3 available
#endif

3. Test Your Application

# Rebuild your application
make clean
make

# Run tests
./run_tests

# Verify functionality
./your_app --test

4. Update Documentation

Update your project’s documentation to reflect the new library:

## Dependencies

- cryptopp-modern 2026.3.0 or later
  (formerly Crypto++ 8.9.0)

Common Migration Scenarios

Scenario 1: Basic Usage (No Changes Needed)

// This code works identically in both libraries
#include <cryptopp/sha.h>
#include <cryptopp/hex.h>

CryptoPP::SHA256 hash;
// ... use hash as before

Action: None required.

Scenario 2: Version-Dependent Code

// Before
#if CRYPTOPP_VERSION >= 890
    useNewFeature();
#else
    useOldFeature();
#endif

// After - Update version number
#if CRYPTOPP_VERSION >= 20251100
    useNewFeature();
#else
    useOldFeature();
#endif

Action: Update version constants.

Scenario 3: Version Display

// Before
std::cout << "Using Crypto++ " << CRYPTOPP_VERSION << std::endl;
// Output: Using Crypto++ 890

// After - Parse new format
int year = CRYPTOPP_VERSION / 10000;
int month = (CRYPTOPP_VERSION / 100) % 100;
int increment = CRYPTOPP_VERSION % 100;
std::cout << "Using cryptopp-modern " << year << "." << month << "." << increment << std::endl;
// Output: Using cryptopp-modern 2026.3.0

Action: Update version display logic.

Scenario 4: CMake Projects

# Before (Crypto++ 8.9.0)
find_package(cryptopp REQUIRED)
target_link_libraries(myapp cryptopp-static)

# After (cryptopp-modern)
find_package(cryptopp-modern REQUIRED)
target_link_libraries(myapp cryptopp::cryptopp)

Action: Update find_package() and target name.

Compatibility Notes

Binary Compatibility

cryptopp-modern maintains binary compatibility with Crypto++ 8.9.0:

Same ABI
Same class layouts
Same symbol names

You can typically replace the library without recompiling (though recompiling is recommended).

Source Compatibility

100% source compatible for all Crypto++ 8.9.0 APIs.

Deprecated Features

cryptopp-modern maintains deprecated features from Crypto++ 8.9.0 for compatibility, but new code should avoid:

SHA-1: Use SHA-256 or BLAKE3
MD5: Use SHA-256 or BLAKE3
DES/3DES: Use AES
RC4: Use ChaCha20

Rollback Plan

If you need to rollback to Crypto++ 8.9.0:

Linux/macOS:

# Uninstall cryptopp-modern
cd /path/to/cryptopp-modern
sudo make uninstall

# Reinstall Crypto++ 8.9.0
cd /path/to/cryptopp-890
sudo make install
sudo ldconfig

Windows: Simply rebuild with the old library files.

Getting Help

If you encounter migration issues:

Check the documentation: Review algorithm-specific pages
Search existing issues: GitHub Issues
Report problems: Open a new issue with:
- Code that worked in Crypto++ 8.9.0
- Error messages from cryptopp-modern
- Platform and compiler details

Benefits of Migration

Security

Regular security updates
Modern algorithms (BLAKE3, Argon2)
Post-quantum cryptography (ML-KEM, ML-DSA, SLH-DSA)
Faster patching of vulnerabilities

Performance

BLAKE3: Significantly faster than SHA-2 (AVX-512 parallel hashing)
Continued optimisations
Better multi-core utilisation

Maintenance

Active development
Regular releases
Community support

Future-Proofing

Post-quantum algorithms protect against quantum computer attacks
Calendar versioning removes version encoding limits
Clear upgrade path
Long-term sustainability

Conclusion

Migration from Crypto++ 8.9.0 to cryptopp-modern is straightforward:

Most code works unchanged
Update version parsing if needed
Optionally adopt new features (BLAKE3, Argon2, post-quantum algorithms)
Enjoy improved organisation and active maintenance

The effort is minimal, and the benefits are substantial.

Installation Quick Start