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.TCKNfor users,TCKNfor external users), only a certificate with the same number can be used. - Signature levels with a timestamp (
Tand 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¶
- In the form, bind the File or FileList widget to the nodes that hold the documents, for example
Files/File. - Select the approving action and open its User Select Script.
-
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; } -
Verify the signature on the server in the task's postwork script; see Verifying Signatures.
- 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 | |
Signing a Text¶
1 2 3 4 5 6 7 8 9 10 11 12 | |
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 ofBES,T,C,X,XXorA. The default isT.placeholder: PDF only. A regular expression that finds the text in the document where the visible signature is placed, for exampleSignature\\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 | |
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.