[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.1 Controlling the library | Controlling Libgcrypt's behavior. | |
3.2 Modules | Description of extension modules. | |
3.3 Error Handling | Error codes and such. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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; Arguments: none
This command dumps randum number generator related statistics to the library's logging stream.
GCRYCTL_DUMP_MEMORY_STATS; Arguments: none
This command dumps memory managment related statistics to the library's logging stream.
GCRYCTL_DUMP_SECMEM_STATS; Arguments: none
This command dumps secure memory manamgent related statistics to the library's logging stream.
GCRYCTL_DROP_PRIVS; Arguments: none
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 GCRYCTL_DISABLE_SECMEM
right
after initialization.
GCRYCTL_DISABLE_SECMEM; Arguments: none
This command disables the use of secure memory. If this command is
used in FIPS mode, FIPS mode will be disabled and the function
gcry_fips_mode_active
returns false. However, in Enforced FIPS
mode this command has no effect at all.
Many applications do not require secure memory, so they should disable
it right away. This command should be executed right after
gcry_check_version
.
GCRYCTL_INIT_SECMEM; Arguments: int nbytes
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 nbytes 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.
GCRYCTL_TERM_SECMEM; Arguments: none
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.
GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none
Disable warning messages about problems with the secure memory
subsystem. This command should be run right after
gcry_check_version
.
GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
Postpone warning messages from the secure memory subsystem. See the initialization example, on how to use it.
GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
Resume warning messages from the secure memory subsystem. See the initialization example, on how to use it.
GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none
This command tells the PRNG to store random numbers in secure memory.
This command should be run right after gcry_check_version
and not
later than the command GCRYCTL_INIT_SECMEM. Note that in FIPS mode the
secure memory is always used.
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 a perfect
attack 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. 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.
GCRYCTL_SET_VERBOSITY; Arguments: int level
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 gcry_check_version
.
GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags
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
gcry_check_version
.
GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags
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 gcry_check_version
.
GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none
This command does nothing. It exists only for backward compatibility.
GCRYCTL_ANY_INITIALIZATION_P; Arguments: none
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.
GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
This command tells the libray that the application has finished the intialization.
GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
This command returns true if the command
GCRYCTL_INITIALIZATION_FINISHED has already been run.
GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops
This command registers a thread-callback structure. See section Multi-Threading.
GCRYCTL_FAST_POLL; Arguments: none
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 systems lacking a proper random device.
GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream
This command dumps information pertaining to the configuration of the library to the given stream. If NULL is given for stream, the log system is used. This command may be used before the intialization has been finished but not before a gcry_version_check.
GCRYCTL_OPERATIONAL_P; Arguments: none
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'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 gcry_version_check.
GCRYCTL_FIPS_MODE_P; Arguments: none
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 gcry_version_check. An application may use this command or the convenience macro below to check whether FIPS mode is actually active.
Returns true if the FIPS mode is active. Note that this is implemented as a macro.
GCRYCTL_FORCE_FIPS_MODE; Arguments: none
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 gcry_check_version 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.
GCRYCTL_SELFTEST; Arguments: none
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Libgcrypt supports the use of `extension modules', which implement algorithms in addition to those already built into the library directly.
This data type represents a `module'.
Functions registering modules provided by the user take a `module
specification structure' as input and return a value of
gcry_module_t
and an ID that is unique in the modules'
category. This ID can be used to reference the newly registered
module. After registering a module successfully, the new functionality
should be able to be used through the normal functions provided by
Libgcrypt until it is unregistered again.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Many functions in Libgcrypt can return an error if they fail. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and cancelling the operation.
Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly. For example, if you try to decrypt a tempered message, the decryption will fail. Another error value actually means that the end of a data buffer or list has been reached. The following descriptions explain for many error codes what they mean usually. Some error values have specific meanings if returned by a certain functions. Such cases are described in the documentation of those functions.
Libgcrypt uses the libgpg-error
library. This allows to share
the error codes with other components of the GnuPG system, and to pass
error values transparently from the crypto engine, or some helper
application of the crypto engine, to the user. This way no
information is lost. As a consequence, Libgcrypt does not use its own
identifiers for error codes, but uses those provided by
libgpg-error
. They usually start with GPG_ERR_
.
However, Libgcrypt does provide aliases for the functions defined in libgpg-error, which might be preferred for name space consistency.
Most functions in Libgcrypt return an error code in the case of failure. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and canceling the operation.
Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly.
GnuPG components, including Libgcrypt, use an extra library named libgpg-error to provide a common error handling scheme. For more information on libgpg-error, see the according manual.
3.3.1 Error Values | The error value and what it means. | |
3.3.2 Error Sources | A list of important error sources. | |
3.3.3 Error Codes | A list of important error codes. | |
3.3.4 Error Strings | How to get a descriptive string from a value. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The gcry_err_code_t
type is an alias for the
libgpg-error
type gpg_err_code_t
. The error code
indicates the type of an error, or the reason why an operation failed.
A list of important error codes can be found in the next section.
The gcry_err_source_t
type is an alias for the
libgpg-error
type gpg_err_source_t
. The error source
has not a precisely defined meaning. Sometimes it is the place where
the error happened, sometimes it is the place where an error was
encoded into an error value. Usually the error source will give an
indication to where to look for the problem. This is not always true,
but it is attempted to achieve this goal.
A list of important error sources can be found in the next section.
The gcry_error_t
type is an alias for the libgpg-error
type gpg_error_t
. An error value like this has always two
components, an error code and an error source. Both together form the
error value.
Thus, the error value can not be directly compared against an error
code, but the accessor functions described below must be used.
However, it is guaranteed that only 0 is used to indicate success
(GPG_ERR_NO_ERROR
), and that in this case all other parts of
the error value are set to 0, too.
Note that in Libgcrypt, the error source is used purely for diagnostic purposes. Only the error code should be checked to test for a certain outcome of a function. The manual only documents the error code part of an error value. The error source is left unspecified and might be anything.
The static inline function gcry_err_code
returns the
gcry_err_code_t
component of the error value err. This
function must be used to extract the error code from an error value in
order to compare it with the GPG_ERR_*
error code macros.
The static inline function gcry_err_source
returns the
gcry_err_source_t
component of the error value err. This
function must be used to extract the error source from an error value in
order to compare it with the GPG_ERR_SOURCE_*
error source macros.
The static inline function gcry_err_make
returns the error
value consisting of the error source source and the error code
code.
This function can be used in callback functions to construct an error value to return it to the library.
The static inline function gcry_error
returns the error value
consisting of the default error source and the error code code.
For GCRY applications, the default error source is
GPG_ERR_SOURCE_USER_1
. You can define
GCRY_ERR_SOURCE_DEFAULT
before including ‘gcrypt.h’ to
change this default.
This function can be used in callback functions to construct an error value to return it to the library.
The libgpg-error
library provides error codes for all system
error numbers it knows about. If err is an unknown error
number, the error code GPG_ERR_UNKNOWN_ERRNO
is used. The
following functions can be used to construct error values from system
errno numbers.
The function gcry_err_make_from_errno
is like
gcry_err_make
, but it takes a system error like errno
instead of a gcry_err_code_t
error code.
The function gcry_error_from_errno
is like gcry_error
,
but it takes a system error like errno
instead of a
gcry_err_code_t
error code.
Sometimes you might want to map system error numbers to error codes directly, or map an error code representing a system error back to the system error number. The following functions can be used to do that.
The function gcry_err_code_from_errno
returns the error code
for the system error err. If err is not a known system
error, the function returns GPG_ERR_UNKNOWN_ERRNO
.
The function gcry_err_code_to_errno
returns the system error
for the error code err. If err is not an error code
representing a system error, or if this system error is not defined on
this system, the function returns 0
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The library libgpg-error
defines an error source for every
component of the GnuPG system. The error source part of an error
value is not well defined. As such it is mainly useful to improve the
diagnostic error message for the user.
If the error code part of an error value is 0
, the whole error
value will be 0
. In this case the error source part is of
course GPG_ERR_SOURCE_UNKNOWN
.
The list of error sources that might occur in applications using Libgcrypt is:
GPG_ERR_SOURCE_UNKNOWN
The error source is not known. The value of this error source is
0
.
GPG_ERR_SOURCE_GPGME
The error source is GPGME itself.
GPG_ERR_SOURCE_GPG
The error source is GnuPG, which is the crypto engine used for the OpenPGP protocol.
GPG_ERR_SOURCE_GPGSM
The error source is GPGSM, which is the crypto engine used for the OpenPGP protocol.
GPG_ERR_SOURCE_GCRYPT
The error source is libgcrypt
, which is used by crypto engines
to perform cryptographic operations.
GPG_ERR_SOURCE_GPGAGENT
The error source is gpg-agent
, which is used by crypto
engines to perform operations with the secret key.
GPG_ERR_SOURCE_PINENTRY
The error source is pinentry
, which is used by
gpg-agent
to query the passphrase to unlock a secret key.
GPG_ERR_SOURCE_SCD
The error source is the SmartCard Daemon, which is used by
gpg-agent
to delegate operations with the secret key to a
SmartCard.
GPG_ERR_SOURCE_KEYBOX
The error source is libkbx
, a library used by the crypto
engines to manage local keyrings.
GPG_ERR_SOURCE_USER_1
GPG_ERR_SOURCE_USER_2
GPG_ERR_SOURCE_USER_3
GPG_ERR_SOURCE_USER_4
These error sources are not used by any GnuPG component and can be
used by other software. For example, applications using
Libgcrypt can use them to mark error values coming from callback
handlers. Thus GPG_ERR_SOURCE_USER_1
is the default for errors
created with gcry_error
and gcry_error_from_errno
,
unless you define GCRY_ERR_SOURCE_DEFAULT
before including
‘gcrypt.h’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The library libgpg-error
defines many error values. The
following list includes the most important error codes.
GPG_ERR_EOF
This value indicates the end of a list, buffer or file.
GPG_ERR_NO_ERROR
This value indicates success. The value of this error code is
0
. Also, it is guaranteed that an error value made from the
error code 0
will be 0
itself (as a whole). This means
that the error source information is lost for this error code,
however, as this error code indicates that no error occurred, this is
generally not a problem.
GPG_ERR_GENERAL
This value means that something went wrong, but either there is not enough information about the problem to return a more useful error value, or there is no separate error value for this type of problem.
GPG_ERR_ENOMEM
This value means that an out-of-memory condition occurred.
GPG_ERR_E...
System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for the system error.
GPG_ERR_INV_VALUE
This value means that some user provided data was out of range.
GPG_ERR_UNUSABLE_PUBKEY
This value means that some recipients for a message were invalid.
GPG_ERR_UNUSABLE_SECKEY
This value means that some signers were invalid.
GPG_ERR_NO_DATA
This value means that data was expected where no data was found.
GPG_ERR_CONFLICT
This value means that a conflict of some sort occurred.
GPG_ERR_NOT_IMPLEMENTED
This value indicates that the specific function (or operation) is not implemented. This error should never happen. It can only occur if you use certain values or configuration options which do not work, but for which we think that they should work at some later time.
GPG_ERR_DECRYPT_FAILED
This value indicates that a decryption operation was unsuccessful.
GPG_ERR_WRONG_KEY_USAGE
This value indicates that a key is not used appropriately.
GPG_ERR_NO_SECKEY
This value indicates that no secret key for the user ID is available.
GPG_ERR_UNSUPPORTED_ALGORITHM
This value means a verification failed because the cryptographic algorithm is not supported by the crypto backend.
GPG_ERR_BAD_SIGNATURE
This value means a verification failed because the signature is bad.
GPG_ERR_NO_PUBKEY
This value means a verification failed because the public key is not available.
GPG_ERR_NOT_OPERATIONAL
This value means that the library is not yet in state which allows to use this function. This error code is in particular returned if Libgcrypt is operated in FIPS mode and the internal state of the library does not yet or not anymore allow the use of a service.
This error code is only available with newer libgpg-error versions, thus
you might see “invalid error code” when passing this to
gpg_strerror
. The numeric value of this error code is 176.
GPG_ERR_USER_1
GPG_ERR_USER_2
...
GPG_ERR_USER_16
These error codes are not used by any GnuPG component and can be freely used by other software. Applications using Libgcrypt might use them to mark specific errors returned by callback handlers if no suitable error codes (including the system errors) for these errors exist already.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The function gcry_strerror
returns a pointer to a statically
allocated string containing a description of the error code contained
in the error value err. This string can be used to output a
diagnostic message to the user.
The function gcry_strerror
returns a pointer to a statically
allocated string containing a description of the error source
contained in the error value err. This string can be used to
output a diagnostic message to the user.
The following example illustrates the use of the functions described above:
{ gcry_cipher_hd_t handle; gcry_error_t err = 0; err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0); if (err) { fprintf (stderr, "Failure: %s/%s\n", gcry_strsource (err), gcry_strerror (err)); } } |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on November, 19 2009 using texi2html 1.78.