ConsignO and VerifiO Server basic documentation
Below documentation corresponds to version 2.8 of the CSA package for ConsignO and VerifiO Server, which is the latest version available to our customers. As we release new versions and tailor functionality, ConsignO and VerifiO Server will differ from version to version. Please, contact us to see documentation to your version of the API.
What are ConsignO and VerifiO Server ?
- ConsignO Server is a software library that enables integration of digital signature operations and PDF manipulations into your existing process. These operations are mainly write operations.
- VerifiO Server is a software library that enables the integration of digital signature verifications and PDF/A verifications into your existing process. These operations are mainly read operations.
From a technical perspective, both libraries are delivered in a single package to facilitate integration for customers who use both sets of functionalities. This package is called ConsignO Server Automation (CSA).
There are various ways to integrate CSA. Of these, 2 API flavors are recommended:
- CSA Web Service / REST API: Intensive and continuous digital signature and PDF operations. This integration requires moderate setup.
- CSA Command line: Used for testing, or when digital signature and PDF operations are sporadic and not intensive. This integration requires a very small setup.
- Microsoft Windows 8,10, Server 2012, Server 2016
- From version 2.7 onward, Java is now embedded within the package.
- Unzip package consigno-server-automation-version.zip into the directory of your choice.
- ConsignO relies on external dependencies for the PDF/A functions. If you have subscribed to these functions (PDF/A conversion and/or PDF/A validation), you need to install these dependencies by unzipping the archive pdfa-libs.zip into the directory of your choice (for example: c:/pdfalibs)
- Define Environment Variables
Basic configuration requires the following environment variables. Ensure these variables are set for the user which will execute the CSA process. Variables should be defined as seen below to work.
|CSA_HOME||Absolute path of the root of CSA installation folder. Warning: for full compatibility with provided samples, ensure the path uses forward slashes '/'. CSA_HOME/bin should to be in the PATH.|
|CSA_LICENSE||Provided by Notarius|
|CSA_SIGNATURE_KEY||Provided by Notarius. This value is SENSITIVE. Make sure it is correctly protected.|
|CSA_WORKING_DIR||This should point to a folder serving as a working directory. CSA uses this folder to store non-persistent information. Relative paths provided in requests will also be resolved against the working directory.|
|CSA_PDFA_LIB||If you have subscribed to PDF/A operations, create this variable and set as value the absolute path to the PDF/A libraries folder. The PDF/A libraries is a zip file provided by Notarius. For Unix platforms you have to set also the environment variable LD_LIBRARY_PATH to the same value, the absolute path to the PDF/A libraries folder.|
|CSA_WEBSERVICES_ENABLED||By default, the web service component is *disabled*. To enable, set this variable to true.|
- Update system PATH
- Add CSA_HOME/bin to your system PATH.
Additional Configuration for CSA Web Service (Optional)
- Local processing port
The web service component builds on top of the existing CSA incoming requests processor. This processor listens on a local TCP/IP port for incoming requests. By default, the port is 5000. This can be changed in conf/daemon.router.xml.
- Web Server port
The web service component launches an embedded web server which, by default, listens on port 8080. This can be changed in conf/consigno-sdk-webservices.properties:
server.port = 8080
- Enabling SSL
While not mandatory, SSL can be configured in conf/consigno-sdk-webservices.properties:
To generate a keystore using an existing private key and certificate you can use command line:
openssl pkcs12 -export -out keystore.p12 -inkey tls.key -in tls.cer -name webserver
In addition, it is possible to generate a self-signed SSL certificate using keytool, which is provided within the CSA package (\jre\bin directory). Nonetheless, it is possible to use the tool of your preference. If using Keytool, it is recommended to check the latest documentation available online.
SSL will be enabled on the same port configured above. It is currently not possible to enable both HTTP and HTTPS.
- Max request size
Request size is driven by 2 variables: the max request size and max upload file size. Since multiple files can be uploaded in the same request, max request size must be greater than max file size. By default:
- Max request size: 250 MB
- Max file size: 200 MB
These can be changed in conf/application.properties:
You can test the installation by running the following command from the /bin folder:
This command will verify local/network requirements. Make sure every test passes before going further.
Execution on CSA CLI Mode
To launch CSA in CLI mode, from the /bin folder run the following command:
If you have setup PATH previously, CSA can be launched from any directory in your system.
Execution on CSA Web Service
To launch CSA in webservice mode, run the following command from the /bin folder:
The running server can be stopped by sending the kill signal SIGINT (equivalent to ctrl-c) to the process. The server will intercept the signal and close gracefully.
- Start as a Windows Service
CSA Web Service can be run as a windows service. To install it as a service, from the /bin folder run the following command:
The service ConsignO Server Automation should appear in the services list.
Most requests to CSA require one or more files in order to execute the desired action. For example, to sign a PDF with a visible appearance, one needs an input file and an image. Each file is sent as a part of the multipart/form-data request, and each file parameter is mapped using the corresponding part name, wrapped in curly braces, inside the json parameter.
Assuming a part named 'file' and another part named 'image', the signPDF request would look like:
Responses are always JSON formatted, and contains the following information:
- code: Return code
- msg: Return message
- response: the response object, which varies depending on the function called.
Code value of 0 indicates success. Any other code indicates failure. When the web service component is used, success is also indicated by the HTTP response return code, where 200 indicates success.
What are events
Most function calls produce events which are ultimately sent to Notarius servers. These events include basic information about the function call, ie. which function, when was it called, by whom, etc.
How are they managed
Events are accumulated in-memory and are sent to Notarius servers when one of following 2 conditions occurs:
- The application (or service) is shutdown. Events are uploaded before complete shutdown.
- The in memory threshold is reached. The threshold can be configured in conf/consigno-sdk-core.properties. Defaults to 10. When threshold is reached, an asynchronous thread will upload the events queue.The threshold should be configured according to how many transactions the application is processing. Notarius needs these event to be uploaded frequently, but allows for them to be queued so that performance is not impacted.
If the server is unable to upload the events, these are persisted on-disk. Further attempts will be done each time the server starts.
To activate, use and validate Notarius’ digital signature, four outbound communication flows to Notarius’ servers must be enabled. These flows are always initiated from the given workstation and use standard protocols. These outbound communication flows are required to activate a digital signature, sign a document and guarantee its authenticity, and validate a third party’s signature (internal or external to your organization). No information pertaining to your electronic documents is communicated to Notarius or any third party.
All configuration details can be found at: https://support.notarius.com/en/help/kb/firewall-configuration/
CSA can be configured to set the preferred Validity status when the application encounters an evaluation signature. By default, the validity set is EVALUATION_PURPOSE, and the global result will be WARNING. By setting another validity status in /conf/consigno-sdk-signature.properties, the CSA admin can allow evaluation signatures to be considered VALID (with global result SUCCESS).
Certain CSA API ressources (like /prepareextsignpdf) call for your Certificate file (.cer). In order to find it, follow the following steps:
- On Windows bar, open the hidden icons. Right-click on the Entrust icon,
- Click on Entrust Certificate Explorer,
- A new window will pop up, select your certificate. Right-click on your certificate, choose Export Certificate.
- Follow the instruction on the wizard, choose either X.509 DER or X.509 base64, choose the directory where you will keep the certificate and give a name to the file.
- Finish the wizard.
Using CertifiO Manager API
- Run the API ressource /certs from the CFM API
- Parse from the response the argument "encodedForm"
- To the value of that argument, add; At the beginning of the string, this text -----BEGIN CERTIFICATE-----
At the end, this text -----END CERTIFICATE-----
- URI: http://localhost:8080/api/v1
- Version: V1
In the current version, the following resources are available:
Determines, previous to signature, the location and the size of the signature field within the document.
By command line:
csa -addsignaturefield -fieldname "Signature1" -fieldpage "last" -fieldx 70.0 -fieldy 90.0 -fieldwidth 100.0
-fieldheight 100.0 -in c:/in.pdf -out c:/out.pdf
This function will list all the available devices along with the available certificates on the machine to which the request is sent. The device type must be mscapi. For mscapi device type, the device value must be all.
This funtion would be used as a previous step to /signPDF to retrieve the device id from the listed devices.
By command line:
csa -listdevices -devicetype mscapi -device all
Digitally signs a PDF document. The signature can be invisible or visible (Assigning an image to a field/zone on the document).
By command line:
-When using a personal Certificate (CertifiO Pro/Employee), use MSCAPi as a device type. To retrieve the certificate device ID, use /listdevices previously.
csa -signpdf -device "de2712" -devicetype mscapi -password -in c:/tmp/vide.pdf -out c:/tmp/signed.pdf -reason "I am the author" -fieldname "Signature1" -img "c:/tmp/image.png"
-When using an organizational Certificate (CertifiO Org), use H2 as a device type.
csa -signpdf -device "http://hh1.notarius.com/hh1-ca1/notarius-test/api/v1" -devicetype "h2" -password -in "C:/tmp/field_1.pdf" -out "c:/tmp/signed.pdf" -reason "I approve"" -img "C:/tmp/image.png"
Applies a ConsignO Desktop template to a PDF. A template is a descriptor of one or more signature fields. This is used when signature fields placement if predictable.
By command line:
csa -applytemplate -in pdffile.pdf -out c:/tmp/pdffile_w_zone.pdf
Retrieves some basic information about a PDF document, like:
- Number and size of pages
- Unsigned signature fields
- PDF/A claimed level
This operation is not costly as no extensive validation of signatures or PDF/A conformity is done.
By command line:
csa -pdfmetadata -in c:/tmp/myfile.pdf
Complete validation of all the signatures appearing on the document. Validation of a signature is based on 3 sub-validations:
- Integrity (was the document modified after signature ?)
- Origin (signed by a trusted signer at signature time or custom date ?)
- Time (issued by certified timestamp authority or taken from local machine ?)
Every signature on a document contains a result for each of these aspect. The global document result (document authenticity) ie equals to the worse result appearing in the document.
By command line:
csa -validatepdf -in c:/tmp/myfile.pdf
Upgrade to Long-Term Validation, this function is used to collect all available revocation information, embed to DSS and apply a timestamp.
By command line:
csa -upgradeltv -in C:/tmp/signed_not_ltv.pdf -tsaendpoint https://timestamp-sandbox1.certifio.com/tsa/testtsa01
An external signature is a signature which is done in a different time/place than where the document resides. For example, a document could be prepared on the server-side, and only a small data structure could be sent to the client-side for signature. This method is bandwidth-effective, as the full document does not travel to the client-side to be signed.
An external signature has 3 steps:
- Preparation step using /prepareExtSignPDF
- Prepare document to be signed using the signature certificate.
- Generate data structure to be signed and retrive the proceesID, dataToSign and algorithm fields from the response, in order to be used in the next steps.
- Signature step using /signatures
- This step can be done at a different time/place than where the preparation step occured. Typically, the data structure is sent client-side, where the digital signature private key resides.
- Option 1; this step can be done with any technology supporting RSA digital signature. The algorithm that needs to be used is called PKCS#1 v1.5 (NoneWithRSA in Java).
- Option 2; use the /signatures in the CFM API. For details on its use when Externally Signing, go see the CFM API documentation. Take note that this is a different API ressource to /signPDF
- Finalization step using /finalizeExtSignPDF
- The resulting signature is embedded in the document prepared in the previous preparation step.
By command line:
csa -prepareextsignpdf -in c:/tmp/myfile.pdf -certificate "c:/tmp/certificate.cer"
-reason "I am the author" -fieldname "Signature1" -img "c:/tmp/image.png"
A CMS signature (Cryptographic Message Syntax) allows signing of any data formats. In a detached mode, the resulting signature is saved in a separate file (.p7s). The signed document is never modified in the process.
By command line:
csa -signcmsdetached -device "de2712" -devicetype mscapi -password -in "c:/tmp/consigno-sdk/vide.pdf" -out "c:/tmp/consigno-sdk/signature_file.p7s"
A CMS signature (Cryptographic Message Syntax) allows signing of any data formats. In an enveloped mode, the resulting file (.p7m) includes both the signature and the original document. The signed document is never modified in the process.
By command line:
csa -signcmsEnveloped -device "de2712" -devicetype mscapi -password -in "c:/tmp/myfile.doc" -out "c:/tmp/signature_file.p7s"