Sharemind HI Server Configuration

1. The `server.yaml` Configuration File

Relative paths are relative to the server.yaml file.

# gRPC API for regular end users.
Server:
  # See below Server Credentials section. PEM format.
  ServerCertificateFile: "server-tls.crt"
  ServerKeyFile: "server-tls.crt"
  # You can use 0 as a port. The bound-to port is written to a file.
  ListenAddress: "localhost:30000"
  # See the Certificate Setup.
  DeploymentRootCertificateFile: "sharemind-hi-project-deployment.crt"

  # By default the peer certificate is verified against the deployment root
  # certificate. If you use a gRPC-Web proxy, you need to disable this behavior
  # with "DO_NOT_REQUEST_OR_REQUIRE_OR_VERIFY".
  # RequireClientCertificate: "VerifyAgainstDeploymentCertificate"

# gRPC API for local administrators. Does not require client side
# authentication.
AdministratorServer:
  # Same as above.
  ServerCertificateFile: "server-tls.crt"
  ServerKeyFile: "server-tls.key"
  ListenAddress: "localhost:30001"

# DFC and enclaves.
Service:
  # See Dataflow Configuration.
  DataflowConfiguration: "dfc.yaml"
  # The period between automatic saves of the core and key enclave state to disk.
  # Disabled with a value equal to 0 seconds. Also see Period Syntax.
  StateSavePeriod: "1h"
  # Where to store Temporary Data.
  TemporaryPath: "/var/tmp/sharemind-hi"

  # Where to store Persistent Data.
  DataStore:
    DataPath: "/var/lib/sharemind-hi/data"
    # Uses regular POSIX file system API to access the file system.
    DataStoreType: "local"

    # Or alternatively for HDFS (Other configuration parameters are configured
    # in `hdfs-client.xml` of the current working directory):
    # DataStoreType: "hdfs"
    # HdfsNameNode: "localhost"
    # HdfsNameNodePort: 9000
    # HdfsUserName: "username"

  # See Monitoring for more information.
  # If omitted, health metrics export is disabled.
  Observability:
    MeterFactoryType: "OSTREAM_FACTORY" # or OTLP_FACTORY. NOOP_FACTORY disables.
    MeterFactoryConfiguration:
      ExportAddress: "http://YOUR_IP_ADDRESS:4318/v1/metrics"
      ExportIntervalMillis: "500"
      ExportTimeoutMillis: "250"
    TracerFactoryType: "OSTREAM_FACTORY" # or OTLP_FACTORY. NOOP_FACTORY disables.
    TracerFactoryConfiguration:
      ExportAddress: "http://YOUR_IP_ADDRESS:4318/v1/traces"
      ExportIntervalMillis: "500"
      ExportTimeoutMillis: "250"

  # Location of the Sharemind HI management enclaves.
  AttestationEnclave:
    EnclaveFile: "/usr/lib/libsharemind_hi_attestation_enclave.signed.so"
  CoreEnclave:
    EnclaveFile: "/usr/lib/libsharemind_hi_core_enclave.signed.so"
    # How many task enclaves are allows to process requests in parallel.
    # Might be relevant due to SGX EPC restrictions.
    # Note: A task enclave itself is single threaded.
    TaskThreads: 1

    # Session Expiration options, three in total. Needs to be specified for
    # each enclave separately, including task enclaves. For task enclaves
    # this effects sessions which are created by the task query action.
    # The total amount of active user sessions
    MaxActiveUserSessions: 1000
    IdleTimeout: "1h"
    AbsoluteTimeout: "24h"
  KeyEnclave:
    EnclaveFile: "/usr/lib/libsharemind_hi_key_enclave.signed.so"
  # Project-specific task enclaves which perform the actual analytics work.
  # They are referenced from the DFC through their `Name`.
  Tasks:
    - Name: "sample_task"
      EnclaveFile: "/usr/lib/libsharemind_hi_sample_task_enclave.signed.so"
    - Name: "another_task"
      EnclaveFile: "/usr/lib/libanother_task.signed.so"

# Remote attestation
Attestation:
  # For ECDSA remote attestation: ECDSA_P256
  # For EPID attestation: EPID_UNLINKABLE or EPID_LINKABLE.
  AttestationAlgorithm: "ECDSA_P256"

  # Only used for `EPID_` AttestationAlgorithm. If you need EPID attestation,
  # then contact us separately for correct configuration of this section.
  # For non-release builds you can deactivate IAS communication.
  IAS:
    ServerURL: "https://your.ias.proxy:30443/"
    # Distributed with the Sharemind HI installation, but can be downloaded from
    # https://certificates.trustedservices.intel.com/Intel_SGX_Attestation_RootCA.pem
    ReportSigningCertificateFile: "AttestationReportSigningCACert.pem"
    ReportSigningCertificateType: "PEM"
    # Your Service Provider ID, from the Intel® Commercial License (not required
    # with ECDSA attestation).
    SPID: "..."

2. Environment Variables

HI_DISABLE_IAS_COMMUNICATION=true: Only on non-release builds. When set to true, the server will skip IAS communication. This can help to test Sharemind HI or develop task enclaves without access to the IAS.

3. Server Credentials

The server requires a private key (ServerKeyFile) and a public certificate (ServerCertificateFile) to create TLS connections with the clients. Certificates from trusted CAs and self-signed certificates are both supported.

To generate a self-signed certificate with OpenSSL for localhost:

openssl genpkey -out server.key -algorithm ed25519
openssl req -new -x509 -days 365 \
    -key server.key -out server.crt \
    -subj "/CN=localhost/" -addext "subjectAltName = DNS:localhost" \
    -addext "basicConstraints = critical, CA:FALSE"

The client needs to trust some certificate in the resulting certificate chain. For self-signed certificates this means that the server certificate needs to be shared with the clients.

4. Period Syntax

A couple of options of the server.yaml and dfc.yaml configuration files specify a time value. The format is as follows:

The time units y, mo, w, d, h, m, s and ms may be used to denote year (365 days), month (30 days), week (7 days), days (24 hours), hours (60 minutes), minutes (60 seconds), seconds (1000 milliseconds) and milliseconds respectively. Multiple different units may be used at the same time, but a greater unit must never come after a lesser unit has already been used. Valid examples include "12s", "1h2m3s", " 1h 3 s " but not "1m2d".

5. Configuring task enclaves

Each task enclave specified in the Dataflow Configuration has a name. In the server configuration file under Tasks, each of these names needs to be connected to a concrete .so enclave file which the Sharemind HI Server can then load.

6. Standard Files

The standard installation bundle of the Sharemind HI Server contains a couple of files which can help you to quickly get the Sharemind HI Server up and running to test whether everything works.

/etc/sharemind-hi/server.yaml
/usr/share/sharemind-hi/server/server.yaml: An example server configuration file.
/usr/share/sharemind-hi/server/dataflow-configuration.yaml: An example dataflow configuration file.
/etc/sharemind-hi/certs/deployment.crt
/usr/share/sharemind-hi/server/deployment.crt: An example server deployment certificate for testing purposes.
/etc/sharemind-hi/certs/localhost.crt
/usr/share/sharemind-hi/server/localhost.crt: An example server certificate for testing purposes. Only works for 'localhost'.
/etc/sharemind-hi/private/localhost.key
/usr/share/sharemind-hi/server/localhost.key: An example server key for testing purposes.
/usr/share/sharemind-hi/server/cyber-isv-ca.crt: Cybernetica’s root CA certificate that is used to sign all deployment certificates.
/usr/share/sharemind-hi/server/AttestationReportSigningCACert.pem: The current remote attestation report signing certificate authority certificate. The same certificate can be downloaded from here: https://certificates.trustedservices.intel.com/Intel_SGX_Attestation_RootCA.pem