This README is better is better viewed through the YARD formatted documentation: rdoc.info/github/mrsimo/gpgme/master/frames for latest github version, or rdoc.info/gems/gpgme for latest gem release.
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.
-
Ruby 1.8 or later
-
GPGME 1.1.2 or later
-
gpg-agent (optional, but recommended)
$ gem install gpgme
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.
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 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 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.
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.
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 => "[email protected]"
-
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? }
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, "[email protected]") # => Returns an array with all the secret keys available in the keychain. # that match "[email protected]"
-
Key exporting
GPGME::Key.export("[email protected]") # => Returns a {GPGME::Data} object with the exported key. key = GPGME::Key.find(:secret, "[email protected]").first key.export # => Returns a {GPGME::Data} object with the exported key.
-
Key importing
GPGME::Key.import(File.open("my.key"))
-
TODO: Key generation
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'
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
The library itself is licensed under LGPLv2.1+. See the file COPYING.LESSER and each file for copyright and warranty information.