1.7 Initializing the Library

The first step is the initialization of LibTMCG. The following function must be invoked early in your program, i.e., before you make use of any other capability of LibTMCG.

Function: bool init_libTMCG (const bool force_secmem =false, const bool gmp_secmem =false, const size_t max_secmem =32768)

The function checks whether the installed third-party libraries match their required versions. Further it initializes them and returns true, if everything was sound. Otherwise false is returned and an appropriate error message is sent to std::cerr.

The three optional arguments define the behaviour concerning the allocation of secure memory (i.e. memory that is not paged out to disk and that is overwritten by zeros before released) from libgcrypt. By default no secure memory is used. If force_secmem is true, than those parts of LibTMCG that use the GNU Crypto Library will allocate and use secure memory for private keys or other secrets. However, the most classes, algorithms, and protocols of LibTMCG does not respect this option yet, because they store their secrets with the GNU Multiple Precision Arithmetic Library. With the second option gmp_secmem the default memory allocator of this library is replaced to use secure memory. Unfortunately, there is no way to specify whether a big integer needs secure memory and thus all memory is allocated in this fashion. This may lead to out of memory aborts, because the allocated secure memory is limited (currently 32kB). The limit of libgcrypt can be adjusted by the third parameter max_secmem, however, probably there are restrictions of the operating system (cf. RLIMIT_MEMLOCK).

Additionally, the function version_libTMCG returns a string containing the version number of the library in a common format. It is strongly recommended to check, whether the installed version matches your requirements.

Function: const std::string version_libTMCG ()

This function returns the version of the library in the format major.minor.revision.

Last but not least, there is a function identifier_libTMCG which returns an identifier of LibTMCG including the version, copyright mark and license.

Function: const std::string identifier_libTMCG ()

This function returns an identifier of the library.