Interactive signing (with UI)

The PKIsigning API for signing with a user interface consists of two parts. The first part is a
REST API and works using HTTP with JSON. The second part is a websocket client that is
addressed from a javascript-file that can be included within the website of the caller.

Both the REST API and the websocket client have to authenticate using the accesstoken as
acquired from our identity server.

Server-side REST API

The endpoint of our production API is https://engine.pkisigning.io/api/signing. For development,
please use our staging environment: https://accengine.pkisigning.io/api/signing. Please note
that the urls are linked to separate identity servers. It is not possible to use access tokens of
the staging environment on our production environment and vice versa.

There are two available methods on the API: InitSession and CloseSession which will be
explained in more detail below.

Initializing a signing session (server-side)

To start signing a document, a new session should be started. With this call, all documents
that should be signed are submitted to the service. Documents have to be sent in base64
encoded formatting.

Please note: for SBR assurance signing, an XBRL publication document should be submitted,
an XBRL auditors report and optional one or more XBRL prepared extension documents. For
PDF signing, only one document can be signed at once.

PDF documents that are protected with an owner password are not supported and will result in a HTTP 422 error Unprocessable entity.

POST /api/signing/initsession HTTP/1.1
Host: https://api.pkisigning.io
Authentication: Bearer kjhafd22323…094alskdfasjasf
Content-Type: application/json 
{
	"documentsToSign": [{
		"filename": "document1.pdf",
		"contents": "<<base64>>",
		"placeholders":["Signer1","Signer2"]
	}],
	"assuranceLevel":"substantial",
    "signatureFormat":"PadES"   
}

Code example 1: Init session POST request - single PDF signing

POST /api/signing/initsession HTTP/1.1
Host: https://api.pkisigning.io
Authentication: Bearer kjhafd22323…094alskdfasjasf
Content-Type: application/json 
{
	"documentsToSign" : [{
		"filename" : "jaarrekening.xbrl",
		"contents" : "<<base64>>",
        "commitmentType" : "urn:sbr:signature-policy:proof-of-integrity-of-the-object-for-which-the-practitioner-expresses-an-opinion",
        "xPathFilter" : {
            "filter" : "/xbrli:xbrl/*[local-name()='DocumentAdoptionStatus' or local-name()='DocumentAdoptionDate' or local-name()='EmailAddressContact'] | //text()[normalize-space()='']",
            "type" : "subtract"
        }
	},
	{
		"filename" : "verklaring.xbrl",
		"contents" : "<<base64>>",
		"commitmentType" : "urn:sbr:signature-policy:proof-of-intent-of-practitioner-to-add-a-copy-of-the-opinion"
	}],
	"assuranceLevel":"qualified",
    "signatureFormat":"XadESDetached",
    "signaturePolicy":"http://www.nltaxonomie.nl/sbr/signature_policy_schema/v2.0/SBR-signature-policy-v2.0.xml",   
}

Code example 2: Init session POST request - SBR assurance linking and signing

Using a signature policy and commitment types for PDF signing is not yet possible.

This API call will return a sessoinId and an encryption key. Both are required to sign the
documents using the webservice-call and also to acquire the signed documents using the
CloseSession call. The encryption key is a value which is used to encrypt all documents that
are sent using the InitSession call. This value is not kept within our systems to provide
maximum security to your files. An incorrect value will lead to decryption errors and endusers
will not be able to sign.

HTTP/1.1 200 OK 
{
	"id": "<<sessionId>>",
	"password": "<<encryptionkey>>"
}

Code example 3: Start session response

Closing a signing session and acquiring signed documents (server-side)

When the documents have been signed, the documents will have to be acquired from our
servers using the CloseSession call.

Code example 4: Closing a session

The API will return one or more signed documents base64 encoded. In case of SBR assurance
signing, only the resulting detached signature will be returned and not the initially sent
documents as these have not been changed by the PKIsigning systems.

Code example 5: Close session response with single document

Code example 6: Close session response with multiple documents

After calling CloseSession, all documents on the server are removed and the session id will
be invalidated. When somehow the CloseSession call is not performed, the session is
automatically cleared after ten minutes.

Client-side javascript

To provide a minimal user interface and also to provide connection to local USB-tokens,
PKIsigning uses a javascript-file that has to be imported within a webapplication. The
javascript can be found at https://engine.pkisigning.io/scripts/pkisigningapi.js. Please note that the
script is using its own url to identify the server to connect to. Therefore please use
https://accengine.pkisigning.io/scripts/pkisigningapi.js when using our staging environment.
The client-side javascript is compatible with AMD loaders like requires en can also be
integrated with a normal script-tag on a webpage. It is not possible to use async attributes to
script-tags. As this script relies on JQuery, it cannot be loaded before the JQuery script as any
defined objects will be overwritten by JQuery.

The PKIsigning script requires minimum JQuery version 3.

Signing

Signing a document can be easily started by calling the following method:

Code example 7: Example of starting a new session from the browser

In this example both the sessionid and encryptionkey as acquired by the initsession call
should be used. Next to that the identity server accesstoken is required for authentication.
The webapplication should somehow provide a method to send these values from the
serverside to the clientside.

Triggers

The script will provide feedback on the signing process using triggers. A trigger is available
for errors, and also to report the signing has succeeded. Also a trigger is available to link to
an overlay like a spinner to indicate the process is busy.
Please see Code example 6 for an example. The alerts can be replaced by a more
application-friendly method-call.

Because the PKIsigning javascript is loading several components on its own, a PKIsigning
initiated event is also provided. This event is raised when all scripts are loaded and the script
is ready to run. It can be used to automatically start the signing process upon loading by
putting the code of example 5 into the body of this event.

Code example 8: Example of event handling in the browser