Client CLI

1. Introduction

The Sharemind HI Client CLI is an application which wraps the Sharemind HI Client C++ Library. Common options are read from a configuration file, persistent state is stored on the local file system, and specific actions are invoked via command line arguments. The CLI provides most of the functionality of the C++ library at the command line. In simpler use cases the CLI might be sufficient as the application for the stakeholders. More complex use cases with additional input data processing, output data visualisation, or when the Linux terminal is not a suitable environment, likely require the use of the C++ or TypeScript libraries in custom client applications.

2. Sharemind HI Package Distribution

Sharemind HI is distributed in two ways. Development packages are distributed in a custom way, negotiated with the application developer. Production packages are distributed through the Sharemind APT repository. The APT repository can be accessed as follows:

# Add Sharemind repository key
wget -qO - https://repo.cyber.ee/sharemind/apt/pubkey.gpg | sudo apt-key add -

# Install HTTPS repository support for APT
sudo apt install apt-transport-https

# Add Sharemind repository
user="..." # provided in a separate document
pass="..." # provided in a separate document
path="HI-$user"
repo_url="https://$user:$pass@repo.cyber.ee/sharemind/apt/$path"

. /etc/os-release # for $UBUNTU_CODENAME. Or use "bionic"/"focal" directly.

echo "deb [arch=amd64] $repo_url $UBUNTU_CODENAME non-free" \
  | sudo tee /etc/apt/sources.list.d/sharemind-hi.list

# Update
sudo apt update

Note: We recommend to hold the installed packages after installation, to prevent installing a client application which is incompatible with the server. For example:

sudo apt install sharemind-hi-client=4.0.0
sudo apt-mark hold sharemind-hi-client

3. Supported Platforms

Currently installation is only supported on the Ubuntu 18.04, 20.04 and 22.04 platform on a x86-64 CPU.

4. Installation

With the following code you will install the following pieces:

Package

Files

sharemind-hi-client

bin/sharemind-hi-client
The application for communicating with the Sharemind HI Server and its man page, and an application.
usr/share/man/man1/sharemind-hi-client.1.gz
Its man page (man sharemind-hi-client).
bin/sharemind-hi-client-init
An application to generate a default client configuration file.

sharemind-hi-audit

bin/sharemind-hi-audit
The application for decrypting the audit log.
usr/share/man/man1/sharemind-hi-audit.1.gz
Its man page (man sharemind-hi-audit).

5. Configuration

For a client application to communicate with a production Sharemind HI Server, a number of certificates, addresses, and enclave identities must be configured.

The default configuration and associated directories and files can be generated in $HOME/.config/sharemind-hi by running:

sharemind-hi-client-init

The resulting default configuration looks similar to the following one:

Client:
  PrivateKeyFile: "/home/user/.config/sharemind-hi/private/client.key"
  PublicKeyCertificateFile: "/home/user/.config/sharemind-hi/certs/client.crt"
  StateFile: "/home/user/.local/share/sharemind-hi/state.bin"
  TrustedEnforcers:
    # - "/home/user/.config/sharemind-hi/certs/a_trusted_enforcer.crt"
Server:
  ServerAddress: "localhost:30000"
  ServerTrustRootCertificatePath: "/etc/ssl/certs"
Attestation:
  AttestationEnclave:
    EnclaveFingerprint: "..."
    SignerFingerprint: "..."
  KeyEnclave:
    EnclaveFingerprint: "..."
    SignerFingerprint: "..."
  CoreEnclave:
    EnclaveFingerprint: "..."
    SignerFingerprint: "..."
AttestationService:
  ReportSigningCertificateFile: "/usr/share/sharemind-hi/client/AttestationReportSigningCACert.pem"
  ReportSigningCertificateType: "PEM"

The default configuration should be modified for use in a production Sharemind HI solution.

General information on the clint configuration can be found on the Client Configuration page.

The sharemind-hi-client manual contains a detailed description of the configuration of the CLI client and the binary. The manual can be accessed by running:

man sharemind-hi-client

6. Operations

The CLI client application allows a stakeholder to perform the following actions:

Remote attestation

sharemind-hi-client -c client-config.yaml -a attestation
Perform remote attestation and set up a new session between the Sharemind HI server and the client.

DFC approval

sharemind-hi-client -c client-config.yaml -a dfcApprove
Stakeholders with the Enforcer role can approve the DFC. The approval procedure displays the staging DFC to the enforcer, who can then accept or decline the DFC after careful examination.

Display the DFC

sharemind-hi-client -c client-config.yaml -a displayDfc
Display the full dataflow configuration, including all topics and all task instances. Output is provided in YAML format. You may use this as a basis to implement arbitrary information extraction logic, for example using yq.

Upload data

sharemind-hi-client -c client-config.yaml -a dataUpload — --topic topic-name --datafile data.file
Uploads data to the specified topic. Data is only uploaded if the stakeholder has the Producer role and is listed as a input provider for the topic in the DFC.

Download data

sharemind-hi-client -c client-config.yaml -a dataDownload — --topic topic-name --dataid 0 --datafile data.file
Downloads data with a specific ID from the specified topic. Data is only downloaded if the stakeholder has the Consumer role and is listed as an output consumer for the topic in the DFC.

Run a task enclave

sharemind-hi-client -c client-config.yaml -a taskRun — --task enclave --wait
Runs a specified task enclave. The optional --wait argument blocks the CLI until the task finishes, and is equivalent to using the taskWait action. The task is only run if the stakeholder has the Runner role and is listed as a runner of the task in the DFC.

Query a task enclave

sharemind-hi-client -c client-config.yaml -a query — --task enclave --timeout 1h2m3s \
--response-out output.file --public-data @./public_arguments.file — --argname1 private_arg1 --argname2 private_arg2
Directly sends a query to a task and waits for its completion. Task arguments are sent in encrypted form, and the response is received in encrypted form. The task is only run if the stakeholder has the Runner role and is listed as a runner of the task in the DFC.
The timeout argument specifies the duration of time the task is allowed to run before it is automatically cancelled. By default no value is set. See Period Syntax for the formatting of the argument.
The response-out argument specifies where the output of the query is written to.
The public-data argument specifies the payload that is sent to task enclave unencrypted. To insert file as input start the argument with '@', e.g. --public-data "@/path/to/file". This can be used for binary input, and also works with the process substitution feature from shells.
The arguments passed after '--' are interpreted as private task arguments. Similar to the public arguments, to insert the content of a file as input start the argument with '@'. Note: The syntax --argname=arg (using =) is not supported.

Wait for a task enclave to finish

sharemind-hi-client -c client-config.yaml -a taskWait — --task enclave --taskinstance 0
Blocks until a specified task enclave finishes. Also displays the tasks status as with the taskStatus action.

Query the status of a task enclave

sharemind-hi-client -c client-config.yaml -a taskRun — --- --task enclave --taskinstance 0
Shows the current state of a task instance. The possible states are PENDING, RUNNING, FINISHED and FAILED. Additionally shows:

task arguments,
the runner of the task
the output topic and data ID of any data written to a topic by the task.
timestamp of starting the enclave
error message, if the enclave failed.

Query the list of task enclaves

sharemind-hi-client -c client-config.yaml -a taskEnclaveList
Lists the task enclaves that are currently loaded in the server and can be used in the dataflow configuration description. Note that the listed enclaves are not necessarily already listed in the DFC. This action

Access the audit log

sharemind-hi-audit --input audit.log.encrypted --key audit.key --output audit.log
Decrypts the audit log. The encrypted audit log needs to be acquired through a custom, solution specific process.