[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.1 Controlling the library | Controlling Libgcrypt's behaviour. | |
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 behaviour of Libgcrypt in several ways. Depending on cmd, more arguments can or have to be provided.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Libgcrypt supports the use of `extension modules', which implement algorithms in addition to those already built into the library directly.
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 successfuly, 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 thus 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] | [ ? ] |
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.
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.
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 diagnostical 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.
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.
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.
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.
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
errnor numbers.
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.
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.
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
.
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 Libgctypt is:
GPG_ERR_SOURCE_UNKNOWN
0
.
GPG_ERR_SOURCE_GPGME
GPG_ERR_SOURCE_GPG
GPG_ERR_SOURCE_GPGSM
GPG_ERR_SOURCE_GCRYPT
libgcrypt
, which is used by crypto engines
to perform cryptographic operations.
GPG_ERR_SOURCE_GPGAGENT
gpg-agent
, which is used by crypto
engines to perform operations with the secret key.
GPG_ERR_SOURCE_PINENTRY
pinentry
, which is used by
gpg-agent
to query the passphrase to unlock a secret key.
GPG_ERR_SOURCE_SCD
gpg-agent
to delegate operations with the secret key to a
SmartCard.
GPG_ERR_SOURCE_KEYBOX
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
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
GPG_ERR_NO_ERROR
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 occured, this is
generally not a problem.
GPG_ERR_GENERAL
GPG_ERR_ENOMEM
GPG_ERR_E...
GPG_ERR_INV_VALUE
GPG_ERR_UNUSABLE_PUBKEY
GPG_ERR_UNUSABLE_SECKEY
GPG_ERR_NO_DATA
GPG_ERR_CONFLICT
GPG_ERR_NOT_IMPLEMENTED
GPG_ERR_DECRYPT_FAILED
GPG_ERR_WRONG_KEY_USAGE
GPG_ERR_NO_SECKEY
GPG_ERR_UNSUPPORTED_ALGORITHM
GPG_ERR_BAD_SIGNATURE
GPG_ERR_NO_PUBKEY
GPG_ERR_USER_1
GPG_ERR_USER_2
...
GPG_ERR_USER_16
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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] | [ ? ] |