Skip to content

Digital Signatures

This document explains how to setup and work with digital signatures for document management.

Background

For a technical background and for understanding what the framework provides, read about Keystores & Digital Signatures. To get an overview of how digital signatures applies to document management, open the end-user documentation and navigate to Topics in IFS Cloud / Create and Maintain Document / Digital Signatures.

This document will focus on how to get digital signatures applied to PDF files connected to a document revision in Document Management. It will be done by creating event actions of type Online SQL against one of a few standard events or a custom event.

Terminology

In this document, we will use the term "digital signature" loosely. On a technical level, a digital signature is complex and includes advanced cryptography, not explained here.

Limitations

  • Currently, only PDF files can be signed using this approach.
  • Due to a limitation in IFS Connect when calling projections, in IFS Cloud 23R2 we still have a limitation where the signatures can only be done as the IFS Connect user. This currently stops us from using personal certificates.

Solution overview

The solution to get digital signatures for document management consists of two main parts:

  • Framework methods for applying a digital certificate to a PDF file
  • Easy-to-use methods in Document Management for signing or certifying a file connected to a document revision.

Framework methods

In the IFS server framework, a mechanism exists for adding digital signatures to PDF files. The framework handles the storage of user-specific or global digital certificates used for signing. The certificates are stored in keystores. Read more about this under Keystores & Digital Signatures.

Sign vs certify

When signing PDF files, you can optionally "certify" the PDF file, using a certain flag in the signature. This is technically the same thing as adding a signature, with the difference that the file can no longer be modified, no additional signatures can be added after the PDF has been certified.

On a high level, this means that first you add one or more user signatures to the PDF file and, as a last optional step, you certify it, to prevent further changes. The certified PDF file is to be seen as the end of the line, so to speak, from a digital signature standpoint.

Multiple signatures supported

Multiple signatures can be added to the PDF file before it is certified. This means that multiple users can sign the content before it is certified. All signatures will be listed in the PDF file, and the associated visual signatures, if available, will be seen.

Keystores

In order to digitally sign a PDF file, two things are needed:

  • A private key of the user
  • A certificate with a trust chain

The private key is what is used to actually sign the PDF content. The certificate is used to make sure we trust the person who signed it.

Both these parts are stored in what we call a keystore. How to handle these is described in Keystores & Digital Signatures.

User-specific or global/public

There are two types of keystores supported in this solution:

  • User-specific
  • Global/public

User-specific keystores is what is used when users sign a PDF file. A user-specific keystore is connected to one user and that keystore will be used when that user wants to sign a PDF file.

There is also support for keystores meant to be used by many users, or the whole company. For example, it could be that a certain report that is supposed to be sent to the government needs to be signed using a special certificate, but it is not user-specific, but used for all users that prints out a certain report. This document will not explain that process and will concentrate on User Certificates and digital signatures.

Methods to do user-specific or global signatures

As part of IFS server framework two new methods have been provided, one for user-specific signatures and one for global/public signatures. These methods are not for end-user or even customer consumption, but will be used by areas like Document Management and IFS Reporting, to sign PDF files (support for other kinds of content can be added in later releases).

Visual representations of a digital signatures, also known as signature appearances (optional)

If the digital signature needs to be printed on paper, it is possible to add a visual representation of it to the signature itself. This is known as a signature appearance and consists of several parts:

  • A visual signature represented by a PNG image, which can either be a scanned version of a hand-written signature or just the a person's name printed as text. This is placed on the left side in the signature appearance. The image file needs to be stored in a document revision in Document Management. The end-user must have at least View access to the document revision.
  • Optional - A watermark, also represented as a PNG image, which is used as the background for the whole signature appearance. These image files are also stored in document revisions.
  • Textual information about the digital signature itself, placed on the right hand side in the signature appearance. The text is generated using some of the content in the digital signature/keystore.

To see some examples on how signature appearances can look like, refer to the framework documentation mentioned at the top of this document.

In the sections below, separate methods are described for "normal" digital signatures, and for signatures with an appearance.

Document Management

Overview

In Document Management, the solution for digital signatures is made up of the following:

  • The event DOCUMENT_APPROVED
  • The event STEP_APPROVED
  • A service for digital signatures
  • Methods in Edm_File_Sign_Util_API for easy signing of PDF files

DOCUMENT_APPROVED event

This event is executed when a document is approved. It includes the four document keys as well as the title of the document that was approved.

STEP_APPROVED event

This event executes when an approval step is approved. This event includes the attributes STEP_NO and STEP_DESCRIPTION. These attributes are useful when we later add a signature to a PDF file.

Web service for digital signatures

A web service/projection/REST API (category = Integration) named DocumentDigitalSignatureService exists to act as the glue between our PL/SQL code and the new digital signature support in the framework. This is meant to be used internally in Docman only but can be used in integrations as well, on your own risk. For details about that API, refer to the API Explorer.

Methods in Edm_File_Sign_Util_API for easy signing of PDF files

A number of public methods exists in the PL/SQL package Edm_File_Sign_Util_API, in Docman. The purpose of these easy-to-use methods is to incorporate digital signatures of PDF files where it fits best in customer flows. Basically there is a method for adding a signature to a PDF file and there is a method to certify a PDF files. There is one simple and once "advanced" version of these methods, described below.

Note: A general requirement is that the end-user that does an operation which results in a signature being added to the PDF file must have at least Edit access to the document.

The first method is used to sign the main PDF file connected to a certain document revision, and the only input needed are the values of the four keys of the document revision that have a PDF file that should be signed. There are a few different scenarios here, and the code will figure out which file to sign. The caller can, optionally, send in a reason / description for why the file is signed, and this will be included in the digital signature in the PDF file.

        PROCEDURE Sign_PDF_File (  
           doc_class_ IN VARCHAR2,  
           doc_no_    IN VARCHAR2,  
           doc_sheet_ IN VARCHAR2,  
           doc_rev_   IN VARCHAR2,  
           reason_    IN VARCHAR2 DEFAULT NULL)  

In case the "simple" method above is not exact enough (does not pick the correct PDF file, if there are many connected to the document), I provided an overloaded version that let the caller specify the exact file / file reference by sending in the document type and file number:

        PROCEDURE Sign_PDF_File (  
           doc_class_ IN VARCHAR2,  
           doc_no_    IN VARCHAR2,  
           doc_sheet_ IN VARCHAR2,  
           doc_rev_   IN VARCHAR2,  
           doc_type_  IN VARCHAR2,  
           file_no_   IN NUMBER,  
           reason_    IN VARCHAR2 DEFAULT NULL)  

Most scenarios should be covered by the first method.

Similarly, there are two methods that can be used to certify the PDF file:

        PROCEDURE Certify_PDF_File (  
           doc_class_ IN VARCHAR2,  
           doc_no_    IN VARCHAR2,  
           doc_sheet_ IN VARCHAR2,  
           doc_rev_   IN VARCHAR2,  
           reason_    IN VARCHAR2 DEFAULT NULL)  

This does more or less the same thing as when we sign a file, with the difference that no more signatures can be added - a status which is called "Certified" in PDF terms. So, while this locks/certifies the PDF file, it is also a signature in itself.

As above, we also provide an overloaded version of this, that let the caller specify the PDF file reference exactly. It has the same interface as the overloaded sign method above:

        PROCEDURE Certify_PDF_File (  
           doc_class_ IN VARCHAR2,  
           doc_no_    IN VARCHAR2,  
           doc_sheet_ IN VARCHAR2,  
           doc_rev_   IN VARCHAR2,  
           doc_type_  IN VARCHAR2,  
           file_no_   IN NUMBER,  
           reason_    IN VARCHAR2 DEFAULT NULL)  

How to add a visual representation, or signature appearance, for the digital signature

Update for IFS Cloud: due to containerization, we no longer support storing the images used for visual signatures on disk. Instead, those images must be kept in document revisions in IFS Document Management. The methods that supported using filenames on disk have been removed in this release.

There are two methods for adding a visual representation of the digital signature. These are described below:

        PROCEDURE Sign_PDF_File_Vis_By_Doc (  
           doc_class_           IN VARCHAR2,  
           doc_no_              IN VARCHAR2,  
           doc_sheet_           IN VARCHAR2,  
           doc_rev_             IN VARCHAR2,  
           reason_              IN VARCHAR2 DEFAULT NULL,  
           --  
           visual_doc_class_    IN VARCHAR2 DEFAULT NULL,  
           visual_doc_no_       IN VARCHAR2 DEFAULT NULL,  
           visual_doc_sheet_    IN VARCHAR2 DEFAULT NULL,  
           visual_doc_rev_      IN VARCHAR2 DEFAULT NULL,  
           --  
           watermark_doc_class_ IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_no_    IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_sheet_ IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_rev_   IN VARCHAR2 DEFAULT NULL,  
           --  
           no_details_          IN BOOLEAN DEFAULT FALSE,  
           --  
           page_                IN NUMBER  DEFAULT 1,  
           x_cm_                IN NUMBER  DEFAULT 0,  
           y_cm_                IN NUMBER  DEFAULT 0,  
           size_pct_            IN NUMBER  DEFAULT 100)  

The above method is used to sign a PDF and at the same time add a visual representation ("signature appearance".) This requires extra parameters to work:

  • doc_class_, doc_no_, doc_sheet_, doc_rev_, reason_ - The document keys of the document to be signed, and the reason, as in the simpler methods described above.
  • visual_doc_class_, visual_doc_no_, visual_doc_sheet_ and visual_doc_rev_ - The keys for a document revision where we store a PNG image file that will be to be used as the visual signature for the person who has signed the document, placed on the left side of the signature appearance. Typically this will a scanned version of a person's hand-written signature. A fallback mechanism kicks in if a filename is not provided, generating a textual representation of the name of the user who signs the document. If the revision happens to have more than one PNG file, the first one is used. If a watermark is used (see below), the PNG need to have a transparent background (it should not be white or black).
  • watermark_doc_class_, watermark_doc_no_, watermark_doc_sheet_ and watermark_doc_rev_ - This is a document revision that keeps a PNG file that will be used as a background for the signature appearance. By using this, it makes it harder to forge a visual signature on paper. If the revision happens to store more than one PNG file, the first one is used.
  • no_details_ - By setting it to TRUE (default is FALSE), the textual details about the digital signature (the right-hand side of it) will not be added to the signature appearance.
  • page_ - The page number (starting at 1) where the signature appearance should be placed. If you do not specify this parameter, it defaults to 1, which is the first page.
  • x_cm_ - The X (horizontal) position of the visual signature, in centimeters. Position 0,0 is in the upper left corner. Example value: 20. If you do not specify this parameter, it defaults to 0, which is the leftmost edge of the PDF
  • y_cm_ - The Y (vertical) position of the visual signature, in centimeters. Example value: 25. If you do not specify this parameter, it defaults to 0, which is the top edge of the PDF.
  • size_pct_ - The size of the signature appearance, in percentage of the maximum size (full width) of the PDF. A good value is 30, which makes the signature fill a third of the width. If you do not specify this parameter, it defaults to 100.

A method with the same parameters also exist for certifying the PDF:

        PROCEDURE Certify_PDF_File_Vis_By_Doc (  
           doc_class_           IN VARCHAR2,  
           doc_no_              IN VARCHAR2,  
           doc_sheet_           IN VARCHAR2,  
           doc_rev_             IN VARCHAR2,  
           reason_              IN VARCHAR2 DEFAULT NULL,  
           --  
           visual_doc_class_    IN VARCHAR2 DEFAULT NULL,  
           visual_doc_no_       IN VARCHAR2 DEFAULT NULL,  
           visual_doc_sheet_    IN VARCHAR2 DEFAULT NULL,  
           visual_doc_rev_      IN VARCHAR2 DEFAULT NULL,  
           --  
           watermark_doc_class_ IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_no_    IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_sheet_ IN VARCHAR2 DEFAULT NULL,  
           watermark_doc_rev_   IN VARCHAR2 DEFAULT NULL,  
           --  
           no_details_          IN BOOLEAN DEFAULT FALSE,  
           --  
           page_                IN NUMBER  DEFAULT 1,  
           x_cm_                IN NUMBER  DEFAULT 0,  
           y_cm_                IN NUMBER  DEFAULT 0,  
           size_pct_            IN NUMBER  DEFAULT 100)  

Visual and watermark images are optional

It is possible to leave out both the visual signature image and the watermark image. Leaving out the visual signature image will make the system generate a textual representation of the name of the logged in user. Leaving out the watermark means there will be no watermark/background as part of the full signature appearance.

Where to store the visual signature and watermark images

When keeping the images in Docman, the question is how to find the image to be used for any given user. There are several ways to do this:

  • Set the user name as the document number, or make it part of the document number. This is the simplest option to setup, and also to write code for.
  • Connect, under Attachments / Documents, the images to the Person, Employee or to some other business object that has a relation to the user. This is a flexible solution since you can easily change the documents by detaching and attaching new ones, but requires a bit more code, since we need to fetch the document keys for the document connected to the Person/Employee/other object.

Here is an example where we use the visual signature stored in a document with the document number DS_<USERNAME>, where <USERNAME> will be the name of the IFS User. The watermark image is also stored on a document revision with the document number WATERMARK:

        DECLARE  
           doc_class_ VARCHAR2 (100)  := Client_SYS.Get_Key_Reference_Value('&KEY_REF', 'DOC_CLASS');  
           doc_no_    VARCHAR2 (100)  := Client_SYS.Get_Key_Reference_Value('&KEY_REF', 'DOC_NO');  
           doc_sheet_ VARCHAR2 (100)  := Client_SYS.Get_Key_Reference_Value('&KEY_REF', 'DOC_SHEET');  
           doc_rev_   VARCHAR2 (100)  := Client_SYS.Get_Key_Reference_Value('&KEY_REF', 'DOC_REV');  
        BEGIN  
           Edm_File_Sign_Util_API.Sign_Pdf_File_Vis_By_Doc (doc_class_, doc_no_, doc_sheet_, doc_rev_, '&STEP_DESCRIPTION',  
                                                            visual_doc_class_ => 'DIGSIGN', visual_doc_no_ => 'DS_' || Fnd_Session_API.Get_Fnd_User, visual_doc_sheet_ => '1', visual_doc_rev_ => 'A1',<br/>                                                            watermark_doc_class_ => 'DIGSIGN', watermark_doc_no_ => 'WATERMARK', watermark_doc_sheet_ => '1', watermark_doc_rev_ => 'A1',<br/>                                                            x_cm_ => 15, y_cm_ => 20, size_pct_ => 30);<br/>        END;<br/>

How to handle multiple signature appearances

Since each signature is applied separately, the framework signing mechanism cannot determine where to place the signature appearances, and also cannot calculate where to place consecutive signatures (so they are not drawn on top of eachother). This will be the responsibility of the person who writes the event action code to handle, in a way that fits the approval and signature process at a company.

One idea could be to use the approval step number to calculate the offset of each signature. In the example below (where some things has been left out for readability), we assume the approval has step numbers from 10 and upwards, in increments of 10:

        DECLARE  
           -- Other variable declarations goes here...  
           offset_ NUMBER;  
        BEGIN  
           offset_ := ((TO_NUMBER ('&STEP_NO') - 10) / 10) * 3; -- For each step above the first one, add a 3 cm offset  
           Edm_File_Sign_Util_API.Sign_Pdf_Vis_By_Doc (... -- Keys and file name parameters goes here, as in earlier examples...  
                                                        x_cm_ => 15, y_cm_ => 15 + offset_, size_pct_ => 30);  
          
        END;  

Above, the first step (step 10) that is approved will have a 0 offset, so the signature will be placed 15 cm down on the Y axis. The next step (20) will be placed 15 + 3 cm, and so on.

Another approach is to have some I