gpgme 1.0.8 → 2.0.0

data/lib/gpgme/data.rb

@@ -0,0 +1,177 @@
+module GPGME
+
+  ##
+  # A class whose purpose is to unify the way we work with the data (both input
+  # and output). Most of the calls expect instances of this class, or will try
+  # to create one from your parameters.
+  #
+  # Read the {#read}, {#write} and {#seek} methods for the most commonly used
+  # methods.
+  class Data
+
+    BLOCK_SIZE = 4096
+
+    class << self
+
+      ##
+      # We implement +self.new+ instead of initialize because objects are actually
+      # instantiated through the C API with stuff like +gpgme_data_new+.
+      #
+      # We try to create a {GPGME::Data} smartly depending on the object passed, and if
+      # another {GPGME::Data} object is passed, it just returns it, so when in
+      # doubt, you can always pass a {GPGME::Data} object.
+      #
+      # @example empty
+      #   data = GPGME::Data.new
+      #   data.write("stuff")
+      #
+      # @example from a string
+      #   data = GPGME::Data.new("From a string")
+      #
+      # @example from a file
+      #   data = GPGME::Data.new(File.open("secure.pass"))
+      #
+      # @example from a file descriptor
+      #   data = GPGME::Data.new(0) # Standard input
+      #   data = GPGME::Data.new(1) # Standard output
+      #
+      #   file = File.open("secure.pass")
+      #   data = GPGME::Data.new(file.fileno) # file descriptor
+      #
+      def new(object = nil)
+        if object.nil?
+          empty!
+        elsif object.is_a?(Data)
+          object
+        elsif object.is_a?(Integer)
+          from_fd(object)
+        elsif object.respond_to? :to_str
+          from_str(object.to_str)
+        elsif object.respond_to? :to_io
+          from_io(object.to_io)
+        elsif object.respond_to? :open
+          from_io(object.open)
+        end
+      end
+
+      # Create a new instance with an empty buffer.
+      def empty!
+        rdh = []
+        err = GPGME::gpgme_data_new(rdh)
+        exc = GPGME::error_to_exception(err)
+        raise exc if exc
+        rdh.first
+      end
+
+      # Create a new instance with internal buffer.
+      def from_str(string)
+        rdh = []
+        err = GPGME::gpgme_data_new_from_mem(rdh, string, string.length)
+        exc = GPGME::error_to_exception(err)
+        raise exc if exc
+        rdh.first
+      end
+
+      # Create a new instance associated with a given IO.
+      def from_io(io)
+        from_callbacks(IOCallbacks.new(io))
+      end
+
+      # Create a new instance from the specified file descriptor.
+      def from_fd(fd)
+        rdh = []
+        err = GPGME::gpgme_data_new_from_fd(rdh, fd)
+        exc = GPGME::error_to_exception(err)
+        raise exc if exc
+        rdh.first
+      end
+
+      # Create a new instance from the specified callbacks.
+      def from_callbacks(callbacks, hook_value = nil)
+        rdh = []
+        err = GPGME::gpgme_data_new_from_cbs(rdh, callbacks, hook_value)
+        exc = GPGME::error_to_exception(err)
+        raise exc if exc
+        rdh.first
+      end
+    end # class << self
+
+    # Read at most +length+ bytes from the data object, or to the end
+    # of file if +length+ is omitted or is +nil+.
+    #
+    # @example
+    #   data = GPGME::Data.new("From a string")
+    #   data.read # => "From a string"
+    #
+    # @example
+    #   data = GPGME::Data.new("From a string")
+    #   data.read(4) # => "From"
+    #
+    def read(length = nil)
+      if length
+        GPGME::gpgme_data_read(self, length)
+      else
+        buf = String.new
+        loop do
+          s = GPGME::gpgme_data_read(self, BLOCK_SIZE)
+          break unless s
+          buf << s
+        end
+        buf
+      end
+    end
+
+    ##
+    # Seek to a given +offset+ in the data object according to the
+    # value of +whence+.
+    #
+    # @example going to the beginning of the buffer after writing something
+    #  data = GPGME::Data.new("Some data")
+    #  data.read # => "Some data"
+    #  data.read # => ""
+    #  data.seek 0
+    #  data.read # => "Some data"
+    #
+    def seek(offset, whence = IO::SEEK_SET)
+      GPGME::gpgme_data_seek(self, offset, IO::SEEK_SET)
+    end
+
+    ##
+    # Writes +length+ bytes from +buffer+ into the data object.
+    # Writes the full buffer if no length passed.
+    #
+    # @example
+    #   data = GPGME::Data.new
+    #   data.write "hola"
+    #   data.seek 0
+    #   data.read # => "hola"
+    #
+    # @example
+    #   data = GPGME::Data.new
+    #   data.write "hola", 2
+    #   data.seek 0
+    #   data.read # => "ho"
+    #
+    def write(buffer, length = buffer.length)
+      GPGME::gpgme_data_write(self, buffer, length)
+    end
+
+    ##
+    # Return the encoding of the underlying data.
+    def encoding
+      GPGME::gpgme_data_get_encoding(self)
+    end
+
+    ##
+    # Sets the encoding for this buffer. Accepts only values in one of the
+    # DATA_ENCODING_* constants.
+    #
+    # @raise [GPGME::Error::InvalidValue] if the value isn't accepted.
+    def encoding=(encoding)
+      err = GPGME::gpgme_data_set_encoding(self, encoding)
+      exc = GPGME::error_to_exception(err)
+      raise exc if exc
+      encoding
+    end
+  end
+end

data/lib/gpgme/engine.rb

@@ -0,0 +1,76 @@
+module GPGME
+
+  ##
+  # Convenience methods to check different aspects of the gpg system
+  # installation.
+  module Engine
+    class << self
+
+      ##
+      # Verify that the engine implementing the protocol +proto+ is installed in
+      # the system. Can be one of +PROTOCOL_OpenPGP+ or +PROTOCOL_CMS+.
+      #
+      # @return [Boolean] true if the engine is installed.
+      #
+      # @example
+      #   GPGME::Engine.check_version(GPGME::PROTOCOL_OpenPGP) # => true
+      #
+      def check_version(proto)
+        err = GPGME::gpgme_engine_check_version(proto)
+        exc = GPGME::error_to_exception(err)
+        !exc
+      end
+
+      ##
+      # Return an array of {GPGME::EngineInfo} structures of enabled engines.
+      #
+      # @example
+      #   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">
+      #
+      def info
+        rinfo = []
+        GPGME::gpgme_get_engine_info(rinfo)
+        rinfo
+      end
+
+      ##
+      # Change the default configuration of the crypto engine implementing
+      # protocol +proto+.
+      #
+      # @param proto
+      #   Can be one of +PROTOCOL_OpenPGP+ or +PROTOCOL_CMS+.
+      #
+      # @param file_name
+      #   The file name of the executable program implementing the protocol.
+      #
+      # @param home_dir
+      #   The directory name of the configuration directory.
+      #
+      # @example
+      #   GPGME::Engine.set
+      #
+      def set_info(proto, file_name, home_dir)
+        err = GPGME::gpgme_set_engine_info(proto, file_name, home_dir)
+        exc = GPGME::error_to_exception(err)
+        raise exc if exc
+      end
+
+      ##
+      # Sets the home dir for the configuration options. This way one could,
+      # for example, load the keys from a customized keychain.
+      #
+      # @example
+      #   GPGME::Engine.home_dir = '/tmp'
+      #
+      def home_dir=(home_dir)
+        current = info.first
+        set_info current.protocol, current.file_name, home_dir
+      end
+    end # class << self
+  end # class Engine
+end # module GPGME

data/lib/gpgme/error.rb

@@ -0,0 +1,66 @@
+module GPGME
+  class Error < StandardError
+    def initialize(error)
+      @error = error
+    end
+    attr_reader :error
+
+    # Return the error code.
+    #
+    # The error code indicates the type of an error, or the reason why
+    # an operation failed.
+    def code
+      GPGME::gpgme_err_code(@error)
+    end
+
+    # Return the error source.
+    #
+    # The error source has not a precisely defined meaning.  Sometimes
+    # it is the place where the error happened, sometimes it is the
+    # place where an error was encoded into an error value.  Usually
+    # the error source will give an indication to where to look for
+    # the problem.  This is not always true, but it is attempted to
+    # achieve this goal.
+    def source
+      GPGME::gpgme_err_source(@error)
+    end
+
+    # Return a description of the error code.
+    def message
+      GPGME::gpgme_strerror(@error)
+    end
+
+    class General < self; end
+    class InvalidValue < self; end
+    class UnusablePublicKey < self
+      attr_accessor :keys
+    end
+    class UnusableSecretKey < self
+      attr_accessor :keys
+    end
+    class NoData < self; end
+    class Conflict < self; end
+    class NotImplemented < self; end
+    class DecryptFailed < self; end
+    class BadPassphrase < self; end
+    class Canceled < self; end
+    class InvalidEngine < self; end
+    class AmbiguousName < self; end
+    class WrongKeyUsage < self
+      attr_accessor :key_usage
+    end
+    class CertificateRevoked < self; end
+    class CertificateExpired < self; end
+    class NoCRLKnown < self; end
+    class NoPolicyMatch < self; end
+    class NoSecretKey < self; end
+    class MissingCertificate < self; end
+    class BadCertificateChain < self; end
+    class UnsupportedAlgorithm < self
+      attr_accessor :algorithm
+    end
+    class BadSignature < self; end
+    class NoPublicKey < self; end
+    class InvalidVersion < self; end
+  end
+end

data/lib/gpgme/io_callbacks.rb

@@ -0,0 +1,21 @@
+module GPGME
+  class IOCallbacks
+    def initialize(io)
+      @io = io
+    end
+
+    def read(hook, length)
+      @io.read(length)
+    end
+
+    def write(hook, buffer, length)
+      @io.write(buffer[0 .. length])
+    end
+
+    def seek(hook, offset, whence)
+      return @io.pos if offset == 0 && whence == IO::SEEK_CUR
+      @io.seek(offset, whence)
+      @io.pos
+    end
+  end
+end

data/lib/gpgme/key.rb

@@ -0,0 +1,242 @@
+module GPGME
+
+  ##
+  # A ruby representation of a public or a secret key.
+  #
+  # Every key has two instances of {GPGME::SubKey}, accessible through
+  # {.subkeys}, and with a {.primary_subkey} where most attributes are
+  # derived from, like the +fingerprint+.
+  #
+  # Also, every key has at least a {GPGME::UserID}, accessible through
+  # {.uids}, with a {.primary_uid}, where other attributes are derived from,
+  # like +email+ or +name+
+  class Key
+    private_class_method :new
+
+    attr_reader :keylist_mode, :protocol, :owner_trust
+    attr_reader :issuer_serial, :issuer_name, :chain_id
+    attr_reader :subkeys, :uids
+
+    include KeyCommon
+
+    class << self
+
+      ##
+      # Returns an array of {GPGME::Key} objects that match the parameters.
+      # * +secret+ set to +:secret+ to get only secret keys, or to +:public+ to
+      #   get only public keys.
+      # * +keys_or_names+ an array or an item that can be either {GPGME::Key}
+      #   elements, or string identifiers like the email or the sha. Leave
+      #   blank to get all.
+      # * +purposes+ get only keys that are usable for any of these purposes.
+      #   See {GPGME::Key} for a list of possible key capabilities.
+      #
+      # @example
+      #   GPGME::Key.find :secret # => first secret key found
+      #
+      # @example
+      #   GPGME::Key.find(:public, "mrsimo@example.com")
+      #   # => return only public keys that match mrsimo@example.com
+      #
+      # @example
+      #   GPGME::Key.find(:public, "mrsimo@example.com", :sign)
+      #   # => return the public keys that match mrsimo@example.com and are
+      #   #    capable of signing
+      def find(secret, keys_or_names = nil, purposes = [])
+        secret = (secret == :secret)
+        keys_or_names = [""] if keys_or_names.nil? || (keys_or_names.is_a?(Array) && keys_or_names.empty?)
+        keys_or_names = [keys_or_names].flatten
+        purposes      = [purposes].flatten.compact.uniq
+
+        keys = []
+        keys_or_names.each do |key_or_name|
+          case key_or_name
+          when Key then keys << key_or_name
+          when String
+            GPGME::Ctx.new do |ctx|
+              keys += ctx.keys(key_or_name, secret).select do |k|
+                k.usable_for?(purposes)
+              end
+            end
+          end
+        end
+        keys
+      end
+
+      def get(fingerprint)
+        Ctx.new do |ctx|
+          ctx.get_key(fingerprint)
+        end
+      end
+
+      # Exports public keys
+      #
+      #   GPGME::Key.export pattern, options
+      #
+      # Private keys cannot be exported due to GPGME restrictions.
+      #
+      # @param pattern
+      #   Identifier of the key to export.
+      #
+      # @param [Hash] options
+      #   * +:output+ specify where to write the key to. It will be converted to
+      #     a {GPGME::Data}, so it could be a file, for example.
+      #   * Any other option accepted by {GPGME::Ctx.new}
+      #
+      # @return [GPGME::Data] the exported key.
+      #
+      # @example
+      #   key = GPGME::Key.export "mrsimo@example.com"
+      #
+      # @example writing to a file
+      #   out = File.open("my.key", "w+")
+      #   GPGME::Key.export "mrsimo@example.com", :output => out
+      #
+      def export(pattern, options = {})
+        output = Data.new(options[:output])
+
+        GPGME::Ctx.new(options) do |ctx|
+          ctx.export_keys(pattern, output)
+        end
+
+        output.seek(0)
+        output
+      end
+
+      # Imports a key
+      #
+      #   GPGME::Key.import keydata, options
+      #
+      # @param keydata
+      #   The key to import. It will be converted to a {GPGME::Data} object,
+      #   so could be a file, for example.
+      # @param options
+      #   Any other option accepted by {GPGME::Ctx.new}
+      #
+      # @example
+      #   GPGME::Key.import(File.open("my.key"))
+      #
+      def import(keydata, options = {})
+        GPGME::Ctx.new(options) do |ctx|
+          ctx.import_keys(Data.new(keydata))
+          ctx.import_result
+        end
+      end
+    end
+
+    ##
+    # Exports this key. Accepts the same options as {GPGME::Ctx.new}, and
+    # +options[:output]+, where you can specify something that can become a
+    # {GPGME::Data}, where the output will go.
+    #
+    # @example
+    #   key.export(:armor => true)
+    #   # => GPGME::Data you can read with ASCII armored format
+    #
+    # @example
+    #   file = File.open("key.asc", "w+")
+    #   key.export(:output => file)
+    #   # => the key will be written to the file.
+    #
+    def export(options = {})
+      Key.export self.sha, options
+    end
+
+    ##
+    # Delete this key. If it's public, and has a secret one it will fail unless
+    # +allow_secret+ is specified as true.
+    def delete!(allow_secret = false)
+      GPGME::Ctx.new do |ctx|
+        ctx.delete_key self, allow_secret
+      end
+    end
+
+    ##
+    # Returns the expiry date for this key
+    def expires
+      primary_subkey.expires
+    end
+
+    ##
+    # Returns true if the key is expired
+    def expired
+      subkeys.any?(&:expired)
+    end
+
+    def primary_subkey
+      @primary_subkey ||= subkeys.first
+    end
+
+    ##
+    # Short descriptive value. Can be used to identify the key.
+    def sha
+      primary_subkey.sha
+    end
+
+    ##
+    # Longer descriptive value. Can be used to identify the key.
+    def fingerprint
+      primary_subkey.fingerprint
+    end
+
+    ##
+    # Returns the main {GPGME::UserID} for this key.
+    def primary_uid
+      uids.first
+    end
+
+    ##
+    # Returns the email for this key.
+    def email
+      primary_uid.email
+    end
+
+    ##
+    # Returns the issuer name for this key.
+    def name
+      primary_uid.name
+    end
+
+    ##
+    # Returns the issuer comment for this key.
+    def comment
+      primary_uid.comment
+    end
+
+    def ==(another_key)
+      fingerprint == another_key.fingerprint
+    end
+
+    def inspect
+      sprintf("#<#{self.class} %s %4d%s/%s %s trust=%s, owner_trust=%s, \
+capability=%s, subkeys=%s, uids=%s>",
+              primary_subkey.secret? ? 'sec' : 'pub',
+              primary_subkey.length,
+              primary_subkey.pubkey_algo_letter,
+              primary_subkey.fingerprint[-8 .. -1],
+              primary_subkey.timestamp.strftime('%Y-%m-%d'),
+              trust.inspect,
+              VALIDITY_NAMES[@owner_trust].inspect,
+              capability.inspect,
+              subkeys.inspect,
+              uids.inspect)
+    end
+
+    def to_s
+      primary_subkey = subkeys[0]
+      s = sprintf("%s   %4d%s/%s %s\n",
+                  primary_subkey.secret? ? 'sec' : 'pub',
+                  primary_subkey.length,
+                  primary_subkey.pubkey_algo_letter,
+                  primary_subkey.fingerprint[-8 .. -1],
+                  primary_subkey.timestamp.strftime('%Y-%m-%d'))
+      uids.each do |user_id|
+        s << "uid\t\t#{user_id.name} <#{user_id.email}>\n"
+      end
+      subkeys.each do |subkey|
+        s << subkey.to_s
+      end
+      s
+    end
+  end
+end