— Function: gcry_error_t gcry_control (enum gcry_ctl_cmds cmd, ...)

This function can be used to influence the general behavior of Libgcrypt in several ways. Depending on cmd, more arguments can or have to be provided.

GCRYCTL_ENABLE_M_GUARD; Arguments: none

This command enables the built-in memory guard. It must not be used to activate the memory guard after the memory management has already been used; therefore it can ONLY be used at initialization time. Note that the memory guard is NOT used when the user of the library has set his own memory management callbacks.

GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none

This command inhibits the use the very secure random quality level (GCRY_VERY_STRONG_RANDOM) and degrades all request down to GCRY_STRONG_RANDOM. In general this is not recommened. However, for some applications the extra quality random Libgcrypt tries to create is not justified and this option may help to get better performace. Please check with a crypto expert whether this option can be used for your application.

This option can only be used at initialization time.

GCRYCTL_DUMP_RANDOM_STATS

This command dumps PRNG related statistics to the librarys logging stream.

GCRYCTL_DUMP_MEMORY_STATS

This command dumps memory manamgent related statistics to the librarys logging stream.

GCRYCTL_DUMP_SECMEM_STATS

This command dumps secure memory manamgent related statistics to the librarys logging stream.

GCRYCTL_DUMP_CONFIG; Arguments: none

This command dumps information pertaining to the configuration of libgcrypt to the logging stream. It may be used before the intialization has been finished but not before a gcry_version_check.

GCRYCTL_DROP_PRIVS

This command disables the use of secure memory and drops the priviliges of the current process. FIXME.

GCRYCTL_DISABLE_SECMEM

This command disables the use of secure memory. FIXME.

GCRYCTL_INIT_SECMEM

GCRYCTL_TERM_SECMEM

GCRYCTL_DISABLE_SECMEM_WARN

GCRYCTL_SUSPEND_SECMEM_WARN

GCRYCTL_RESUME_SECMEM_WARN

GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none

This command tells the PRNG to store random numbers in secure memory. FIXME: what about initialization time?

GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename

This command specifies the file, which is to be used as seed file for the PRNG. If the seed file is registered prior to initialization of the PRNG, the seed file's content (if it exists and seems to be valid) is fed into the PRNG pool. After the seed file has been registered, the PRNG can be signalled to write out the PRNG pool's content into the seed file with the following command.

GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none

Write out the PRNG pool's content into the registered seed file.

Multiple instances of the applications sharing the same random seed file can be started in parallel, in which case they will read out the same pool and then race for updating it (the last update overwrites earlier updates). They will differentiate only by the weak entropy that is added in read_seed_file based on the PID and clock, and up to 16 bytes of weak random non-blockingly. The consequence is that the output of these different instances is correlated to some extent. In the perfect scenario, the attacker can control (or at least guess) the PID and clock of the application, and drain the system's entropy pool to reduce the "up to 16 bytes" above to 0. Then the dependencies of the inital states of the pools are completely known. Note that this is not an issue if random of GCRY_VERY_STRONG_RANDOM quality is requested as in this case enough extra entropy gets mixed.

GCRYCTL_SET_VERBOSITY

GCRYCTL_SET_DEBUG_FLAGS

GCRYCTL_CLEAR_DEBUG_FLAGS

GCRYCTL_DISABLE_INTERNAL_LOCKING

GCRYCTL_ANY_INITIALIZATION_P

GCRYCTL_INITIALIZATION_FINISHED_P

GCRYCTL_INITIALIZATION_FINISHED

GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops

This command registers a thread-callback structure. See section “multi threading” for more information on this command.

GCRYCTL_FAST_POLL

Run a fast random poll.

GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename

This command may be used to override the default name of the EGD socket to connect to. It may be used only during initialization as it is not thread safe. Changing the socket name again is not supported. The function may return an error if the given filename is too long for a local socket name.

EGD is an alternative random gatherer, used only on a few systems.