openpgp 0.0.2 → 0.0.3

data/lib/openpgp/client/gnupg.rb

@@ -24,6 +24,8 @@ module OpenPGP module Client
 
     ##
     # Prints the program version and licensing information.
+    #
+    # @return [void]
     def version
       puts "gpg.rb (GnuPG compatible) #{VERSION}"
       puts
@@ -36,17 +38,24 @@ module OpenPGP module Client
     end
 
     ##
-    # Prints a usage message summarizing the most useful command-line options.
+    # Prints a usage message summarizing the most useful command-line
+    # options.
+    #
+    # @return [void]
     def help() end
 
     ##
     # Prints warranty information.
+    #
+    # @return [void]
     def warranty
       raise NotImplementedError
     end
 
     ##
     # Prints a list of all available options and commands.
+    #
+    # @return [void]
     def dump_options
       self.class.public_instance_methods(false).each do |command|
         if command =~ /^[\w\d_]+$/
@@ -60,30 +69,41 @@ module OpenPGP module Client
 
     ##
     # Makes a signature.
+    #
+    # @return [void]
     def sign
       raise NotImplementedError # TODO
     end
 
     ##
     # Makes a clear text signature.
+    #
+    # @return [void]
     def clearsign
       raise NotImplementedError # TODO
     end
 
     ##
     # Makes a detached signature.
+    #
+    # @return [void]
     def detach_sign
       raise NotImplementedError # TODO
     end
 
     ##
     # Encrypts data.
+    #
+    # @return [void]
     def encrypt
       raise NotImplementedError # TODO
     end
 
     ##
     # Encrypts with a symmetric cipher using a passphrase.
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def symmetric(file)
       print OpenPGP.encrypt(File.read(file), {
         :symmetric  => true,
@@ -96,6 +116,9 @@ module OpenPGP module Client
 
     ##
     # Stores only (make a simple RFC1991 literal data packet).
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def store(file)
       Message.write(stdout) do |msg|
         msg << Packet::LiteralData.new({
@@ -109,32 +132,47 @@ module OpenPGP module Client
 
     ##
     # Decrypts data.
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def decrypt(file)
       raise NotImplementedError # TODO
     end
 
     ##
     # Verifies data.
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def verify(file)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Identical to --multifile --verify.
+    # Identical to `--multifile --verify`.
+    #
+    # @param  [Array<String>] files
+    # @return [void]
     def verify_files(*files)
       options[:multifile] = true
       files.each { |file| verify(file) }
     end
 
     ##
-    # Identical to --multifile --encrypt.
+    # Identical to `--multifile --encrypt`.
+    #
+    # @param  [Array<String>] files
+    # @return [void]
     def encrypt_files(*files)
       options[:multifile] = true
       files.each { |file| encrypt(file) }
     end
 
     ##
-    # Identical to --multifile --decrypt.
+    # Identical to `--multifile --decrypt`.
+    #
+    # @param  [Array<String>] files
+    # @return [void]
     def decrypt_files(*files)
       options[:multifile] = true
       files.each { |file| decrypt(file) }
@@ -142,12 +180,18 @@ module OpenPGP module Client
 
     ##
     # Lists keys from the public keyrings.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def list_keys(*keys)
       list_public_keys(*keys)
     end
 
     ##
     # Lists keys from the public keyrings.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def list_public_keys(*keys)
       public_keyrings.each do |keyring_filename, keyring|
         puts (keyring_filename = File.expand_path(keyring_filename))
@@ -168,6 +212,9 @@ module OpenPGP module Client
 
     ##
     # Lists keys from the secret keyrings.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def list_secret_keys(*keys)
       secret_keyrings.each do |keyring_filename, keyring|
         puts (keyring_filename = File.expand_path(keyring_filename))
@@ -187,19 +234,26 @@ module OpenPGP module Client
     end
 
     ##
-    # Same as +list_keys+, but the signatures are listed too.
+    # Same as {#list_keys}, but the signatures are listed too.
+    #
+    # @return [void]
     def list_sigs
       raise NotImplementedError # TODO
     end
 
     ##
-    # Same as +list_sigs+, but the signatures are verified.
+    # Same as {#list_sigs}, but the signatures are verified.
+    #
+    # @return [void]
     def check_sigs
       raise NotImplementedError # TODO
     end
 
     ##
     # Lists all keys (or the specified ones) along with their fingerprints.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def fingerprint(*keys)
       options[:fingerprint] = true
       list_keys(*keys)
@@ -207,102 +261,149 @@ module OpenPGP module Client
 
     ##
     # Lists only the sequence of packets.
+    #
+    # @return [void]
     def list_packets
       raise NotImplementedError # TODO
     end
 
     ##
     # Presents a menu to work with a smartcard.
+    #
+    # @return [void]
     def card_edit
       raise NotImplementedError # TODO
     end
 
     ##
     # Shows the content of the smart card.
+    #
+    # @return [void]
     def card_status
       raise NotImplementedError # TODO
     end
 
     ##
     # Presents a menu to allow changing the PIN of a smartcard.
+    #
+    # @return [void]
     def change_pin
       raise NotImplementedError # TODO
     end
 
     ##
     # Removes key from the public keyring.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def delete_key(name)
       raise NotImplementedError # TODO
     end
 
     ##
     # Removes key from the secret and public keyring.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def delete_secret_key(name)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Removes key from the secret and public keyring. If a secret key exists, it will be removed first.
+    # Removes key from the secret and public keyring. If a secret key
+    # exists, it will be removed first.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def delete_secret_and_public_key(name)
       raise NotImplementedError # TODO
     end
 
     ##
     # Exports keys from the public keyring.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def export(*keys)
       raise NotImplementedError # TODO
     end
 
     ##
     # Sends keys to a keyserver.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def send_keys(*keys)
       raise NotImplementedError # TODO
     end
 
     ##
     # Exports the secret keys.
+    #
+    # @return [void]
     def export_secret_keys
       raise NotImplementedError # TODO
     end
 
     ##
     # Exports the secret subkeys.
+    #
+    # @return [void]
     def export_secret_subkeys
       raise NotImplementedError # TODO
     end
 
     ##
-    # Imports/merges keys, adding the given keys to the keyring.
+    # Imports/merges keys, adding the given `keys` to the keyring.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def import(*keys)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Alias for +import+.
+    # Alias for {#import}.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def fast_import(*keys)
       import(*keys)
     end
 
     ##
-    # Imports the keys with the given key IDs from a keyserver.
+    # Imports the `keys` with the given key IDs from a keyserver.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def recv_keys(*keys)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Requests updates from a keyserver for keys that already exist on the local keyring.
+    # Requests updates from a keyserver for keys that already exist on the
+    # local keyring.
+    #
+    # @param  [Array<String>] keys
+    # @return [void]
     def refresh_keys(*keys)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Searches the keyserver for the given names.
+    # Searches the keyserver for the given `names`.
+    #
+    # @param  [Array<String>] names
+    # @return [void]
     def search_keys(*names)
       raise NotImplementedError # TODO
     end
 
     ##
     # Retrieves keys located at the specified URIs.
+    #
+    # @param  [Array<String>] uris
+    # @return [void]
     def fetch_keys(*uris)
       require 'open-uri'
       raise NotImplementedError # TODO
@@ -310,36 +411,53 @@ module OpenPGP module Client
 
     ##
     # Does trust database maintenance.
+    #
+    # @return [void]
     def update_trustdb
       raise NotImplementedError # TODO
     end
 
     ##
     # Does trust database maintenance without user interaction.
+    #
+    # @return [void]
     def check_trustdb
       raise NotImplementedError # TODO
     end
 
     ##
-    # Sends the ownertrust values to stdout.
+    # Sends the ownertrust values to `stdout`.
+    #
+    # @return [void]
     def export_ownertrust
       raise NotImplementedError # TODO
     end
 
     ##
-    # Updates the trustdb with the ownertrust values stored in +files+ or stdin.
+    # Updates the trustdb with the ownertrust values stored in `files` or
+    # `stdin`.
+    #
+    # @param  [Array<String>] files
+    # @return [void]
     def import_ownertrust(*files)
       raise NotImplementedError # TODO
     end
 
     ##
     # Creates signature caches in the keyring.
+    #
+    # @return [void]
     def rebuild_keydb_caches
       raise NotImplementedError # TODO
     end
 
     ##
-    # Prints message digest of algorithm +algo+ for all given files or stdin.
+    # Prints message digest of algorithm `algo` for all given `files` or
+    # `stdin`.
+    #
+    # @param  [String, #to_s] algo
+    # @param  [Array<String>] files
+    # @return [void]
     def print_md(algo, *files)
       unless digest_algorithms.include?(algorithm = algo.to_s.upcase.to_sym)
         abort "gpg: invalid hash algorithm `#{algo}'"
@@ -353,7 +471,11 @@ module OpenPGP module Client
     end
 
     ##
-    # Prints message digests of all available algorithms for all given files or stdin.
+    # Prints message digests of all available algorithms for all given
+    # `files` or `stdin`.
+    #
+    # @param  [Array<String>] files
+    # @return [void]
     def print_mds(*files)
       files.each do |file|
         digest_algorithms.each do |algorithm|
@@ -366,7 +488,11 @@ module OpenPGP module Client
     end
 
     ##
-    # Emits +count+ random bytes of the given quality level.
+    # Emits `count` random bytes of the given quality level.
+    #
+    # @param  [Integer, #to_i] level
+    # @param  [Integer, #to_i] count
+    # @return [void]
     def gen_random(level = 0, count = nil)
       wrong_args "--gen-random 0|1|2 [count]" unless (0..2).include?(level)
 
@@ -384,6 +510,11 @@ module OpenPGP module Client
 
     ##
     # Generates a prime number.
+    #
+    # @param  [Integer, #to_i] mode
+    # @param  [Integer, #to_i] bits
+    # @param  [Integer, #to_i] qbits
+    # @return [void]
     def gen_prime(mode, bits, qbits = nil)
       case mode.to_i
         when 1..4
@@ -395,6 +526,9 @@ module OpenPGP module Client
 
     ##
     # Packs an arbitrary input into an OpenPGP ASCII armor.
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def enarmor(file)
       text = OpenPGP.enarmor(File.read(file), :armored_file, :comment => 'Use "gpg --dearmor" for unpacking', :line_length => 64)
       puts text # FIXME
@@ -402,6 +536,9 @@ module OpenPGP module Client
 
     ##
     # Unpacks an arbitrary input from an OpenPGP ASCII armor.
+    #
+    # @param  [String, #to_s] file
+    # @return [void]
     def dearmor(file)
       data = OpenPGP.dearmor(File.read(file))
       puts data # FIXME
@@ -411,46 +548,75 @@ module OpenPGP module Client
 
     ##
     # Generates a new key pair.
+    #
+    # @return [void]
     def gen_key
       raise NotImplementedError # TODO
     end
 
     ##
     # Generates a revocation certificate for the complete key.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def gen_revoke(name)
       raise NotImplementedError # TODO
     end
 
     ##
     # Generates a designated revocation certificate for a key.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def desig_revoke(name)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Present a menu which enables you to do most of the key management related tasks.
+    # Presents a menu which enables you to do most of the key management
+    # related tasks.
+    #
+    # @param  [String, #to_s] key
+    # @return [void]
     def edit_key(key)
       raise NotImplementedError # TODO
     end
 
     ##
     # Signs a public key with your secret key.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def sign_key(name)
       raise NotImplementedError # TODO
     end
 
     ##
-    # Signs a public key with your secret key but marks it as non-exportable.
+    # Signs a public key with your secret key but marks it as
+    # non-exportable.
+    #
+    # @param  [String, #to_s] name
+    # @return [void]
     def lsign_key(name)
       raise NotImplementedError # TODO
     end
 
     protected
 
+      ##
+      # @return [IO]
       def stdin()  $stdin  end
+
+      ##
+      # @return [IO]
       def stdout() $stdout end
+
+      ##
+      # @return [IO]
       def stderr() $stdout end
 
+      ##
+      # @return [String]
       def read_passphrase
         if options[:passphrase]
           options[:passphrase]
@@ -459,30 +625,47 @@ module OpenPGP module Client
         end
       end
 
+      ##
+      # @return [Hash]
       def public_keyrings
         {public_keyring_file => keyring(public_keyring_file)} # FIXME
       end
 
+      ##
+      # @return [Hash]
       def secret_keyrings
         {secret_keyring_file => keyring(secret_keyring_file)} # FIXME
       end
 
+      ##
+      # @param  [String, #to_s] file
+      # @return [Message]
       def keyring(file)
         OpenPGP::Message.parse(File.read(File.expand_path(file)))
       end
 
+      ##
+      # @return [String]
       def public_keyring_file
         File.join(options[:homedir], 'pubring.gpg')
       end
 
+      ##
+      # @return [String]
       def secret_keyring_file
         File.join(options[:homedir], 'secring.gpg')
       end
 
+      ##
+      # @return [String]
       def trustdb_file
         File.join(options[:homedir], 'trustdb.gpg')
       end
 
+      ##
+      # @param  [Packet]          packet
+      # @param  [Symbol, #to_sym] type
+      # @return [void]
       def print_key_listing(packet, type)
         puts unless (is_sub_key = [:sub, :ssb].include?(type))
         puts "#{type}   #{format_keyspec(packet)} #{Time.at(packet.timestamp).strftime('%Y-%m-%d')}"
@@ -491,14 +674,24 @@ module OpenPGP module Client
         end
       end
 
+      ##
+      # @param  [Packet, #to_s] packet
+      # @return [void]
       def print_uid_listing(packet)
         puts "uid" + (' ' * 18) + packet.to_s
       end
 
+      ##
+      # @param  [Packet] key
+      # @return [String]
       def format_keyspec(key)
         "____?/#{key.key_id}" # TODO
       end
 
+      ##
+      # @param  [String]  input
+      # @param  [Integer] column
+      # @return [String]
       def format_fingerprint(input, column = 0)
         group_size = case input.size
           when 32 then 2 # MD5
@@ -526,10 +719,15 @@ module OpenPGP module Client
         return output
       end
 
+      ##
+      # @param  [String, #to_s] file
+      # @return [void]
       def parse_options_file(file)
         # TODO
       end
 
+      ##
+      # @return [Symbol]
       def cipher_algorithm
         unless options[:cipher_algo]
           Cipher::CAST5 # this is the default cipher
@@ -542,14 +740,20 @@ module OpenPGP module Client
         end
       end
 
+      ##
+      # @return [Symbol]
       def digest_algorithm
         options[:digest_algo]
       end
 
+      ##
+      # @return [Symbol]
       def compress_algorithm
         options[:compress_algo]
       end
 
+      ##
+      # @return [Hash]
       def cipher_algorithms
         {
           :"3DES"   => Cipher::TripleDES,
@@ -562,10 +766,14 @@ module OpenPGP module Client
         }
       end
 
+      ##
+      # @return [Array]
       def digest_algorithms
         [:MD5, :SHA1, :RIPEMD160, :SHA256, :SHA384, :SHA512]
       end
 
+      ##
+      # @return [Hash]
       def compress_algorithms
         {
           :none     => nil,
@@ -575,9 +783,11 @@ module OpenPGP module Client
         }
       end
 
+      ##
+      # @param  [String, #to_s] usage
+      # @return [void]
       def wrong_args(usage)
         abort "usage: gpg.rb [options] #{usage}"
       end
   end
-
 end end