Client C++ Library

1. Introduction

The Sharemind HI Client C++ Library provides the most complete API, but it is kept minimal and offloads things like configuration and state management to the user of the library.

2. Installation

When developing the client application for Linux, it is recommended to use the sharemind-hi-create-task-enclave-project binary (from the same package). This pulls in all the necessary dependencies including the Sharemind HI Client CLI, Sharemind HI Server and CMake helpers.

The C++ library can also be used on iOS and Android. Documentation and source code is provided separately, if requested.

The following packages and files are relevant:

Package

Files

sharemind-hi-client-c++-lib

lib/libsharemind_hi_client.so

sharemind-hi-client-c++-dev

usr/include/sharemind-hi/sharemind-hi/client/Client.h
And more headers.

sharemind-hi-client-grpc-c++-lib

lib/libsharemind_hi_client_grpc.so
For communicating through gRPC with the Sharemind HI Server.

sharemind-hi-client-grpc-c++-dev

usr/include/sharemind-hi/sharemind-hi/client-grpc/GrpcChannel.h

sharemind-hi-audit-log-c++-lib

lib/libsharemind_hi_audit.so For decrypting the audit log and verifying decrypted audit log entries. Note that you also need the flatbuffers file to parse the decrypted audit log entries.

sharemind-hi-audit-log-c++-dev

usr/include/sharemind-hi/sharemind-hi/audit-log/AuditLog.h

sharemind-hi-audit-fbs-dev

usr/include/sharemind-hi/sharemind-hi/fbs/enclave_messages_audit.fbs
The flatbuffers file for parsing the decrypted audit log.

sharemind-hi-c++-cmake-helpers

lib/cmake/sharemind-hi/sharemind-hi-config.cmake
And more files.
Suggested if you want to use the C++ client library from within your CMake project.

sharemind-hi-create-task-enclave-project

bin/sharemind-hi-create-task-enclave-project
And more files.
Recommended when developing a solution.

3. CMake Integration

The following code shows how to link against the C++ client library with CMake:

# (1) Tell CMake where it can find the Sharemind HI sources.
SET(sharemind-hi_ROOT "/home/user/sharemind-hi/sim")

# (2) Search for the package.
FIND_PACKAGE(sharemind-hi REQUIRED COMPONENTS client)

# (3) Link it into your target.
TARGET_LINK_LIBRARIES(your_app PRIVATE sharemind-hi::client)

4. Operations

The sharemind_hi::client::Client class from the Client.h file provides the interface to communicate with the Sharemind HI Server. The class is initialized with a set of configuration options which resemble the configuration file of the CLI client.

// Small excerpt with the most relevant functions.
class Client {
    // Manual remote attestation
    auto redoAttestation() -> void;

    // Enforcer: Approve the DFC
    auto dataflowConfigurationApprove(…) -> void;

    // Auditor: Access the audit log
    auto auditLogDownloadKey() -> AuditLogKey;

    // Producer: Upload data
    auto dataUpload(...) -> DataId;

    // Consumer: Download data
    auto dataDownload(...) -> void;

    // Task Runner: Run the task
    auto taskRun(...) -> TaskInstance;
    auto query(...) -> QueryResponse;

    // All stakeholders: Query information about a task instance
    auto taskWait(...) -> void;
    auto taskStatus(...) -> TaskInstance;

    // ...
};

The client can be configured to either talk directly through gRPC with the server, or hand all messages to a custom callback of yours which needs to translate the message to a gRPC call in your back end. This is explained in the TunneledChannel.h header file.

The audit log can be decrypted with a function from the AuditLog.h header:

size_t decrypt(std::istream & encryptedFile,
               enclave::AuditLogKey const &,
               std::ostream & outFile,
               bool verify = true);

The header files contain more documentation.