openpgp 0.0.2 → 0.0.3

data/AUTHORS

@@ -1,2 +1 @@
-* Arto Bendiken <arto.bendiken@gmail.com> (Lead developer)
-* Kévin Lacointe <kevinlacointe@gmail.com> (Some GnuPG patches)
+* Arto Bendiken <arto.bendiken@gmail.com>

data/CONTRIBUTORS

@@ -0,0 +1 @@
+* Kévin Lacointe <kevinlacointe@gmail.com> (Some GnuPG patches)

data/README

@@ -3,7 +3,6 @@ OpenPGP.rb: OpenPGP for Ruby
 
 This is a pure-Ruby implementation of the OpenPGP Message Format (RFC 4880).
 
-* <http://openpgp.rubyforge.org/>
 * <http://github.com/bendiken/openpgp>
 
 ### About OpenPGP
@@ -28,12 +27,13 @@ Features
 Examples
 --------
 
+    require 'rubygems'
     require 'openpgp'
 
 ### Decoding an ASCII-armored message
 
     require 'open-uri'
-    text = open('http://ar.to/pgp.txt').read
+    text = open('http://openpgp.rubyforge.org/pgp.txt').read
 
     msg = OpenPGP::Message.parse(OpenPGP.dearmor(text))
 
@@ -56,6 +56,21 @@ Documentation
 
 * <http://openpgp.rubyforge.org/>
 
+Dependencies
+------------
+
+* [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
+* [Open4](http://rubygems.org/gems/open4) (>= 1.0.1)
+
+Installation
+------------
+
+The recommended installation method is via [RubyGems](http://rubygems.org/).
+To install the latest official release of OpenPGP.rb, do:
+
+    % [sudo] gem install openpgp             # Ruby 1.8.7+ or 1.9.x
+    % [sudo] gem install backports openpgp   # Ruby 1.8.1+
+
 Download
 --------
 
@@ -68,21 +83,13 @@ as follows:
 
     % wget http://github.com/bendiken/openpgp/tarball/master
 
-Installation
-------------
-
-The recommended installation method is via RubyGems. To install the latest
-official release from Gemcutter, do:
-
-    % [sudo] gem install openpgp
-
 Resources
 ---------
 
 * <http://openpgp.rubyforge.org/>
 * <http://github.com/bendiken/openpgp>
-* <http://gemcutter.org/gems/crm114>
-* <http://rubyforge.org/projects/openpgp>
+* <http://rubygems.org/gems/openpgp>
+* <http://rubyforge.org/projects/openpgp/>
 * <http://raa.ruby-lang.org/project/openpgp/>
 * <http://www.ohloh.net/p/openpgp>
 
@@ -90,10 +97,35 @@ Authors
 -------
 
 * [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
-* [Kévin Lacointe](mailto:kevinlacointe@gmail.com)
+
+Contributors
+------------
+
+* [Kévin Lacointe](mailto:kevinlacointe@gmail.com) - <http://github.com/klacointe>
+
+Contributing
+------------
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+* Do document every method you add using [YARD][] annotations. Read the
+  [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `.gemspec` or `VERSION` files. If you need to change them,
+  do so on your private branch only.
+* Do feel free to add yourself to the `CONTRIBUTORS` file and the
+  corresponding list in the the `README`. Alphabetical order applies.
+* Don't touch the `AUTHORS` file. If your contributions are significant
+  enough, be assured we will eventually add you in there.
+* Do note that in order for us to merge any non-trivial changes (as a rule
+  of thumb, additions larger than about 15 lines of code), we need an
+  explicit [public domain dedication][PDD] on record from you.
 
 License
 -------
 
 OpenPGP.rb is free and unencumbered public domain software. For more
 information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[YARD]:      http://yardoc.org/
+[YARD-GS]:   http://yardoc.org/docs/yard/file:docs/GettingStarted.md
+[PDD]:       http://unlicense.org/#unlicensing-contributions

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/openpgp.rb

@@ -1,17 +1,31 @@
-require 'openpgp/version'
-require 'openpgp/util'
+if RUBY_VERSION < '1.8.7'
+  # @see http://rubygems.org/gems/backports
+  begin
+    require 'backports/1.8.7'
+  rescue LoadError
+    begin
+      require 'rubygems'
+      require 'backports/1.8.7'
+    rescue LoadError
+      abort "OpenPGP.rb requires Ruby 1.8.7 or the Backports gem (hint: `gem install backports')."
+    end
+  end
+end
 
 module OpenPGP
+  require 'openpgp/util'
+
   autoload :Algorithm, 'openpgp/algorithm'
   autoload :Armor,     'openpgp/armor'
   autoload :Buffer,    'openpgp/buffer'
   autoload :Cipher,    'openpgp/cipher'
-  autoload :Engine,    'openpgp/engine'
   autoload :Digest,    'openpgp/digest'
+  autoload :Engine,    'openpgp/engine'
   autoload :Message,   'openpgp/message'
   autoload :Packet,    'openpgp/packet'
   autoload :Random,    'openpgp/random'
   autoload :S2K,       'openpgp/s2k'
+  autoload :VERSION,   'openpgp/version'
 end
 
 OpenPGP::Engine::OpenSSL.install!

data/lib/openpgp/algorithm.rb

@@ -1,4 +1,5 @@
 module OpenPGP
+  ##
   module Algorithm
     ##
     # OpenPGP public-key algorithms.

data/lib/openpgp/armor.rb

@@ -14,27 +14,42 @@ module OpenPGP
       ARMORED_FILE      = 'ARMORED FILE' # a GnuPG extension
     end
 
+    ##
+    # @param  [String, #to_s] marker
+    # @return [String]
     def self.marker(marker)
       marker = Markers.const_get(marker.to_s.upcase.to_sym) if marker.is_a?(Symbol)
       marker.to_s.upcase
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-6.2
+    # @param  [String, #to_s] marker
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-6.2
     def self.header(marker)
       "-----BEGIN PGP #{marker(marker)}-----"
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-6.2
+    # @param  [String, #to_s] marker
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-6.2
     def self.footer(marker)
       "-----END PGP #{marker(marker)}-----"
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-6
-    # @see http://tools.ietf.org/html/rfc4880#section-6.2
-    # @see http://tools.ietf.org/html/rfc2045
+    # @param  [String]                 data
+    # @param  [String, #to_s]          marker
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :version (nil)
+    # @option options [String, #to_s]  :comment (nil)
+    # @option options [Hash]           :headers (nil)
+    # @option options [Integer]        :line_length (nil)
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-6
+    # @see    http://tools.ietf.org/html/rfc4880#section-6.2
+    # @see    http://tools.ietf.org/html/rfc2045
     def self.encode(data, marker = :message, options = {})
       Buffer.write do |text|
         text << self.header(marker)     << "\n"
@@ -50,8 +65,13 @@ module OpenPGP
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-6
-    # @see http://tools.ietf.org/html/rfc2045
+    # @param  [String]                 text
+    # @param  [String, #to_s]          marker
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Boolean]        :crc (false)
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-6
+    # @see    http://tools.ietf.org/html/rfc2045
     def self.decode(text, marker = nil, options = {})
       data, crc, state = Buffer.new, nil, :begin
 
@@ -87,13 +107,18 @@ module OpenPGP
       data
     end
 
+    ##
     class CRCError < IOError; end
 
     protected
 
       ##
-      # Returns the Base64-encoded version of +input+, with a configurable
+      # Returns the Base64-encoded version of `input`, with a configurable
       # output line length.
+      #
+      # @param  [String]  input
+      # @param  [Integer] line_length
+      # @return [String]
       def self.encode64(input, line_length = nil)
         if line_length.nil?
           [input].pack('m')
@@ -110,7 +135,10 @@ module OpenPGP
       end
 
       ##
-      # Returns the Base64-decoded version of +input+.
+      # Returns the Base64-decoded version of `input`.
+      #
+      # @param  [String] input
+      # @return [String]
       def self.decode64(input)
         input.unpack('m').first
       end

data/lib/openpgp/buffer.rb

@@ -3,22 +3,30 @@ require 'stringio'
 module OpenPGP
   ##
   class Buffer < StringIO
+    ##
+    # @return [String]
     def self.write(*args, &block)
       buffer = self.new(*args, &block)
       buffer.string
     end
 
+    ##
+    # @yield  [buffer]
+    # @yieldparam [Buffer] buffer
     def initialize(*args, &block)
       super
       block.call(self) if block_given?
     end
 
     ##
+    # @return [String]
     def read_string
       read_bytes(length = read_byte)
     end
 
     ##
+    # @param  [String, #to_s] value
+    # @return [Buffer]
     def write_string(value)
       value = value.to_s
       self << [value.size].pack('C')
@@ -26,19 +34,25 @@ module OpenPGP
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.5
+    # @return [Integer]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.5
     def read_timestamp
       read_unpacked(4, 'N')
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.5
+    # @param  [Integer, #to_i] value
+    # @return [Buffer]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.5
     def write_timestamp(value)
       self << [value.to_i].pack('N')
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.1
+    # @param  [Integer] count
+    # @param  [Integer] base
+    # @return [Integer]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.1
     def read_number(count, base = nil)
       number, shift = 0, count * 8
       read_bytes(count).each_byte do |octet|
@@ -48,13 +62,16 @@ module OpenPGP
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.1
+    # @param  [Integer] value
+    # @return [Buffer]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.1
     def write_number
       # TODO
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.2
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.2
     def read_mpi
       length = read_unpacked(2, 'n')      # length in bits
       length = ((length + 7) / 8.0).floor # length in bytes
@@ -62,39 +79,71 @@ module OpenPGP
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.2
+    # @param  [String] value
+    # @return [Buffer]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.2
     def write_mpi
       # TODO
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-3.7
+    # @return [S2K]
+    # @see    http://tools.ietf.org/html/rfc4880#section-3.7
     def read_s2k()     S2K.parse(self) end
 
+    ##
+    # @param  [S2K] s2k
+    # @return [Buffer]
     def write_s2k(s2k) s2k.write(self) end
 
+    ##
+    # @param  [Integer] count
+    # @param  [String]  format
+    # @return [Integer]
     def read_unpacked(count, format)
       read_bytes(count).unpack(format).first
     end
 
+    ##
+    # @param  [Integer] value
+    # @return [Buffer]
     def write_unpacked
       # TODO
     end
 
+    ##
+    # @param  [Integer] count
+    # @return [String]
     def read_bytes(count)
       read(count)
     end
 
+    ##
+    # @param  [String] value
+    # @return [Buffer]
     def write_bytes(value)
       self << value
     end
 
+    ##
+    # @return [String]
     def read_byte
-      getc
+      getbyte
     end
 
+    ##
+    # @param  [#chr, #to_s] value
+    # @return [Buffer]
     def write_byte(value)
       self << (value.respond_to?(:chr) ? value : value.to_s[0]).chr
     end
+
+    ##
+    # @return [String]
+    def string
+      string = super
+      string.force_encoding(Encoding::ASCII_8BIT) if string.respond_to?(:force_encoding)
+      string
+    end
   end
 end

data/lib/openpgp/cipher.rb

@@ -16,7 +16,9 @@ module OpenPGP
     DEFAULT = AES128
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-9.2
+    # @param  [Symbol, String, Integer] identifier
+    # @return [Class]
+    # @see    http://tools.ietf.org/html/rfc4880#section-9.2
     def self.for(identifier)
       case identifier
         when Symbol then const_get(identifier.to_s.upcase)
@@ -32,9 +34,18 @@ module OpenPGP
       end
     end
 
-    attr_accessor :key, :options
+    # @return [S2K]
+    attr_accessor :key
+
+    # @return [Hash]
+    attr_accessor :options
+
+    # @return [String]
     attr_accessor :engine
 
+    ##
+    # @param  [S2K]                    key
+    # @param  [Hash{Symbol => Object}] options
     def initialize(key, options = {})
       @key = case key
         when S2K then key.to_key(key_size)
@@ -43,24 +54,36 @@ module OpenPGP
       @options = options
     end
 
+    ##
+    # @return [Integer]
     def self.to_i() identifier end
 
+    ##
+    # @return [Integer]
     def self.identifier
       const_get(:IDENTIFIER)
     end
 
+    ##
+    # @return [Integer]
     def identifier()
       self.class.identifier
     end
 
+    ##
+    # @return [Integer]
     def key_size
       @key_size ||= engine.key_len
     end
 
+    ##
+    # @return [Integer]
     def block_size
       @block_size ||= engine.block_size
     end
 
+    ##
+    # @return [String]
     def engine
       @engine ||= Engine::OpenSSL.use do
         OpenSSL::Cipher.new(self.class.const_get(:ENGINE))
@@ -68,7 +91,9 @@ module OpenPGP
     end
 
     ##
-    # @see http://tools.ietf.org/html/rfc4880#section-13.9
+    # @param  [String] plaintext
+    # @return [String]
+    # @see    http://tools.ietf.org/html/rfc4880#section-13.9
     def encrypt(plaintext)
       ciphertext = String.new
 
@@ -101,12 +126,18 @@ module OpenPGP
       ciphertext
     end
 
+    ##
+    # @param  [String] ciphertext
+    # @return [String]
     def decrypt(ciphertext)
       # TODO
       engine.reset
       engine.decrypt
     end
 
+    ##
+    # @param  [String] block
+    # @return [String]
     def encrypt_block(block)
       engine.encrypt
       engine.key = @key