= EnMail

ifdef::env-github[] image:https://img.shields.io/gem/v/enmail.svg[ Gem Version, link="https://rubygems.org/gems/enmail"] image:https://img.shields.io/travis/riboseinc/enmail/master.svg[ Build Status, link="https://travis-ci.com/riboseinc/enmail/branches"] image:https://img.shields.io/codecov/c/github/riboseinc/enmail.svg[ Test Coverage, link="https://codecov.io/gh/riboseinc/enmail"] image:https://img.shields.io/codeclimate/maintainability/riboseinc/enmail.svg[ "Code Climate", link="https://codeclimate.com/github/riboseinc/enmail"] endif::[]

EnMail (encrypted mail) signs or encrypts correspondence sent via the Ruby https://rubygems.org/gems/mail[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:

[source,ruby]

mail = Mail.new mail.from = "Very Myself me@example.com" mail.to = "Someone Else someone@example.com" 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

.Adapter features comparison [options="header"] |======= | | GPGME | RNP | Protocol | Open PGP | Open PGP | Supporting library | https://gnupg.org/software/gpgme/index.html[GnuPG Made Easy] | https://www.rnpgp.com/[RNP] | Native extensions | yes | yes, from https://github.com/ffi/ffi[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 | https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+gpgme%22[See GitHub] | https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+rnp%22[See GitHub] |=======

See adapter-specific guides for details:

ifdef::env-browser,env-github[]

• <<docs/GPGMEAdapter.adoc#,GPGME>>
• <<docs/RNPAdapter.adoc#,RNP>> endif::[] ifndef::env-browser,env-github[]
• {file:docs/GPGMEAdapter.adoc}
• {file:docs/RNPAdapter.adoc} endif::[]

== Development

=== Setup

Clone the repository.

[source,sh]

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.

[source,sh]

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:

[source,sh]

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 https://github.com/riboseinc/gpg-build-scripts[riboseinc/gpg-build-scripts], and included here as a Git submodule. Learn more about submodules from https://blog.github.com/2016-02-01-working-with-submodules/[The GitHub Blog].

=== Contributing

First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant https://www.ribose.com[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 https://github.com/riboseinc/enmail/issues[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 https://help.github.com/articles/about-git-rebase/[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 https://www.ribose.com[Ribose Inc.]

== License

This gem is licensed under MIT license.