hexapdf 0.32.2 → 0.33.0

data/lib/hexapdf/document.rb

@@ -64,32 +64,43 @@ end
 #
 # Here are some pointers to more in depth information:
 #
-# * For information about the command line application, see the HexaPDF::CLI module.
+# * HexaPDF::CLI has information about the accompanying command line application.
 # * HexaPDF::Document provides information about how to work with a PDF file.
+# * HexaPDF::Composer is the main class for easily creating PDF documents from scratch.
 # * HexaPDF::Content::Canvas provides the canvas API for drawing/writing on a page or form XObject
+# * HexaPDF::Type::AcroForm::Form is the entry point for working with interactive forms.
+# * HexaPDF::Type::Outline has information on working with outlines/bookmarks.
+# * HexaPDF::Encryption provides information on how encryption works.
+# * HexaPDF::DigitalSignature is the entry point for working with digital signaturs.
 module HexaPDF
 
   autoload(:Composer, 'hexapdf/composer')
 
   # == HexaPDF::Document
   #
-  # Represents one PDF document.
+  # Represents a PDF document.
   #
-  # A PDF document consists of (indirect) objects, so the main job of this class is to provide
-  # methods for working with these objects. However, since a PDF document may also be
+  # A PDF document essentially consists of (indirect) objects, so the main job of this class is to
+  # provide methods for working with these objects. However, since a PDF document may also be
   # incrementally updated and can therefore contain one or more revisions, there are also methods
-  # for working with these revisions.
+  # for working with these revisions (see Revisions for details).
   #
-  # Note: This class provides everything to work on PDF documents on a low-level basis. This means
-  # that there are no convenience methods for higher PDF functionality. Those can be found in the
-  # objects linked from here, like #catalog.
+  # Additionally, there are many convenience methods for easily accessing the most important PDF
+  # functionality, like encrypting a document (#encrypt), working with digital signatures
+  # (#signatures), accessing the interactive form data (#acro_form), working with the pages
+  # (#pages), fonts (#fonts) and images (#images).
   #
-  # == Known Messages
+  # Note: This class provides the basis for working with a PDF document. The higher PDF
+  # functionality is *not* implemented here but either in the appropriate PDF type classes or in
+  # special convenience classes. All this functionality can be accessed via the convenience methods
+  # described above.
+  #
+  # == Available Message Hooks
   #
   # The document object provides a basic message dispatch system via #register_listener and
   # #dispatch_message.
   #
-  # Following are the messages that are used by HexaPDF itself:
+  # Following messages are used by HexaPDF itself:
   #
   # :complete_objects::
   #      This message is called before the first step of writing a document. Listeners should
@@ -138,17 +149,22 @@ module HexaPDF
       end
     end
 
-    # The configuration for the document.
+    # The configuration object for the document.
+    #
+    # See Configuration for details.
     attr_reader :config
 
     # The revisions of the document.
+    #
+    # See Revisions.
     attr_reader :revisions
 
     # Creates a new PDF document, either an empty one or one read from the provided +io+.
     #
     # When an IO object is provided and it contains an encrypted PDF file, it is automatically
     # decrypted behind the scenes. The +decryption_opts+ argument has to be set appropriately in
-    # this case.
+    # this case. In case this is not wanted, the configuration option 'document.auto_decrypt' needs
+    # to be used.
     #
     # Options:
     #
@@ -183,8 +199,8 @@ module HexaPDF
     #   doc.object(ref)    -> obj or nil
     #   doc.object(oid)    -> obj or nil
     #
-    # Returns the current version of the indirect object for the given exact reference or for the
-    # given object number.
+    # Returns the current version of the indirect object for the given exact reference (see
+    # Reference) or for the given object number.
     #
     # For references to unknown objects, +nil+ is returned but free objects are represented by a
     # PDF Null object, not by +nil+!
@@ -199,7 +215,7 @@ module HexaPDF
     #   doc.object?(oid)    -> true or false
     #
     # Returns +true+ if the the document contains an indirect object for the given exact reference
-    # or for the given object number.
+    # (see Reference) or for the given object number.
     #
     # Even though this method might return +true+ for some references, #object may return +nil+
     # because this method takes *all* revisions into account. Also see the discussion on #each for
@@ -212,7 +228,7 @@ module HexaPDF
 
     # Dereferences the given object.
     #
-    # Return the object itself if it is not a reference, or the indirect object specified by the
+    # Returns the object itself if it is not a reference, or the indirect object specified by the
     # reference.
     def deref(obj)
       obj.kind_of?(Reference) ? object(obj) : obj
@@ -227,7 +243,7 @@ module HexaPDF
     # HexaPDF::Object. If it is not the latter, #wrap is called with the object and the
     # additional keyword arguments.
     #
-    # See: Revisions#add_object
+    # See: #wrap, Revisions#add_object
     def add(obj, **wrap_opts)
       obj = wrap(obj, **wrap_opts) unless obj.kind_of?(HexaPDF::Object)
 
@@ -266,14 +282,14 @@ module HexaPDF
       HexaPDF::Importer.for(self).import(obj, source: source)
     end
 
-    # Wraps the given object inside a HexaPDF::Object class which allows one to use
+    # Wraps the given object inside a HexaPDF::Object (sub)class which allows one to use
     # convenience functions to work with the object.
     #
     # The +obj+ argument can also be a HexaPDF::Object object so that it can be re-wrapped if
-    # needed.
+    # necessary.
     #
     # The class of the returned object is always a subclass of HexaPDF::Object (or of
-    # HexaPDF::Stream if a +stream+ is given). Which subclass is used, depends on the values of the
+    # HexaPDF::Stream if +stream+ is given). Which subclass is used, depends on the values of the
     # +type+ and +subtype+ options as well as on the 'object.type_map' and 'object.subtype_map'
     # global configuration options:
     #
@@ -291,13 +307,13 @@ module HexaPDF
     #
     # * If there is no valid class after the above steps, HexaPDF::Stream is used if a stream is
     #   given, HexaPDF::Dictionary if the given object is a hash, HexaPDF::PDFArray if it is an
-    #   array or else HexaPDF::Object is used.
+    #   array or else HexaPDF::Object.
     #
     # Options:
     #
     # :type:: (Symbol or Class) The type of a PDF object that should be used for wrapping. This
     #         could be, for example, :Pages. If a class object is provided, it is used directly
-    #         instead of the type detection system.
+    #         instead of determining the class through the type detection system.
     #
     # :subtype:: (Symbol) The subtype of a PDF object which further qualifies a type. For
     #            example, image objects in PDF have a type of :XObject and a subtype of :Image.
@@ -341,7 +357,9 @@ module HexaPDF
       if subtype
         sub_klass = GlobalConfiguration.constantize('object.subtype_map', type, subtype) { klass }
         if type ||
-            sub_klass&.each_field&.none? {|name, field| field.required? && !data.value.key?(name) }
+            sub_klass&.each_field&.none? do |name, field|
+              field.required? && !data.value.key?(name) && name != :Type
+            end
           klass = sub_klass
         end
       end
@@ -410,6 +428,11 @@ module HexaPDF
     #    doc.register_listener(name) {|*args| block}       -> block
     #
     # Registers the given listener for the message +name+.
+    #
+    # If +callable+ is provided, it needs to be an Object responding to #call. Otherwise the block
+    # has to be provided. The arguments that are provided to the #call method depend on the message.
+    #
+    # See: dispatch_message
     def register_listener(name, callable = nil, &block)
       callable ||= block
       (@listeners[name] ||= []) << callable
@@ -420,6 +443,8 @@ module HexaPDF
     #
     # See the main Document documentation for an overview of messages that are used by HexaPDF
     # itself.
+    #
+    # See: register_listener
     def dispatch_message(name, *args)
       @listeners[name]&.each {|obj| obj.call(*args) }
     end
@@ -427,10 +452,10 @@ module HexaPDF
     UNSET = ::Object.new # :nordoc:
 
     # Caches and returns the given +value+ or the value of the given block using the given
-    # +pdf_data+ and +key+ arguments as composite cache key. If a cached value already exists and
-    # +update+ is +false+, the cached value is just returned.
+    # +pdf_data+ and +key+ arguments as composite cache key.
     #
-    # Set +update+ to +true+ to force an update of the cached value.
+    # If a cached value already exists and +update+ is +false+, the cached value is just returned.
+    # If +update+ is set to +true+, an update of the cached value is forced.
     #
     # This facility can be used to cache expensive operations in PDF objects that are easy to
     # compute again.
@@ -444,7 +469,7 @@ module HexaPDF
     # Returns +true+ if there is a value cached for the composite key consisting of the given
     # +pdf_data+ and +key+ objects.
     #
-    # Also see: #cache
+    # See: #cache
     def cached?(pdf_data, key)
       @cache.key?(pdf_data) && @cache[pdf_data].key?(key)
     end
@@ -455,29 +480,32 @@ module HexaPDF
     # It is *not* recommended to clear the whole cache! Better clear the cache for individual PDF
     # objects!
     #
-    # Also see: #cache
+    # See: #cache, #cached?
     def clear_cache(pdf_data = nil)
       pdf_data ? @cache[pdf_data].clear : @cache.clear
     end
 
-    # Returns the Pages object that provides convenience methods for working with pages.
+    # Returns the Pages object that provides convenience methods for working with the pages of the
+    # PDF file.
     #
-    # Also see: HexaPDF::Type::PageTreeNode
+    # See: Pages, Type::PageTreeNode
     def pages
       @pages ||= Pages.new(self)
     end
 
-    # Returns the Images object that provides convenience methods for working with images.
+    # Returns the Images object that provides convenience methods for working with images (e.g.
+    # adding them to the PDF or listing them).
     def images
       @images ||= Images.new(self)
     end
 
-    # Returns the Files object that provides convenience methods for working with files.
+    # Returns the Files object that provides convenience methods for working with embedded files.
     def files
       @files ||= Files.new(self)
     end
 
-    # Returns the Fonts object that provides convenience methods for working with fonts.
+    # Returns the Fonts object that provides convenience methods for working with the fonts used in
+    # the PDF file.
     def fonts
       @fonts ||= Fonts.new(self)
     end
@@ -496,14 +524,16 @@ module HexaPDF
 
     # Returns the main AcroForm object for dealing with interactive forms.
     #
-    # See HexaPDF::Type::Catalog#acro_form for details on the arguments.
+    # The meaning of the +create+ argument is detailed at Type::Catalog#acro_form.
+    #
+    # See: Type::AcroForm::Form
     def acro_form(create: false)
       catalog.acro_form(create: create)
     end
 
-    # Returns the main document outline object.
+    # Returns the entry object to the document outline (a.k.a. bookmarks).
     #
-    # See HexaPDF::Type::Outline for details.
+    # See: Type::Outline
     def outline
       catalog.outline
     end
@@ -513,7 +543,7 @@ module HexaPDF
     # Tasks provide an extensible way for performing operations on a PDF document without
     # cluttering the Document interface.
     #
-    # See Task for more information.
+    # See: Task
     def task(name, **opts, &block)
       task = config.constantize('task.map', name) do
         raise HexaPDF::Error, "No task named '#{name}' is available"
@@ -522,11 +552,15 @@ module HexaPDF
     end
 
     # Returns the trailer dictionary for the document.
+    #
+    # See: Type::Trailer
     def trailer
       @revisions.current.trailer
     end
 
     # Returns the document's catalog, the root of the object tree.
+    #
+    # See: Type::Catalog
     def catalog
       trailer.catalog
     end
@@ -537,14 +571,16 @@ module HexaPDF
     # version has been set manually and the catalog's /Version key refers to a later version, the
     # later version is used.
     #
-    # See: PDF1.7 s7.2.2
+    # See: PDF2.0 s7.2.2
     def version
       catalog_version = (catalog[:Version] || '1.0').to_s
       (@version < catalog_version ? catalog_version : @version)
     end
 
-    # Sets the version of the PDF document. The argument must be a string in the format 'M.N'
-    # where M is the major version and N the minor version (e.g. '1.4' or '2.0').
+    # Sets the version of the PDF document.
+    #
+    # The argument +value+ must be a string in the format 'M.N' where M is the major version and N
+    # the minor version (e.g. '1.4' or '2.0').
     def version=(value)
       raise ArgumentError, "PDF version must follow format M.N" unless value.to_s.match?(/\A\d\.\d\z/)
       @version = value.to_s
@@ -557,9 +593,9 @@ module HexaPDF
 
     # Encrypts the document.
     #
-    # This is done by setting up a security handler for this purpose and populating the trailer's
-    # Encrypt dictionary accordingly. The actual encryption, however, is only done when writing the
-    # document.
+    # Encryption is done by setting up a security handler for this purpose and populating the
+    # trailer's Encrypt dictionary accordingly. The actual encryption, however, is only done when
+    # writing the document.
     #
     # The security handler used for encrypting is selected via the +name+ argument. All other
     # arguments are passed on the security handler.
@@ -567,9 +603,8 @@ module HexaPDF
     # If the document should not be encrypted, the +name+ argument has to be set to +nil+. This
     # removes the security handler and deletes the trailer's Encrypt dictionary.
     #
-    # See: HexaPDF::Encryption::SecurityHandler#set_up_encryption and
-    # HexaPDF::Encryption::StandardSecurityHandler::EncryptionOptions for possible encryption
-    # options.
+    # See: Encryption::SecurityHandler#set_up_encryption and
+    # Encryption::StandardSecurityHandler::EncryptionOptions for possible encryption options.
     def encrypt(name: :Standard, **options)
       if name.nil?
         trailer.delete(:Encrypt)
@@ -605,17 +640,16 @@ module HexaPDF
     # Signs the document and writes it to the given file or IO object.
     #
     # For details on the arguments +file_or_io+, +signature+ and +write_options+ see
-    # HexaPDF::DigitalSignature::Signatures#add.
+    # DigitalSignature::Signatures#add.
     #
     # The signing handler to be used is determined by the +handler+ argument together with the rest
-    # of the keyword arguments (see HexaPDF::DigitalSignature::Signatures#signing_handler for
-    # details).
+    # of the keyword arguments (see DigitalSignature::Signatures#signing_handler for details).
     #
-    # If not changed, the default signing handler is
-    # HexaPDF::DigitalSignature::Signing::DefaultHandler.
+    # If not changed, the default signing handler is DigitalSignature::Signing::DefaultHandler.
     #
-    # *Note*: Once signing is done the document cannot be changed anymore since it was written. If a
-    # document needs to be signed multiple times, it needs to be loaded again after writing.
+    # *Note*: Once signing is done the document cannot be changed anymore since it was written
+    # during the signing process. If a document needs to be signed multiple times, it needs to be
+    # loaded again afterwards.
     def sign(file_or_io, handler: :default, signature: nil, write_options: {}, **handler_options)
       handler = signatures.signing_handler(name: handler, **handler_options)
       signatures.add(file_or_io, handler, signature: signature, write_options: write_options)
@@ -626,7 +660,7 @@ module HexaPDF
     #
     # If a block is given, it is called on validation problems.
     #
-    # See HexaPDF::Object#validate for more information.
+    # See Object#validate for more information.
     def validate(auto_correct: true, only_loaded: false, &block) #:yield: msg, correctable, object
       result = trailer.validate(auto_correct: auto_correct, &block)
       each(only_loaded: only_loaded) do |obj|
@@ -651,7 +685,7 @@ module HexaPDF
     #   This is needed, for example, when modifying a signed PDF and the original signature should
     #   stay valid.
     #
-    #   See: PDF1.7 s7.5.6
+    #   See: PDF2.0 s7.5.6
     #
     # validate::
     #   Validates the document and raises an error if an uncorrectable problem is found.

data/lib/hexapdf/encryption/aes.rb

@@ -43,7 +43,7 @@ module HexaPDF
     # Common interface for AES algorithms
     #
     # This module defines the common interface that is used by the security handlers to encrypt or
-    # decrypt data with AES. It has to be *prepended* by any AES algorithm class.
+    # decrypt data with AES. It has to be *prepended* by any specific AES algorithm class.
     #
     # See the ClassMethods module for available class level methods of AES algorithms.
     #
@@ -79,7 +79,7 @@ module HexaPDF
         # The data is padded using the PKCS#5 padding scheme and the initialization vector is
         # prepended to the encrypted data,
         #
-        # See: PDF1.7 s7.6.2.
+        # See: PDF2.0 s7.6.3
         def encrypt(key, data)
           iv = random_bytes(BLOCK_SIZE)
           iv << new(key, iv, :encrypt).process(pad(data))
@@ -112,7 +112,7 @@ module HexaPDF
         # It is assumed that the initialization vector is included in the first BLOCK_SIZE bytes
         # of the data. After the decryption the PKCS#5 padding is removed.
         #
-        # See: PDF1.7 s7.6.2.
+        # See: PDF2.0 s7.6.3
         def decrypt(key, data)
           return data if data.empty? # Handle invalid files with empty strings
           if data.length % BLOCK_SIZE != 0 || data.length < BLOCK_SIZE
@@ -167,7 +167,7 @@ module HexaPDF
         # Pads the data to a muliple of BLOCK_SIZE using the PKCS#5 padding scheme and returns the
         # result.
         #
-        # See: PDF1.7 s7.6.2
+        # See: PDF2.0 s7.6.3
         def pad(data)
           padding_length = BLOCK_SIZE - data.size % BLOCK_SIZE
           data + padding_length.chr * padding_length
@@ -179,7 +179,7 @@ module HexaPDF
         # In case the padding is not correct as per the specification, it is assumed that there is
         # no padding and the input is returned as is.
         #
-        # See: PDF1.7 s7.6.2
+        # See: PDF2.0 s7.6.3
         def unpad(data)
           padding_length = data.getbyte(-1)
           if padding_length > BLOCK_SIZE || padding_length == 0 ||

data/lib/hexapdf/encryption/arc4.rb

@@ -65,7 +65,7 @@ module HexaPDF
 
         # Encrypts the given +data+ with the +key+.
         #
-        # See: PDF1.7 s7.6.2.
+        # See: PDF2.0 s7.6.3
         def encrypt(key, data)
           new(key).process(data)
         end

data/lib/hexapdf/encryption/fast_aes.rb

@@ -48,7 +48,7 @@ module HexaPDF
     #
     # This implementation is using AES in Cipher Block Chaining (CBC) mode.
     #
-    # See: PDF1.7 s7.6.2
+    # See: PDF2.0 s7.6.3
     class FastAES
 
       prepend AES
@@ -68,7 +68,7 @@ module HexaPDF
         @cipher.send(mode)
         @cipher.key = key
         @cipher.iv = iv
-        @cipher.padding = 0
+        @cipher.padding = 0 # Padding handled by HexaPDF, also no @cipher.final call needed
       end
 
       # Encrypts or decrypts the given data whose length must be a multiple of 16.

data/lib/hexapdf/encryption/fast_arc4.rb

@@ -45,7 +45,7 @@ module HexaPDF
 
       # Implementation of the general encryption algorithm ARC4 using OpenSSL as backend.
       #
-      # See: PDF1.7 s7.6.2
+      # See: PDF2.0 s7.6.3
       class FastARC4
 
         prepend ARC4

data/lib/hexapdf/encryption/identity.rb

@@ -42,7 +42,7 @@ module HexaPDF
     # This "algorithm" does nothing, i.e. it returns the given data as is without encrypting or
     # decrypting it.
     #
-    # See: PDF1.7 s7.6.5
+    # See: PDF2.0 s7.6.6
     module Identity
 
       class << self

data/lib/hexapdf/encryption/ruby_aes.rb

@@ -51,7 +51,7 @@ module HexaPDF
     #
     # This implementation is using AES in Cipher Block Chaining (CBC) mode.
     #
-    # See: PDF1.7 s7.6.2
+    # See: PDF2.0 s7.6.3
     class RubyAES
 
       prepend AES

data/lib/hexapdf/encryption/ruby_arc4.rb

@@ -46,7 +46,7 @@ module HexaPDF
     #
     # For reference: This implementation is about 250 times slower than the FastARC4 version.
     #
-    # See: PDF1.7 s7.6.2
+    # See: PDF2.0 s7.6.3
     class RubyARC4
 
       prepend ARC4

data/lib/hexapdf/encryption/security_handler.rb

@@ -47,12 +47,12 @@ module HexaPDF
     # Contains entries common to all encryption dictionaries. If a specific security handler
     # needs further fields it should derive a new subclass and add the new fields there.
     #
-    # See: PDF1.7 s7.6.1
+    # See: PDF2.0 s7.6.2
     class EncryptionDictionary < Dictionary
 
       define_field :Filter,    type: Symbol, required: true
       define_field :SubFilter, type: Symbol, version: '1.3'
-      define_field :V,         type: Integer, required: true
+      define_field :V,         type: Integer, required: true, allowed_values: [0, 1, 2, 3, 4, 5]
       define_field :Lenth,     type: Integer, default: 40, version: '1.4'
       define_field :CF,        type: Dictionary, version: '1.5'
       define_field :StmF,      type: Symbol, default: :Identity, version: '1.5'
@@ -70,12 +70,8 @@ module HexaPDF
       # Ensures that the encryption dictionary's content is valid.
       def perform_validation
         super
-        unless [1, 2, 4, 5].include?(value[:V])
-          yield("Value of /V is not one of 1, 2, 4 or 5", false)
-          return
-        end
-        if value[:V] == 2 && (!key?(:Length) || value[:Length] < 40 ||
-          value[:Length] > 128 || value[:Length] % 8 != 0)
+        length = self[:Length]
+        if self[:V] == 2 && (!key?(:Length) || length < 40 || length > 128 || length % 8 != 0)
           yield("Invalid value for /Length field when /V is 2", false)
         end
       end
@@ -94,8 +90,8 @@ module HexaPDF
     # * The method ::set_up_decryption is used when a security handler should be created from the
     #   document's encryption dictionary.
     #
-    # Security handlers could also be created with the ::new method but this is discouraged because
-    # the above methods provide the correct handling in both cases.
+    # It is *not* recommended to create security handlers manually but only with those two methods
+    # listed above.
     #
     #
     # == Using SecurityHandler Instances
@@ -107,12 +103,16 @@ module HexaPDF
     # * #encrypt_string
     # * #encrypt_stream
     #
-    # How the decryption/encryption key is actually computed is deferred to a sub class.
+    # How the decryption/encryption key is actually computed is deferred to a sub class, as per the
+    # PDF specification.
     #
     # Additionally, the #encryption_key_valid? method can be used to check whether the
     # SecurityHandler instance is built from/built for the current version of the encryption
     # dictionary.
     #
+    # Note that any manual changes to the encryption dictionary will invalidate the key and lead to
+    # an error!
+    #
     #
     # == Implementing a SecurityHandler Class
     #
@@ -151,8 +151,8 @@ module HexaPDF
         # The encryption algorithm.
         attr_reader :algorithm
 
-        # Creates a new encrypted stream data object by utilizing the given stream data object as
-        # template. The arguments +key+ and +algorithm+ are used for decrypting purposes.
+        # Creates a new encrypted stream data object by utilizing the given stream data object +obj+
+        # as template. The arguments +key+ and +algorithm+ are used for decrypting purposes.
         def initialize(obj, key, algorithm)
           obj.instance_variables.each {|v| instance_variable_set(v, obj.instance_variable_get(v)) }
           @key = key
@@ -214,7 +214,7 @@ module HexaPDF
 
         handler = handler.new(document)
         dict = document.trailer[:Encrypt] = handler.set_up_decryption(dict, **options)
-        HexaPDF::Object.make_direct(dict.value)
+        HexaPDF::Object.make_direct(dict.value, document)
         document.revisions.current.update(dict)
         document.revisions.each do |r|
           loader = r.loader
@@ -264,7 +264,7 @@ module HexaPDF
       # Decrypts the strings and the possibly attached stream of the given indirect object in
       # place.
       #
-      # See: PDF1.7 s7.6.2
+      # See: PDF2.0 s7.6.3
       def decrypt(obj)
         return obj if @is_encrypt_dict[obj] || obj.type == :XRef
 
@@ -292,7 +292,7 @@ module HexaPDF
       # Note that some strings won't be encrypted as per the specification. The returned string,
       # however, is always a different object.
       #
-      # See: PDF1.7 s7.6.2
+      # See: PDF2.0 s7.6.3
       def encrypt_string(str, obj)
         return str.dup if str.empty? || obj == document.trailer[:Encrypt] || obj.type == :XRef ||
           (obj.type == :Sig && obj[:Contents].equal?(str))
@@ -302,6 +302,9 @@ module HexaPDF
       end
 
       # Returns a Fiber that encrypts the contents of the given stream object.
+      #
+      # Note that some streams *must not be* encrypted. For those, their standard stream encoding
+      # fiber is returned.
       def encrypt_stream(obj)
         return obj.stream_encoder if obj.type == :XRef
 
@@ -321,8 +324,8 @@ module HexaPDF
         end
       end
 
-      # Computes the encryption key and sets up the algorithms for encrypting the document based on
-      # the given options, and returns the corresponding encryption dictionary.
+      # Computes the encryption key, sets up the algorithms for encrypting the document based on the
+      # given options, and returns the corresponding encryption dictionary.
       #
       # The security handler specific +options+ as well as the +algorithm+ argument are passed on to
       # the #prepare_encryption method.
@@ -340,7 +343,7 @@ module HexaPDF
       # force_v4::
       #   Forces the use of protocol version 4 when key_length=128 and algorithm=:arc4.
       #
-      # See: PDF1.7 s7.6.1, PDF2.0 s7.6.1
+      # See: PDF2.0 s7.6.2
       def set_up_encryption(key_length: 128, algorithm: :aes, force_v4: false, **options)
         @dict = document.wrap({}, type: encryption_dictionary_class)
 
@@ -382,9 +385,13 @@ module HexaPDF
       #
       # The security handler specific +options+ are passed on to the #prepare_decryption method.
       #
-      # See: PDF1.7 s7.6.1, PDF2.0 s7.6.1
+      # See: PDF2.0 s7.6.2
       def set_up_decryption(dictionary, **options)
         @dict = document.wrap(dictionary, type: encryption_dictionary_class)
+        @dict.validate do |msg, correctable, obj|
+          next if correctable
+          raise HexaPDF::Error, "Validation error for encryption dictionary (#{obj.oid},#{obj.gen}): #{msg}"
+        end
 
         case dict[:V]
         when 1, 2
@@ -495,7 +502,7 @@ module HexaPDF
 
       # Computes the key for decrypting the indirect object with the given algorithm.
       #
-      # See: PDF1.7 s7.6.2 (algorithm 1), PDF2.0 s7.6.2.2 (algorithm 1.A)
+      # See: PDF2.0 s7.6.3.2 (algorithm 1), PDF2.0 s7.6.3.3 (algorithm 1.A)
       def object_key(oid, gen, algorithm)
         key = encryption_key
         return key if dict[:V] == 5
@@ -508,13 +515,13 @@ module HexaPDF
 
       # Returns the length of the encryption key in bytes based on the security handlers version.
       #
-      # See: PDF1.7 s7.6.1, PDF2.0 s7.6.1
+      # See: PDF2.0 s7.6.2
       def key_length
         case dict[:V]
         when 1 then 5
         when 2 then dict[:Length] / 8
-        when 4 then 16 # PDF2.0 s7.6.1 specifies that a /V of 4 is equal to length of 128bit
-        when 5 then 32 # PDF2.0 s7.6.1 specifies that a /V of 5 is equal to length of 256bit
+        when 4 then 16 # PDF2.0 s7.6.2 specifies that a /V of 4 is equal to length of 128bit
+        when 5 then 32 # PDF2.0 s7.6.2 specifies that a /V of 5 is equal to length of 256bit
         end
       end