class HexaPDF::Document::Signatures::DefaultHandler

Parent	Object

This is the default signing handler which provides the ability to sign a document with the adbe.pkcs7.detached or ETSI.CAdES.detached algorithms. It is registered under the :default name.

Usage¶ ↑

The signing handler is used by default by all methods that need a signing handler. Therefore it is usually only necessary to provide the actual attribute values.

This handler provides two ways to create the PKCS#7 signed-data structure required by Signatures#add:

By providing the signing certificate together with the signing key and the certificate chain. This way HexaPDF itself does the signing. It is the preferred way if all the needed information is available.

Assign the respective data to the certificate, key and certificate_chain attributes.
By using an external signing mechanism. Here the actual signing happens “outside” of HexaPDF, for example, in custom code or even asynchronously. This is needed in case the signing certificate plus key are not directly available but only an interface to them (e.g. when dealing with a HSM).

Assign a callable object to external_signing. If the signing process needs to be asynchronous, make sure to set the signature_size appropriately, return an empty string during signing and later use Signatures.embed_signature to embed the actual signature.

Additional functionality:

Optionally setting the reason, location and contact information.
Making the signature a certification signature by applying the DocMDP transform method.

Example:

# Signing using certificate + key
document.sign("output.pdf", certificate: my_cert, key: my_key,
              certificate_chain: my_chain)

# Signing using an external mechanism:
signing_proc = lambda do |io, byte_range|
  io.pos = byte_range[0]
  data = io.read(byte_range[1])
  io.pos = byte_range[2]
  data << io.read(byte_range[3])
  signing_service.pkcs7_sign(data)
end
document.sign("output.pdf", signature_size: 10_000, external_signing: signing_proc)

Implementing a Signing Handler¶ ↑

This class also serves as an example on how to create a custom handler: The public methods signature_size, finalize_objects and sign are used by the digital signature algorithm. See their descriptions for details.

Once a custom signing handler has been created, it can be registered under the 'signature.signing_handler' configuration option for easy use. It has to take keyword arguments in its initialize method to be compatible with the Signatures#handler method.

Attributes

certificate[RW]¶

The certificate with which to sign the PDF.

certificate_chain[RW]¶

The certificate chain that should be embedded in the PDF; normally contains all certificates up to the root certificate.

contact_info[RW]¶

The contact information. If used, will be set on the signature object.

doc_mdp_permissions[R]¶

The DocMDP permissions that should be set on the document.

See doc_mdp_permissions=

external_signing[RW]¶

A callable object fulfilling the same role as the sign method that is used instead of the default mechanism for signing.

If this attribute is set, the attributes certificate, key and certificate_chain are not used.

key[RW]¶

The private key for the certificate.

location[RW]¶

The signing location. If used, will be set on the signature object.

reason[RW]¶

The reason for signing. If used, will be set on the signature object.

signature_size[W]¶

The size of the serialized signature that should be reserved.

If this attribute has not been set, an empty string will be signed using sign to determine the signature size.

The size needs to be at least as big as the final signature, otherwise signing results in an error.

signature_type[RW]¶

The type of signature to be written (i.e. the value of the /SubFilter key).

The value can either be :adobe (the default; uses a detached PKCS7 signature) or :etsi (uses an ETSI CAdES compatible signature).

Public Class Methods

new(**arguments)¶

Creates a new DefaultHandler with the given attributes.

Public Instance Methods

doc_mdp_permissions=(permissions)¶

Sets the DocMDP permissions that should be applied to the document.

Valid values for permissions are:

nil: Don't set any DocMDP permissions (default).
:no_changes or 1: No changes whatsoever are allowed.
:form_filling or 2: Only filling in forms and signing are allowed.
:form_filling_and_annotations or 3: Only filling in forms, signing and annotation creation/deletion/modification are allowed.

finalize_objects(_signature_field, signature)¶

Finalizes the signature field as well as the signature dictionary before writing.

sign(io, byte_range)¶

Returns the DER serialized OpenSSL::PKCS7 structure containing the signature for the given IO byte ranges.

The byte_range argument is an array containing four numbers [offset1, length1, offset2, length2]. The offset numbers are byte positions in the io argument and the to-be-signed data can be determined by reading length bytes at the offsets.

signature_size¶