ConsignO® and VerifiO Server basic documentation
http://localhost:8080/api/v1
Introduction
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 application 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 application 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 applications 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.
Step One - Getting Started
OS Requirements
- Microsoft Windows 10, 11, Server 2016, Server 2019, Server 2022
- Lastest supported version of Microsoft Visual C++
- Virtual Machine requirements:
- 2vCPU or more,
- 4Gig of RAM or more,
- 30GB of disk or more (typically 50% reserved for the OS)
- A Linux implementation is also possible.
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)
Step Two - Configuration
- 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.
Notice that each time you make a modification in the values of any of the variables defined below, you should refresh the command prompt window (if you have it open).
| 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 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)
2. If you choose to configure CSA web service, make sure the environment variables are configured on the admin user of the server.
- 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
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
Use OpenSSL 1.1.0 to create the pkcs12. 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. Versions older than 2.13, changes can be done on the following lines:
spring.http.multipart.max-file-size=200MB
spring.http.multipart.max-request-size=250MB
Between versions 2.13 and 2.15.8, replace the above lines for the following:
spring.servlet.multipart.max-file-size=200MB
spring.servlet.multipart.max-request-size=250MB
Version 2.15.9 and going forward, these lines of configuration will be:
spring.servlet.multipart.max-file-size=200MB
spring.servlet.multipart.max-request-size=250MB
Step Three - Verification
You can test the installation by running the following command from the /bin folder:
csa -verifyrequirement
This command will verify local/network requirements. Make sure every test passes before going further.
Step Four - Execution
Execution on CSA CLI Mode
To launch CSA in CLI mode, from the /bin folder run the following command:
csa
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 on command line, run the following command from the /bin folder:
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.
- 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 as an administrator:
csa-service install
The service ConsignO® Server Automation should appear in the services list. Make sure that the service is started log on as Administrator. Environment Variables could also be set as System Variables and start the service from the command prompt with the following command:
csa-service start
- Verify Web Service
To verify that the service is installed correctly, two ways are possible:
- Postman: this test is recommended as it allows to validate firewall configuration and external connectivity to the service. Before you test, make sure you are using the IP address of the server where ConsignO® Server is installed and the listening port is the one configured in the Web Services properties. Make sure that the port is available in advance. By default, the port is 8080 but, it could be changed if necessary. E.g. http:// 172.30.4.23:80/api/v1/signPDF
- Web browser: if postman failed, and the server is well configured, validating on a local web browser can be done. The web browser should be on the same system as the server where ConsignO® Server has been installed. The result of the API call localhost:8080/api/v1 would be a page with the message 'CSA Webservice API'.
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 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:
{
"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.
Firewall configuration
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.
Configuration
All configuration details can be found at: https://support.notarius.com/en/help/kb/firewall-configuration/
Adding HTTPS header authentication
Right from the outset, ConsignO® Server can be configured to implement a minimal level of authentication for the REST API by utilizing an API key passed through the request header. To set this up, users need to configure the header directly from the originating application, and our system will take care of the validation process.
Configuration
1. API Key Definition:
In the consigno-sdk-webservices.properties file in the path consigno-server-automation\conf, one or more API keys can be defined as per the requirements. Keys can be separated by commas, allowing for flexible configuration.
2. Request Header Configuration:
To ensure proper authentication, every REST request must include a custom HTTP header named x-api-key. This header should carry the value of the API key defined earlier. This practice ensures that the request's authenticity can be verified on the server side.
3. Validation via Logs:
After processing an incoming request, the server proceeds to validate the supplied API key. This validation is done by comparing the provided key with the authorized keys, as configured in the consigno-sdk-webservices.properties file.
It's vital to monitor and ensure the correctness of this API key-based configuration. This validation process is reflected in the log/csa.log file, accessible after the web service's startup. Log entries should provide information about the success or failure of API key authentication.
- If the supplied key matches one of the authorized keys, the request is accepted for further processing. Code 200 OK.Examples:INFO [main] c.n.c.s.w.c.SecurityConfig - Securing server with 1 API keys
- However, if the key is missing or invalid, the server appropriately rejects the request and responds with an appropriate error 401 Unauthorized.
Evaluation certificates - Validity status 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).
Find your certificate file .cer
Certain CSA API ressources (like /prepareextsignpdf) call for your Certificate file (.cer). In order to find it, follow the following steps:
Manual process
- 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-----
API resources
- URI: http://localhost:8080/api/v1
- Version: V1
In the current version, the following resources are available:
/addSignatureField
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
-ConsignO® Server uses the term "units" as a unit length. 1 unit = 1 /72". Origin is in the top left corner of the document. To define the location of a signature zone:
- Convert your PDF document size in units. Ex.: A 8.5" x 11" (letter format) will be 612 x 792 units.
- Based on the location of the zone, derive the right coordinates for the top left corner of the zone.
/listDevices
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
/signPDF
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"
If the document has a signature field (fielname), its content can be made of:
- Image
- CustomText
- Image + customText
By command line:
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" -customtext "Information is certified by {crlf} {cn} to be accurate on {date, yyyy-MM-dd HH:mm}." -haligntext "CENTER" -valigntext "MIDDLE"
/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 are predictable. Templates should be in XML format.
By command line:
csa -applytemplate -in pdffile.pdf -out c:/tmp/pdffile_w_zone.pdf
-template "c:/tmp/template.xml"
/stampingPDF
This function is used to apply a stamp to the document. A stamp is simply an image that is applied to the document without digitally signing it.
By command line:
csa -stamp -in c:/tmp/consigno-sdk/vide_with_zone.pdf -out c:/tmp/consigno-sdk/stamped.pdf -fieldname "Field1" -img "c:/tmp/image.png"
/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
/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 -level PDF/A-1b -in c:/tmp/myfile.pdf -out "c:/tmp/converted.pdf" -flatten true
/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
/fillForm
/applyTimestamp
This function is used to timestamp a PDF document. Timestamping is an additional service offered by Notarius that provides a document with a standard time (not the signer's desktop time) and includes a private key as unique fingerprint.
By command line:
csa -applytimestamp -tsaendpoint https://timestamp-sandbox1.certifio.com/tsa/testtsa01 -in "c:/tmp/consigno-sdk/signed.pdf"
-out "c:/tmp/consigno-sdk/timestamped.pdf"
/upgradeLTV
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
-out C:/tmp/upgradedToLtv.pdf
/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"
/listEmbeddedFiles
This function will list the files that are currently embedded in a PDF.
By command line:
csa -listembeddedfiles -in "c:/pdffile.pdf"
/removeEmbeddedFiles
This function removes embedded files from a PDF
By command line:
csa -removeembeddedfiles -in "c:/file1.pdf" -out "c:/file2.pdf"
/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 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"
/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
/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 SHA-256
/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 "de2712" -devicetype mscapi -password -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 "de2712" -devicetype mscapi -password -in "c:/tmp/myfile.doc" -out "c:/tmp/signature_file.p7s"
/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
/validateCMS
Complete validation of all CMS signatures of a document. Both encapsulated and not encapsulated (external) signatures are supported. Validation of a CMS signatures is based on 2 sub-validations:
- Integrity (was the document modified after signature ?)
- Origin (signed by a trusted signer at signature time or custom date ?) Every signatures on a document contains a result for each of these aspect.
By command line:
csa -validatecms -in c:/tmp/file.xml -sig c:/tmp/file.xml.sig1,c:/tmp/file.xml.sig2