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

* Detecting problems in Gpg4win components by enabling diagnostic messages (log-files), section 23 of the compendium (v3.0.0): [[https://gpg4win.org/doc/en/gpg4win-compendium_29.html|English]]  
[[https://gpg4win.org/doc/de/gpg4win-compendium_29.html|Deutsch]]

TODO: link to relevant sections in 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 (see links at the top).
There are many places where additional output can be found or enabled.
# When you face problems while trying to get a public key it can be helpful to [[/DebugWithDirmngr|use the dirmngr]].
# 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.
# [[Gpg4win/RunAsUser|Run Gpg4win as user]], not as administrator.


== 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]]".

Since Gpg4win-3.1.3 Kleopatra offers to decrypt such messages anyway if they
were done using an old encryption algorithm. In that case you only need to click
on the decrypt anyway button. For messages that were encrypted using modern
algorithms but still don't use MDC there is a hard failure that will be shown
in diagnostics. Such new algo, no MDC, messages are supposed to be rare and
might be an indication of broken / insecure software or configuration.

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"
}}}

Alternatively only using Kleopatra you can also decrypt it with Gpg4win-3.1.1 and then encrypt it again after your key has been updated to ensure MDC is used (see below)

=== Update key to ensure MDC is used even by older versions

* In Kleopatra double click your key to open the details window.
* Open the edit expiry dialog (the pen button next to the expiry date).
* Close the dialog with OK (you don't need to change the actual expiry date).

== Can't sign files anymore

=== Possible Reason: Activated VS-NfD mode

{{kleopatra_vs_nfd_compliant_communication_not_possible.png}}

This error is shown when you use a version of Gpg4win which is not compliant to VS-NfD while the VS-NfD mode is activated.
There are two options to solve this issue:
*Get a VS-NfD-compliant version of Gpg4win called [[https://gnupg.com/gnupg-desktop.html|GnuPG VS-Desktop]]
*Enable a different mode in Gpg4win:
**Open Settings -> Configure Kleopatra... -> Crypto Operations
**On the bottom there is a drop down menu for the active GnuPG Profile. Here you select "default".

== 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}}}.

* Second check that it is correctly installed:
There should be a gpgol.dll under {{{c:\Program Files\Gpg4win\bin\gpgol.dll}}} or for 64bit Outlook {{{c:\Program Files (x86)\bin_64\gpgol.dll}}} there is a known issue (as of 3.1.7) that if Outlook is running while Gpg4win is updated and you install Gpg4win multiple times without restarting that the dll is not correctly installed.

If it is correctly installed and enabled:


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}}}.


You can also enable logging even if Outlook does not start by launching {{{c:\Program Files\Gpg4win\bin\gpgolconfig.exe}}} directly. This gives you the config dialog of Gpg4win with the usual debugging options.

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

== GpgOL: Not all attachments can be shown

{{gpgol_not_all_attachments_can_be_shown.png}}

=== Possible reason: Attachment too big

Outlook has a limit for the size of files. When you are using I~MAP or P~OP3 the limit is 20 MB. When you use an Exchange Server the limit depends on the settings of the server (default: 10 MB). 
\\\\If you try to read an encrypted email which contains a bigger file the message shown above appears. Microsoft published an [[https://docs.microsoft.com/en-us/outlook/troubleshoot/message-body/attachment-size-exceeds-the-allowable-limit-error|instruction]] to increase the limit in the registry editor.

== Hints / Tips

=== 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. 
(With {{{gpg --debug help}}} showing available choices to give after {{{--debug}}}.)
{{{
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>
}}}

=== 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.


=== Manually update GpgOL to a beta
Sometimes after reporting an issue on https://dev.gnupg.org you might be asked to install an updated GpgOL binary which contains a fix that should be tested, as it is sometimes impossible for the developers to reproduce the exact conditions for a problem.

The binaries can be found as HTTPS secured download under:
https://files.gpg4win.org/Beta/gpgol/

Look for the directory of the version you want to use and open it. In there you find the corresponding source code and two binaries.\\
The gpgol.dll in the top level binary is the 32 Bit version of GpgOL.\\
The gpgol.dll in the x64 sub directory is the 64 Bit version of GpgOL.

Which version you need depends on your Outlook Version. You can find out if you have a 32bit or 64bit outlook by looking at \\ {{{File -> Office Account -> Info about Microsoft Outlook}}}. \\
64 Bit versions have it noted at the top of the info window.

{{outlook-info.png}}

Once you have downloaded the correct version you need to *shutdown Outlook* and replace the gpgol.dll in the installation directory of Gpg4win. For the 64 bit version the gpgol.dll must be placed in the {{{bin_64}}} subfolder.

The default paths are:\\
{{{c:\Program Files (x86)\Gpg4win\bin\gpgol.dll}}} for 32 bit. \\
{{{c:\Program Files (x86)\Gpg4win\bin_64\gpgol.dll}}} for 64 bit. 

**General warning**: Beta versions are naturally less tested, than stable released versions.
They still may have critical defects. On the other hand, they may also have important defects fixed.
Depending on the need of your security level, you should estimate if it is okay to use a beta version for
your production environment with real keys. Rule of thumb, unless noted otherwise, we believe that
it is okay to use a beta version in production settings for normal security requirements
and as a precaution do should use it in high security environments or with highly sensitive key-material.


=== Antivirus reports on Gpg4win
See [[Gpg4win/AntiVirusSoftware]]

=== Disable Gpg4win update check and notification

To disable and hide the update check and notification of Gpg4win create a new file in the Gpg4win Installation directory in the subfolder "share". The file needs to have the name "kleopatrarc" and no file extension.

e.g.: {{{c:\program files\gpg4win\share\kleopatrarc}}}

The contents of the file should be:
{{{
[KDE Action Restrictions][$i]
action/help_check_updates=false

[UpdateNotification][$i]
NeverShow=true
}}}

=== Restoring corrupted Archives created by Kleopatra

Kleopatra before Version 3.1.6 had an issue that might have caused the creation of corrupted archives. [[https://dev.gnupg.org/T4332|T4332]] If you are affected get errors when extracting such an archive
the good news are: The data can be restored with some effort because there were only "bad blocks" added
and no data removed.

To repair such an Archive:
* Open it with a hex editor
* Search for blocks of 512 bytes or larger multiples of 512 which are all zero.
* Remove these blocks
* Try to extract again or use gpgtar --skip-crypto -t "damaged-archive.tar"

If you are in luck and your data does not naturally contain blocks of 512 zeros this should do the trick.
If your data can contain blocks of 512 zeros naturally, e.g. pdfs. It gets more complicated. In that case
your best bet is to look for "candidate blocks" remove them. Run gpgtar and check if the errors changed.

If you need assistance with that you can ask on one of the channels under: https://www.gpg4win.org/community.html