Class: HexaPDF::Encryption::SecurityHandler

Inherits:
Object
  • Object
show all
Defined in:
lib/hexapdf/encryption/security_handler.rb

Overview

Base class for all security handlers.

Creating SecurityHandler Instances

The base class provides two class methods for this:

  • The method ::set_up_encryption is used when a security handler instance should be created that populates the document’s encryption dictionary.

  • 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.

Using SecurityHandler Instances

The SecurityHandler base class provides the methods for decrypting an indirect object and for encrypting strings and streams:

  • #decrypt

  • #encrypt_string

  • #encrypt_stream

How the decryption/encryption key is actually computed is deferred to a sub class.

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.

Implementing a SecurityHandler Class

Each security handler has to implement the following methods:

prepare_encryption(**options)

Prepares the security handler for use in encrypting the document.

See the #set_up_encryption documentation for information on which options are passed on to this method.

Returns the encryption key as well as the names of the string, stream and embedded file algorithms.

prepare_decryption(**options)

Prepares the security handler for decryption by using the information from the document’s encryption dictionary as well as the provided arguments.

See the #set_up_decryption documentation for additional information.

Returns the encryption key that should be used for decryption.

Additionally, the following methods can be overridden to provide a more specific meaning:

encryption_dictionary_class

Returns the class that is used for the encryption dictionary. Should be derived from the EncryptionDictionary class.

Direct Known Subclasses

StandardSecurityHandler

Defined Under Namespace

Classes: EncryptedStreamData

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ SecurityHandler

Creates a new SecurityHandler for the given document.



246
247
248
249
250
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 246

def initialize(document)
  @document = document
  @encrypt_dict_hash = nil
  @encryption_details = {}
end

Instance Attribute Details

#encryption_details ⇒ Object (readonly)

A hash containing information about the used encryption. This information is only available once the security handler has been set up for decryption or encryption.

Available keys:

:version

The version of the security handler in use.

:string_algorithm

The algorithm used for encrypting/decrypting strings.

:stream_algorithm

The algorithm used for encrypting/decrypting streams.

:embedded_file_algorithm

The algorithm used for encrypting/decrypting embedded files.

:key_length

The key length in bits.



243
244
245
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 243

def encryption_details
  @encryption_details
end

Class Method Details

.set_up_decryption(document, **options) ⇒ Object

:call-seq:

SecurityHandler.set_up_decryption(document, **options)   -> handler

Sets up and returns the security handler that is used for decrypting the given document and modifies the document’s object loader so that the decryption is handled automatically behind the scenes.

The decryption_opts has to contain decryption options specific to the security handler that is used by the PDF file.

See: #set_up_decryption



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 204

def self.set_up_decryption(document, **options)
  dict = document.trailer[:Encrypt]
  if dict.nil?
    raise HexaPDF::EncryptionError, "No /Encrypt dictionary found"
  end
  handler = document.config.constantize('encryption.filter_map', dict[:Filter]) do
    document.config.constantize('encryption.sub_filter_map', dict[:SubFilter]) do
      raise HexaPDF::EncryptionError, "Could not find a suitable security handler"
    end
  end

  handler = handler.new(document)
  document.trailer[:Encrypt] = handler.set_up_decryption(dict, **options)
  document.revisions.each do |r|
    loader = r.loader
    r.loader = lambda do |xref_entry|
      obj = loader.call(xref_entry)
      xref_entry.compressed? ? obj : handler.decrypt(obj)
    end
  end

  handler.freeze
end

.set_up_encryption(document, handler_name, **options) ⇒ Object

:call-seq:

SecurityHandler.set_up_encryption(document, handler_name, **options)   -> handler

Sets up and returns the security handler with the specified name for the document and modifies then document’s encryption dictionary accordingly.

The encryption_opts can contain any encryption options for the specific security handler and the common encryption options.

See: #set_up_encryption (for the common encryption options).



181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 181

def self.set_up_encryption(document, handler_name, **options)
  handler = document.config.constantize('encryption.filter_map', handler_name) do
    document.config.constantize('encryption.sub_filter_map', handler_name) do
      raise HexaPDF::EncryptionError, "Could not find the specified security handler"
    end
  end

  handler = handler.new(document)
  document.trailer[:Encrypt] = handler.set_up_encryption(**options)
  handler.freeze
end

Instance Method Details

#decrypt(obj) ⇒ Object

Decrypts the strings and the possibly attached stream of the given indirect object in place.

See: PDF1.7 s7.6.2



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 262

def decrypt(obj)
  return obj if obj == document.trailer[:Encrypt] || obj.type == :XRef

  key = object_key(obj.oid, obj.gen, string_algorithm)
  each_string_in_object(obj.value) do |str|
    next if str.empty? || (obj.type == :Sig && obj[:Contents].equal?(str))
    str.replace(string_algorithm.decrypt(key, str))
  end

  if obj.kind_of?(HexaPDF::Stream)
    unless string_algorithm == stream_algorithm
      key = object_key(obj.oid, obj.gen, stream_algorithm)
    end
    obj.data.stream = EncryptedStreamData.new(obj.raw_stream, key, stream_algorithm)
  end

  obj
end

#encrypt_stream(obj) ⇒ Object

Returns a Fiber that encrypts the contents of the given stream object.



293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 293

def encrypt_stream(obj)
  return obj.stream_encoder if obj.type == :XRef

  key = object_key(obj.oid, obj.gen, stream_algorithm)
  source = obj.stream_source
  result = obj.stream_encoder(source)
  if result == source && obj.raw_stream.kind_of?(EncryptedStreamData) &&
      obj.raw_stream.key == key && obj.raw_stream.algorithm == stream_algorithm
    obj.raw_stream.undecrypted_fiber
  else
    stream_algorithm.encryption_fiber(key, result)
  end
end

#encrypt_string(str, obj) ⇒ Object

Returns the encrypted version of the string that resides in the given indirect object.

See: PDF1.7 s7.6.2



284
285
286
287
288
289
290
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 284

def encrypt_string(str, obj)
  return str if str.empty? || obj == document.trailer[:Encrypt] || obj.type == :XRef ||
    (obj.type == :Sig && obj[:Contents].equal?(str))

  key = object_key(obj.oid, obj.gen, string_algorithm)
  string_algorithm.encrypt(key, str)
end

#encryption_key_valid? ⇒ Boolean

Checks if the encryption key computed by this security handler is derived from the document’s encryption dictionary.

Returns:

  • (Boolean) 


254
255
256
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 254

def encryption_key_valid?
  document.unwrap(document.trailer[:Encrypt]).hash == @encrypt_dict_hash
end

#set_up_decryption(dictionary, **options) ⇒ Object

Uses the given encryption dictionary to set up the security handler for decrypting the document.

The security handler specific options are passed on to the #prepare_decryption method.

See: PDF1.7 s7.6.1, PDF2.0 s7.6.1



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 369

def set_up_decryption(dictionary, **options)
  @dict = document.wrap(dictionary, type: encryption_dictionary_class)

  case dict[:V]
  when 1, 2
    strf = stmf = eff = :arc4
  when 4, 5
    strf, stmf, eff = [:StrF, :StmF, :EFF].map do |alg|
      if dict[:CF] && (cf_dict = dict[:CF][dict[alg]])
        case cf_dict[:CFM]
        when :V2 then :arc4
        when :AESV2, :AESV3 then :aes
        when :None then :identity
        else
          raise(HexaPDF::UnsupportedEncryptionError,
                "Unsupported encryption method: #{cf_dict[:CFM]}")
        end
      else
        :identity
      end
    end
    eff = stmf unless dict[:EFF]
  else
    raise HexaPDF::UnsupportedEncryptionError, "Unsupported encryption version #{dict[:V]}"
  end

  set_up_security_handler(prepare_decryption(**options), strf, stmf, eff)
  @encrypt_dict_hash = document.unwrap(@dict).hash

  @dict
end

#set_up_encryption(key_length: 128, algorithm: :aes, force_v4: false, **options) ⇒ Object

Computes the encryption key and 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.

Options for all security handlers:

key_length

The key length in bits. Possible values are in the range of 40 to 128 and 256 and it needs to be divisible by 8.

algorithm

The encryption algorithm. Possible values are :arc4 for ARC4 encryption with key lengths of 40 to 128 bit or :aes for AES encryption with key lengths of 128 or 256 bit.

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



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/hexapdf/encryption/security_handler.rb', line 327

def set_up_encryption(key_length: 128, algorithm: :aes, force_v4: false, **options)
  @dict = document.wrap({}, type: encryption_dictionary_class)

  dict[:V] =
    case key_length
    when 40
      1
    when 48, 56, 64, 72, 80, 88, 96, 104, 112, 120
      2
    when 128
      (algorithm == :aes || force_v4 ? 4 : 2)
    when 256
      5
    else
      raise(HexaPDF::UnsupportedEncryptionError,
            "Invalid key length #{key_length} specified")
    end
  dict[:Length] = key_length if dict[:V] == 2

  if ![:aes, :arc4].include?(algorithm)
    raise(HexaPDF::UnsupportedEncryptionError,
          "Unsupported encryption algorithm: #{algorithm}")
  elsif key_length < 128 && algorithm == :aes
    raise(HexaPDF::UnsupportedEncryptionError,
          "AES algorithm needs a key length of 128 or 256 bit")
  elsif key_length == 256 && algorithm == :arc4
    raise(HexaPDF::UnsupportedEncryptionError,
          "ARC4 algorithm can only be used with key lengths between 40 and 128 bit")
  end

  result = prepare_encryption(algorithm: algorithm, **options)
  @encrypt_dict_hash = document.unwrap(dict).hash
  set_up_security_handler(*result)
  @dict
end