A plugin for Redmine to enhance the security of email communication by
developed for C3S - (Cultural Commons Collecting Society) <https://c3s.cc>
_
Users may
Administrators may
Encrypted mails may be
Unencrypted mails may be
Notifications affected:
This plugin has been tested with ::
gnupg 1.4.18
ruby 2.1.5p273
rails 4.2.3
redmine 3.1.0
gpgme 2.0.9
mail-gpg 0.2.4
Note: gpg
== 2.0.X will not work (see here <https://stackoverflow.com/a/27768542>
_). gpg
>= 2.1 will probably work, if a gpgme passphrase callback function is added to the code (but is still missing). Downgrade to 1.X or install 1.X parallel and symlink /usr/bin/gpg
to /usr/bin/gpg2
``$cd /path/to/redmine/plugins``
/path/to/redmine/plugins/openpgp
``$git clone https://github.com/C3S/redmine_openpgp openpgp``
``$git show pgp | gpg --import``
``$git tag --verify 1.0``
``$git checkout tags/1.0``
``$cd /path/to/redmine``
``$bundle install``
``$RAILS_ENV=production bundle exec rake redmine:plugins:migrate``
``$sudo service apache2 restart``
Administration / Settings / Email notifications
Administration / Settings / General
Administration / Settings / Incoming emails
*.asc, *.pgp, *.gpg
Note: The remote server needs enough entropy to generate random, secure keys. If the server side generation process does not proceed or the client side connection has a timeout, connect to the remote server and try ls -R /
several times. If you use rngd
for entropy generation, be advised not to use /dev/urandom
as source for important keys.
Adding an existing private PGP key server-side
#. Export the private PGP key (ascii armored) and save it into a file on the server
#. Change into redmine root directory
``$cd /path/to/redmine``
#. Use a rake task to add the existing key, deleting the old one. Point ``keyfile`` to the absolute path to the key file and choose a ``secret``:
``$RAILS_ENV="production" bundle exec rake redmine:update_redmine_pgpkey keyfile="/path/to/key.asc" secret="passphrase"``
Generating a new private PGP key server-side
``$cd /path/to/redmine``
secret
: ``$RAILS_ENV="production" bundle exec rake redmine:generate_redmine_pgpkey secret="passphrase"``
Managing a private PGP keys client-side
#. Log into redmine as administrator
#. Visit http://REDMINE.URL/pgp (or follow the new "PGP" link in the account menue)
#. Follow the instructions (on the right side)
Users
-----
#. Log into redmine
#. Visit http://REDMINE.URL/pgp (or follow the new "PGP" link in the account menue)
#. Add your public PGP key
#. Copy & paste the public PGP key for the redmine server into a local file on your machine
#. Import this file into your local gpg key ring
*Note:* The private PGP key for the redmine server has to be added by an administrator, before the corresponding public PGP key is displayed.
Uninstallation
==============
#. Change into redmine root directory
``$cd /path/to/redmine``
#. Downgrade the database
``$RAILS_ENV=production rake redmine:plugins:migrate NAME=openpgp VERSION=0``
#. Remove the files
``$rm -r /path/to/redmine/plugins/openpgp``
Implementation
==============
The table ``pgpkeys`` is added to the redmine database:
- each entry associates a redmine user (``user_id``) with the unique fingerprint of a key (``fpr``). This allows for matching fingerprints instead of email address, thus enabling redmine users to delete/update their keys and use keys, which don't match their email address
- the entry with ``user_id`` 0 is reserved for the private key of the redmine server additionally containing the secret passphrase (``secret``)
The following gems are used:
- ``mail-gpg`` for de-/encryption and signature handling within ``Mail`` / ``ActionMailer``
- ``gpgme`` to interact with ``gpg`` running on the server
Whenever a key is added:
- the key is imported into the ``gpg`` key ring of the system user owning the redmine process
- an entry is added to the table ``pgpkeys``
Whenever a key is removed:
- the corresponding entry in the table ``pgpkeys`` is deleted
- if there are no other references to this key within the table ``pgpkeys``:
- the key is **removed from the gpg key ring** as well
Whenever a mail is sent:
- if the plugin is enabled globally or on project level:
- if the recipient owns a key:
- the mail is encryted for the recipient
- if the redmine server owns a key:
- the mail is signed by the redmine user
- else: the mail is blocked / filtered / passed unchanged, depending on the plugin settings
Whenever a mail is recieved:
- it will be decrypted if encrypted
- depending on the plugin settings it will be rejected if the signature is invalid
Improvements
============
- Add tests
- Add languages
- Add LDAP integration for importing keys
- Add gpgme passphrase callback for ``gpg`` >= 2.1, retaining compatibility to ``gpg`` < 2
Links
=====
- `GPG <http://www.gnupg.org/gph/en/manual/x56.html>`_ (reference)
- `ActionMailer <http://apidock.com/rails/ActionMailer/Base>`_ (reference)
- `mail <http://www.rubydoc.info/gems/mail>`_ (reference)
- `gpgme <http://www.rubydoc.info/gems/gpgme/2.0.9>`_ (reference)
- `mail-gpg <http://www.rubydoc.info/gems/mail-gpg/0.2.4>`_ (reference)
- `PGP/MIME <http://www.ietf.org/rfc/rfc3156.txt>`_ (RFC)
- `PGP Formats <http://binblog.info/2008/03/12/know-your-pgp-implementation/>`_ (explanation)
Contributions
=============
- `Alexander Blum <https://github.com/timegrid>`_
License
=======
::
Redmine plugin for email encryption with the OpenPGP standard
Copyright (C) 2015 Alexander Blum <a.blum@free-reality.net>
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 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.