There are several places where someone finds information about how to trouble shoot
a crypto application problem.

TODO: link to the sections in the gpg4win compendium and other [[documentation]].

For problems with adele see EmailExercisesRobot.

<<TableOfContents(4)>>

== General

# If the problem is with GpgOL, try the operation with GpgEX or Kleopatra, to exclude Outlook's influence.
Note that **if GpgEX/Kleopatra works, you have a fallback solution to just work via files and send them by attachment**, so can can still use crypto, 
but with less comfort.
# If GUI frontend applications fail, try to do the operations on the command line. 
This way you can often exclude that the problem is within the frontend. 
And you sometimes get additional helpful messages.
# Look at or activate and look at additional diagnostic output. (http://gpg4win.de/doc/en/gpg4win-compendium_29.html, TODO link or refer to specific section in the official docs.)
There are many ways where additional output can be found or enabled.
# Try to reproduce, sometimes a different installation or a different computer gives 
you an idea about the difference between a running and a problem case.
# Precisely check the version numbers of components. 
# Check general operating or usage issues. Things like a full harddrive or wrong filesystem permissions.

== Decryption Failure with Gpg4win-3.1.2 or later

Starting with Gpg4win-3.1.2 the MDC message integrity mechanism, which has been
well established for over 15 years, is now enforced by GnuPG.
The reason for this was the public attention to attacks possible against messages without MDC
with the publication of "[[https://www.gpg4win.org/statement-efail.html|EFail]]".

In Gpg4win-3.1.2 the error is not well handled in the G~U~I. Leading only to a
"Decryption Failed" error. This will be improved in later versions.

You can fix the error by re-encrypting it. Afterwards it
can be used as usual in Kleopatra and will be integrity protected.

To decrypt it, even without an MDC, open the command line (see below for additional hints)
and decrypt your file like:
{{{
    gpg --ignore-mdc-error --decrypt "path_to_your_file"
}}}

Additionally to decrypting this will list the keyids of the recipients of that message,
which you can then use in the command to re-encrypt the message.

{{{
    gpg -r "recipient_keyid_1" -r "recipient_keyid_2" --encrypt "path_to_your_file"
}}}


== Hints / Tips

=== Checking the package integrity

If the downloaded package seems to be broken, please check the integrity of the downloaded package, by validating the checksum. You find a List of the checksums and a guide for *Nix systems [[https://gnupg.org/download/integrity_check.html|here]]. If you have a Windows System, open the terminal and compare the output of

"//certutil -hashfile FileToHash.exe sha1//"

to the ones on the site. Older Windows systems have to download a [[https://support.microsoft.com/en-us/kb/934576?spid=12925&sid=1569|Windows Patch]] which provides this functionality.


=== Command line operations
The manual of the GnuPG (crypto engine) will describe the command line usage in detail,
but for testing we give some simple commands here.

First you need to open the "cmd.exe" command line application in windows. 
Then you can type commands at the prompt. For good results, create a new directory and
change into it with {{{cd}}} and create or copy a testfile you can operate on for, example {{{hello.txt}}}.

An example to use your own key to sign something with CMS with double verbose output:
{{{
gpgsm.exe -vv --sign hello.txt >hello.p7s
}}}

An example to decrypt something with OpenPGP, no extra output
{{{
gpg --decrypt hello.gpg
}}}
and now with full diagnostic output (be careful when sharing with others, this may contain sensitive information),
usually you start with no diagnostic output, then add "-v"s and additional "--debug" options.
{{{
gpg --debug-all -vvv hello.gpg
}}}

==== Passphrase on the command line
The private key, which is protected by a passphrase, is handled by gpg-agent. This means that with GnuPG
2.1 adding {{{--passphrase}}} on the command line will no longer work out of the box.
If you really don't want a passphrase (you have it in a script or the command line history anyway) It is suggested to remove
the passphrase from that key. Other options are:

* Increase the cache timeout (e.g. put "default-cache-ttl 3600" into gpg-agent.conf
* [[https://gnupg.org/documentation/manuals/gnupg/gpg_002dpreset_002dpassphrase.html|gpg-preset-passphrase]]
/!\ Pay attention to the necessary gpg-agent config and how to find out about the {{{keygrip}}}. 
* Use the loopback feature to let the agent ask the invoking program for the passphrase instead of pinentry by adding "--pinentry-mode loopback" to the gpg invocation.

e.g.:
{{{
  gpg --pinentry-mode loopback --passphrase <yourpassphrase> -d <somefile>
}}}

=== Windows > 8 and Server 2012 Task Scheduler Problems

GnuPG uses (as suggested by Microsoft and usual) {{{%APPDATA%\gnupg}}} to store data on Windows. When launched from the Task Scheduler {{{%APPDATA%}}} is not always set to the correct users directory. (If you launch it with system privileges it is another place altogether). GnuPG as a result is unable to find the Keys or configuration in the directory Windows provides.

This is a known Windows bug. [[https://support.microsoft.com/en-us/kb/2968540|See the Knowledge Base article]] Or [[https://social.technet.microsoft.com/Forums/windowsserver/en-US/5e6dc56d-9069-42e3-a7e3-87437cf8ed81/scheduled-tasks-run-in-the-default-user-profile|This technet discussion]]

Instead of the Workaround mentioned in the knowledge base article GnuPG provides you with the option to set the Home directory as part of the command. (--homedir) Which makes it easy to workaround that bug.

For example:
{{{
  gpg --homedir c:\Users\aheinecke\AppData\Roaming\gnupg --encrypt -r <recipient> <file>
}}}

Would ignore the broken value of {{{%APPDATA%}}} and use the keys stored in {{{c:\Users\aheinecke\AppData\Roaming\gnupg}}} instead. Make sure access rights are set accordingly of course so that this works with the user the Scheduled task runs under.

=== GpgOL won't load in Outlook
First check that it is enabled under {{{File->Options->Add-Ins  Com-Add-Ins}}}.
If that does not work or it can't be enabled there:


Check in the Windows Registry that
{{{
HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\Addins\GNU.GpgOL LoadBehavior
}}}
is set to 3.

**In the following Registry Keys replace <~V~E~R~S~I~O~N> with your Outlook Version. The <~V~E~R~S~I~O~N> values are:**
* Outlook 2010: 14.0
* Outlook 2013: 15.0
* Outlook 2016: 16.0

Additionally, if they exist, delete all {{{REG_BINARY}}} Entries under:
{{{
HKEY_CURRENT_USER\Software\Microsoft\Office\<VERSION>\Outlook\Resiliency\DisabledItems
}}}

and

{{{
HKEY_CURRENT_USER\Software\Microsoft\Office\<VERSION>\Outlook\Resiliency\CrashingAddinList
}}}

Finally create the Registry Key:
{{{
HKEY_CURRENT_USER\Software\Microsoft\Office\<VERSION>\Outlook\Resiliency\DoNotDisableAddinList
}}}
And add a {{{REG_DWORD}}} entry with name {{{GNU.GpgOL}}} and value {{{1}}}.

=== GpgOL does not work
Check if you have one of the known [[GpgOL/IncompatibleAddons|incompatible Addons]].

=== Enable GpgOL debugging
GpgOL can log what it does internally. You might be asked for such a debug log to analyze a problem.

To enable it:

* Close Outlook
* Open regedit.exe and
* set {{{HKEY_CURRENT_USER\Software\GNU\GpgOL}}} {{{enableDebug}}} to either 1 or 1922
* set  {{{HKEY_CURRENT_USER\Software\GNU\GpgOL}}} {{{logFile}}} to some writeable file (e.g. c:\users\<youruser>\gpgol.txt )
* Open Outlook again and reproduce the problem, close it and you have a debug log..

The value of enableDebug -> If set to 1 it logs less and should not leak any private data except Mail Addresses. If set to 1922 the log will contain the plaintext of decrypted messages, so only use that if you have a test mail or some unconfidential mail.