class HexaPDF::DigitalSignature::Signing::DefaultHandler

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.

Note: Currently only RSA is supported, DSA and ECDSA are not. See the examples below for how to handle them using external signing.

CMS and PAdES Signatures¶ ↑

The handler supports the older standard of CMS signatures as well as the newer PAdES signatures specified in PDF 2.0. By default, CMS signatures are created but this can be changed by setting signature_type to :pades.

When creating PAdES signatures the following two PAdES baseline signatures are supported: B-B and B-T. The difference between those two is that a timestamp handler was defined for B-T compatibility.

Signing Modes - Internal, External, External/Asynchronous¶ ↑

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

• By providing the signing certificate together with the signing key and the certificate chain, HexaPDF itself does the signing internally. 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*, a callable object assigned to external_signing. Here the actual signing happens “outside” of HexaPDF, for example, in custom code or even asynchronously. This is needed in case the signing key is not directly available but only an interface to it (e.g. when dealing with a HSM).

  Depending on whether certificate is set the signing happens differently:

  • If certificate is not set, the callable object is used instead of sign, so it needs to accept the same arguments as sign and needs to return a complete, DER-serialized CMS signed data object.

  • If certificate is set, the CMS signed data object is created by HexaPDF. The callable external_signing object is called with the used digest algorithm and the already digested data which needs to be signed (but not digested) and the signature returned.

  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.

Optional Data¶ ↑

Besides the required data, some optional attributes can also be specified:

• Reason, location and contact information

• Making the signature a certification signature by applying the DocMDP transform method and a DoCMDP permission

Examples¶ ↑

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

# Signing using an external mechanism without certificate set
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).to_der
end
document.sign("output.pdf", signature_size: 10_000, external_signing: signing_proc)

# Signing using external mechanism with certificate set
signing_proc = lambda do |digest_method, hash|
  signing_service.sign_raw(digest_method, hash)
end
document.sign("output.pdf", certificate: my_cert, certificate_chain: my_chain,
              external_signing: signing_proc)

# Signing with DSA or ECDSA certificate/keys
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])
  OpenSSL::PKCS7.sign(certificate, key, data, certificate_chain,
                      OpenSSL::PKCS7::DETACHED | OpenSSL::PKCS7::BINARY).to_der
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.