blockchain_certification.md

Certifaction CLI for Blockchain Document Certification

This is Certifaction CLI for blockchain document certification.

Directly jump to the Installation section to install the CLI on your platform.

Please create an Issue to report any bug and propose new features.

Notes: Certifaction CLI is being developed at a fast pace and this documentation will already contain upcoming features not yet available in the most recent public release. Those features will be flagged with the [Upcoming Feature] notation.

• Introduction
• Requirements
• Functionality
• Document certification
• Document verification
• Usage options
  • Standalone application integration
  • Running the HTTP server on a node
• Authentication
• Installation
• Interactive CLI
• HTTP Server Mode

Introduction

Certifaction is the electronic signature technology for the Internet. With our solution, we empower people and companies to certify and verify documents in total privacy at any time, at any scale. By integrating with our straightforward API and tools, any business can provide the right level of security and compliance to their processes and products.

This document describes the Certifaction command line interface (CLI) , which provides a command line interface and an HTTP server that can be used by third party applications to certify and verify documents while preserving the documents’ confidentiality.

Requirements

The CLI is distributed as an executable file compatible with recent Linux, Windows and macOS operating systems and can be run in a Docker container.

The CLI requires access to the Certifaction API and an authentication token for most of its commands.

When using the CLI as an HTTP server, the executable will listen to HTTP ports which must be accessible to client applications.

Functionality

The CLI provides three main functionalities for your documents:

• Digital signatures
• Certification
• Verification

The document digital signature functionality is detailed in the main README. The rest of this document will focus on the document certification and verification.

Document certification

During document certification, the CLI will:

1. Receive the PDF document to certify and process it (add security features and the certification footer).
2. The processed document is returned and must replace the initial document (as this will be the document that will be certified).
3. The hash of the file and a public key is sent to the Certifaction API for registration.
4. The certification is timestamped in Ethereum.
5. The certification data is stored encrypted in a public database.

Document verification

During verification, the CLI will calculate the document hash and extract the private certification data decryption key, then call the Certifaction API that will find any certification timestamps in the blockchain and return the encrypted certification data.

1. The document to verify is provided to the CLI
2. The document hash is sent to the Certifaction API
3. The verification Certifaction API will search Ethereum for all the certification timestamps for the given hash and return them.
4. The timestamps refers to encrypted certification data stored in content addressable storage (CAS).
5. The Certifaction API returns the encrypted certification data to the CLI since it cannot decrypt them without the private decryption key contained only in the document.
6. The certification data are decrypted and a verification result is returned.

Usage options

The Certifaction CLI can be used in two modes:

• Interactive to execute commands on the shell, as part of a script or from a third party application.
• Server mode that exposes HTTP endpoints.

In both cases, the CLI sits between the third party application and the Certifaction API and will handle document certification, verification and revocation without leaking the document content outside the controlled IT infrastructure of the client.

In addition to being a useful command line utility, the CLI can be used by standalone applications to sign and certify documents with Certifaction without having to integrate and link to external libraries.

An application can call the CLI to either process documents stored in a directory or using the standard input/output. The CLI can also be deployed as an HTTP server container in the client's datacenter or cloud in order to integrate existing document workflows with Certifaction without ever exposing documents to the outside world.

Standalone application integration

In this scenario, the standalone application will use the OS command execution available to their platform to run the Certifaction commands. The documents can either be saved and loaded on the file system, or they can be passed to the command using the standard input and output.

Running the HTTP server on a node

In this scenario, the Certifaction CLI is started in server mode, either directly in a node or VM, or inside a Docker container. The client will use HTTP to sign and verify documents with the guarantee that documents do not leave the client IT system. This is the best option for centralized document signature where documents are signed during an automated document workflow.

Authentication

Document signature, revocation and getting user information require authentication. The authentication is done by passing an authentication token or an API key:

• Access tokens can be issued by you or by an external OIDC provider. Either case, Certifaction will have to register the identity provider.
• API keys are managed from the Certifaction web application. They can only be used for server side API integration.
• For HIN Sign authentication, please follow the instructions:
  • German
  • French

Installation

The CLI is delivered as an executable compatible with most of the usual platforms and can be found in the Release section of this repository.

Simply download the file for your platform and install it.

Please create an Issue if you do not find an executable for your platform.

Interactive CLI

• General usage
• Checking the health of the API and its dependencies
• Checking the API liveliness
• Prepare a document for signing
• Certify a document
• Revoke a document
• Verify a document
• Get the authenticated user information
• Export data
• Start the HTTP server

General usage

certifaction [certifaction flags] <command> [arguments]

The available commands are:

help                getting help about a command
download            download and decrypt document from digital archive
export              export data
health              return the health of the Certifaction API
info                return the metadata of provided file
ping                ping the Certifaction API
info                return the metadata of provided file
prepare             prepare a document for signing
register            register a document
verify              verify a document
revoke              revoke a document
user                return the authenticated user information
server              starts the HTTP server

Use certifaction help <command> for more information about a command.

Here are the command global flags that can be used for every command:

--env <name>      Optional environment name.  Defaults to prod.
                  Will automatically setup the API URL and
                  Ethereum contract addresses for a Given
                  Certifaction environment.
--api <URL>       Overrides the default Certifaction API URL
--token <access token>    The authentication token.  Please ensure that you
                          surround the token with quotes as it could contain
                          special characters.
--api-key <api key>       An API key created in the account settings
--verbose       Increase logs verbosity. Can be repeated multiple times
                to increase it even more.

Download file from digital archive

Usage

certifaction download [DA URL]

Description

Downloads document from the digital archive and then decrypts it.

Checking the health of the API and its dependencies

Usage

certifaction health

Description

Returns the API and its dependencies' health. The result is formatted as a JSON array of dependency objects. Returns an error if the API or any of its dependencies is not healthy.

Checking the API liveliness

Usage

certifaction ping

Description:

Returns success if the API is responsive, returns an error if not.

Get document metadata

Usage

certifaction info [input | url]

Description:

Retrieves metadata (salt, digital archive URL, hash and claim keys) stored from the file and returns them as a JSON.

Prepare a document for signing

Usage

certifaction prepare [prepare flags] [-o output] [input | url]

Description

Prepares a document for signing. A salt and a document claim encryption key pair is added to the document, and optionally a branded footer. If enabled, a Digital Twin QR code with a document encryption key will be added to the document. If the input file is already a digital original then the command will return the input file unchanged. Currently only processes PDF files. An error is returned if the input is not a PDF file. If the input parameter is omitted, then the command will take its input from stdin. If the output parameter is omitted, then the output will be returned to stdout.

Flags

--digital-twin     Adds a Digital Twin footer, encrypts the document and stores it.
                  Uses the footer template given by the -footer parameter.
                  If no -footer parameter is provided, then the default footer is used.
--language         Overrides the default language. Available languages are de, en, fr and it.
--scope            Optional signature scope override to choose between
                  register, sign and certify.

Register a document

Usage

certifaction register [register flags] [prepare flags] [-o output] [input | url]

Description

Digitally registers the document given as input or digitally registers the document with the hash given with the --hash flag. The document must be prepared. If the document is not prepared then it will be prepared first before signing unless the --no-prepare flag is used. If the --no-prepare flag is used and the document was not prepared, then an error is returned. If the document is prepared during registration, then the command will honor the prepare command flags. If the input parameter and the --hash flag are omitted, then the command will take its input from stdin. The command will output the prepared file. If the output parameter is omitted, then the output will be returned to stdout.

Flags

--scope           Optional signature scope override to choose between
                 register, sign and certify.
--no-prepare      Do not prepare the document if it is not already
                 prepared and return an error instead.
--hash            String, the hash of the document to sign
--note            Optional note to be saved together with the signature
--legal-weight    Allows to select type of the signature. Possible values are
                 "standard" and "QES". Defaults to "standard".
--jurisdiction   Only valid with "QES" signature, currently the only supported
                 value is "ZertES"

Certify a document

Usage

certifaction certify [certify flags] [prepare flags] [-o output] [input | url]

Description

Digitally certif the document given as input or digitally certifies the document with the hash given with the --hash flag. The document must be prepared. If the document is not prepared then it will be prepared first before certifying unless the --no-prepare flag is used. If the --no-prepare flag is used and the document was not prepared, then an error is returned. If the document is prepared during certifying, then the command will honor the prepare command flags. If the input parameter and the --hash flag are omitted, then the command will take its input from stdin. The command will output the prepared file. If the output parameter is omitted, then the output will be returned to stdout.

Flags

--no-prepare       Do not prepare the document if it is not already
                 prepared and return an error instead.
--hash            String, the hash of the document to sign

Verify a document

Usage

certifaction verify [-o output] [input | url]

Description

Verifies the file given as input. Returns the verification result as a JSON. If the input parameter is omitted, then the command will take its input from stdin. If the output parameter is omitted, then the output will be returned to stdout. Returns success if the document is authentic and signed from verified users, otherwise returns an error.

Revoke a document

Usage

certifaction revoke [revoke flags] [input | url]

Description

Revokes the document given as input. The document must be a digital original document. After revocation, any additional claims will be ignored during verification. Return an error if the document cannot be revoked. If the input parameter and the -hash flag are omitted, then the command will take its input from stdin.

Flags

--hash     string     The hash of the document to revoke

Get the authenticated user information

Usage

certifaction user [user flags]

Description

Returns the user information as a JSON. Returns an error if the user is not authenticated.

Export data

Usage

certifaction export [claims]

Description

Allows export of a user's data. At the moment only claims can be exported. Please note that claims are publicly accessible, but they are encrypted with a key that is integrated in the corresponding document. This export command serves the purpose of making full backups more convenient.

Start the HTTP server

Usage

certifaction server [server flags]

Description

Starts the Certifaction HTTP server.

Flags

--port number    server port number

HTTP Server Mode

• General usage
• Authentication
• TLS connection
• Common response code
• Get the API documentation
• Checking the health of the API and its dependencies
• Response
• Checking the API liveliness
• Prepare a document for signing
• Sign a document
• Verify a document
• Revoke a document
• Request a document signature
• Get the authenticated user information

General usage

This is the mode when the CLI is started using the certifaction server command as following:

certifaction server [server flags]

The CLI will start an HTTP server at the configured port and listen to the following endpoints:

GET  /health          Returns the health of the Certifaction API
GET  /ping            Pings the Certifaction API
POST /prepare         Prepares a document for signing
POST /register        Registers a document
POST /verify          Verifies a document
POST /revoke          Revokes a document
POST /download        Downloads and decrypts a document from the digital archive
GET  /user            Returns the authenticated user information
GET  /docs            Returns the API documentation [Upcoming feature]

The endpoints directly mirror the CLI commands.

Authentication

When indicated, the requests must be authenticated using the Authorization header as following:

Authorization: Bearer <AccessToken>

If the request is not authenticated a HTTP 401 Unauthorized response is returned.

TLS connection

The server does not terminate TLS connections. If TLS is required, a proxy must be placed before the server.

Common response code

400 Bad Request             Client error
401 Unauthorized            The request is not authenticated
403 Forbidden               The request is authenticated but the
                            client is not authorized
500 Internal Server Error   An unexpected server error occurred
503 Service Unavailable     Temporary service unavailability

Checking the health of the API and its dependencies

Usage

GET /health

Description

Returns the health of Certifaction services dependency.

Authenticated

No

Query parameters

None

Response

200 OK    an application/json array containing service status objects

Checking the API liveliness

Usage

GET /ping

Description

Returns success if the API is running.

Authenticated

No

Query parameters

None

Response

200 OK    No content

Prepare a document for signing

Usage

POST /prepare

Description

Takes the input file and prepares it for signing. A salt and a document claim encryption key pair is added to the document, and optionally a branded footer. If enabled, a Digital Twin QR code with a document encryption key will be added to the document. The resulting document is called a digital original. If the input file is already a digital original then the command will return the input file unchanged. Currently only processes PDF files. An error is returned if the input is not a PDF file.

Authenticated

Yes

Header

Accept-Language: used to select the right footer language

Query parameters

digital-twin=true: activates the Digital Twin feature
scope=<string>: overrides the default user signing scope. The possible values are register, sign and certify

Response

200 OK    the prepared application/pdf file

Body

An application/pdf body containing the document to prepare

Register a document

Usage

POST /register

Description

Digitally registers the document given as input. The document must be a digital original, i.e. it must have been prepared with the prepare command. If the document is not a digital original, then it will be prepared first before signing unless the no-prepare flag is used. If the no-prepare flag is used and the document was not prepared, then an error is returned. If the document is prepared during registering, then the command will honor the prepare query parameters.

Authenticated

Yes

Header

Accept-Language: used to select the right footer language

Query parameters

scope=<string>: overrides the default user signing scope. The possible values are register, sign and certify
no-prepare=true: do not prepare the document if it is not prepared and return an error instead.
hash=<string>: the hash of the document to sign
filename=<string>: the name of the file
note=<string>: additional note to be stored in claim
legal-weight=<string>: allows to select type of the signature. Possible values are "standard" and "QES". Defaults to "standard".
jurisdinction=<string>: only valid with "QES" signature, currently the only supported value is "ZertES"

In addition, the query will accept the prepare query parameters.

Response

200 OK    the signed application/pdf file

Body

An application/pdf body containing the document to register

Verify a document

Usage

POST /verify

Description

Verifies the file given as input. Returns the verification result as a JSON.

Authenticated

No

Header

None

Query parameters

None

Response

200 OK    the application/json verification result

Body

An application/pdf body containing the document to verify

Example

Verification result:

{
 "on_blockchain": true,
 "issuer_img": "https://example.com/images/verified_by_acme.png",
 "issuer_verified": true,
 "issuer_title": "",
 "file": {
   "hash": "0x61c2ec21338308bb9283917041db4a70dee2c9d3258228d8c6039d5b431a1653",
   "status": "registered",
   "claim_key": "044aa7b14f1538954c83062083da2db3e41d4d7cb75f7069baeffbbf45f1adcad091c0113fb440ed848d01c667022c73806b8f26622b4562daabdb6dfc87d4b543",
   "txHash": "0x64f4b4f5a0baa42f529efe1e2d8f0d2b41481b9b236698f20a92680bf60e386f",
   "registered_at": "2021-01-14T09:53:59Z"
 },
 "revoked": false,
 "encrypted": true,
 "claims": [
   {
     "@context": "https://schema.certifaction.io/encryptedclaim/v1",
     "@id": "cert:hash:0x61c2ec21338308bb9283917041db4a70dee2c9d3258228d8c6039d5b431a1653",
     "algorithm": "ECIES",
     "claim": "BHnbTfqOfN93h+lT0fbFdpFareoWq293lopv000HLk9K8EZ5aXUYXXmpx6y9hV7RTgHXQfkgzj/Km3tjOOxrzWpUxQ1JLPHqaTqE0DMzhEV97/UXk1ooF/nlV/fwyhg+zRnoqJWmcUMpB/Rdamu0Ur4pfNVB8VKbr5WFQlDNWrXjFQfWFqH66JebSThX0HcGqcAldxc8yGo5r0rHBcnFQxbZPu/SzxFcsc7fg9IfQaYp1FOyBBYfAJlhbLCtn0ahdb2IKynjltqqLSWpyx8rWq+1CsN4SHfQYE1+XfOhitU+wlsNbj5vhO4Q2t4l8jZyThrEWcc7cVindVmc6cdziAI/nTbDuQ+aj0GN5Gwb0jiR3MP9CNeUKU9vg+Twx4I1W/inOlpYYAuJ8MDz1Kcr58g4FpSIBL4v43rk6ZDfX9I/bMclc3O+HFotmAWoTGWcxfqCKdTSR2PoOw9pmyNd3oPbNQSOXuWGDrbLE2mZB7hR76VIWHe18Pgd6gATsaFqIcnyVGY1OIrcbpMn1cDfMNoeWTd7rg/mjbPztYW5VT/U7oar4jTAiqaZQZpNC7HFypz2DwV6cnDxNnaoVYJMZzia0UmNaW5+WYKVykAueh376OH52FQjt1MAF4jl3bn8l7V0RPHN6Ma4M82/xMb+k+ELucJI8MAVZvqOeobZbATVSadZFbtEw3vykHsPNCuF50SA9FiFELVFSp7CQwpn2k9HR6EM90D6pdtL/QL+q5HFE1iMzUopQyg3Klebpxz9zpOfrIThSTLBwwcr6HiLkbu9A+NpAIwpxqkhKUiOjWeGYeP9nKDQ1Ez6ltqm9dKhpcFci/C+1403b687FEFuk1yrf3znaPzDwjU6gKBmbAFqJRpurnyow+h9+t/F0eFqHBFZSuJrsqf467WTvEewlvuB+yc6cf/DSPnf7mX7u56AJ+amMLkTyn6plC0nD3bTzXYSAWkV1UhSb9Yb7Q/Wj0B6s7YtEgs/3pdEssLGx2nABZa0W4uxQDpejYozX8PBeedZ/S5zW5nfItnFgqVNZOBm5+r9QO2DVGhKJXATDsqORuAbLg/AZlmQv/gSSo6Or0pa7g0kRmy0eS7LDf17KFK27Jec5vv0FAc69/DPtt/CG8b9kcdMVwnjMRnhkcwJhuU1ehubDxqBKvq6iPYLZiOZYvdjE6Fqo4Kxn66mmhNdoHVbmhFYF1FpPE74I9xV2vn6xIvPw70C60yaWe8r+bxDUKdBzIWX1SFWYzUaGMiKlxBuTKSkiqXT3frNzuHqd7A48luk2gNQEOk2o73lnjXkNgEELjPo+CynS94g+g/EoRey+aqnVPfDQaRyfcmBsUwJOKeOf6O0VBaeV9/PxDf7Cg=="
   }
 ]
}

Explanation of essential fields:

Field | Description ----- | ----------- on_blockchain | Indicates whether the file has been registered on the blockchain issuer_img| Optionally has a path to an image or logo of the issuer issuer_verified| Defines whether the issuer identity has been verified file.hash| Hash of the file file.status| Temporary status of the file in our database ('registered', 'revoked', 'registering', 'revoking'). Might temporarily differ from status on the blockchain until the file has definitely been confirmed on the blockchain. For verification use on_blockchain and revoked fields instead. file.txHash| Transaction hash of the registration on the blockchain. Can be checked for example on https://etherscan.io. file.registered_at| Time when file has been registered. revoked| Indicates whether the file has been revoked on the blockchain. If a file has been revoked it will have on_blockchain: true encrypted| Indicates where the data under claims is encrypted for privacy reasons claims| Claims about the file. Claims have already been verified before returning the result but can optionally be verified by the costumer.

Revoke a document

Usage

POST /revoke

Description

Revokes the document given as input. The document must be a digital original document. After revoking, any additional claims will be ignored during verification. Return an error if the document cannot be revoked.

Authenticated

Yes

Header

None

Query parameters

None

Response

200 OK    no content

Body

An application/pdf body containing the document to revoke

Download file from digital archive

Usage

GET /download

Description

Downloads document from the digital archive and then decrypts it.

Authenticated

No

Query parameters

file=: digital archive URL

Response

200 OK    An application/pdf body containing the document

Get the authenticated user information

Usage

GET /user

Description

Returns the user information as a JSON.

Authenticated

Yes

Header

None

Query parameters

None

Response

200 OK    an application/json user object

Body

An application/pdf body containing the document for which a signature is requested

Example

{
 "id": 506,
 "uuid": "GzOysSHa8EB",
 "external_id": "5fe0a47220148a00686f055a",
 "email": "[email protected]",
 "name": "Hans Muster",
 "eth_address": "0x124bf6e60b4ec8dc7bc314aaca4ab09dc4da1ecd",
 "quota": 2,
 "subscription_type": "credits"
}

Explanation of essential fields:

Field | Description ----- | ----------- email| Email address of the user quota| The amount of credits the user has left to register or revoke files if the subscription type is credits. subscription_type| The subscription type of the user. Can be credits or flat_rate

Get the API documentation [Upcoming feature]

Usage

GET /docs

Description

Returns the API documentation that was generated from a swagger file. The source swagger file URL can be found in the page.

Authenticated

No

Query parameters

None

Response