Crypto++: free C++ Class Library of Cryptographic Schemes Version 8.9 - October 1, 2023
Crypto++ Library is a free C++ class library of cryptographic schemes. Currently the library contains the following algorithms:
algorithm type nameauthenticated encryption schemes GCM, CCM, EAX, ChaCha20Poly1305 and XChaCha20Poly1305
high speed stream ciphers ChaCha (8/12/20), ChaCha (IETF), Panama, Salsa20,
Sosemanuk, XSalsa20, XChaCha20
AES and AES candidates AES (Rijndael), RC6, MARS, Twofish, Serpent,
CAST-256
ARIA, Blowfish, Camellia, CHAM, HIGHT, IDEA,
Kalyna (128/256/512), LEA, SEED, RC5, SHACAL-2,
other block ciphers SIMON (64/128), Skipjack, SPECK (64/128),
Simeck, SM4, Threefish (256/512/1024),
Triple-DES (DES-EDE2 and DES-EDE3), TEA, XTEAblock cipher modes of operation ECB, CBC, CBC ciphertext stealing (CTS), CFB, OFB, counter mode (CTR), XTS
message authentication codes BLAKE2s, BLAKE2b, CMAC, CBC-MAC, DMAC, GMAC, HMAC,
Poly1305, Poly1305 (IETF), SipHash, Two-Track-MAC,
VMAC
BLAKE2s, BLAKE2b, Keccack (F1600), LSH (256/512),
hash functions SHA-1, SHA-2 (224/256/384/512), SHA-3 (224/256),
SHA-3 (384/512), SHAKE (128/256), SipHash, SM3, Tiger,
RIPEMD (128/160/256/320), WHIRLPOOL
RSA, DSA, Deterministic DSA, ElGamal,
public-key cryptography Nyberg-Rueppel (NR), Rabin-Williams (RW), LUC,
LUCELG, EC-based German Digital Signature (ECGDSA),
DLIES (variants of DHAES), ESIGNpadding schemes for public-key PKCS#1 v2.0, OAEP, PSS, PSSR, IEEE P1363 systems EMSA2 and EMSA5
Diffie-Hellman (DH), Unified Diffie-Hellman (DH2),
key agreement schemes Menezes-Qu-Vanstone (MQV), Hashed MQV (HMQV),
Fully Hashed MQV (FHMQV), LUCDIF, XTR-DH
elliptic curve cryptography ECDSA, Deterministic ECDSA, ed25519, ECNR, ECIES,
ECDH, ECMQV, x25519
insecure or obsolescent MD2, MD4, MD5, Panama Hash, DES, ARC4, SEALalgorithms retained for backwards 3.0, WAKE-OFB, DESX (DES-XEX3), RC2, compatibility and historical SAFER, 3-WAY, GOST, SHARK, CAST-128, Square value
Other features include:
The Crypto++ library was originally written by Wei Dai. The library is now maintained by several team members and the community. You are welcome to use it for any purpose without paying anyone, but see License.txt for the fine print.
The following compilers are supported for this release. Please visit http://www.cryptopp.com the most up to date build instructions and porting notes.
Important Usage Notes
If a constructor for A takes a pointer to an object B (except primitive types such as int and char), then A owns B and will delete B at A's destruction. If a constructor for A takes a reference to an object B, then the caller retains ownership of B and should not destroy it until A no longer needs it.
Crypto++ is thread safe at the class level. This means you can use Crypto++ safely in a multithreaded application, but you must provide synchronization when multiple threads access a common Crypto++ object.
MSVC-Specific Information
To compile Crypto++ with MSVC, open "cryptest.sln" (for MSVC 2003 - 2015) and build one or more of the following projects:
cryptest Non-DLL-Import Configuration - This builds the full static library along with a full test driver. cryptest DLL-Import Configuration - This builds a static library containing only algorithms not in the DLL, along with a full test driver that uses both the DLL and the static library. cryptdll - This builds the DLL. Please note that if you wish to use Crypto++ as a FIPS validated module, you must use a pre-built DLL that has undergone the FIPS validation process instead of building your own. dlltest - This builds a sample application that only uses the DLL.
The DLL used to provide FIPS validated cryptography. The library was moved to the CMVP's Historical Validation List. The library and the DLL are no longer considered validated. You should no longer use the DLL.
To use the Crypto++ DLL in your application, #include "dll.h" before including any other Crypto++ header files, and place the DLL in the same directory as your .exe file. dll.h includes the line #pragma comment(lib, "cryptopp") so you don't have to explicitly list the import library in your project settings. To use a static library form of Crypto++, make the "cryptlib" project a dependency of your application project, or specify it as an additional library to link with in your project settings. In either case you should check the compiler options to make sure that the library and your application are using the same C++ run-time libraries and calling conventions.
DLL Memory Management
Because it's possible for the Crypto++ DLL to delete objects allocated by the calling application, they must use the same C++ memory heap. Three methods are provided to achieve this.
When Crypto++ attaches to a new process, it searches all modules loaded into the process space for exported functions "GetNewAndDeleteForCryptoPP" and "SetNewAndDeleteFromCryptoPP". If one of these functions is found, Crypto++ uses methods 1 or 2, respectively, by calling the function. Otherwise, method 3 is used.
Linux and Unix-like Specific Information
A makefile is included for you to compile Crypto++ with GCC and compatibles. Make sure you are using GNU Make and GNU ld. The make process will produce two files, libcryptopp.a and cryptest.exe. Run "cryptest.exe v" for the validation suite and "cryptest.exe tv all" for additional test vectors.
The makefile uses '-DNDEBUG -g2 -O2' CXXFLAGS by default. If you use an alternate build system, like Autotools or CMake, then ensure the build system includes '-DNDEBUG' for production or release builds. The Crypto++ library uses asserts for debugging and diagnostics during development; it does not rely on them to crash a program at runtime.
If an assert triggers in production software, then unprotected sensitive information could be egressed from the program to the filesystem or the platform's error reporting program, like Apport on Ubuntu or CrashReporter on Apple.
The makefile orders object files to help remediate problems associated with
C++ static initialization order. The library does not use custom linker scripts.
If you use an alternate build system, like Autotools or CMake, and collect source
files into a list, then ensure these three are at the head of the list: 'cryptlib.cpp
cpu.cpp integer.cpp
If your linker supports initialization attributes, like init_priority, then you can define CRYPTOPP_INIT_PRIORITY to control object initialization order. Set it to a value like 250. User programs can use CRYPTOPP_USER_PRIORITY to avoid conflicts with library values. Initialization attributes are more reliable than object file ordering, but its not ubiquitously supported by linkers.
The makefile links to the static version of the Crypto++ library to avoid binary planting and other LD_PRELOAD tricks. You should use the static version of the library in your programs to help avoid unwanted redirections.
Side Channel Attacks
Crypto++ attempts to resist side channel attacks using various remediations. The remediations are applied as a best effort but are probably incomplete. They are incomplete due to cpu speculation bugs like Spectre, Meltdown, Foreshadow. The attacks target both cpu caches and internal buffers. Intel generally refers to internal buffer attacks as "Microarchitectural Data Sampling" (MDS).
The library uses hardware instructions when possible for block ciphers, hashes and other operations. The hardware acceleration remediates some timing attacks. The library also uses cache-aware algorithms and access patterns to minimize leakage cache evictions.
Elliptic curves over binary fields are believed to leak information. The task is a work in progress. We don't believe binary fields are used in production, so we feel it is a low risk at the moment.
Crypto++ does not engage Specter remediations at this time. The GCC options for Specter are -mfunction-return=thunk and -mindirect-branch=thunk, and the library uses them during testing. If you want the Specter workarounds then add the GCC options to your CXXFLAGS when building the library.
To help resist attacks you should disable hyperthreading on cpus. If you suspect or find an information leak then please report it.
Documentation and Support
Crypto++ is documented through inline comments in header files, which are processed through Doxygen to produce an HTML reference manual. You can find a link to the manual from http://www.cryptopp.com. Also at that site is the Crypto++ FAQ, which you should browse through before attempting to use this library, because it will likely answer many of questions that may come up. Finally, the site provides the wiki which has many topics and code examples.
If you run into any problems, please try the Crypto++ mailing list. The subscription information and the list archive are available on http://www.cryptopp.com.
Source Code and Contributing
The source code and its planned changes are available at the following locations.
Contributions of all types are welcomed. Contributions include the following.
If you think you have found a bug in the library, then you should discuss it on the Users mailing list. Discussing it will help bring the issue to the attention of folks who can help resolve the issue. If you want to contribute a bug fix to the library, then make a Pull Request or make a Diff available somewhere. Also see Bug Reports on the wiki.
Features and enhancements are welcomed additions to the library. This category tends to be time consuming because algorithms and their test cases need to be reviewed and merged. Please be mindful of the test cases, and attempt to procure them from an independent source.
The library cherishes test scripts and test cases. They ensure the library is fit and they help uncover issues with the library before users experience them. If you have some time, then write some test cases, especially the ones that are intended to break things.
Branch and release testing is your chance to ensure Master (and planned merges) meets your expectations and perform as expected. If you have a few spare cycles, then please test Master on your favorite platform. We need more testing on MinGW, Windows Phone, Windows Store, Solaris 10 (and below), and modern iOS and OS X (including TV and Watch builds).
Documentation and updates includes both the inline source code annotations using Doxygen, and the online information provided in the wiki. The wiki is more verbose and usually provides more contextual information than the API reference. Besides testing, documentation is one of the highest returns on investment.
History
The items in this section comprise the most recent history. Please see History.txt for the record back to Crypto++ 1.0.
8.9.0 - October 1, 2023
8.8.0 - June 25, 2023
8.7.0 - August 7, 2022
8.6.0 - September 21, 2021
8.5.0 - March 7, 2021
8.4.0 - January 2, 2021
8.3.0 - December 20, 2020
8.2.0 - April 28, 2019
8.1.0 - February 22, 2019
8.0.0 - December 28, 2018
June 2015 - Changing of the guard. Wei Dai turned the library over to the community. The first community release was Crypto++ 5.6.3. Wei is no longer involved with the daily operations of the project. Wei still provides guidance when we have questions.
Originally written by Wei Dai, maintained by the Crypto++ Project