¶ ↑
GPGMEThis README is better viewed through the YARD formatted documentation: rdoc.info/github/ueno/gpgme/master/frames for latest github version, or rdoc.info/gems/gpgme for latest gem release.
¶ ↑
Requirements-
Ruby 1.8 or later
-
GPGME 1.1.2 or later
-
gpg-agent (optional, but recommended)
¶ ↑
Installation$ gem install gpgme
¶ ↑
APIGPGME 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 APIFor 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 APIThe 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 APIThe 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.
¶ ↑
UsageAll 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.
¶ ↑
CryptoThe {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? }
¶ ↑
KeyThe {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
¶ ↑
EngineProvides three convenience methods to obtain information about the gpg engine one is currently using. For example:
-
Getting current information
GPGME::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'
¶ ↑
ContributingTo 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
¶ ↑
LicenseThe library itself is licensed under LGPLv2.1+. See the file COPYING.LESSER and each file for copyright and warranty information.