How to Decrypt Files Using GPG

This help file is intended to give more detailed, platform-specific instructions on how to decrypt files using GNU Privacy Guard (GPG) for those that need it.

First, some background: File encryption is required by U.S. Federal law when transmitting the proprietary information utilized in peer reviews. We have endeavored to make this process as simple as possible while using free software that is supported on all popular OS platforms, but we recognize that it is obviously not as easy as it could be. Please accept our apologies for the inconvenience and our thanks for the additional time and effort it takes to decrypt these files.

Windows

  1. First, download and install the latest version of GPG4Win. You will need administrator access to install it. Make sure you install the GPA component. It may not be part of the default installation.

  2. After GPG4Win has been successfully installed, launch GPA (gpa.exe), either by clicking on its icon or selecting it from the Windows "Start" menu.

  3. After it has launched, click on the "Files" icon in the toolbar of the "GNU Privacy Assistant - Key Manager" window. It is the third icon from the right in the toolbar, next to the "Clipboard" icon. This will open up the "GNU Privacy Assistant - File Manager" window.

  4. In that window, click on the "Open" icon in the toolbar (the first icon on the left of the "File Manager" toolbar) and then navigate to the encrypted (*.asc) file and open it. The file should now be listed in the "File Manager" window.

  5. Finally, click on the "Decrypt" button. This will present a dialog box for you to enter the passphrase. Type (or paste) the passphrase, which should have already been supplied to you by the mission's peer review staff. After a few moments, the file will be decrypted and you can quit GPA.

  6. You will likely still need to untar the decrypted file. There are many Windows programs to do that (e.g., 7-Zip, WinZip, Winrar, Winace), and you may already have one of those utilities installed.

  • Alternatively, you can use the command line interface in a Windows Terminal session. Note that the executable will probably be named "gpg2.exe" instead of "gpg2" or "gpg". It will probably be installed in C:\Program Files\GNU\GnuPG\. If that is the case, you should amend the recommended command line from "gpg2" to "gpg2.exe" (or "C:\Program Files\GNU\GnuPG\gpg2.exe") accordingly.

  • When using the command line interface, if you encounter a gpg error message that says "Bad session key", try adding the option --no-symkey-cache after gpg in the decryption command.

macOS

  1. First, download and install the latest GPG Suite to use GPG 2.x. We recommend that you Customize the install and only install the "MacGPG" component. The other components in the GPG Suite are not needed, but feel free to install them if you so desire.

    Alternatively, if you already use and are familiar with MacPorts or Homebrew or Fink, you can install the gpg2 command using one of those Mac open source package managers and then skip to step 5. For MacPorts or Fink, the package name to install is gnupg2. For Homebrew, the package name is gnupg.

  2. Locate the downloaded image file ("GPG_Suite-2022.2.dmg" or similar) in the Finder and double-click it to mount it.

  3. After the image mounts, double-click on the "Install" icon in the image's window and follow the installer's instructions to install GPG on your Mac. We recommend that you click on the Customize button and uncheck every sub-package except for the "MacGPG2" sub-package (unless you plan on using GPG for other things on your Mac and want those other features). You will need administrator access to perform the install.

  4. Next, launch the Terminal application, which should be located in the "Utilities" folder inside your main "Applications" folder. Alternatively, use Spotlight to locate it by searching for "Terminal" (without the quotes).

  5. Once you have a Terminal window open, you will need to change directory to where the encrypted file was downloaded. For example, if the encrypted file is in your Downloads folder, you would type:

    cd ~/Downloads/

    If the encrypted file is on your desktop, you would type:

    cd ~/Desktop/

    If the encrypted file is in your home directory, you would just type:

    cd

  6. Finally, copy and paste one of the Unix-compatible commands for decrypting files, as given in the peer review instructions, into the Terminal window. The second command should work on macOS and is recommended. If you get an error in the Terminal window that says "gpg: command not found" or similar, replace "gpg" with "/usr/local/MacGPG2/bin/gpg --no-symkey-cache" in the decryption command and try again. If that doesn't work, try "/usr/local/bin/gpg" instead and/or use the following commands to determine where GPG was installed:

    /usr/local/bin/gpg --version
/usr/local/MacGPG2/bin/gpg2 --version
/usr/local/MacGPG1/bin/gpg --version
/usr/local/gnupg-2.2/bin/gpg --version
/opt/local/bin/gpg --version

    You may find it convenient to create a command alias so that you do not have to type the complete path each time. Depending on what type of shell you are using, you can do that by typing one of the following commands, chosen appropriately, in a Terminal window (for the bash shell):

    alias gpg=/usr/local/bin/gpg
alias gpg=/usr/local/MacGPG1/bin/gpg
alias gpg='/usr/local/MacGPG2/bin/gpg2 --no-symkey-cache'
alias gpg='/usr/local/gnupg-2.2/bin/gpg2 --no-symkey-cache'
alias gpg=/opt/local/bin/gpg

    If your shell is tcsh instead of bash, defining an alias is similar. The only difference is that you should not type the equal sign (=) in the above examples. Type a space instead.

    Note that, if the version of gpg you are using is ≥ 2.2.7, adding --no-symkey-cache to your alias (as shown in a couple of the most common cases above) is highly recommended. Alternatively, to avoid typing this option all the time or including it in your alias, you can add it to your ~/.gnupg/gpg.conf file by executing:

    echo "no-symkey-cache" >> ~/.gnupg/gpg.conf

    If you are not sure which shell you are using or this is confusing, you can skip defining an alias and instead just type the full path to the command when issuing the decryption command.

  7. Depending on which Terminal command you used, you might still need to untar the decrypted file. We recommend utilizing the free utility The Unarchiver for that purpose. It can also be downloaded for free from the Mac App Store.

If at some point you ever encounter a gpg error message that says "Bad session key" on the Mac, here are the steps to resolve it:

First off, try adding the option --no-symkey-cache after gpg in the decryption command, like so:

/usr/local/MacGPG2/bin/gpg --no-symkey-cache --decrypt --output foo.tar foo.tar.asc

This requires your version of gpg to be ≥ 2.2.7. If you have an older version of gpg, the easiest solution is probably to upgrade your GPG installation. If you don't want to do that for some reason or if it's not feasible or if you still get the "Bad session key" error message after upgrading GPG, please try the following steps:

  1. Launch the Keychain Access application. It should be located in the "Utilities" folder inside your main "Applications" folder. Alternatively, use Spotlight to locate it by searching for "Keychain Access" (without the quotes).

  2. In the search box in the top-right corner of the Keychain Access window, type "gnupg" (without the quotes).

  3. That should reveal a keychain item named "GnuPG" in the list below. Click on it. Then, select the "Delete" menu item from the "Edit" menu in the menu bar. This will present a dialog box. Click on the "Delete" button in the dialog box to confirm deletion of the GnuPG keychain item.

  4. Quit the Keychain Access application.

  5. Open the Terminal application (as described in the steps above), and, in the Terminal window, type the following command:

    /usr/local/MacGPG2/bin/gpgconf --kill gpg-agent

    If that gives an error, try the following command:

    killall gpg-agent

    The end result of executing one of the above commands is that there should be no gpg-agent process running on your system. You can confirm that by executing the following: 

    ps auxgww | grep gpg-agent | grep -v grep

Linux, BSD, Solaris, or Other Unix-Like OS

Most popular Linux distributions ship with GPG already installed. You should be able to just copy and paste the decryption command (as given in the peer review instructions) into any terminal window. If not, consult your distribution's software package manager on how to install GPG (a.k.a. "gnupg"). Alternatively, the source code is also available.

If the version of gpg you are using is ≥ 2.2.7, make sure you use the --no-symkey-cache option when decrypting or add it to your ~/.gnupg/gpg.conf file by executing:

echo "no-symkey-cache" >> ~/.gnupg/gpg.conf

If the ~/.gnupg/ directory doesn't exist, create it first:

mkdir ~/.gnupg
chmod 700 ~/.gnupg

Alternatively, you could define an alias, like so (for the bash shell):

alias gpg='gpg --no-symkey-cache'

If your shell is tcsh instead of bash, defining an alias is similar. The only difference is that you should not type the equal sign (=) in the above example. Type a space instead.

If at some point you ever encounter a gpg error message that says "Bad session key" or "No secret key" on Linux, here are some things to try to hopefully resolve such errors:

  • Sometimes the X11 dialog box used to enter the passphrase can cause problems. Switching to entering the passphrase in your terminal window might help. Do you have /usr/bin/pinetry-tty installed?

    ls -l /usr/bin/pinetry-tty

    If not, please install it. On Ubuntu systems, you would use these commands to install it: 

    sudo apt install pinentry-tty
sudo update-alternatives --config pinentry

    The second command there will prompt you to pick an alternative for pinentry, and you should pick pinentry-tty from the list of options. You may need to ask your system administrator to do this for you if you do not have sudo or root privileges. If you are using a different flavor of Linux, the commands will likely be different but probably similar.

    If you have /usr/bin/pinentry-tty or you are able to install it, execute the following two commands afterward and then try the decryption again:

    echo "pinentry-program /usr/bin/pinentry-tty" >> ~/.gnupg/gpg-agent.conf
rm ~/.gnupg/S.*
gpg-connect-agent reloadagent /bye

  • Also, try restarting gpg-agent and/or clearing its cache. First, check the output of the following command to determine if gpg-agent is "active" for your user:

    • systemctl --user status gpg-agent
    If it is active, then try executing the following commands and finally try the decryption again: 
    systemctl --user stop gpg-agent
ps auxgww | grep gpg-agent | grep -v grep
systemctl --user start gpg-agent
systemctl --user status gpg-agent

  • If you are still getting errors from GPG, please try rebooting your Linux system.
Last Modified: Friday, 10-Jan-2025 08:17:38 UTC
For assistance please contact the RPS Help Desk
XRISM@JAXA | PV targets | XRISM ESA GO program | Science with XRISM | Related sites

ARK/RPS is a service provided by NASA/GSFC