зеркало из https://github.com/github/ruby-gpgme.git
150 строки
4.7 KiB
Plaintext
150 строки
4.7 KiB
Plaintext
= GPGME
|
|
|
|
This README is better viewed through the YARD formatted documentation:
|
|
http://rdoc.info/github/ueno/ruby-gpgme/frames for latest github
|
|
version, or http://rdoc.info/gems/gpgme for latest gem release.
|
|
|
|
{<img src="https://travis-ci.org/ueno/ruby-gpgme.png?branch=master" alt="Build Status" />}[https://travis-ci.org/ueno/ruby-gpgme]
|
|
{<img src="https://coveralls.io/repos/ueno/ruby-gpgme/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/ueno/ruby-gpgme]
|
|
|
|
== 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.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.
|