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 21R2 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 IF-statements that checks the step number, or the description, and hardcodes the offset or the X and Y values as needed.
So, those methods are the base of the Docman part of digital signatures.
System Effects¶
When a PDF file has a signature added or when it is certified, the following things happen:
- A new signature or certify section is added to the PDF file, and can be seen inside Adobe Acrobat Reader. If a signature appearance has been added, it will be visible when the PDF file is opened or printed.
- The PDF file in the Docman file repository will be modified directly (no copy of the original file is saved).
- A history line is added to the document revision in Docman.
Explanation¶
With these "pieces" above, it is easy to setup an automated process for digital signatures of PDF files in Document Management. What will "drive" the process forward is the new and enhanced events, on which we will attach event actions. These event actions will contain a few simple code lines to call the new methods in Edm_File_Sign_Util_API, to sign or certify the PDF file.
Optionally, a customer can add a lot of logic in the code of these custom events, to handle any scenario they like. For example, they might not want to have digital signatures added to all documents, probably only to a few document classes. Or they don't want it to be applied on documents connected to certain objects, and so on. With little work, the process can be tailored to the exact needs of the customer, without complex basic data.
No client or business logic changes in Docman right now¶
At this time there is no functionality added to the Docman clients (for example no new right mouse button menu commands, or command buttons) nor the standard business logic in Docman more than what has been described about the events. The events will drive the digital signature process.
Setup¶
This section will describe how to setup an automatic digital signature process for Document Management using the pieces explained earlier.
Overview¶
Basically, the setup process will consist of the following parts:
- Setting up keystores
- Setting up and activating event actions
Setting up keystores¶
This section will explain how to setup keystores for all users that should sign PDF documents.
Setting up and activating event actions¶
Document approval¶
Here we will use the event DOCUMENT_APPROVED, and attach an event action to it. When a document is approved, this event and its event action will be executed.
This is how to register an event action:
- As an administrator, open the window Events.
- Query and find the event called DOCUMENT_APPROVED.
- Right click the DOCUMENT_APPROVED event and select Create new action for Event.
- Click the Action Type list, and select the option Execute Online SQL.
- Enter a description of the event action in the Action Description field.
- In the Action Details section, in the text area SQL Statement, add the following text:
BEGIN
Edm_File_Sign_Util_API.Certify_Pdf_File ('&DOC_CLASS', '&DOC_NO', '&DOC_SHEET', '&DOC_REV', 'Signature from IFS');
END;
The above code will call the certify method in Edm_File_Sign_Util_API which will certify the PDF file connected to the document. Optionally, you can change the text "Signature from IFS" to something else. It will be set as the "reason" in the signature added to the PDF file.
The code above is quite simple and it will be executed for all documents that are approved. Possibly this is not what you want. Something more advanced can easily be added. Here is an example where the PDF file will only be certified for the classes DRAWINGS and SPECS:
BEGIN
IF '&DOC_CLASS' IN ('DRAWINGS', 'SPECS') THEN
Edm_File_Sign_Util_API.Certify_Pdf_File ('&DOC_CLASS', '&DOC_NO', '&DOC_SHEET', '&DOC_REV', 'Signature from IFS');
END IF;
END;
Similarly it would be possible to make sure that the user exist in a certain group, that he/she has a certain role/permission set granted, etc. To setup more advanced configurations like that you need to have some knowledge of the data model of Document Management and other parts of IFS Cloud. Consult IFS support for help with such work.
- Select the check box Action Enabled.
- Save.
Now the event action, as well as the event it is attached to, should be enabled. You can test that things are working in the following way:
- Open the window Document Revision.
- Create a new document and check in a PDF file.
- Approve or release the document.
- View the document.
- Now it should be possible to view signatures in the signature panel.
Approval routing step approval¶
To get a digital signature added to the document when an approval step is approved, use the event STEP_APPROVED and follow the same steps as for DOCUMENT_APPROVED. Use the following code in the SQL Statement text box:
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 (doc_class_, doc_no_, doc_sheet_, doc_rev_, '&STEP_DESCRIPTION');
END;
Due to the nature of how the general approval routing functionality is implemented (approval steps can be added to any type of business object in IFS), this code looks a bit more complicated. But basically we are just extracting the keys of the documents from the general key reference on the approval step, and use those keys to sign the PDF file on the document. Once the document keys are assigned to the four variables, we can implement any kind of checks/logic we want for when PDF signing should be active.
In the example above, only a digital signature was added, with no signature appearance. The same approach can be used to add an appearance, like this:
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/>
In the code above, the image files used for the visual signature as well as the watermark are stored as files connected to document revisions. In order for every user to get their own visual signature, we use the user name (fetched by the function Fnd_Session_API.Get_Fnd_User) as part of the document number.
If different signature appearances will be applied to the same document, the code in the event action need to take this into account. Neither the logic in Docman nor the logic in the framework can take this into account. In some way, the code must "know" how many signature appearances that will be added, such that X and Y can be calculated.
It is a good idea to also add conditions to this event action, such that it only executes for document revisions. To do that, add a condition on the OBJECT_TYPE field, testing for "DocIssue".
Also make sure to enable the event action.
Try the event action out by adding an approval step to a document that have a PDF file, and set the currently logged in user's person ID in Person ID field. Start the approval routing and approve the approval step. A new signature should now have been added to the PDF file.
Optional setup - custom actions¶
Optionally, it is possible to setup one or more custom actions to call some of the method above, and then adding custom commands to call such actions from a page, via a page configuration. This would allow a user to activate a command to directly sign a PDF file.