Appendix B How to solve problems

Everyone knows that software often does not do what it should do and thus there is a need to track down problems. This is in particular true for applications using a complex library like GPGME and of course also for the library itself. Here we give a few hints on how to solve such problems.

First of all you should make sure that the keys you want to use are installed in the GnuPG engine and are usable. Thus the first test is to run the desired operation using gpg or gpgsm on the command line. If you can’t figure out why things don’t work, you may use GPGME’s built in trace feature. This feature is either enabled using the environment variable GPGME_DEBUG or, if this is not possible, by calling the function gpgme_set_global_flag. The value is the trace level and an optional file name. If no file name is given the trace output is printed to stderr.

For example

GPGME_DEBUG=9:/home/user/mygpgme.log

(Note that under Windows you use a semicolon in place of the colon to separate the fields.)

A trace level of 9 is pretty verbose and thus you may want to start off with a lower level. The exact definition of the trace levels and the output format may change with any release; you need to check the source code for details. In any case the trace log should be helpful to understand what is going going on. Warning: The trace log may reveal sensitive details like passphrases or other data you use in your application. If you are asked to send a log file, make sure that you run your tests only with play data.

The trace function makes use of gpgrt’s logging function and thus the special socket:// and tcp:// files may be used. Because this conflicts with the use of colons to separate fields, the following hack is used: If the file name contains the string ^// all carets are replaced by colons. For example to log to TCP port 42042 this can be used:

GPGME_DEBUG=5:tcp^//127.0.0.1^42042