pdfrb 0.1.0

data/lib/pdfrb/encryption/security_handler.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Encryption
+    # Security handler base class. Subclasses implement +decrypt+,
+    # +encrypt+, +set_up_decryption+, +set_up_encryption+. Dispatch
+    # is via `/Filter` on the trailer's `/Encrypt` dict.
+    class SecurityHandler
+      attr_reader :document, :encrypt_dict
+
+      def initialize(document)
+        @document = document
+        @encrypt_dict = nil
+      end
+
+      # Dispatch on the trailer's /Encrypt /Filter.
+      def self.for(document, decryption_opts: {})
+        trailer = document.trailer
+        return nil unless trailer
+
+        ref = trailer[:Encrypt]
+        return nil unless ref
+
+        encrypt = ref.is_a?(Pdfrb::Model::Reference) ?
+                    document.object(ref) : ref
+        return nil unless encrypt
+
+        filter = encrypt[:Filter] || :Standard
+        klass = HANDLERS[filter.to_s] ||
+                raise(Pdfrb::EncryptionError, "unsupported /Filter #{filter.inspect}")
+        handler = klass.new(document)
+        handler.set_up_decryption(**decryption_opts)
+        handler
+      end
+
+      # Subclasses override.
+      def set_up_decryption(**_opts)
+        raise NotImplementedError
+      end
+
+      def decrypt(_bytes, _oid, _gen)
+        raise NotImplementedError
+      end
+
+      def encrypt(_bytes, _oid, _gen)
+        raise NotImplementedError
+      end
+
+      def encrypted?
+        !@encrypt_dict.nil?
+      end
+
+      HANDLERS = {}.freeze
+      private_constant :HANDLERS
+
+      class << self
+        def registry; @registry ||= {}; end
+
+        def register(filter_name, klass)
+          registry[filter_name.to_s] = klass
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/encryption/standard_security_handler.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Pdfrb
+  module Encryption
+    # Standard security handler (s7.6.3). V1..V6 / R2..R6.
+    # Owns per-document key derivation + per-object (de)cryption.
+    #
+    # Supports:
+    #   V1, V2 + R2     : RC4 40-bit and 128-bit (PDF 1.4-1.5).
+    #   V4   + R4       : RC4 or AES-128 with crypt filters (PDF 1.5+).
+    #   V5   + R5       : AES-256 (PDF 1.7 Ext. 3).
+    #   V6   + R6       : AES-256 (PDF 2.0).
+    #
+    # AES uses the openssl stdlib. RC4 is pure Ruby (TODO 119).
+    class StandardSecurityHandler < SecurityHandler
+      register "Standard", self
+
+      attr_reader :file_key, :version, :revision
+
+      def set_up_decryption(password: "")
+        @encrypt_dict = read_encrypt_dict
+        return unless @encrypt_dict
+
+        @version = @encrypt_dict[:V].to_i
+        @revision = @encrypt_dict[:R].to_i
+        id0 = document.trailer[:ID].to_a.first.b
+        unless verify_password(password)
+          raise Pdfrb::EncryptionError, "incorrect password"
+        end
+        derive_file_key(password, id0)
+      end
+
+      # Verify the user (or owner) password. Returns true on match.
+      def verify_password(password)
+        PasswordVerification.verify_user_password(
+          password: password,
+          encrypt_dict: @encrypt_dict,
+          id0: document.trailer[:ID].to_a.first.b
+        )
+      end
+
+      def decrypt(bytes, oid, gen)
+        return bytes if @file_key.nil?
+
+        case cipher_type
+        when :rc4 then RC4.new(object_key(oid, gen, 16)).process(bytes)
+        when :aes then AES.new(key_size: aes_key_bits, mode: :CBC).decrypt(bytes, object_key(oid, gen, aes_key_bits / 8 + 5).byteslice(0, aes_key_bits / 8))
+        else bytes
+        end
+      end
+
+      def encrypt(bytes, oid, gen)
+        return bytes if @file_key.nil?
+
+        case cipher_type
+        when :rc4 then RC4.new(object_key(oid, gen, 16)).process(bytes)
+        when :aes then AES.new(key_size: aes_key_bits, mode: :CBC).encrypt(bytes, object_key(oid, gen, aes_key_bits / 8 + 5).byteslice(0, aes_key_bits / 8), random_iv)
+        else bytes
+        end
+      end
+
+      private
+
+      def read_encrypt_dict
+        ref = document.trailer[:Encrypt]
+        return nil unless ref
+
+        encrypt = ref.is_a?(Pdfrb::Model::Reference) ?
+                    document.object(ref) : ref
+        encrypt.is_a?(Pdfrb::Model::Cos::Dictionary) ? encrypt : nil
+      end
+
+      def derive_file_key(password, id0)
+        @file_key = PasswordVerification.derive_key_rc4(
+          password: password,
+          o_entry: @encrypt_dict[:O].to_s.b,
+          p_flags: @encrypt_dict[:P].to_i,
+          id0: id0,
+          revision: @revision,
+          key_length_bits: (@encrypt_dict[:Length] || 40).to_i,
+          encrypt_metadata: @encrypt_dict.fetch(:EncryptMetadata, true)
+        )
+      end
+
+      def cipher_type
+        return :rc4 if @version <= 2
+        return :aes if @version >= 4 && @version <= 5
+
+        # V6 (PDF 2.0) — AES-256 always.
+        :aes
+      end
+
+      def aes_key_bits
+        @version >= 5 ? 256 : 128
+      end
+
+      # Per-object key per Algorithm 1: MD5(file_key + oid(LE) + gen(LE) + (sAlT for AES)).
+      def object_key(oid, gen, output_len)
+        md5 = Digest::MD5.new
+        md5.update(@file_key)
+        md5.update([oid].pack("V"))
+        md5.update([gen].pack("V"))
+        md5.update("sAlT".b) if cipher_type == :aes
+        md5.digest.byteslice(0, output_len)
+      end
+
+      def random_iv
+        OpenSSL::Random.random_bytes(16)
+      rescue StandardError
+        require "securerandom"
+        SecureRandom.random_bytes(16)
+      end
+    end
+  end
+end

data/lib/pdfrb/encryption.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "digest"
+
+module Pdfrb
+  # Encryption layer (s7.6). Security handlers own per-document key
+  # derivation and per-object (de)cryption. The Standard handler
+  # covers V1..V6 / R2..R6 (RC4 40-bit through AES-256).
+  #
+  # The Crypt stream filter routes through the active handler; the
+  # Serializer accepts an +encrypter+ slot set by the handler.
+  module Encryption
+    autoload :SecurityHandler, "pdfrb/encryption/security_handler"
+    autoload :StandardSecurityHandler, "pdfrb/encryption/standard_security_handler"
+    autoload :RC4, "pdfrb/encryption/rc4"
+    autoload :AES, "pdfrb/encryption/aes"
+    autoload :PasswordVerification, "pdfrb/encryption/password_verification"
+  end
+end

data/lib/pdfrb/error.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Base class for every Pdfrb error. Rescue this to catch anything the
+  # gem raises. Subclasses carry typed metadata about the failure.
+  class Error < StandardError; end
+
+  # Lexing or parsing the byte stream failed. Carries +source_position+
+  # (a [line, column] pair or byte offset) when known.
+  class ParseError < Error
+    attr_reader :source_position
+
+    def initialize(message, source_position: nil)
+      @source_position = source_position
+      super(message)
+    end
+  end
+
+  # Lexer hit a byte or construct it could not consume (bad hex digit,
+  # unterminated string literal, invalid number, etc.).
+  class LexError < ParseError; end
+
+  # Tokens did not form a valid PDF structure (unbalanced << >>,
+  # missing endobj, malformed xref, etc.).
+  class SyntaxError < ParseError; end
+
+  # A PDF file violates the spec but Pdfrb recovered (or attempted to).
+  # +recovered?+ tells the caller whether reconstruction succeeded.
+  class MalformedPdfError < ParseError
+    attr_reader :recovered
+
+    def initialize(message, recovered: false, **opts)
+      @recovered = recovered
+      super(message, **opts)
+    end
+
+    def recovered? = @recovered
+  end
+
+  # Model -> bytes serialization failed.
+  class SerializeError < Error; end
+
+  # A stream filter (FlateDecode, LZWDecode, ...) failed to decode or
+  # encode. Carries +filter_name+.
+  class FilterError < Error
+    attr_reader :filter_name
+
+    def initialize(message, filter_name: nil)
+      @filter_name = filter_name
+      super(message)
+    end
+  end
+
+  # Encryption setup, decryption, or encryption failed. Subclassed
+  # further by the Encryption namespace as needed (DecryptionError,
+  # UnsupportedEncryptionError).
+  class EncryptionError < Error; end
+
+  # PDF version requested or detected is not supported by Pdfrb.
+  class UnsupportedVersionError < Error
+    attr_reader :version
+
+    def initialize(message, version: nil)
+      @version = version
+      super(message)
+    end
+  end
+
+  # An indirect reference could not be resolved (dangling pointer,
+  # wrong generation, free list, corrupt xref entry).
+  class ObjectReferenceError < Error
+    attr_reader :oid, :gen
+
+    def initialize(message, oid: nil, gen: nil)
+      @oid = oid
+      @gen = gen
+      super(message)
+    end
+  end
+
+  # An Arlington predicate or field-level validation rule fired.
+  # Carries +field_name+ and +predicate_name+ for diagnostics.
+  class ValidationError < Error
+    attr_reader :field_name, :predicate_name
+
+    def initialize(message, field_name: nil, predicate_name: nil)
+      @field_name = field_name
+      @predicate_name = predicate_name
+      super(message)
+    end
+  end
+end

data/lib/pdfrb/filter/ascii_85_decode.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Filter
+    # ASCII85Decode (s7.4.3). Adobe's base-85 encoding with EOD `~>`.
+    # The `z` shorthand expands to four zero bytes.
+    class ASCII85Decode
+      include Base
+
+      register_as "ASCII85Decode"
+
+      class << self
+        def decoder(bytes, _parms, _document)
+          out = +""
+          group = []
+          bytes.each_byte do |b|
+            ch = b.chr
+            case ch
+            when "z"
+              raise bad_byte(b) unless group.empty?
+
+              out << "\x00\x00\x00\x00".b
+            when "~"
+              # EOD marker. Flush any partial group.
+              break
+            when " "
+            else
+              next unless (33..117).cover?(b)
+
+              group << b
+              if group.length == 5
+                out << decode_group(group)
+                group.clear
+              end
+            end
+          end
+          unless group.empty?
+            n = group.length
+            padded = group + [117] * (5 - n)
+            decoded = decode_group(padded)
+            out << decoded.byteslice(0, n - 1)
+          end
+          out.force_encoding(Encoding::BINARY)
+        end
+
+        def encoder(bytes, _parms, _document)
+          out = +""
+          bytes.bytes.each_slice(4) do |quad|
+            padded = quad + [0] * (4 - quad.length)
+            num = padded[0] << 24 | padded[1] << 16 | padded[2] << 8 | padded[3]
+            chars = +""
+            5.times { chars << (num % 85 + 33).chr; num /= 85 }
+            chars.reverse!
+            n = quad.length + 1
+            out << chars.byteslice(0, n)
+          end
+          out << "~>"
+          out.force_encoding(Encoding::BINARY)
+        end
+
+        private
+
+        def decode_group(group)
+          num = group.reduce(0) { |acc, b| acc * 85 + (b - 33) }
+          [
+            (num >> 24) & 0xFF,
+            (num >> 16) & 0xFF,
+            (num >> 8) & 0xFF,
+            num & 0xFF
+          ].pack("C4").force_encoding(Encoding::BINARY)
+        end
+
+        def bad_byte(b)
+          Pdfrb::FilterError.new("ASCII85Decode bad byte #{b}", filter_name: "ASCII85Decode")
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/filter/ascii_hex_decode.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Filter
+    # ASCIIHexDecode (s7.4.2). Hex string -> bytes. EOD marker `>`.
+    class ASCIIHexDecode
+      include Base
+
+      register_as "ASCIIHexDecode"
+
+      HEX = (0..9).each_with_object({}) { |d, h| h[d.to_s] = d }
+                 .merge(("a".."f").each_with_index.with_object({}) { |(c, i), h| h[c] = 10 + i })
+                 .merge(("A".."F").each_with_index.with_object({}) { |(c, i), h| h[c] = 10 + i }).freeze
+      private_constant :HEX
+
+      class << self
+        def decoder(bytes, _parms, _document)
+          nibbles = +""
+          bytes.each_byte do |b|
+            ch = b.chr
+            break if ch == ">"
+
+            nibbles << ch if HEX.key?(ch)
+          end
+          nibbles << "0" if nibbles.length.odd?
+
+          [nibbles].pack("H*").force_encoding(Encoding::BINARY)
+        end
+
+        def encoder(bytes, _parms, _document)
+          hex = bytes.unpack1("H*")
+          "#{hex}>".force_encoding(Encoding::BINARY)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/filter/base.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Filter
+    # Common interface for stream filters. Subclasses must implement
+    # `decoder(bytes, parms, document)` and `encoder(bytes, parms,
+    # document)` class methods, and call `register_as` at the bottom
+    # of the file.
+    module Base
+      class << self
+        def included(host)
+          host.extend(ClassMethods)
+        end
+      end
+
+      module ClassMethods
+        # Register this class under +name+ in Pdfrb::Filter.registry.
+        def register_as(name)
+          Pdfrb::Filter.register(name, self)
+        end
+
+        def decoder(_bytes, _parms, _document)
+          raise NotImplementedError, "#{name}.decoder not implemented"
+        end
+
+        def encoder(_bytes, _parms, _document)
+          raise NotImplementedError, "#{name}.encoder not implemented"
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/filter/crypt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Filter
+    # Crypt filter (s7.4.16). Routes through the document's security
+    # handler when the document is encrypted; pass-through when not.
+    # The `/Identity` name means "no decryption".
+    class Crypt
+      include Base
+
+      register_as "Crypt"
+
+      class << self
+        def decoder(bytes, parms, document)
+          return bytes unless document
+          return bytes if parms == :Identity || parms.nil?
+
+          handler = document.security_handler if document.respond_to?(:security_handler)
+          return bytes unless handler
+
+          handler.decrypt(bytes, document.current_object_oid)
+        end
+
+        def encoder(bytes, parms, document)
+          return bytes unless document
+          return bytes if parms == :Identity || parms.nil?
+
+          handler = document.security_handler if document.respond_to?(:security_handler)
+          return bytes unless handler
+
+          handler.encrypt(bytes, document.current_object_oid)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/filter/flate_decode.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Pdfrb
+  module Filter
+    # FlateDecode (s7.4.8). zlib + optional PNG predictor (s7.4.8.4).
+    class FlateDecode
+      include Base
+
+      register_as "FlateDecode"
+
+      class << self
+        def decoder(bytes, parms, _document)
+          decoded = zlib_inflate(bytes)
+          return decoded unless parms && parms.is_a?(::Hash)
+
+          predictor = parms[:Predictor] || 1
+          return decoded if predictor == 1
+
+          apply_png_predictor_decode(
+            decoded,
+            predictor: predictor,
+            columns: parms[:Columns] || 1,
+            colors: parms[:Colors] || 1,
+            bits_per_component: parms[:BitsPerComponent] || 8
+          )
+        end
+
+        def encoder(bytes, parms, _document)
+          zlib_deflate(bytes)
+        end
+
+        private
+
+        def zlib_inflate(bytes)
+          Zlib::Inflate.inflate(bytes)
+        rescue Zlib::Error => e
+          raise Pdfrb::FilterError.new("FlateDecode inflate failed: #{e.message}",
+                                       filter_name: "FlateDecode")
+        end
+
+        def zlib_deflate(bytes)
+          Zlib::Deflate.deflate(bytes)
+        rescue Zlib::Error => e
+          raise Pdfrb::FilterError.new("FlateDecode deflate failed: #{e.message}",
+                                       filter_name: "FlateDecode")
+        end
+
+        # PNG unfilter (s7.4.8.4 / RFC 2083 6.6).
+        # predictor: 10..15 = PNG predictors; we implement the None/Sub/Up/
+        # Average/Paeth (filter type byte at start of each row).
+        def apply_png_predictor_decode(bytes, predictor:, columns:, colors:, bits_per_component:)
+          return bytes unless (10..15).cover?(predictor)
+
+          row_len = columns * colors * (bits_per_component / 8)
+          row_len += 1 # leading filter-type byte per row
+          rows = bytes.each_byte.each_slice(row_len).to_a
+          prev_row = nil
+          bpp = (colors * (bits_per_component / 8)) || 1
+          bpp = 1 if bpp.zero?
+
+          out = +""
+          rows.each do |row|
+            filter_type = row[0]
+            data = row[1..]
+            unfiltered = unfilter_row(filter_type, data, prev_row, bpp)
+            out << unfiltered.pack("C*")
+            prev_row = unfiltered
+          end
+          out.force_encoding(Encoding::BINARY)
+        end
+
+        def unfilter_row(filter_type, data, prev_row, bpp)
+          case filter_type
+          when 0 then data
+          when 1 then png_sub(data, bpp)
+          when 2 then png_up(data, prev_row)
+          when 3 then png_average(data, prev_row, bpp)
+          when 4 then png_paeth(data, prev_row, bpp)
+          else data
+          end
+        end
+
+        def png_sub(data, bpp)
+          bytes = data.dup
+          bpp.upto(bytes.length - 1).each do |i|
+            bytes[i] = (bytes[i] + bytes[i - bpp]) & 0xFF
+          end
+          bytes
+        end
+
+        def png_up(data, prev_row)
+          return data unless prev_row
+
+          bytes = data.dup
+          (0...bytes.length).each do |i|
+            bytes[i] = (bytes[i] + (prev_row[i] || 0)) & 0xFF
+          end
+          bytes
+        end
+
+        def png_average(data, prev_row, bpp)
+          bytes = data.dup
+          (0...bytes.length).each do |i|
+            left = bytes[i - bpp] || 0
+            up = prev_row ? (prev_row[i] || 0) : 0
+            bytes[i] = (bytes[i] + ((left + up) / 2)) & 0xFF
+          end
+          bytes
+        end
+
+        def png_paeth(data, prev_row, bpp)
+          bytes = data.dup
+          (0...bytes.length).each do |i|
+            left = bytes[i - bpp] || 0
+            up = prev_row ? (prev_row[i] || 0) : 0
+            up_left = prev_row ? (prev_row[i - bpp] || 0) : 0
+            bytes[i] = (bytes[i] + paeth(left, up, up_left)) & 0xFF
+          end
+          bytes
+        end
+
+        def paeth(a, b, c)
+          p = a + b - c
+          pa = (p - a).abs
+          pb = (p - b).abs
+          pc = (p - c).abs
+          return a if pa <= pb && pa <= pc
+          return b if pb <= pc
+
+          c
+        end
+      end
+    end
+  end
+end