benburkert-gpgme 0.1.0

data/README.rdoc

@@ -0,0 +1,162 @@
+= 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.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+require 'rcov/rcovtask'
+require 'yard'
+
+
+desc "Re-compile the extensions"
+task :compile do
+  FileUtils.rm_rf('tmp') if File.directory?('tmp')
+  mkdir 'tmp'
+
+  Dir.chdir('tmp') do
+    system "ruby #{File.dirname(__FILE__)}/ext/gpgme/extconf.rb"
+    system "make"
+  end
+end
+
+task :default => [:test]
+
+Rake::TestTask.new(:test => :compile) do |t|
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+Rake::Task['test'].comment = "Run all tests"
+
+YARD::Rake::YardocTask.new
+
+Rcov::RcovTask.new do |t|
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+  t.rcov_opts = ["-x gems"]
+end
+

data/THANKS

@@ -0,0 +1,15 @@
+Ruby-GPGME was originally written by Daiki Ueno.  Other people
+contributed by reporting problems, suggesting various improvements or
+submitting actual code.  Here is a list of those people.  Help us keep
+it complete and free of errors.
+
+
+
+Carl Corliss
+Jérémie Pierson
+Kouhei Sutou
+Kris Nuttycombe
+Marc Dequènes
+Rob Pitt
+Rory McKinley
+Sam Hall

data/benburkert-gpgme.gemspec

@@ -0,0 +1,30 @@
+Gem::Specification.new do |s|
+  s.name              = 'benburkert-gpgme'
+  s.version           = '0.1.0'
+  s.authors           = ['Daiki Ueno']
+  s.date              = '2011-05-09'
+  s.email             = 'ueno@unixuser.org'
+  s.extensions        = ['ext/gpgme/extconf.rb']
+  s.files             = `git ls-files`.split("\n")
+  s.has_rdoc          = true
+  s.rubyforge_project = 'ruby-gpgme'
+  s.homepage          = 'http://rubyforge.org/projects/ruby-gpgme/'
+  s.require_paths     = ['lib', 'ext']
+  s.summary           = "Ben Burkert's fork of the Ruby binding of GPGME."
+  s.description       = %q{Ruby-GPGME is a Ruby language binding of GPGME (GnuPG
+Made Easy). GnuPG Made Easy (GPGME) is a library designed to make access to
+GnuPG easier for applications. It provides a High-Level Crypto API for
+encryption, decryption, signing, signature verification and key management.}
+
+  s.add_development_dependency "mocha",     "~> 0.9.12"
+  s.add_development_dependency "minitest",  "~> 2.1.0"
+  s.add_development_dependency "yard",      "~> 0.6.7"
+  s.add_development_dependency "rcov",      "~> 0.9.9"
+
+  case RUBY_VERSION
+  when "1.9.2"
+    s.add_development_dependency "ruby-debug19" , "~> 0.11.6"
+  else
+    s.add_development_dependency "ruby-debug" , "~> 0.10.4"
+  end
+end

data/examples/edit.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+# If you do not have gpg-agent installed, comment out the following
+# and set it as :passphrase_callback.
+#
+# def passfunc(hook, uid_hint, passphrase_info, prev_was_bad, fd)
+#   $stderr.write("Passphrase for #{uid_hint}: ")
+#   $stderr.flush
+#   begin
+#     system('stty -echo')
+#     io = IO.for_fd(fd, 'w')
+#     io.puts(gets)
+#     io.flush
+#   ensure
+#     (0 ... $_.length).each do |i| $_[i] = ?0 end if $_
+#     system('stty echo')
+#   end
+#   $stderr.puts
+# end
+
+unless ENV['GPG_AGENT_INFO']
+  $stderr.puts("gpg-agent is not running.  See the comment in #{$0}.")
+  exit(1)
+end
+
+unless ENV['GNUPGHOME']
+  $stderr.write('As GNUPGHOME is not set, the generated key pair will be stored into *your* keyring.  Really proceed? (y/N) ')
+  $stderr.flush
+  exit(1) unless gets.chomp == 'y'
+end
+
+unless ARGV.length == 1
+  $stderr.puts("Usage: #{$0} KEYGRIP")
+  exit(1)
+end
+
+def progfunc(hook, what, type, current, total)
+  $stderr.write("#{what}: #{current}/#{total}\r")
+  $stderr.flush
+end
+
+def editfunc(hook, status, args, fd)
+  case status
+  when GPGME::GPGME_STATUS_GET_BOOL
+    begin
+      $stderr.write("#{args} (y/n) ")
+      $stderr.flush
+      line = gets
+    end until line =~ /\A\s*[ny]\s*\z/
+    io = IO.for_fd(fd)
+    io.puts(line.strip)
+    io.flush
+  when GPGME::GPGME_STATUS_GET_LINE, GPGME::GPGME_STATUS_GET_HIDDEN
+    $stderr.write("#{args}: ")
+    $stderr.flush
+    line = gets
+    io = IO.for_fd(fd)
+    io.puts(line)
+    io.flush
+  else
+    $stderr.puts([status, args].inspect)
+  end
+end
+
+ctx = GPGME::Ctx.new({:progress_callback => method(:progfunc),
+		       # :passphrase_callback => method(:passfunc)
+		     })
+keystr = ARGV.shift
+keys = ctx.keys(keystr)
+if keys.empty?
+  $stderr.puts("Can't find key for \"#{keystr}\"")
+  exit(1)
+end
+
+$stderr.puts(keys.first.inspect)
+ctx.edit_key(keys.first, method(:editfunc))

data/examples/genkey.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+# If you do not have gpg-agent installed, comment out the following
+# and set it as :passphrase_callback.
+#
+# def passfunc(hook, uid_hint, passphrase_info, prev_was_bad, fd)
+#   $stderr.write("Passphrase for #{uid_hint}: ")
+#   $stderr.flush
+#   begin
+#     system('stty -echo')
+#     io = IO.for_fd(fd, 'w')
+#     io.puts(gets)
+#     io.flush
+#   ensure
+#     (0 ... $_.length).each do |i| $_[i] = ?0 end if $_
+#     system('stty echo')
+#   end
+#   $stderr.puts
+# end
+
+unless ENV['GPG_AGENT_INFO']
+  $stderr.puts("gpg-agent is not running.  See the comment in #{$0}.")
+  exit(1)
+end
+
+unless ENV['GNUPGHOME']
+  $stderr.write('As GNUPGHOME is not set, the generated key pair will be stored into *your* keyring.  Really proceed? (y/N) ')
+  $stderr.flush
+  exit(1) unless gets.chomp == 'y'
+end
+
+def progfunc(hook, what, type, current, total)
+  $stderr.write("#{what}: #{current}/#{total}\r")
+  $stderr.flush
+end
+
+ctx = GPGME::Ctx.new({:progress_callback => method(:progfunc),
+		       # :passphrase_callback => method(:passfunc)
+		     })
+
+ctx.genkey(<<'EOF', nil, nil)
+<GnupgKeyParms format="internal">
+Key-Type: DSA
+Key-Length: 1024
+Subkey-Type: ELG-E
+Subkey-Length: 1024
+Name-Real: Joe Tester
+Name-Comment: with stupid passphrase
+Name-Email: joe@foo.bar
+Expire-Date: 0
+Passphrase: abc
+</GnupgKeyParms>
+EOF
+$stderr.puts

data/examples/keylist.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+GPGME.list_keys(ARGV.shift) do |key|
+  puts(key)
+end

data/examples/roundtrip.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+# If you do not have gpg-agent installed, comment out the following
+# and set it as :passphrase_callback.
+#
+# def passfunc(hook, uid_hint, passphrase_info, prev_was_bad, fd)
+#   $stderr.write("Passphrase for #{uid_hint}: ")
+#   $stderr.flush
+#   begin
+#     system('stty -echo')
+#     io = IO.for_fd(fd, 'w')
+#     io.puts(gets)
+#     io.flush
+#   ensure
+#     (0 ... $_.length).each do |i| $_[i] = ?0 end if $_
+#     system('stty echo')
+#   end
+#   $stderr.puts
+# end
+
+unless ENV['GPG_AGENT_INFO']
+  $stderr.puts("gpg-agent is not running.  See the comment in #{$0}.")
+  exit(1)
+end
+
+plain = 'test test test'
+puts("Plaintext:\n#{plain}")
+
+# Perform symmetric encryption on PLAIN.
+cipher = GPGME::encrypt(nil, plain, {:armor => true,
+			  # :passphrase_callback => method(:passfunc)
+			})
+puts("Ciphertext:\n#{cipher}")
+
+plain = GPGME::decrypt(cipher, {
+			 # :passphrase_callback => method(:passfunc)
+		       })
+puts("Plaintext:\n#{plain}")

data/examples/sign.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+# If you do not have gpg-agent installed, comment out the following
+# and set it as :passphrase_callback.
+#
+# def passfunc(hook, uid_hint, passphrase_info, prev_was_bad, fd)
+#   $stderr.write("Passphrase for #{uid_hint}: ")
+#   $stderr.flush
+#   begin
+#     system('stty -echo')
+#     io = IO.for_fd(fd, 'w')
+#     io.puts(gets)
+#     io.flush
+#   ensure
+#     (0 ... $_.length).each do |i| $_[i] = ?0 end if $_
+#     system('stty echo')
+#   end
+#   $stderr.puts
+# end
+
+unless ENV['GPG_AGENT_INFO']
+  $stderr.puts("gpg-agent is not running.  See the comment in #{$0}.")
+  exit(1)
+end
+
+puts GPGME::clearsign('test test test', {
+                   # :passphrase_callback => method(:passfunc)
+                 })

data/examples/verify.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'gpgme'
+
+GPGME::verify(ARGF.read, nil, $stdout) do |signature|
+  puts(signature.to_s)
+end

data/ext/gpgme/extconf.rb

@@ -0,0 +1,26 @@
+require 'mkmf'
+
+unless find_executable('gpgme-config')
+  $stderr.puts("gpgme-config not found")
+  exit(1)
+end
+
+$CFLAGS += ' ' << `gpgme-config --cflags`.chomp
+$libs += ' ' << `gpgme-config --libs`.chomp
+
+checking_for('gpgme >= 1.1.3') do
+  if try_run(<<'End')
+#include <gpgme.h>
+#include <stdlib.h>
+int main (void) {
+  return gpgme_check_version ("1.1.3") == NULL;
+}
+End
+    true
+  else
+    $CFLAGS += ' -DRUBY_GPGME_NEED_WORKAROUND_KEYLIST_NEXT'
+    false
+  end
+end
+have_func('gpgme_op_export_keys')
+create_makefile ('gpgme_n')