openpgp 0.0.2 → 0.0.3

data/lib/openpgp/packet.rb

@@ -9,12 +9,17 @@ module OpenPGP
 
     ##
     # Returns the implementation class for a packet tag.
+    #
+    # @param  [Integer, #to_i] tag
+    # @return [Class]
     def self.for(tag)
       @@tags[tag.to_i] || self
     end
 
     ##
     # Returns the packet tag for this class.
+    #
+    # @return [Integer]
     def self.tag
       @@tags.index(self)
     end
@@ -22,13 +27,15 @@ module OpenPGP
     ##
     # Parses an OpenPGP packet.
     #
-    # @see http://tools.ietf.org/html/rfc4880#section-4.2
+    # @param  [Buffer, #to_str] data
+    # @return [Packet]
+    # @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)
 
       unless data.eof?
-        new = ((tag = data.getc) & 64).nonzero? # bit 6 indicates new packet format if set
-        data.ungetc(tag)
+        new = ((tag = data.getbyte) & 64).nonzero? # bit 6 indicates new packet format if set
+        data.ungetbyte(tag) rescue data.ungetc(tag.ord) # FIXME in backports/1.8.7
         send(new ? :parse_new_format : :parse_old_format, data)
       end
     end
@@ -36,20 +43,22 @@ module OpenPGP
     ##
     # Parses a new-format (RFC 4880) OpenPGP packet.
     #
-    # @see http://tools.ietf.org/html/rfc4880#section-4.2.2
+    # @param  [Buffer, #to_str] data
+    # @return [Packet]
+    # @see    http://tools.ietf.org/html/rfc4880#section-4.2.2
     def self.parse_new_format(data)
-      tag = data.getc & 63
-      len = data.getc
+      tag = data.getbyte & 63
+      len = data.getbyte
 
       case len
         when 0..191   # 4.2.2.1. One-Octet Lengths
           data_length = len
         when 192..223 # 4.2.2.2. Two-Octet Lengths
-          data_length = ((len - 192) << 8) + data.getc + 192
+          data_length = ((len - 192) << 8) + data.getbyte + 192
         when 224..254 # 4.2.2.4. Partial Body Lengths
           data_length = 1 << (len & 0x1f)
         when 255      # 4.2.2.3. Five-Octet Lengths
-          data_length = (data.getc << 24) | (data.getc << 16) | (data.getc << 8) | data.getc
+          data_length = (data.getbyte << 24) | (data.getbyte << 16) | (data.getbyte << 8) | data.getbyte
       end
 
       Packet.for(tag).parse_body(Buffer.new(data.read(data_length)), :tag => tag)
@@ -58,14 +67,16 @@ module OpenPGP
     ##
     # Parses an old-format (PGP 2.6.x) OpenPGP packet.
     #
-    # @see http://tools.ietf.org/html/rfc4880#section-4.2.1
+    # @param  [Buffer, #to_str] data
+    # @return [Packet]
+    # @see    http://tools.ietf.org/html/rfc4880#section-4.2.1
     def self.parse_old_format(data)
-      len = (tag = data.getc) & 3
+      len = (tag = data.getbyte) & 3
       tag = (tag >> 2) & 15
 
       case len
         when 0 # The packet has a one-octet length. The header is 2 octets long.
-          data_length = data.getc
+          data_length = data.getbyte
         when 1 # The packet has a two-octet length. The header is 3 octets long.
           data_length = data.read(2).unpack('n').first
         when 2 # The packet has a four-octet length. The header is 5 octets long.
@@ -80,10 +91,15 @@ module OpenPGP
     end
 
     ##
+    # @param  [Buffer]                 body
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Packet]
     def self.parse_body(body, options = {})
       self.new(options)
     end
 
+    ##
+    # @param  [Hash{Symbol => Object}] options
     def initialize(options = {}, &block)
       options.each { |k, v| send("#{k}=", v) }
       block.call(self) if block_given?
@@ -91,8 +107,12 @@ module OpenPGP
 
     #def to_s() body end
 
+    ##
+    # @return [Integer]
     def size() body.size end
 
+    ##
+    # @return [String]
     def body
       respond_to?(:write_body) ? Buffer.write { |buffer| write_body(buffer) } : ""
     end

data/lib/openpgp/random.rb

@@ -2,6 +2,10 @@ module OpenPGP
   module Random
     ##
     # Generates a random number.
+    #
+    # @param  [Integer]                bits
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Integer]
     def self.number(bits = 32, options = {})
       octets = bytes((bits / 8.0).ceil).unpack('C*')
       number = octets.inject { |number, octet| number = (number << 8) | octet }
@@ -11,18 +15,26 @@ module OpenPGP
     ##
     # Generates a pseudo-random prime number of the specified bit length.
     #
-    # @see http://openssl.org/docs/crypto/BN_generate_prime.html
-    # @see http://openssl.org/docs/apps/genrsa.html
+    # @param  [Integer]                bits
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Integer]
+    # @see    http://openssl.org/docs/crypto/BN_generate_prime.html
+    # @see    http://openssl.org/docs/apps/genrsa.html
     def self.prime(bits, options = {})
       raise NotImplementedError # TODO
     end
 
     ##
     # Generates a random byte.
+    #
+    # @return [String]
     def self.byte() bytes(1) end
 
     ##
     # Generates a string of random bytes.
+    #
+    # @param  [Integer] count
+    # @return [String]
     def self.bytes(count, &block)
       octets = File.open('/dev/urandom', 'r') {|f| f.read(count) } # FIXME
       block_given? ? octets.each_byte(&block) : octets

data/lib/openpgp/s2k.rb

@@ -4,9 +4,15 @@ module OpenPGP
   #
   # @see http://tools.ietf.org/html/rfc4880#section-3.7
   class S2K
+    # @return [String]
     attr_accessor :passphrase
+
+    # @return [Integer]
     attr_accessor :algorithm
 
+    ##
+    # @param  [Buffer] input
+    # @return [S2K]
     def self.parse(input)
       case mode = input.read_byte
         when 0        then S2K::Simple.parse(input)       # Simple S2K
@@ -17,10 +23,15 @@ module OpenPGP
       end
     end
 
+    ##
+    # @return [Integer]
     def self.identifier
       const_get(:IDENTIFIER)
     end
 
+    ##
+    # @param  [String, #to_s]          passphrase
+    # @param  [Hash{Symbol => Object}] options
     def initialize(passphrase = nil, options = {}, &block)
       @passphrase = passphrase.to_s
       options.each { |k, v| instance_variable_set("@#{k}", v) }
@@ -28,23 +39,34 @@ module OpenPGP
       block.call(self) if block_given?
     end
 
+    ##
+    # @param  [Buffer] buffer
+    # @return [void]
     def write(buffer)
       buffer.write_byte(identifier)
       buffer.write_byte(digest.to_i)
     end
 
+    ##
+    # @return [Integer]
     def identifier
       @identifier || self.class.identifier
     end
 
+    ##
+    # @return [Hash]
     def to_hash
       {:mode => identifier, :algorithm => digest.to_i}
     end
 
+    ##
+    # @return [String]
     def to_s
       Buffer.write { |buffer| write(buffer) }
     end
 
+    ##
+    # @return [Object]
     def to_key(key_size = 16)
       key = if digest.size >= key_size
         digest.digest(digest_input)
@@ -58,6 +80,8 @@ module OpenPGP
       key[0, key_size]
     end
 
+    ##
+    # @return [Class]
     def digest
       @digest ||= case algorithm
         when nil    then Digest::DEFAULT
@@ -68,10 +92,17 @@ module OpenPGP
       end
     end
 
+    ##
+    # @param  [Integer] length
+    # @return [String]
     def digest_input_with_preload(length = 0)
       ("\0" * length) << digest_input
     end
 
+    ##
+    # @return [String]
+    # @raise  [NotImplementedError] unless implemented in subclass
+    # @abstract
     def digest_input
       raise NotImplementedError
     end
@@ -81,10 +112,15 @@ module OpenPGP
     class Simple < S2K
       IDENTIFIER = 0x00
 
+      ##
+      # @param  [Buffer] input
+      # @return [S2K]
       def self.parse(input)
         self.new(nil, :algorithm => input.read_byte)
       end
 
+      ##
+      # @return [String]
       def digest_input
         passphrase
       end
@@ -95,27 +131,40 @@ module OpenPGP
     class Salted < S2K
       IDENTIFIER = 0x01
 
+      ##
+      # @param  [Buffer] input
+      # @return [S2K]
       def self.parse(input)
         self.new(nil, :algorithm => input.read_byte, :salt => input.read_bytes(8))
       end
 
+      # @return [String]
       attr_accessor :salt
 
+      ##
+      # @param  [String, #to_s]          passphrase
+      # @param  [Hash{Symbol => Object}] options
       def initialize(passphrase = nil, options = {}, &block)
         super(passphrase, options, &block)
-
         @salt = Random.bytes(8) unless @salt
       end
 
+      ##
+      # @param  [Buffer] buffer
+      # @return [void]
       def write(buffer)
         super(buffer)
         buffer.write_bytes(salt)
       end
 
+      ##
+      # @return [Hash]
       def to_hash
         super.merge({:salt => salt})
       end
 
+      ##
+      # @return [String]
       def digest_input
         salt.to_s[0, 8] << passphrase
       end
@@ -126,29 +175,42 @@ module OpenPGP
     class Iterated < Salted
       IDENTIFIER = 0x03
 
+      ##
+      # @param  [Buffer] input
+      # @return [S2K]
       def self.parse(input)
         self.new(nil, :algorithm => input.read_byte, :salt => input.read_bytes(8)) do |s2k|
           s2k.count = s2k.decode_count(input.read_byte)
         end
       end
 
+      # @return [Integer]
       attr_reader :count
 
+      ##
+      # @param  [String, #to_s]          passphrase
+      # @param  [Hash{Symbol => Object}] options
       def initialize(passphrase = nil, options = {}, &block)
         super(passphrase, options, &block)
-
         @count = 65536 unless @count
       end
 
+      ##
+      # @param  [Buffer] buffer
+      # @return [void]
       def write(buffer)
         super(buffer)
         buffer.write_byte(encode_count(count))
       end
 
+      ##
+      # @return [Hash]
       def to_hash
         super.merge(:count => count)
       end
 
+      ##
+      # @return [String]
       def digest_input
         buffer = Buffer.write do |buffer|
           iterations = count
@@ -163,10 +225,16 @@ module OpenPGP
 
         EXPBIAS = 6
 
+        ##
+        # @param  [Integer] count
+        # @return [Integer]
         def decode_count(count)
           (16 + (count & 15)) << ((count >> 4) + EXPBIAS)
         end
 
+        ##
+        # @param  [Integer] iterations
+        # @return [Integer]
         def encode_count(iterations)
           case iterations
             when 0..1024           then 0

data/lib/openpgp/util.rb

@@ -1,36 +1,36 @@
 module OpenPGP
   ##
-  # Alias for OpenPGP::Armor.encode().
+  # Alias for {OpenPGP::Armor.encode}.
   def self.enarmor(data, marker = :message, options = {})
     Armor.encode(data, marker, options)
   end
 
   ##
-  # Alias for OpenPGP::Armor.decode().
+  # Alias for {OpenPGP::Armor.decode}.
   def self.dearmor(text, marker = nil, options = {})
     Armor.decode(text, marker, options)
   end
 
   ##
-  # Alias for OpenPGP::Message.encrypt().
+  # Alias for {OpenPGP::Message.encrypt}.
   def self.encrypt(data, options = {})
     (msg = Message.encrypt(data, options)) ? msg.to_s : nil
   end
 
   ##
-  # Alias for OpenPGP::Message.decrypt().
+  # Alias for {OpenPGP::Message.decrypt}.
   def self.decrypt(data, options = {})
     raise NotImplementedError # TODO
   end
 
   ##
-  # Alias for OpenPGP::Message.sign().
+  # Alias for {OpenPGP::Message.sign}.
   def self.sign
     raise NotImplementedError # TODO
   end
 
   ##
-  # Alias for OpenPGP::Message.verify().
+  # Alias for {OpenPGP::Message.verify}.
   def self.verify
     raise NotImplementedError # TODO
   end
@@ -41,8 +41,10 @@ module OpenPGP
   CRC24_POLY = 0x01864cfb
 
   ##
-  # @see http://tools.ietf.org/html/rfc4880#section-6
-  # @see http://tools.ietf.org/html/rfc4880#section-6.1
+  # @param  [String] data
+  # @return [Integer]
+  # @see    http://tools.ietf.org/html/rfc4880#section-6
+  # @see    http://tools.ietf.org/html/rfc4880#section-6.1
   def self.crc24(data)
     crc = CRC24_INIT
     data.each_byte do |octet|
@@ -58,8 +60,10 @@ module OpenPGP
   ##
   # Returns the bit length of a multiprecision integer (MPI).
   #
-  # @see http://tools.ietf.org/html/rfc4880#section-3.2
+  # @param  [String] data
+  # @return [Integer]
+  # @see    http://tools.ietf.org/html/rfc4880#section-3.2
   def self.bitlength(data)
-    data.empty? ? 0 : (data.size - 1) * 8 + (Math.log(data[0]) / Math.log(2)).floor + 1
+    data.empty? ? 0 : (data.size - 1) * 8 + (Math.log(data[0].ord) / Math.log(2)).floor + 1
   end
 end

data/lib/openpgp/version.rb

@@ -2,13 +2,21 @@ module OpenPGP
   module VERSION
     MAJOR = 0
     MINOR = 0
-    TINY  = 2
+    TINY  = 3
     EXTRA = nil
 
-    STRING = [MAJOR, MINOR, TINY].join('.')
-    STRING << "-#{EXTRA}" if EXTRA
+    STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
 
-    def self.to_s()   STRING end
+    ##
+    # @return [String]
+    def self.to_s() STRING end
+
+    ##
+    # @return [String]
     def self.to_str() STRING end
+
+    ##
+    # @return [Array(Integer, Integer, Integer)]
+    def self.to_a() [MAJOR, MINOR, TINY] end
   end
 end