Redmine plugin for email encryption with the OpenPGP standard
Ruby HTML
Switch branches/tags
Nothing to show
Clone or download
Latest commit a22a9be Sep 4, 2015

README.rst

Redmine OpenPGP

A plugin for Redmine to enhance the security of email communication by

  • de-/encrypting in-/outgoing emails with the OpenPGP standard
  • filtering content of unencrypted emails

developed for C3S - (Cultural Commons Collecting Society)

Details

Users may

  • add / remove their public PGP key
  • see the public PGP key of the redmine server

Administrators may

  • choose to pass / reject incoming mails without a valid signature for all projects
  • activate outgoing mail handling for all / selected / no projects
  • add / generate / remove a private PGP key for the redmine server (both server-side / client-side)
  • choose to pass / filter / block outgoing unencrypted mails
  • add a footer message to filtered mails

Encrypted mails may be

  • PGP/MIME or PGP/Inline (incoming)
  • PGP/MIME (outgoing)

Unencrypted mails may be

  • blocked: no mail is sent
  • filtered: body is reduced to the link to the added / updated object and an invitation to add the public PGP key; headers & subject are unchanged
  • unchanged: mail is sent unchanged

Notifications affected:

  • attachments_added
  • document_added
  • issue_add
  • issue_edit
  • message_posted
  • news_added
  • news_comment_added
  • wiki_content_added
  • wiki_content_updated

Dependencies

Compatibility

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). 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

Installation

  1. Change into plugin directory

    $cd /path/to/redmine/plugins

  2. Clone this repo into /path/to/redmine/plugins/openpgp

    $git clone https://github.com/C3S/redmine_openpgp openpgp

  3. Import the public PGP key for signature verification

    $git show pgp | gpg --import

  4. Verify the signature

    $git tag --verify 1.0

  5. Change to current release tag

    $git checkout tags/1.0

  6. Change into redmine root directory

    $cd /path/to/redmine

  7. Install gems

    $bundle install

  8. Migrate database

    $RAILS_ENV=production bundle exec rake redmine:plugins:migrate

  9. Restart redmine

    $sudo service apache2 restart

Configuration

Administrators

  1. Configure redmine
    • Administration / Settings / Email notifications
      • Emission email address
    • Administration / Settings / General
      • Host name and path
      • Protocol
    • Administration / Settings / Incoming emails
      • Enable WS for incoming emails
      • API key
      • Exclude attachments by name: *.asc, *.pgp, *.gpg
  2. Configure plugin
    • Administration / Plugins / Openpgp
  3. Add or generate a private PGP key for the redmine server
    • either server-side (secure)
    • or client-side (INSECURE over http, more or less secure over https)

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

  1. Export the private PGP key (ascii armored) and save it into a file on the server

  2. Change into redmine root directory

    $cd /path/to/redmine

  3. 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

  1. Change into redmine root directory

    $cd /path/to/redmine

  2. Use a rake task to generate the new key, deleting the old one. Choose a secret:

    $RAILS_ENV="production" bundle exec rake redmine:generate_redmine_pgpkey secret="passphrase"

Managing a private PGP keys client-side

  1. Log into redmine as administrator
  2. Visit http://REDMINE.URL/pgp (or follow the new "PGP" link in the account menue)
  3. Follow the instructions (on the right side)

Users

  1. Log into redmine
  2. Visit http://REDMINE.URL/pgp (or follow the new "PGP" link in the account menue)
  3. Add your public PGP key
  4. Copy & paste the public PGP key for the redmine server into a local file on your machine
  5. 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

  1. Change into redmine root directory

    $cd /path/to/redmine

  2. Downgrade the database

    $RAILS_ENV=production rake redmine:plugins:migrate NAME=openpgp VERSION=0

  3. 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

Contributions

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/>.