Confidencial Official Documentation Site

ℹ️

This page describes how to use the Confidencial CLI, which lets users perform Confidencial actions such as encryption using shell commands and scripts. Please contact us if you would like to get access to it.

ℹ️

While the CLI does not currently support decryption, the Confidencial

Software Development Kit (SDK) can be used to decrypt files and can be invoked from JavaScript code running in a Node environment (using the child_process module) or in a web browser

🌐

An internet connection is required to use the CLI in cases where end users’ public (encryption) keys need to be obtained

Authentication

🔑

Most CLI actions require authentication in the form of a machine token. See

🪙

Creating a machine token for instructions on how to create one.

Actions

ℹ️

The CLI is currently capable of encrypting PDF files. Support for decryption and other file formats is coming soon. Have a file format you’d like to see supported? Contact us.

Encryption

Encryption commands take the form of


c11-cli -machineToken "your machine token" -a encrypt -if "/inputfile.pdf" -of "/outfile.pdf"

where your machine token is the token you obtained by following the steps in

🪙

Creating a machine token, inputfile.pdf is the name of the file you’d like to encrypt, and outfile.pdf is the name of encrypted version of the file you’d like to create.

ℹ️

It is recommended that you remove your original, unencrypted versions of your files after you have created corresponding encrypted versions of them. If necessary, you can revert encrypted versions to unencrypted versions using the Confidencial

Software Development Kit (SDK) (and later using the command-line interface).

Specifying multiple recipients

By default, documents are encrypted only for the user that generated the machine token that was supplied in the command line. To specify a different set of users that can decrypt the document, provide a “recipients” file via the -rf <recipients.json> option. A recipients file is a JSON-formatted file that contains the organization name and email address of all users that should be permitted to decrypt the document. See example recipients file below.


[
  {
    "organization": "org-name-1",
    "email": "person1@example.com"
  },
  {
    "organization": "org-name-2",
    "email": "person2@example.com"
  }
]

Document tracing

You can trace activity related to documents protected with the CLI using Confidencial’s feature. This feature is enabled by default if additional document recipients are not specified (i.e. if the -rf option is not used). To trace documents protected with the CLI when additional recipients are specified (i.e. when the -rf option is used), specify the -asOwner option in the command line.

PDF page streaming

A PDF page streaming encryption mode is available to support use cases in which a PDF may be served to a client on a page-by-page basis. When the -withPageStreaming option is specified, the encrypted data within the PDF document is stored such that encryption data can be retrieved for specific pages. This is in contrast to the default encryption mode, in which encryption data for the entire document is stored within a single object. To use page streaming mode, include -withPageStreaming <policies.json> in the command line, where <policies.json> is the path to a JSON file that specifies which pages should be encrypted for which end users. An example policies file is shown below.


{
  "policies": [
    {
      "pages": [1],
      "recipients": [
        {
          "organization": "org",
          "email": "example1@domain.com"
        },
        {
          "organization": "org",
          "email": "example2@domain.com"
        }
      ]
    },
    {
      "pages": [2, 3, 4],
      "recipients": [
        {
          "organization": "org",
          "email": "example3@domain.com"
        }
      ]
    }
  ]
}

With page streaming mode, each page within a PDF document can be encrypted for a different set of users. The resulting encrypted data can then be retrieved from the document on a page-by-page basis.

Examples

Extracting a single page from a Confidencial PDF encrypted by the CLI in page streaming mode (Java)

The Java code below uses a third-party PDF library to extract a single page (and corresponding Confidencial encryption metadata) from a PDF file that has been encrypted with the Confidencial CLI in page streaming mode. With the single page extracted, it can be passed to the Confidencial

Software Development Kit (SDK) to be decrypted and displayed to an end user.


package tst;

import java.io.File;
import java.io.IOException;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDDocumentInformation;

public class Main {

	public static void main(String[] args) throws IOException {

		System.out.println("Process started");
		//Read Pdf file encrypted by Confidencial CLI
		File file = new File("files\\sample.c11.pdf");
		PDDocument sourceDocument= PDDocument.load(file);
		//Extract confidencialData from PDF custom metadata for a given page number
		int pageNumber=1;
		PDDocumentInformation documentInformation =	sourceDocument.getDocumentInformation();
		String confidencialData = documentInformation.getCustomMetadataValue("confidencialData_" + pageNumber);
		//create a new PDF file
		PDDocument singlePdfPageDocument = new PDDocument();
		//add first page from encrypted PDF file
		singlePdfPageDocument.addPage(sourceDocument.getPage(0));
		//add confidencialData to custom metadata
		singlePdfPageDocument.getDocumentInformation().setCustomMetadataValue("confidencialData", confidencialData);
		//save the file
		singlePdfPageDocument.save("files\\sample.page1.pdf");
		sourceDocument.close();
		singlePdfPageDocument.close();
		System.out.println("Process completed successfully");

	}

}

Command-Line Interface (CLI)