Skip to content

Electronic Signatures

Emakin can sign files and texts with an electronic signature in two ways:

Signer Where Surface Use it when
The current user, with their own certificate Browser User select script with AltiKare.Signature A person must sign the document as part of a decision, such as an approval.
The organization, with a server certificate Server $Crypto.Sign in a server script such as the postwork script The document must carry an organization signature or seal without user interaction.

Signatures can be verified on the server with $Crypto.VerifyFile and $Crypto.Verify.

For a handwritten signature image instead of an electronic signature, use the Hand Signature widget.

Signing by the User

The user signs in the browser when an action is selected. The action is submitted only after the signature is completed. For a complete example process, see Sign Attachments on Approval.

Prerequisites

  • The user has an electronic signature certificate and the Kolay İmza signing application installed. If the application cannot be started, the signing dialog shows a link to install it.
  • If the user's identity has a national identity number (Person.TCKN for users, TCKN for external users), only a certificate with the same number can be used.
  • Signature levels with a timestamp (T and above) require the time stamping settings to be configured.
  • The files to sign are uploaded through a File or FileList widget, so their data nodes contain file identifiers.

Signing Attached Files

  1. In the form, bind the File or FileList widget to the nodes that hold the documents, for example Files/File.
  2. Select the approving action and open its User Select Script.
  3. Add a script that signs the files and completes the action only when the signature succeeds:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    const files = $Xml.SelectAll('Files/File');
    
    if (files.length === 0) {
        // nothing to sign, continue with the action
        return true;
    }
    
    try {
        const result = await AltiKare.Signature.signFiles(files, 'T', 'Signature\\d');
    
        if (!result) {
            // the user closed the signing dialog
            return false;
        }
    
        $Xml.SetValue('Signer/Name', result.certificateName);
        $Xml.SetValue('Signer/SerialNumber', result.certificateSerialNumber);
    
        return true;
    } catch (err) {
        alert('Signing failed: ' + err.message);
        return false;
    }
    
  4. Verify the signature on the server in the task's postwork script; see Verifying Signatures.

  5. Disable Allow Bulk Selection for the action, because bulk and email selection do not run the user select script.

The signed content replaces the content of each file as a new revision when the action is submitted. The file identifiers in the form data stay the same. If the user closes the signing dialog or the selection is cancelled, the files are not changed.

Keeping a Separate Signature File

When the original file must stay unchanged, create a detached signature and store its identifier in a separate field that is bound to a File widget. Pass 'Cades' as the type; otherwise a PDF is signed with an embedded PAdES signature:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const sourceId = $Xml.Evaluate('Contract');

const result = await AltiKare.Signature.sign([sourceId], false, 'BES', '', 'Cades');

if (!result) {
    return false;
}

$Xml.SetValue('ContractSignature', result.files[0].id);
$Xml.SelectSingle('ContractSignature').SetAttribute('HasFileRevision', 'True');

return true;

Signing a Text

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const text = $Xml.Evaluate('Decision/Summary');

const result = await AltiKare.Signature.signText(text, true, 'BES');

if (!result) {
    return false;
}

$Xml.SetValue('Decision/SignatureFile', result.files[0].id);
$Xml.SelectSingle('Decision/SignatureFile').SetAttribute('HasFileRevision', 'True');

return true;

Browser Signature Functions

Function Use
AltiKare.Signature.signFiles(fileNodes, format, placeholder, type) Signs the files referenced by the given form data nodes. The signature is embedded in each file as a new revision.
AltiKare.Signature.sign(fileIds, false, format, placeholder, 'Cades') Creates a separate (detached) CAdES signature file for each source file. The source files are not changed.
AltiKare.Signature.signText(texts, attachSource, format) Signs one or more plain texts and creates a signature file for each.

All functions are asynchronous; call them with await. The result is null when the user closes the signing dialog, otherwise a result object.

Use signFiles to embed signatures in files that are already in the form. Signature files created by sign and signText are new files: store each identifier in a form field and mark the field with the HasFileRevision attribute, as in the examples above, so that the file is kept when the action is submitted. A new file that is not stored this way is discarded.

Parameters:

  • format: Signature level. One of BES, T, C, X, XX or A. The default is T.
  • placeholder: PDF only. A regular expression that finds the text in the document where the visible signature is placed, for example Signature\\d. Leave empty to sign without a visible placement.
  • type: Optional. Forces the signature type (Cades, Pades) instead of selecting it from the file type.

Signature type by file:

File Signature type Notes
.pdf PAdES Levels above T are applied as T.
.eml S/MIME
Other files and texts CAdES

Result object:

Property Description
certificateName Name of the signer on the certificate.
certificateIssuer Issuer of the signer's certificate.
certificateSerialNumber Serial number of the signer.
files Signed outputs. Each item has id, the identifier of the signed or signature file, and for signFiles and sign also sourceId, the identifier of the source file.

Signing on the Server

Use $Crypto.Sign to sign with a certificate available to the server, for example a PFX file or a PKCS#11 device holding an organization certificate. The signature runs in a server script and does not need the user's certificate or a signing application. See the $Crypto.Sign reference for request options and examples.

Do not write certificate passwords or PINs as plain text in a script. Agree with your system administrator where the certificate and its secret are stored for the environment.

Verifying Signatures

A browser signature is user input. When the process depends on a valid signature, verify it on the server in the postwork script with $Crypto.VerifyFile. At that point the signed revision is already the file's content:

1
2
3
4
5
6
7
8
9
if ($WorkItem.SelectedAction == 'Approve') {
    $Xml.SelectAll('Files/File', function (file) {
        var result = $Crypto.VerifyFile(file.Evaluate(), 'Pades');

        if (!result.AllValid) {
            throw new Error('The attached document does not have a valid signature.');
        }
    });
}

Throwing an error rejects the completion and the task stays open. If the task uses Execute Delay, the postwork script runs later in a separate transaction, so the error no longer reaches the user who selected the action.

Use the format that matches the signature type of the file (Pades for PDF, Cades for other files and detached signatures). The VerifyResult also lists the individual signatures and the validation log.