Skip to content

riboseinc/enmail

Repository files navigation

EnMail

Gem Version Build Status Test Coverage Code Climate

EnMail (encrypted mail) signs or encrypts correspondence sent via the Ruby mail gem.

EnMail has open architecture. Multiple adapters are supported, and new ones can be implemented with ease. Currently, GPGME and RNP adapters are available out of the box. Both implement OpenPGP standard.

Basic usage

Given some e-mail:

mail = Mail.new
mail.from = "Very Myself <[email protected]>"
mail.to = "Someone Else <[email protected]>"
mail.subject = "It is very important"
mail.body = "Or, whatever"

adapter = ::EnMail::Adapters::RNP

# sign message
EnMail.protect :sign, mail, adapter: adapter

# encrypt message
EnMail.protect :encrypt, mail, adapter: adapter

# sign and encrypt message
EnMail.protect :sign_and_encrypt_encapsulated, mail, adapter: adapter

# or
EnMail.protect :sign_and_encrypt_combined, mail, adapter: adapter

Adapters

Table 1. Adapter features comparison
GPGME RNP

Protocol

Open PGP

Open PGP

Supporting library

GnuPG Made Easy

RNP

Native extensions

yes

yes, from FFI

Sign

yes

yes

Encrypt

yes

yes

Sign and encrypt

yes, encapsulated and combined

yes, encapsulated and combined

Password-protected keys

yes, password must be a String

yes, password must be a String or Proc

Bugs, issues and feature requests

See GitHub

See GitHub

See adapter-specific guides for details:

Development

Setup

Clone the repository.

git clone https://github.com/riboseinc/enmail
Note
GnuPG will create UNIX sockets in the <project_root>/tmp/pgp_home directory. Be advised that paths to UNIX sockets have limited length (about 100 characters). Therefore, please ensure that path to directory you are cloning repository into is less than 50 characters long, or you may experience weird errors.

Setup your environment.

bin/setup

Above one will take a short while. As the final step, tests will be run in order to prove your setup’s correctness.

Regenerating OpenPGP keys

If you ever need to regenerate your development OpenPGP keys, execute:

bundle exec rake pgp_keys:regenerate
Note
Always run tests after pulling new changes from the upstream. If they fail, it’s likely that OpenPGP keys should be regenerated.

Submodules

GnuPG is installed in Travis CI via scripts maintained in a sister repository riboseinc/gpg-build-scripts, and included here as a Git submodule. Learn more about submodules from The GitHub Blog.

Contributing

First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant Ribose Inc. the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.

Here are a few technical guidelines to follow:

  1. Open an issue to discuss a new feature.

  2. Write tests to support your new feature.

  3. Make sure the entire test suite passes locally and on CI.

  4. Open a Pull Request.

  5. After receiving feedback, perform an interactive rebase on your branch, in order to create a series of cohesive commits with descriptive messages.

  6. Party!

Credits

This gem is developed, maintained and funded by Ribose Inc.

License

This gem is licensed under MIT license.