Individual Module

Introduction

Sometimes it is needed to delegate the signature process to e.g. an external webservice. This is possible by implementing your own signature module.

You can extend an existing module or implement your own module class by implementing the SetaPDF_Signer_Signature_Module_ModuleInterface interface.

Additional interfaces are available which allow modifications of the signature dictionary or the document instance: SetaPDF_Signer_Signature_DictionaryInterface and SetaPDF_Signer_Signature_DocumentInterface.

Example

PHP
<?php
class MySignatureModule implements 
    SetaPDF_Signer_Signature_Module_ModuleInterface,
    SetaPDF_Signer_Signature_DictionaryInterface,
    SetaPDF_Signer_Signature_DocumentInterface
{
    /**
     * Create a signature for the file in the given $tmpPath.
     *
     * @param SetaPDF_Core_Reader_FilePath $tmpPath
     * @return string
     */
    public function createSignature(SetaPDF_Core_Reader_FilePath $tmpPath)
    {
        // get hash
        $hashAlgorithm = 'sha256';
        $hashValue = hash_file($hashAlgorithm, $tmpPath);

        // e.g. call an external webservice to create the signature
        $signature = callWebserviceToCreateSignature($hashValue, $hashAlgorithm);

        // return the signature value
        return $signature;
    }

    /**
     * Method to update the signature dictionary.
     *
     * @param SetaPDF_Core_Type_Dictionary $dictionary
     */
    public function updateSignatureDictionary(SetaPDF_Core_Type_Dictionary $dictionary)
    {
        // update the signature dictionary if needed
    }

    /**
     * Method to allow updates onto the document instance.
     *
     * @param SetaPDF_Core_Document $document
     */
    public function updateDocument(SetaPDF_Core_Document $document)
    {
        // make changes or check to the document instance
    }
}

Build Properties Dictionary

If you want embed information about the software or module that was involved in the signing process, you can save these information in the Build Properties Dictionary, which you can create at runtime by implementing the SetaPDF_Signer_Signature_DictionaryInterface. For details about the content of this Build Properties Dictionary please see here.

To display the application name and version in e.g. Adobe Acrobat such as this:

You can implement this in your own module like this:

PHP
class MyPadesModul extends SetaPDF_Signer_Signature_Module_Pades
{
    public function updateSignatureDictionary(SetaPDF_Core_Type_Dictionary $dictionary)
    {
        parent::updateSignatureDictionary($dictionary);

        $dictionary['Prop_Build'] = new SetaPDF_Core_Type_Dictionary([
            'App' => new SetaPDF_Core_Type_Dictionary([
                'REx' => new SetaPDF_Core_Type_String('1.2.3'),
                'Name' => new SetaPDF_Core_Type_Name('My awesome signature service')
            ])
        ]);
    }
}