ConsignO and VerifiO Server basic documentation API documentation
http://localhost:8080/api/v1
Introduction
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:
- Web Service / REST API: Intensive and continuous digital signature and PDF operations. This integration requires moderate setup.
- Command line: Used for testing, or when digital signature and PDF operations are sporadic and not intensive. This integration requires a very small setup.
Installation / Configuration (Basic)
At the end of this section, you will be able to run CSA in command line mode.
OS Requirements
- Microsoft Windows 7,8,10, Server 2012, Server 2016
- From version 2.7 onward, Java is now embeded within the package.
Configuration
Environment Variables
Basic configuration requires the following environment variables. Ensure these variables are set for the user which will execute the CSA process.
Environment variable | Description |
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 needs 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 librairies folder. The PDF/A librairies 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 librairies folder. |
Installation
- 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)
Execution
You can test the installation by running the following command:
csa -verifyrequirement
This command will verify local/network requirements. Make sure every test passes before going further.
Installation / Configuration (Web Service)
At the end of this section, you will be able to run CSA in web service mode.
Configuration
Evironment Variables
Web Service configuration requires the following environment variables. Ensure these variables are set for the user which will execute the CSA process.
Environment variable | Description |
CSA_WEBSERVICES_ENABLED | By default, the web service component is disabled. To enable, set this variable to true. |
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:
server.ssl.key-store: keystore.p12
server.ssl.key-store-password: mypassword
server.ssl.keyStoreType: PKCS12
server.ssl.keyAlias: webserver
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 greated than max file size. By default:
- Max request size: 250 MB
- Max file size: 200 MB
These can be changed in conf/application.properties:
spring.http.multipart.max-file-size=200MB
spring.http.multipart.max-request-size=250MB
Execution
To launch CSA in webservice mode, run the following command:
csa -server
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.
Windows Service
CSA can be run as a windows service. To install as a service, from the /bin folder run the following command:
csa-service install
The service ConsignO Server Automation should appear in the services list.
Mapping input files to JSON attributes
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 in the multipart/form-data request, and each file param 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:
{
"in":"{file}",
...
"img": "{image}",
...
}
{"in":"{file}","out":"outputfilename.pdf", ...}
Response format
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.
Events
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.
Evaluation certificates
CSA can be configured to set the prefered 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).
/pdfMetadata
Retrieves some basic information about a PDF document, like:
- Number and size of pages
- Signatures
- 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
/validatePDFA
Verifies that a PDF/A document complies to the claimed level included in the document. This function cannot be used to verify conformance for a level different than the one present in the document.
By command line:
csa -validatepdfa -in c:/tmp/myfile.pdf
/validatePDF
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
/convertToPDFA
Converts a document to PDF/A using the level passed as parameter.
By command line:
csa -converttopdfa -in c:/tmp/myfile.pdf -level PDF/A-1b
/signPDF
Digitally signs a PDF document. The signature can be invisible or visible (using an image).
By command line:
csa -signpdf -device "c:/signature.epf" -devicetype epf -password c:/tmp/consigno-sdk/00000000.ual
-in c:/tmp/consigno-sdk/vide.pdf -out c:/tmp/consigno-sdk/signed.pdf
-reason "I am the author" -fieldname "Signature1" -img "c:/tmp/image.png"
/prepareExtSignPDF
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 server-side, and only a small data structure could be sent client-side for signature. This method is bandwidth-effective, as the full document does not travel client-side to be signed.
An external signature has 3 steps:
- Preparation step
- Prepare document to be signed using the signature certificate
- Calculate data structure to be signed
- Signature step
- 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.
- 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).
- Finalization step
- 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"
/finalizeExtSignPDF
Finalizes a document signature. See /prepareExtSignPDF for details on what happens.
By command line:
csa -finalizeextsignpdf -processid 6b50d524-4a6d-4b39-a84a-f57195641b7c
-in base64EncodedRawSignature -out c:/tmp/signed.pdf
/signCMSDetached
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 "c:/signature.epf"
-devicetype epf -password c:/tmp/consigno-sdk/00000000.ual
-in c:/tmp/consigno-sdk/vide.pdf -out c:/tmp/consigno-sdk/signature_file.p7s
/signCMSEnveloped
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 "c:/signature.epf"
-devicetype epf -password c:/tmp/password.ual
-in c:/tmp/myfile.doc -out c:/tmp/signature_file.p7s
/prepareExtSignCMS
Similar to an external PDF signature, but CMS-based. See /prepareExtSignPDF for further explanations.
By command line:
csa -prepareextsigncms -in c:/tmp/myfile.doc -certificate c:/tmp/certificate.cer -algorithm SHA256
/finalizeExtSignCMS
Similar to an external PDF signature, but CMS-based. See /finalizeExtSignPDF for further explanations.
By command line:
csa -finalizeextsigncms -processid 6b50d524-4a6d-4b39-a84a-f57195641b7c
-in base64EncodedRawSignature -out c:/tmp/signed.p7m -encapsulate true
/fillForm
/applyTemplate
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
-template "c:/tmp/template.xml"
/addEmbeddedFiles
Adds one or more files to the PDF, as attached files.
By command line:
csa -addembeddedfiles -in pdffile.pdf -out c:/tmp/pdffile_w_files.pdf
-files "c:/tmp/data1.xml" "c:/tmp/data2.xml"