gpg/README.md

   1 ---
   2 title: Gnu Privacy Guard
   3 homepage: https://gnupg.org/
   4 tagline: |
   5   GnuPG: a complete implementation of OpenPGP (RFC4880), also known as **P**retty **G**ood **P**rivacy.
   6 ---
   7
   8 ### Before you start
   9
  10 If `~/.gitconfig` exists and has both `name` and `email` fields, then a new gpg
  11 key will be created after the install. Otherwise, you'll have to create one
  12 yourself.
  13
  14 ## Cheat Sheet
  15
  16 > Among other things, gpg is particularly useful for signing and verifying git
  17 > commits (and emails too).
  18
  19 Here we'll cover:
  20
  21 - Important GPG Files & Directories
  22 - Creating New Keys
  23 - Listing Keys
  24 - Signing Git Commits
  25 - Exporting GPG Keys for GitHub
  26 - Publishing GPG Keys to "the Blockchain"
  27 - Running GPG Agent with launchd
  28
  29 ### Files
  30
  31 These are the files / directories that are created and/or modified with this
  32 install:
  33
  34 ```txt
  35 ~/.config/envman/PATH.env
  36 ~/.local/opt/gnupg/bin/gpg
  37 ~/.local/opt/gnupg/bin/gpg-agent
  38 ~/.local/opt/gnupg/bin/pinentry-mac.app/Contents/MacOS/pinentry-mac
  39 ~/.gnupg/gpg-agent.conf
  40 ~/Library/LaunchAgent/gpg-agent.plist
  41 ```
  42
  43 ### How to create a new GPG key
  44
  45 See the [Cheat Sheet](./gpg-pubkey) at [gpg-pubkey](./gpg-pubkey).
  46
  47 ### How to List GPG Key(s)
  48
  49 ```bash
  50 gpg --list-secret-keys --keyid-format LONG
  51 ```
  52
  53 ### How to configure git to sign commits
  54
  55 See the [Cheat Sheet](./git-config-gpg) at [gpg-pubkey](./git-config-gpg).
  56
  57 ### How to Export GPG Key for GitHub
  58
  59 See the [Cheat Sheet](./gpg-pubkey) at [gpg-pubkey](./gpg-pubkey).
  60
  61 ### How to Publish GPG Keys
  62
  63 GPG is the OG "blockchain", as it were.
  64
  65 If you'd like to publish your (public) key(s) to the public Key Servers for time
  66 and all eternity, you can:
  67
  68 ```bash
  69 gpg --send-keys "${MY_KEY_ID}"
  70 ```
  71
  72 (no IPFS needed 😉)
  73
  74 ### How to start gpg-agent with launchd
  75
  76 (**Note**: this is **done for you** on install, but provided here for reference)
  77
  78 It's a trick question: You can't.
  79
  80 You need to use `gpg-connect-agent` instead.
  81
  82 `~/Library/LaunchAgents/gpg-agent.plist`:
  83
  84 ```xml
  85 <?xml version="1.0" encoding="UTF-8"?>
  86 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  87 <plist version="1.0">
  88 <dict>
  89         <key>Label</key>
  90         <string>gpg-agent</string>
  91         <key>ProgramArguments</key>
  92         <array>
  93                 <string>MY_HOME/.local/opt/gnupg/bin/gpg-connect-agent</string>
  94                 <string>--agent-program</string>
  95                 <string>MY_HOME/.local/opt/gnupg/bin/gpg-agent</string>
  96                 <string>--homedir</string>
  97                 <string>MY_HOME/.gnupg/</string>
  98                 <string>/bye</string>
  99         </array>
 100
 101         <key>RunAtLoad</key>
 102         <true/>
 103
 104         <key>WorkingDirectory</key>
 105         <string>MY_HOME</string>
 106
 107         <key>StandardErrorPath</key>
 108         <string>MY_HOME/.local/share/gpg-agent/var/log/gpg-agent.log</string>
 109         <key>StandardOutPath</key>
 110         <string>MY_HOME/.local/share/gpg-agent/var/log/gpg-agent.log</string>
 111 </dict>
 112 </plist>
 113 ```
 114
 115 And then start it with launchctl:
 116
 117 ```bash
 118 launchctl load -w ~/Library/LaunchAgents/gpg-agent.plist
 119 ```
 120
 121 ### Troubleshooting 'gpg failed to sign the data'
 122
 123 `gpg` is generally expected to be used with a Desktop client. On Linux servers
 124 you may get this error:
 125
 126 ```txt
 127 error: gpg failed to sign the data
 128 fatal: failed to write commit object
 129 ```
 130
 131 Try to load the `gpg-agent`, set `GPG_TTY`, and then run a clearsign test.
 132
 133 ```bash
 134 gpg-connect-agent /bye
 135 export GPG_TTY=$(tty)
 136 echo "test" | gpg --clearsign
 137 ```
 138
 139 If that works, update your `~/.bashrc`, `~/.zshrc`, and/or
 140 `~/.config/fish/config.fish` to include the following:
 141
 142 ```bash
 143 gpg-connect-agent /bye
 144 export GPG_TTY=$(tty)
 145 ```
 146
 147 If this is failing on Mac or Windows, then `gpg-agent` is not starting as
 148 expected on login (for Mac the above may work), and/or the `pinentry` command is
 149 not in the PATH.
 150
 151 If you just installed `gpg`, try closing and reopening your Terminal, or
 152 possibly rebooting.