From a51eb772698ed78be4d538392541cc97fd636400 Mon Sep 17 00:00:00 2001 From: Victor Koronen Date: Sat, 25 Jan 2014 15:21:15 +0100 Subject: [PATCH] Move documentation into README and doc/ * Moves general documentation, such as the description and installation instructions, to a new README file at the root of the repo. * Moves detailed documentation, such at command descriptions, into a text file under doc/ that can be indexed and searched through using Vim's `:help` command. --- README.markdown | 82 +++++++++++++++++++++++++ doc/gnupg.txt | 81 +++++++++++++++++++++++++ plugin/gnupg.vim | 153 +---------------------------------------------- 3 files changed, 166 insertions(+), 150 deletions(-) create mode 100644 README.markdown create mode 100644 doc/gnupg.txt diff --git a/README.markdown b/README.markdown new file mode 100644 index 0000000..2bf810d --- /dev/null +++ b/README.markdown @@ -0,0 +1,82 @@ +# vim-gnupg + +This script implements transparent editing of gpg encrypted files. The filename +must have a `.gpg`, `.pgp` or `.asc` suffix. When opening such a file the +content is decrypted, when opening a new file the script will ask for the +recipients of the encrypted file. The file content will be encrypted to all +recipients before it is written. The script turns off viminfo, swapfile, and +undofile to increase security. + +## Installation + +Copy the `gnupg.vim` file to the `$HOME/.vim/plugin` directory. Refer to `:help +add-plugin`, `:help add-global-plugin` and `:help runtimepath` for more details +about Vim plugins. + +From `man 1 gpg-agent`: + +> You should always add the following lines to your `.bashrc` or whatever +> initialization file is used for all shell invocations: +> +> GPG_TTY=`tty` +> export GPG_TTY +> +> It is important that this environment variable always reflects the output of +> the tty command. For W32 systems this option is not required. + +Most distributions provide software to ease handling of gpg and gpg-agent. +Examples are keychain or seahorse. + +If there are specific actions that should take place when editing a +GnuPG-managed buffer, an autocmd for the User event and GnuPG pattern can be +defined. For example, the following will set `textwidth` to 72 for all +GnuPG-encrypted buffers: + + autocmd User GnuPG setl textwidth=72 + +This will be triggered before any BufRead or BufNewFile autocmds, and therefore +will not take precedence over settings specific to any filetype that may get +set. + +## Known Issues + +In some cases gvim can't decrypt files. + +This is caused by the fact that a running gvim has no TTY and thus gpg is not +able to ask for the passphrase by itself. This is a problem for Windows and +Linux versions of gvim and could not be solved unless a "terminal emulation" is +implemented for gvim. To circumvent this you have to use any combination of +gpg-agent and a graphical pinentry program: + +- gpg-agent only: + you need to provide the passphrase for the needed key to gpg-agent + in a terminal before you open files with gvim which require this key. +- pinentry only: + you will get a popup window every time you open a file that needs to + be decrypted. +- gpgagent and pinentry: + you will get a popup window the first time you open a file that + needs to be decrypted. + +## Credits + +- Mathieu Clabaut for inspirations through his vimspell.vim script. +- Richard Bronosky for patch to enable `.pgp` suffix. +- Erik Remmelzwaal for patch to enable windows support and patient beta testing. +- Lars Becker for patch to make gpg2 working. +- Thomas Arendsen Hein for patch to convert encoding of gpg output. +- Karl-Heinz Ruskowski for patch to fix unknown recipients and trust model and + patient beta testing. +- Giel van Schijndel for patch to get `GPG_TTY` dynamically. +- Sebastian Luettich for patch to fix issue with symmetric encryption an set + recipients. +- Tim Swast for patch to generate signed files. +- James Vega for patches for better `*.asc` handling, better filename escaping + and better handling of multiple keyrings. + +## License + +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. See http://www.gnu.org/copyleft/gpl-2.0.txt diff --git a/doc/gnupg.txt b/doc/gnupg.txt new file mode 100644 index 0000000..24231e9 --- /dev/null +++ b/doc/gnupg.txt @@ -0,0 +1,81 @@ +*gnupg.txt* Vim plugin for transparent editing of gpg encrypted files. + +Maintainer: James McCoy +Original Author: Markus Braun +License: GPLv2+ + +INTRODUCTION *gnupg* + +This script implements transparent editing of gpg encrypted files. The +filename must have a .gpg, .pgp or .asc suffix. When opening such a file the +content is decrypted, when opening a new file the script will ask for the +recipients of the encrypted file. The file content will be encrypted to all +recipients before it is written. The script turns off viminfo, swapfile, and +undofile to increase security. + +COMMANDS *gnupg-commands* + + *gnupg-:GPGEditRecipients* +:GPGEditRecipients Opens a scratch buffer to change the list of + recipients. Recipients that are unknown (not in your + public key) are highlighted and have a prepended "!". + Closing the buffer makes the changes permanent. + + *gnupg-:GPGViewRecipients* +:GPGViewRecipients Prints the list of recipients. + + *gnupg-:GPGEditOptions* +:GPGEditOptions Opens a scratch buffer to change the options for + encryption (symmetric, asymmetric, signing). Closing + the buffer makes the changes permanent. WARNING: There + is no check of the entered options, so you need to + know what you are doing. + + *gnupg-:GPGViewOptions* +:GPGViewOptions Prints the list of options. + +VARIABLES *gnupg-variables* + + *gnupg-g:GPGExecutable* +g:GPGExecutable If set used as gpg executable, otherwise the system + chooses what is run when "gpg" is called. Defaults to + "gpg". + + *gnupg-g:GPGUseAgent* +g:GPGUseAgent If set to 0 a possible available gpg-agent won't be + used. Defaults to 1. + + *gnupg-g:GPGPreferSymmetric* +g:GPGPreferSymmetric If set to 1 symmetric encryption is preferred for new + files. Defaults to 0. + + *gnupg-g:GPGPreferArmor* +g:GPGPreferArmor If set to 1 armored data is preferred for new files. + Defaults to 0 unless a "*.asc" file is being edited. + + *gnupg-g:GPGPreferSign* +g:GPGPreferSign If set to 1 signed data is preferred for new files. + Defaults to 0. + + *gnupg-g:GPGDefaultRecipients* +g:GPGDefaultRecipients If set, these recipients are used as defaults when no + other recipient is defined. This variable is a Vim + list. Default is unset. + + *gnupg-g:GPGUsePipes* +g:GPGUsePipes If set to 1, use pipes instead of temporary files when + interacting with gnupg. When set to 1, this can cause + terminal-based gpg agents to not display correctly + when prompting for passwords. Defaults to 0. + + *gnupg-g:GPGHomedir* +g:GPGHomedir If set, specifies the directory that will be used for + GPG's homedir. This corresponds to gpg's --homedir + option. This variable is a Vim string. + + *gnupg-g:GPGFilePattern* +g:GPGFilePattern If set, overrides the default set of file patterns + that determine whether this plugin will be activated. + Defaults to '*.\(gpg\|asc\|pgp\)'. + + vim:tw=78:et:ft=help:norl: diff --git a/plugin/gnupg.vim b/plugin/gnupg.vim index dfb2a5b..c6374e0 100644 --- a/plugin/gnupg.vim +++ b/plugin/gnupg.vim @@ -1,153 +1,6 @@ -" Name: gnupg.vim -" Last Change: 2013 Sep 09 -" Maintainer: James McCoy -" Original Author: Markus Braun -" Summary: Vim plugin for transparent editing of gpg encrypted files. -" License: This program is free software; you can redistribute it and/or -" modify it under the terms of the GNU General Public License -" as published by the Free Software Foundation; either version -" 2 of the License, or (at your option) any later version. -" See http://www.gnu.org/copyleft/gpl-2.0.txt -" -" Section: Documentation {{{1 -" -" Description: {{{2 -" -" This script implements transparent editing of gpg encrypted files. The -" filename must have a ".gpg", ".pgp" or ".asc" suffix. When opening such -" a file the content is decrypted, when opening a new file the script will -" ask for the recipients of the encrypted file. The file content will be -" encrypted to all recipients before it is written. The script turns off -" viminfo, swapfile, and undofile to increase security. -" -" Installation: {{{2 -" -" Copy the gnupg.vim file to the $HOME/.vim/plugin directory. -" Refer to ':help add-plugin', ':help add-global-plugin' and ':help -" runtimepath' for more details about Vim plugins. -" -" From "man 1 gpg-agent": -" -" ... -" You should always add the following lines to your .bashrc or whatever -" initialization file is used for all shell invocations: -" -" GPG_TTY=`tty` -" export GPG_TTY -" -" It is important that this environment variable always reflects the out‐ -" put of the tty command. For W32 systems this option is not required. -" ... -" -" Most distributions provide software to ease handling of gpg and gpg-agent. -" Examples are keychain or seahorse. -" -" If there are specific actions that should take place when editing a -" GnuPG-managed buffer, an autocmd for the User event and GnuPG pattern can -" be defined. For example, the following will set 'textwidth' to 72 for all -" GnuPG-encrypted buffers: -" -" autocmd User GnuPG setl textwidth=72 -" -" This will be triggered before any BufRead or BufNewFile autocmds, and -" therefore will not take precedence over settings specific to any filetype -" that may get set. -" -" Commands: {{{2 -" -" :GPGEditRecipients -" Opens a scratch buffer to change the list of recipients. Recipients that -" are unknown (not in your public key) are highlighted and have -" a prepended "!". Closing the buffer makes the changes permanent. -" -" :GPGViewRecipients -" Prints the list of recipients. -" -" :GPGEditOptions -" Opens a scratch buffer to change the options for encryption (symmetric, -" asymmetric, signing). Closing the buffer makes the changes permanent. -" WARNING: There is no check of the entered options, so you need to know -" what you are doing. -" -" :GPGViewOptions -" Prints the list of options. -" -" Variables: {{{2 -" -" g:GPGExecutable -" If set used as gpg executable, otherwise the system chooses what is run -" when "gpg" is called. Defaults to "gpg". -" -" g:GPGUseAgent -" If set to 0 a possible available gpg-agent won't be used. Defaults to 1. -" -" g:GPGPreferSymmetric -" If set to 1 symmetric encryption is preferred for new files. Defaults to 0. -" -" g:GPGPreferArmor -" If set to 1 armored data is preferred for new files. Defaults to 0 -" unless a "*.asc" file is being edited. -" -" g:GPGPreferSign -" If set to 1 signed data is preferred for new files. Defaults to 0. -" -" g:GPGDefaultRecipients -" If set, these recipients are used as defaults when no other recipient is -" defined. This variable is a Vim list. Default is unset. -" -" g:GPGUsePipes -" If set to 1, use pipes instead of temporary files when interacting with -" gnupg. When set to 1, this can cause terminal-based gpg agents to not -" display correctly when prompting for passwords. Defaults to 0. -" -" g:GPGHomedir -" If set, specifies the directory that will be used for GPG's homedir. -" This corresponds to gpg's --homedir option. This variable is a Vim -" string. -" -" g:GPGFilePattern -" If set, overrides the default set of file patterns that determine -" whether this plugin will be activated. Defaults to -" '*.\(gpg\|asc\|pgp\)'. -" -" Known Issues: {{{2 -" -" In some cases gvim can't decrypt files - -" This is caused by the fact that a running gvim has no TTY and thus gpg is -" not able to ask for the passphrase by itself. This is a problem for Windows -" and Linux versions of gvim and could not be solved unless a "terminal -" emulation" is implemented for gvim. To circumvent this you have to use any -" combination of gpg-agent and a graphical pinentry program: -" -" - gpg-agent only: -" you need to provide the passphrase for the needed key to gpg-agent -" in a terminal before you open files with gvim which require this key. -" -" - pinentry only: -" you will get a popup window every time you open a file that needs to -" be decrypted. -" -" - gpgagent and pinentry: -" you will get a popup window the first time you open a file that -" needs to be decrypted. -" -" Credits: {{{2 -" -" - Mathieu Clabaut for inspirations through his vimspell.vim script. -" - Richard Bronosky for patch to enable ".pgp" suffix. -" - Erik Remmelzwaal for patch to enable windows support and patient beta -" testing. -" - Lars Becker for patch to make gpg2 working. -" - Thomas Arendsen Hein for patch to convert encoding of gpg output. -" - Karl-Heinz Ruskowski for patch to fix unknown recipients and trust model -" and patient beta testing. -" - Giel van Schijndel for patch to get GPG_TTY dynamically. -" - Sebastian Luettich for patch to fix issue with symmetric encryption an set -" recipients. -" - Tim Swast for patch to generate signed files. -" - James Vega for patches for better '*.asc' handling, better filename -" escaping and better handling of multiple keyrings. +" gnupg.vim - Vim plugin for transparent editing of gpg encrypted files. +" Maintainer: James McCoy +" Original Author: Markus Braun " " Section: Plugin header {{{1