Overview

gpgedit - minimalist password management
========================================

LICENSE
-------
Copyright (c) 2013-2014 Tobias Dammers.

This software is distributed under a BSD-style license; see the enclosed
LICENSE file for the actual license text.

WHAT IS IT?
-----------
gpgedit is a simple wrapper around GnuPG (gpg), that simplifies managing
arbitrary secrets in text files, typically login credentials, passwords, API
keys and similar information.

I wrote it to replace my previous manual routine of storing passwords in
GPG-encrypted files and decrypting them to clear-text files for editing; the
manual approach was prone to human errors (deleting the wrong file, or failing
to delete the clear-text file), and also rather clumsy. Being a programmer, I
automated the manual routine in a little python script, and while I was at it,
I changed it to be yet a bit more secure (most notably, I'm using the
`mkstemp()` routine which throws in a few measures to make the tempfile less
likely to be tampered with than a regular text file).

HOW IT WORKS
------------
gpgedit has two modes of operation: editing and showing. The `edit` command
creates or updates an existing secret file by decrypting it into a tempfile,
calling your favorite editor on it (`$EDITOR`), encrypting the tempfile back
into the original secret file using the same recipients, and finally deleting
the tempfile. The `show` command simply outputs the decrypted tempfile on
STDOUT; if you want to write it to the system clipboard, consider something
like `xclip`.

SECURITY CAVEATS
----------------
gpgedit decrypts to a tempfile; special care is taken to keep this file hidden
from other processes (see
[mkstemp](http://docs.python.org/2/library/tempfile.html#tempfile.mkstemp) for
details). However, there are possible attack vectors on such tempfiles:
- If the partition on which the tempfile is stored is not encrypted, it may be
  possible to recover the information in it simply by mounting the disk into a
  different system and inspecting it at the block level.
- While editing the tempfile, the secret is stored unencrypted in system RAM as
  well as the temp dir; this means that malware that is active while editing
  may compromise your secrets, e.g. keyloggers, memory scanners, etc.
- Encryption is only as strong as the key; so be careful with your keys, even
  if they are protected with a passphrase.
- In general, be sure to understand how this tool works before using it. You
  should make an educated decision in balancing security and privacy against
  convenience and pragmatism.
- Terminal emulators can have fairly long scrollback buffers, and things like
  screen or tmux may keep STDOUT data around for quite a long time, with
  considerable attack surface. If you print secrets on STDOUT, keep this in
  mind.
- The Python script uses exception handling to make sure the tempfile gets
  deleted. However, if you hard-kill the script before it reaches the `finally`
  block (e.g. `kill -9`), the tempfile containing the clear-text secret will
  not be deleted until the tempdir is cleaned up (typically at reboot). There
  is little I can do about this, due to the nature of SIGKILL.

Further, gpgedit only encrypts; it does not verify in any way. This means that
while an attacker cannot read the contents of your encrypted files without
access to the private key, they can trivially fabricate encrypted files that
are indistinguishable from secrets you have encrypted yourself. They can also
change the name of any of your secret files, provided that they have write
access to the relevant storage. Various attacks are possible as a result. For
now, the only possible defense is to prevent write access to your gpg-encrypted
files; I do intend to add signing support to gpgedit in the near future though.
For now, you should prevent write access to the directory where you keep your
secrets; storing them on (and retrieving them from) systems that you do not
control (e.g. external VCS hosting, off-site backup services, cloud storage,
etc.) should also be avoided.

INSTALLING
----------
Requirements:

* A UNIX-like OS (tested on Debian 7.0, but should work on most other
  UNIX-likes)
* Python 2.x (3.x might work but is untested)
* GPG

To install, simply check out the latest version from
[git](https://bitbucket.org/tdammers/gpgedit), and put the `gpgedit` file
somewhere on your path.

`$EDITOR` should point to your favorite editor; to check, just type `echo
$EDITOR` at a command prompt. This should print something like `/usr/bin/vim`
or `/usr/bin/nano` or whatever your editor of choice is. If it's empty, add
something like `export EDITOR=/usr/bin/nano` to the appropriate startup files
(.xsession, .profile, .bashrc, as required) and re-login. If you have done it
correctly, typing `$EDITOR` at a command prompt should fire up your editor.

USAGE
-----
To create a new secret:

	gpgedit edit path/to/secret.gpg

This will create a new empty secret file and open it in your editor. Write down
your secret, save and exit. Then gpg will be run, and since you're creating a
new secret, it will ask you for recipients. Once you're done entering
recipients, gpgedit will delete your clear-text secret and leave you with just
the secret. Note that if you haven't added yourself to the recipients, you will
be unable to decrypt your own secret file!

To extract a secret:

	gpgedit show path/to/secret.gpg

This will ask for your passphrase (if your private key is protected with one,
as it should), and then output the clear-text message on STDOUT.

To extract a secret and copy it directly to the system clipboard using xclip:

	gpgedit show path/to/secret.gpg | xclip -i

(Note that the system clipboard is rather easy to access, so you may want to
avoid this as an extra precaution).

To delete a secret:

	rm path/to/secret.gpg

RELEASE HISTORY
---------------

- 0.1 (2013-06-17): Initial release. 
- 0.2 (2014-03-21):
    - Disables GPG compression to avoid certain attacks on the encryption
      cipher
    - Added the 'recode' command (re-encrypt a file unchanged, without firing
      up an editor)
    - Added the 'version' command

CONTACT
-------
Feel free to contact me for bug reports, feature requests, questions, success
stories, etc.:

	tdammers@gmail.com

If you want to fork this project, by all means be my guest. I would love to
hear from you when you do, but this is absolutely not a requirement at all.