https://github.com/riboseinc/enmail
Ruby mail extension for sending/receiving secure mail
https://github.com/riboseinc/enmail
Last synced: about 1 month ago
JSON representation
Ruby mail extension for sending/receiving secure mail
- Host: GitHub
- URL: https://github.com/riboseinc/enmail
- Owner: riboseinc
- License: mit
- Created: 2017-03-26T08:28:36.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2021-07-20T06:18:20.000Z (almost 4 years ago)
- Last Synced: 2025-04-11T03:46:51.057Z (about 1 month ago)
- Language: Ruby
- Homepage: https://open.ribose.com
- Size: 286 KB
- Stars: 1
- Watchers: 6
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
= 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 "
mail.to = "Someone Else "
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[]
* <>
* <>
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 `/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.