Client Configuration

1. Overview

To securely connect to a production Sharemind HI server, a stakeholder needs to meticulously configure a number of certificates and addresses.

In general, the user needs to configure their own key pair for identification, optionally a key pair for the recovery from backup procedure, server connection details, and attestation details, like enclave fingerprints. During the runtime the client will produce a state which should be persisted across invocations.

The remote attestation quote identifies the code in the enclave through a hash, which is called the fingerprint. As of now, the enclave fingerprints differ based on the operating system which runs the Sharemind HI Server. Hence you need to make sure to check the enclave fingerprints, even if they are already provided in your default configuration.

Encryption in the Sharemind HI client application is always enforced and can not be disabled by configuration. The choice of cryptographic primitives (including the set of allowed ciphers for TLS) is currently fixed to reasonably secure values and can not be configured.

The private keys of the client (both for identification and for recovery procedure) must be kept secure for the entire lifecycle of the solution and should not be lost. If a regular stakeholder loses their private key, it is possible to generate a new key pair and update the DFC, however this requires the whole DFC upgrade procedure to be completed. Stakeholders with the Enforcer role must take special care to not lose their private keys. As all enforcers have to agree to update the DFC, all of the enforcers must have access to their private key to perform the DFC upgrade. If an enforcer loses their key, upgrading the DFC becomes impossible. Similarly, if any stakeholder loses their recovery key the recovery procedure becomes impossible to complete.

2. Configuration structure

While the format used for the client configuration depends on the specific client library being used (YAML for the CLI library, JSON for the TypeScript library and a C++ struct for the C++ library), the general structure remains the same for all clients. The configuration is divided into four sections—​the client’s credentials, information about the Sharemind HI Server, enclave fingerprints, and information about the attestation service.

2.1. Client credentials

The client’s credentials always include the private key and certificate of the stakeholder, a path to a state file, and a list certificates of trusted enforcers. Optionally, it can include a recovery key pair, used for the recovery procedures.

Before the client can communicate with a production Sharemind HI deployment, they need to generate a public-cryptography key pair. Their public key certificate needs to be signed by the coordinator with the deployment keys.

The client state is used to store session information and detect any rollback attacks. Specifically, the client state contains:

  • The session key with the attestation enclave. This is used to establish communication channels with the core enclave and key enclave.

  • The last seen core enclave audit log timestamp. This is used to detect simple rollback attacks.

  • The dataflow configuration history. This is used to track the state of dataflow configuration upgrades and rollback attacks.

For clients which are input provider, output consumer, or optionally task runner, a set of trusted enforcers needs to be configured manually. The concept of trusted enforcers is required to create a link of trust between the clients who interact with the dataflow configuration and the enforcers which validate that the dataflow configuration is correctly configured. Therefore, the client needs to receive the certificates of the enforcers they trust over an authenticated communication channel, e.g. by exchanging and verifying the certificate vis-à-vis, or using the signing functionality of the Estonian ID card. At least one required trusted enforcer needs to be configured to upload or download data.

2.2. Server credentials

The server section of the client configuration only includes the address of the Sharemind HI Server, and a trusted root certificate. If the Sharemind HI server is configured to use a self-signed certificate for TLS connections, the trusted root certificate needs to point to a local copy of that certificate.

2.3. Enclave credentials

Enclave and signer fingerprints are used to verify the integrity of the secure enclaves before any data is sent over. The fingerprints of all enclaves involved in a specific solution should be provided by the coordinator during deployment.

2.4. Attestation service

The attestation service section should contain the certificate of Report Signing CA. The certificate is provided in the client packages, but it is also publicly available from Intel.