debian/gnupg-agent.README.Debian

   1 gpg-agent system integration
   2 ============================
   3
   4 Since 2.1.x, gpg and most related processes will auto-launch gpg-agent
   5 if needed.  These auto-launched processes will inherit whatever
   6 environment they started from, and they will not terminate
   7 automatically.
   8
   9 systemd
  10 =======
  11
  12 Since 2.1.17, users on machines with systemd will have their gpg-agent
  13 process launched automatically by systemd's user session, upon first
  14 access of any of the expected gpg-agent sockets (including the ssh
  15 socket).  systemd will also cleanly tear this process down at session
  16 logout.
  17
  18 If dbus-user-session and pinentry-gnome3 packages are installed, then
  19 all user interaction with this systemd-managed gpg-agent process
  20 (e.g. prompting for passwords or confirmations, etc) will take place
  21 over the d-bus session, for better integration with graphical
  22 environments like GNOME.
  23
  24 Users who don't want systemd to manage their gpg-agent in this way for
  25 all future sessions should do:
  26
  27     systemctl --user mask --now gpg-agent.service gpg-agent.socket gpg-agent-ssh.socket gpg-agent-extra.socket gpg-agent-browser.socket
  28
  29 Doing this means that gpg-agent will fall back to its manual mode of
  30 operation.  (This decision can be reversed by the user with "unmask"
  31 instead of "mask")
  32
  33 See systemctl(1) for more details about managing the gpg-agent*.socket
  34 units.
  35
  36 ssh-agent emulation
  37 ===================
  38
  39 gpg-agent offers an ssh-agent emulation which can be achieved by
  40 setting the environment variable SSH_AUTH_SOCK to:
  41
  42     /run/user/$(id -u)/gnupg/S.gpg-agent.ssh
  43
  44 (replace $(id -u) with the user's numeric user ID, of course).
  45
  46 But ssh doesn't have a way to tell ssh-agent how to prompt the user
  47 when necessary; the systemd-managed gpg-agent process will only know
  48 how to prompt the user if you have dbus-user-session and
  49 pinentry-gnome3 installed.  This is the recommended configuration for
  50 gpg-agent's ssh-agent emulation on desktop machines running systemd,
  51 and doesn't need any additional configuration.
  52
  53 However, if dbus-user-session and pinentry-gnome3 are not in use, by
  54 default the systemd-managed gpg-agent will not know how to get
  55 feedback from the user when a request is first received by ssh.  You
  56 can give it a hint for all future ssh connections by running:
  57
  58     gpg-connect-agent updatestartuptty /bye
  59
  60 You may wish to do this in the login scripts for your user session if
  61 you run systemd without dbus-user-session and pinentry-gnome3, and you
  62 plan to use gpg-agent's ssh-agent emulation.
  63
  64 Manual gpg-agent startup and teardown
  65 =====================================
  66
  67 Any user who wants to launch gpg-agent manually (e.g., to talk to it
  68 with a tool from outside the GnuPG suite) and is *not* using systemd
  69 should first ensure that it is launched with:
  70
  71     gpgconf --launch gpg-agent
  72
  73 If gpg-agent is launched manually or automatically (but not supervised
  74 by systemd), you probably want to ensure that it terminates when your
  75 session ends with:
  76
  77     gpgconf --kill gpg-agent
  78
  79 If you're not using systemd, you may wish to add this to your session
  80 logout scripts.
  81
  82  -- Daniel Kahn Gillmor <dkg@fifthhorseman.net>, Mon, 23 Jan 2017 22:56:08 -0500