HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Encryption  »  SecurityHandler

Classes and Modules

class HexaPDF::Encryption::SecurityHandler

Parent Object

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.

It is not recommended to create security handlers manually but only with those two methods listed above.

Using SecurityHandler Instances ↑

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

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 ↑

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.

Attributes

encryption_details[R]

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.

Public Class Methods

new(document)

Creates a new SecurityHandler for the given document.

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

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

Public Instance Methods

decrypt(obj)

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

See: PDF2.0 s7.6.3

encrypt_stream(obj)

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.

encrypt_string(str, obj)

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

Note that some strings won’t be encrypted as per the specification. The returned string, however, is always a different object.

See: PDF2.0 s7.6.3

encryption_key_valid?()

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

set_up_decryption(dictionary, **options)

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: PDF2.0 s7.6.2

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

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.

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: PDF2.0 s7.6.2