Skip to content
Redmine plugin for email encryption with the OpenPGP standard
Ruby HTML
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
config
db/migrate
lib
test
Gemfile
LICENSE.txt
README.rst
init.rb

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/>.
You can’t perform that action at this time.