= GPGME

This README is better is better viewed through the YARD formatted documentation:
http://rdoc.info/github/mrsimo/gpgme/master/frames for latest github version, or
http://rdoc.info/gems/gpgme for latest gem release.

== History behind this fork

This project started as my Ruby Mendicant University. The idea is to give an
overhaul to the API of this gem. As a relativelly new developer in the ruby
world, I found the documentation not very newbie friendly, and the API somewhat
different to the kind I'm used to in the ruby world.

GPG is a very powerful tool, and this gem is implemented using the C bindings,
making it very fast, and the only proper way to do it.

My objectives are as follows:

* Add test coverage of some type.
* Make documentation a little bit more newbie friendly.
* Improve the API to be more idiomatic.

== Requirements

* Ruby 1.8 or later
* GPGME 1.1.2 or later
* gpg-agent (optional, but recommended)

== Installation

 $ gem install gpgme

== API

GPGME provides three levels of API. The highest level API is as simple as it
gets, the mid level API provides more functionality but might be less
user-friendly, and the lowest level API is close to the C interface of GPGME.

=== The highest level API

For example, to create a cleartext signature of the plaintext from
stdin and write the result to stdout can be written as follows.

 crypto = GPGME::Crypto.new
 crypto.clearsign $stdin, :output => $stdout

=== The mid level API

The same example can be rewritten in the mid level API as follows.

 plain = GPGME::Data.new($stdin)
 sig   = GPGME::Data.new($stdout)
 GPGME::Ctx.new do |ctx|
   ctx.sign(plain, sig, GPGME::SIG_MODE_CLEAR)
 end

=== The lowest level API

The same example can be rewritten in the lowest level API as follows.

 ret = []
 GPGME::gpgme_new(ret)
 ctx = ret.shift
 GPGME::gpgme_data_new_from_fd(ret, 0)
 plain = ret.shift
 GPGME::gpgme_data_new_from_fd(ret, 1)
 sig = ret.shift
 GPGME::gpgme_op_sign(ctx, plain, sig, GPGME::SIG_MODE_CLEAR)

As you see, it's much harder to write a program in this API than the
highest level API. However, if you are already familiar with the C
interface of GPGME and want to control detailed behavior of GPGME, it
might be useful.

== Usage

All the high level methods attack the mid level {GPGME::Ctx} API. It is
recommended to read through the #{GPGME::Ctx.new} methods for common options.

Also, most of the input/output is done via {GPGME::Data} objects that create a
common interface for reading/writing to normal strings, or other common
objects like files. Read the {GPGME::Data} documentation to understand
how it works. Every time the lib needs a {GPGME::Data} object, it will be
automatically converted to it.

=== Crypto

The {GPGME::Crypto} class has the high level convenience methods to encrypt,
decrypt, sign and verify signatures. Here are some examples, but it is
recommended to read through the {GPGME::Crypto} class to see all the options.

* Document encryption via {GPGME::Crypto#encrypt}:
 crypto = GPGME::Crypto.new
 crypto.encrypt "Hello world!", :recipients => "someone@example.com"

* Symmetric encryption:
 crypto = GPGME::Crypto.new :password => "gpgme"
 crypto.encrypt "Hello world!", :symmetric => true


* Document decryption via {GPGME::Crypto#decrypt} (including signature verification):
 crypto.decrypt File.open("text.gpg")

* Document signing via {GPGME::Crypto#sign}. Also the clearsigning and detached signing.
 crypto.sign "I hereby proclaim Github the beneficiary of all my money when I die"

* Sign verification via {GPGME::Crypto#verify}
 sign = crypto.sign "Some text"
 data = crypto.verify(sign) { |signature| signature.valid? }

=== Key

The {GPGME::Key} object represents a key, and has the high level related
methods to work with them and find them, export, import, deletetion and
creation.

* Key listing
 GPGME::Key.find(:secret, "someone@example.com")
 # => Returns an array with all the secret keys available in the keychain.
 #    that match "someone@example.com"

* Key exporting
 GPGME::Key.export("someone@example.com")
 # => Returns a {GPGME::Data} object with the exported key.

 key = GPGME::Key.find(:secret, "someone@example.com").first
 key.export
 # => Returns a {GPGME::Data} object with the exported key.

* Key importing
 GPGME::Key.import(File.open("my.key"))

* TODO: Key generation

=== Engine

Provides three convenience methods to obtain information about the gpg engine
one is currently using. For example:

* Getting current information
 GPGME::Engine.engine_info.first
      # => #<GPGME::EngineInfo:0x00000100d4fbd8
             @file_name="/usr/local/bin/gpg",
             @protocol=0,
             @req_version="1.3.0",
             @version="1.4.11">

* Changing home directory to work with different settings:
 GPGME::Engine.home_dir = '/tmp'

== Contributing

To run the local test suite you need bundler and gpg:

 bundle
 rake compile   # simple rake task to compile the extension
 rake           # runs the test suite

== License

The library itself is licensed under LGPLv2.1+.  See the file
COPYING.LESSER and each file for copyright and warranty information.