/usr/share/doc/libgcrypt11-doc/html/Controlling-the-library.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for Libgcrypt
(version 1.5.3, 17 December 2013),
which is GNU's library of cryptographic building blocks.

Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version. The text of the license can be found in the
section entitled "GNU General Public License". -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The Libgcrypt Reference Manual: Controlling the library</title>

<meta name="description" content="The Libgcrypt Reference Manual: Controlling the library">
<meta name="keywords" content="The Libgcrypt Reference Manual: Controlling the library">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Generalities.html#Generalities" rel="up" title="Generalities">
<link href="Modules.html#Modules" rel="next" title="Modules">
<link href="Generalities.html#Generalities" rel="prev" title="Generalities">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Controlling-the-library"></a>
<div class="header">
<p>
Next: <a href="Modules.html#Modules" accesskey="n" rel="next">Modules</a>, Up: <a href="Generalities.html#Generalities" accesskey="u" rel="up">Generalities</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Controlling-the-library-1"></a>
<h3 class="section">3.1 Controlling the library</h3>

<dl>
<dt><a name="index-gcry_005fcontrol"></a>Function: <em>gcry_error_t</em> <strong>gcry_control</strong> <em>(enum gcry_ctl_cmds <var>cmd</var>, ...)</em></dt>
<dd>
<p>This function can be used to influence the general behavior of
Libgcrypt in several ways.  Depending on <var>cmd</var>, more
arguments can or have to be provided.
</p>
<dl compact="compact">
<dt><code>GCRYCTL_ENABLE_M_GUARD; Arguments: none</code></dt>
<dd><p>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 before
<code>gcry_check_version</code>.  Note that the memory guard is NOT used
when the user of the library has set his own memory management
callbacks.
</p>
</dd>
<dt><code>GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none</code></dt>
<dd><p>This command inhibits the use the very secure random quality level
(<code>GCRY_VERY_STRONG_RANDOM</code>) and degrades all request down to
<code>GCRY_STRONG_RANDOM</code>.  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.
</p>
<p>This option can only be used at initialization time.
</p>

</dd>
<dt><code>GCRYCTL_DUMP_RANDOM_STATS; Arguments: none</code></dt>
<dd><p>This command dumps randum number generator related statistics to the
library&rsquo;s logging stream.
</p>
</dd>
<dt><code>GCRYCTL_DUMP_MEMORY_STATS; Arguments: none</code></dt>
<dd><p>This command dumps memory managment related statistics to the library&rsquo;s
logging stream.
</p>
</dd>
<dt><code>GCRYCTL_DUMP_SECMEM_STATS; Arguments: none</code></dt>
<dd><p>This command dumps secure memory manamgent related statistics to the
library&rsquo;s logging stream.
</p>
</dd>
<dt><code>GCRYCTL_DROP_PRIVS; Arguments: none</code></dt>
<dd><p>This command disables the use of secure memory and drops the priviliges
of the current process.  This command has not much use; the suggested way
to disable secure memory is to use <code>GCRYCTL_DISABLE_SECMEM</code> right
after initialization.
</p>
</dd>
<dt><code>GCRYCTL_DISABLE_SECMEM; Arguments: none</code></dt>
<dd><p>This command disables the use of secure memory.  If this command is
used in FIPS mode, FIPS mode will be disabled and the function
<code>gcry_fips_mode_active</code> returns false.  However, in Enforced FIPS
mode this command has no effect at all.
</p>
<p>Many applications do not require secure memory, so they should disable
it right away.  This command should be executed right after
<code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_INIT_SECMEM; Arguments: int nbytes</code></dt>
<dd><p>This command is used to allocate a pool of secure memory and thus
enabling the use of secure memory.  It also drops all extra privileges
the process has (i.e. if it is run as setuid (root)).  If the argument
<var>nbytes</var> is 0, secure memory will be disabled.  The minimum amount
of secure memory allocated is currently 16384 bytes; you may thus use a
value of 1 to request that default size.
</p>
</dd>
<dt><code>GCRYCTL_TERM_SECMEM; Arguments: none</code></dt>
<dd><p>This command zeroises the secure memory and destroys the handler.  The
secure memory pool may not be used anymore after running this command.
If the secure memory pool as already been destroyed, this command has
no effect.  Applications might want to run this command from their
exit handler to make sure that the secure memory gets properly
destroyed.  This command is not necessarily thread-safe but that
should not be needed in cleanup code.  It may be called from a signal
handler.
</p>
</dd>
<dt><code>GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none</code></dt>
<dd><p>Disable warning messages about problems with the secure memory
subsystem. This command should be run right after
<code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none</code></dt>
<dd><p>Postpone warning messages from the secure memory subsystem.
See <a href="Initializing-the-library.html#sample_002duse_002dsuspend_002dsecmem">the initialization example</a>, on how to
use it.
</p>
</dd>
<dt><code>GCRYCTL_RESUME_SECMEM_WARN; Arguments: none</code></dt>
<dd><p>Resume warning messages from the secure memory subsystem.
See <a href="Initializing-the-library.html#sample_002duse_002dresume_002dsecmem">the initialization example</a>, on how to
use it.
</p>
</dd>
<dt><code>GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none</code></dt>
<dd><p>This command tells the PRNG to store random numbers in secure memory.
This command should be run right after <code>gcry_check_version</code> and not
later than the command GCRYCTL_INIT_SECMEM.  Note that in FIPS mode the
secure memory is always used.
</p>
</dd>
<dt><code>GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename</code></dt>
<dd><p>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&rsquo;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&rsquo;s content into the seed
file with the following command.
</p>

</dd>
<dt><code>GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none</code></dt>
<dd><p>Write out the PRNG pool&rsquo;s content into the registered seed file.
</p>
<p>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 a perfect
attack scenario, the attacker can control (or at least guess) the PID
and clock of the application, and drain the system&rsquo;s entropy pool to
reduce the &quot;up to 16 bytes&quot; 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 <code>GCRY_VERY_STRONG_RANDOM</code> quality is
requested as in this case enough extra entropy gets mixed.  It is also
not an issue when using Linux (rndlinux driver), because this one
guarantees to read full 16 bytes from /dev/urandom and thus there is no
way for an attacker without kernel access to control these 16 bytes.
</p>
</dd>
<dt><code>GCRYCTL_SET_VERBOSITY; Arguments: int level</code></dt>
<dd><p>This command sets the verbosity of the logging.  A level of 0 disables
all extra logging whereas positive numbers enable more verbose logging.
The level may be changed at any time but be aware that no memory
synchronization is done so the effect of this command might not
immediately show up in other threads.  This command may even be used
prior to <code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags</code></dt>
<dd><p>Set the debug flag bits as given by the argument.  Be aware that that no
memory synchronization is done so the effect of this command might not
immediately show up in other threads.  The debug flags are not
considered part of the API and thus may change without notice.  As of
now bit 0 enables debugging of cipher functions and bit 1 debugging of
multi-precision-integers.  This command may even be used prior to
<code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags</code></dt>
<dd><p>Set the debug flag bits as given by the argument.  Be aware that that no
memory synchronization is done so the effect of this command might not
immediately show up in other threads.  This command may even be used
prior to <code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none</code></dt>
<dd><p>This command does nothing.  It exists only for backward compatibility.
</p>
</dd>
<dt><code>GCRYCTL_ANY_INITIALIZATION_P; Arguments: none</code></dt>
<dd><p>This command returns true if the library has been basically initialized.
Such a basic initialization happens implicitly with many commands to get
certain internal subsystems running.  The common and suggested way to
do this basic intialization is by calling gcry_check_version.
</p>
</dd>
<dt><code>GCRYCTL_INITIALIZATION_FINISHED; Arguments: none</code></dt>
<dd><p>This command tells the library that the application has finished the
intialization.
</p>
</dd>
<dt><code>GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none</code></dt>
<dd><p>This command returns true if the command<br>
GCRYCTL_INITIALIZATION_FINISHED has already been run.
</p>
</dd>
<dt><code>GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops</code></dt>
<dd><p>This command registers a thread-callback structure.
See <a href="Multi_002dThreading.html#Multi_002dThreading">Multi-Threading</a>.
</p>
</dd>
<dt><code>GCRYCTL_FAST_POLL; Arguments: none</code></dt>
<dd><p>Run a fast random poll.
</p>
</dd>
<dt><code>GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename</code></dt>
<dd><p>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.
</p>
<p>EGD is an alternative random gatherer, used only on systems lacking a
proper random device.
</p>
</dd>
<dt><code>GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream</code></dt>
<dd><p>This command dumps information pertaining to the configuration of the
library to the given stream.  If NULL is given for <var>stream</var>, the log
system is used.  This command may be used before the intialization has
been finished but not before a <code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_OPERATIONAL_P; Arguments: none</code></dt>
<dd><p>This command returns true if the library is in an operational state.
This information makes only sense in FIPS mode.  In contrast to other
functions, this is a pure test function and won&rsquo;t put the library into
FIPS mode or change the internal state.  This command may be used before
the intialization has been finished but not before a <code>gcry_check_version</code>.
</p>
</dd>
<dt><code>GCRYCTL_FIPS_MODE_P; Arguments: none</code></dt>
<dd><p>This command returns true if the library is in FIPS mode.  Note, that
this is no indication about the current state of the library.  This
command may be used before the intialization has been finished but not
before a <code>gcry_check_version</code>.  An application may use this command or
the convenience macro below to check whether FIPS mode is actually
active.
</p>
<dl>
<dt><a name="index-gcry_005ffips_005fmode_005factive"></a>Function: <em>int</em> <strong>gcry_fips_mode_active</strong> <em>(void)</em></dt>
<dd>
<p>Returns true if the FIPS mode is active.  Note that this is
implemented as a macro.
</p></dd></dl>



</dd>
<dt><code>GCRYCTL_FORCE_FIPS_MODE; Arguments: none</code></dt>
<dd><p>Running this command puts the library into FIPS mode.  If the library is
already in FIPS mode, a self-test is triggered and thus the library will
be put into operational state.  This command may be used before a call
to <code>gcry_check_version</code> and that is actually the recommended way to let an
application switch the library into FIPS mode.  Note that Libgcrypt will
reject an attempt to switch to fips mode during or after the intialization.
</p>
</dd>
<dt><code>GCRYCTL_SET_ENFORCED_FIPS_FLAG; Arguments: none</code></dt>
<dd><p>Running this command sets the internal flag that puts the library into
the enforced FIPS mode during the FIPS mode initialization.  This command
does not affect the library if the library is not put into the FIPS mode and
it must be used before any other libgcrypt library calls that initialize
the library such as <code>gcry_check_version</code>. Note that Libgcrypt will
reject an attempt to switch to the enforced fips mode during or after
the intialization.
</p>
</dd>
<dt><code>GCRYCTL_SELFTEST; Arguments: none</code></dt>
<dd><p>This may be used at anytime to have the library run all implemented
self-tests.  It works in standard and in FIPS mode.  Returns 0 on
success or an error code on failure.
</p>
</dd>
<dt><code>GCRYCTL_DISABLE_HWF; Arguments: const char *name</code></dt>
<dd>
<p>Libgcrypt detects certain features of the CPU at startup time.  For
performace tests it is sometimes required not to use such a feature.
This option may be used to disabale a certain feature; i.e. Libgcrypt
behaves as if this feature has not been detected.  Note that the
detection code might be run if the feature has been disabled.  This
command must be used at initialization time; i.e. before calling
<code>gcry_check_version</code>.
</p>
</dd>
</dl>

</dd></dl>

<hr>
<div class="header">
<p>
Next: <a href="Modules.html#Modules" accesskey="n" rel="next">Modules</a>, Up: <a href="Generalities.html#Generalities" accesskey="u" rel="up">Generalities</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
libgcrypt11-doc 1.5.3-2ubuntu4 / usr / share / doc / libgcrypt11-doc / html / Controlling-the-library.html
