openpgp 0.0.2 → 0.0.3

data/lib/openpgp/digest.rb

@@ -14,6 +14,9 @@ module OpenPGP
 
     DEFAULT = SHA1
 
+    ##
+    # @param  [Symbol, String, Integer] identifier
+    # @return [Class]
     def self.for(identifier)
       case identifier
         when Symbol then const_get(identifier.to_s.upcase)
@@ -28,30 +31,46 @@ module OpenPGP
       end
     end
 
+    ##
+    # @return [Integer]
     def self.to_i() identifier end
 
+    ##
+    # @return [Integer]
     def self.identifier
       const_get(:IDENTIFIER)
     end
 
+    ##
+    # @return [Symbol]
     def self.algorithm
       name.split('::').last.to_sym unless self == Digest
     end
 
+    ##
+    # @return [Integer]
     def self.hexsize
       size * 2
     end
 
+    ##
+    # @return [Integer]
     def self.size
       require 'digest' unless defined?(::Digest)
       ::Digest.const_get(algorithm).new.digest_length
     end
 
+    ##
+    # @param  [String] data
+    # @return [String]
     def self.hexdigest(data)
       require 'digest' unless defined?(::Digest)
       ::Digest.const_get(algorithm).hexdigest(data).upcase
     end
 
+    ##
+    # @param  [String] data
+    # @return [String]
     def self.digest(data)
       require 'digest' unless defined?(::Digest)
       ::Digest.const_get(algorithm).digest(data)

data/lib/openpgp/digest/md5.rb

@@ -1,5 +1,6 @@
 module OpenPGP
   class Digest
+    ##
     class MD5 < Digest
       IDENTIFIER = 1
     end

data/lib/openpgp/digest/rmd160.rb

@@ -1,5 +1,6 @@
 module OpenPGP
   class Digest
+    ##
     class RIPEMD160 < Digest
       IDENTIFIER = 3
     end

data/lib/openpgp/digest/sha1.rb

@@ -1,5 +1,6 @@
 module OpenPGP
   class Digest
+    ##
     class SHA1 < Digest
       IDENTIFIER = 2
     end

data/lib/openpgp/digest/sha2.rb

@@ -1,17 +1,21 @@
 module OpenPGP
   class Digest
+    ##
     class SHA224 < Digest
       IDENTIFIER = 11
     end
 
+    ##
     class SHA256 < Digest
       IDENTIFIER = 8
     end
 
+    ##
     class SHA384 < Digest
       IDENTIFIER = 9
     end
 
+    ##
     class SHA512 < Digest
       IDENTIFIER = 10
     end

data/lib/openpgp/engine.rb

@@ -1,8 +1,11 @@
 module OpenPGP
+  ##
   class Engine
     autoload :GnuPG,   'openpgp/engine/gnupg'
     autoload :OpenSSL, 'openpgp/engine/openssl'
 
+    ##
+    # @return [Boolean]
     def self.available?
       begin
         load!(true)
@@ -12,14 +15,25 @@ module OpenPGP
       end
     end
 
+    ##
+    # @param  [Boolean] reload
+    # @return [void]
+    # @raise  [LoadError]
     def self.load!(reload = false)
       raise LoadError
     end
 
+    ##
+    # @return [void]
+    # @raise  [LoadError]
     def self.install!
       load!
     end
 
+    ##
+    # @yield  [engine]
+    # @yieldparam [Engine] engine
+    # @return [void]
     def self.use(&block)
       load!
       block.call(self)
@@ -27,6 +41,9 @@ module OpenPGP
 
     protected
 
+      ##
+      # @param  [Module] extension
+      # @return [void]
       def self.install_extensions!(extension)
         name = extension.name.split('::').last.to_sym
 

data/lib/openpgp/engine/gnupg.rb

@@ -6,6 +6,8 @@ module OpenPGP class Engine
   class GnuPG < Engine
     class Error < IOError; end
 
+    ##
+    # @return [Boolean]
     def self.available?
       self.new.available?
     end
@@ -19,9 +21,14 @@ module OpenPGP class Engine
       :no_random_seed_file   => true,
     }
 
+    # @return [String]
     attr_accessor :where
+
+    # @return [Hash{Symbol => Object}]
     attr_accessor :options
 
+    ##
+    # @param  [Hash{Symbol => Object}] options
     def initialize(options = {})
       @where   = '/usr/bin/env gpg' # FIXME
       @options = OPTIONS.merge!(options)
@@ -29,18 +36,25 @@ module OpenPGP class Engine
 
     ##
     # Determines if GnuPG is available.
+    #
+    # @return [Boolean]
     def available?
       !!version
     end
 
     ##
     # Returns the GnuPG version number.
+    #
+    # @return [String]
     def version
       exec(:version).readline =~ /^gpg \(GnuPG\) (.*)$/ ? $1 : nil
     end
 
     ##
     # Generates a new OpenPGP keypair and stores it GnuPG's keyring.
+    #
+    # @param  [Hash{Symbol => String}] info
+    # @return [Integer]
     def gen_key(info = {})
       stdin, stdout, stderr = exec3(:gen_key) do |stdin, stdout, stderr|
         stdin.puts "Key-Type: #{info[:key_type]}"           if info[:key_type]
@@ -64,22 +78,34 @@ module OpenPGP class Engine
 
     ##
     # Exports a specified key from the GnuPG keyring.
+    #
+    # @param  [String] key_id
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Message]
     def export(key_id = nil, opts = {})
       OpenPGP::Message.parse(exec([:export, *[key_id].flatten], opts ).read)
     end
 
-    ##
     ##
     # Imports a specified keyfile into the GnuPG keyring.
+    #
+    # @return [void]
     def import()
       # TODO
     end
 
+    ##
+    # @param  [String] key_id
+    # @return [void]
     def delete_secret_and_public_key(key_id)
       opts = {:batch => true}
       OpenPGP::Message.parse(exec([:delete_secret_and_public_key, key_fingerprint(key_id)], opts ).read)
     end
 
+    ##
+    # @param  [String] key_id
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
     def key_fingerprint(key_id, opts = {})
       message = exec([:fingerprint, *[key_id].flatten], opts ).read
       if message =~ /Key fingerprint = (.*)\n/
@@ -90,24 +116,36 @@ module OpenPGP class Engine
 
     ##
     # Returns an array of key IDs/titles of the keys in the public keyring.
+    #
+    # @return [Array]
     def list_keys()
       # TODO
     end
 
     ##
     # Encrypts the given plaintext to the specified recipients.
+    #
+    # @param  [String] plaintext
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
     def encrypt(plaintext, options = {})
       # TODO
     end
 
     ##
     # Decrypts the given ciphertext using the specified key ID.
+    #
+    # @param  [String] ciphertext
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
     def decrypt(ciphertext, options = {})
       # TODO
     end
 
     ##
     # Makes an OpenPGP signature.
+    #
+    # @return [void]
     def sign()
       # TODO
     end
@@ -139,6 +177,10 @@ module OpenPGP class Engine
     ##
     # Executes a GnuPG command, yielding the standard input and returning
     # the standard output.
+    #
+    # @param  [String] command
+    # @param  [Hash{Symbol => Object}] options
+    # @return [IO]
     def exec(command, options = {}, &block) #:yields: stdin
       exec4(command, options) do |pid, stdin, stdout, stderr|
         block.call(stdin) if block_given?
@@ -152,6 +194,10 @@ module OpenPGP class Engine
     ##
     # Executes a GnuPG command, yielding and returning the standard input,
     # output and error.
+    #
+    # @param  [String] command
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Array(IO, IO, IO)]
     def exec3(command, options = {}, &block) #:yields: stdin, stdout, stderr
       exec4(command, options) do |pid, stdin, stdout, stderr|
         block.call(stdin, stdout, stderr) if block_given?
@@ -165,6 +211,10 @@ module OpenPGP class Engine
     ##
     # Executes a GnuPG command, yielding the process identifier as well as
     # the standard input, output and error.
+    #
+    # @param  [String] command
+    # @param  [Hash{Symbol => Object}] options
+    # @return [void]
     def exec4(command, options = {}, &block) #:yields: pid, stdin, stdout, stderr
       require 'rubygems'
       require 'open4'
@@ -175,6 +225,10 @@ module OpenPGP class Engine
 
       ##
       # Constructs the GnuPG command-line for use with +exec+.
+      #
+      # @param  [String] command
+      # @param  [Hash{Symbol => Object}] options
+      # @return [String]
       def cmdline(command, options = {})
         command = [command].flatten
         cmdline = [where]
@@ -186,6 +240,9 @@ module OpenPGP class Engine
 
       ##
       # Translates Ruby symbols into GnuPG option arguments.
+      #
+      # @param  [String, #to_s] option
+      # @return [String]
       def option(option)
         "--" << option.to_s.gsub('_', '-')
       end

data/lib/openpgp/engine/openssl.rb

@@ -1,15 +1,24 @@
 module OpenPGP
   class Engine
     class OpenSSL < Engine
+      ##
+      # @param  [Boolean] reload
+      # @return [void]
+      # @raise  [LoadError]
       def self.load!(reload = false)
         require 'openssl' unless defined?(::OpenSSL) || reload
       end
 
+      ##
+      # @return [void]
+      # @raise  [LoadError]
       def self.install!
         load!
         [Random, Digest].each { |mod| install_extensions! mod }
       end
 
+      ##
+      # @private
       module Random #:nodoc:
         def number(bits = 32, options = {})
           ::OpenSSL::BN.rand(bits)
@@ -24,6 +33,8 @@ module OpenPGP
         end
       end
 
+      ##
+      # @private
       module Digest #:nodoc:
         def size
           ::OpenSSL::Digest.new(algorithm.to_s).digest_length
@@ -38,10 +49,11 @@ module OpenPGP
         end
       end
 
+      ##
+      # @private
       module Cipher #:nodoc:
         # TODO
       end
-
     end
   end
 end

data/lib/openpgp/message.rb

@@ -8,10 +8,15 @@ module OpenPGP
   class Message
     include Enumerable
 
+    # @return [Array<Packet>]
     attr_accessor :packets
 
     ##
     # Creates an encrypted OpenPGP message.
+    #
+    # @param  [Object]                 data
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Message]
     def self.encrypt(data, options = {}, &block)
       if options[:symmetric]
         key    = (options[:key]    || S2K::DEFAULT.new(options[:passphrase]))
@@ -38,6 +43,9 @@ module OpenPGP
     end
 
     ##
+    # @param  [Object]                 data
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Object]
     def self.decrypt(data, options = {}, &block)
       raise NotImplementedError # TODO
     end
@@ -45,8 +53,10 @@ module OpenPGP
     ##
     # Parses an OpenPGP message.
     #
-    # @see http://tools.ietf.org/html/rfc4880#section-4.1
-    # @see http://tools.ietf.org/html/rfc4880#section-4.2
+    # @param  [Buffer, #to_str] data
+    # @return [Message]
+    # @see    http://tools.ietf.org/html/rfc4880#section-4.1
+    # @see    http://tools.ietf.org/html/rfc4880#section-4.2
     def self.parse(data)
       data = Buffer.new(data.to_str) if data.respond_to?(:to_str)
 
@@ -61,36 +71,56 @@ module OpenPGP
       msg
     end
 
+    ##
+    # @return [IO, #write] io
+    # @return [void]
     def self.write(io = nil, &block)
       data = self.new(&block).to_s
       io.respond_to?(:write) ? io.write(data) : data
     end
 
+    ##
+    # @param  [Array<Packet>] packets
     def initialize(*packets, &block)
       @packets = packets.flatten
       block.call(self) if block_given?
     end
 
+    ##
+    # @yield  [packet]
+    # @yieldparam [Packet] packet
+    # @return [Enumerator]
     def each(&block) # :yields: packet
       packets.each(&block)
     end
 
+    ##
+    # @return [Array<Packet>]
     def to_a
       packets.to_a
     end
 
+    ##
+    # @param  [Packet] packet
+    # @return [self]
     def <<(packet)
       packets << packet
     end
 
+    ##
+    # @return [Boolean]
     def empty?
       packets.empty?
     end
 
+    ##
+    # @return [Integer]
     def size
       inject(0) { |sum, packet| sum + packet.size }
     end
 
+    ##
+    # @return [String]
     def to_s
       Buffer.write do |buffer|
         packets.each do |packet|