Skip to content

Configuration

Due to the ability to securely operate CAS remotely, its configuration is split into two independent parts:

  • An availability configuration, supplied by the CAS operator at startup, and
  • an owner configuration, provisioned by the CAS owner at runtime.

Availability Configuration

The availability configuration encompasses file paths and network interfaces - everything that is necessary in order to start a CAS instance. The configuration is read from a TOML-formatted file.

This part of the configuration is not security-sensitive. It does not take part in remote attestation, is stored unencrypted, and can be changed by the CAS operator at any time.

Example Configuration File

[database]
path = "/etc/cas/cas.db"

[api]
api_listen = "0.0.0.0:8081"
enclave_listen = "0.0.0.0:18765"

Database

CAS stores its data in an SQLite database, the location of which is determined in by the database.path option of the configuration:

database.path = "/etc/cas/database.sqlite"

The database is always encrypted to protect the confidentiality of the contained secrets. The database encryption key is stored as cipher text in a separate file with the same filename, but ending with .key-store.

Note

Note that the key used to encrypt the database encryption key is derived using SGX' seal key derivation feature. Therefore, CAS can only decrypt the database encryption key and access the database if it is executed with the same version on the same machine which has created the .key-store file, or the key is explicitly made available to a CAS on another machine or to another version with CAS' Backup & Upgrade feature.

In particular, that means if the machine hosting CAS breaks, e.g. due to hardware failure, or is not available anymore, for example, because it was a cloud machine, access to all data stored by CAS is lost!

Security in Debug Mode

In debug mode, SGX generally does not protect your data as the debug interface exposes the enclave's memory. That means one can easily extract the database encryption key from a CAS running in SGX debug mode with our scone-gdb debugger. However, you might not be aware of this. Therefore, to counteract a false sense of security (and help debugging) CAS will dump its database encryption key anytime it does not run in production mode to the console and into a file next to the database file ending with .key.

To reiterate: this is not a security vulnerability. Any slightly invested attacker could easily extract the key with a debugger.

Interfaces

At the moment CAS offers two interfaces:

  • A client REST API with which clients can upload, upgrade and query sessions, and
  • an enclave interface with which enclaves communicate with CAS.

These configuration options will determine on which network interfaces and ports CAS will listen for incoming connection. Interfaces are defined with values satisfying std::net::SocketAddr's FromStr implementation.

The client API is configured via the api_listen option while the enclave interface is configured through the enclave_listen option:

[api]
enclave_listen = "0.0.0.0:18765"
api_listen = "0.0.0.0:8080"

Note

A configuration with an IP address of 0.0.0.0 will make the CAS listen on any available network interface.

Audit Log

[audit_log]
file_path = "/storage/cas_audit.log"

The audit log file path can be adjusted. The default path is /var/log/cas/audit/cas_audit.log. Audit logging is disabled by default, it must be enabled in the owner configuration.

Warning

If the log file cannot be written to, for example because the disk is full, all logged operations will fail and be rolled back (if audit logging is enabled). This means that most requests to CAS will fail, rendering CAS unusable until the issue is resolved.

Owner Configuration

After its initial start, a new CAS instance remains in an unprovisioned state. In this state, its functionality is severely limited until someone claims ownership and provides a configuration. Since the owner configuration contains security-sensitive information, it is necessary to attest the CAS beforehand. The configuration will be stored encrypted as part of the CAS database.

The SCONE CLI is the primary tool to manage the CAS' owner configuration:

  1. Initial provisioning: scone cas provision --config-file <...>
  2. Later configuration update: scone cas update-config --config-file <...>

Please refer to the SCONE CLI documentation for a full description. The configuration file is usually provided in TOML format.

Example Configuration File

The following file can be used for a development environment:

[api_identity]
common_name = "cas"
alt_names = ["cas", "localhost"]
country_name = "DE"
org_name = "scontain GmbH"
state_or_province = "Saxony"
locality = "Dresden"
email = "info@scontain.com"

[ias]
spid            = "E4FC1FA1A60F6A3697AAD1942742BCF4"
linkable_quotes = true
sp_key          = "251be9acabab4cc187eb7ffbaca2b291"

[dcap]
subscription_key = "00000000000000000000000000000000"

[audit_log]
mode = "signed"

API Identity

Contents of the TLS end-entity server and client certificate presented by CAS can be configured in the api_identity section:

[api_identity]
common_name = "cas"
alt_names = ["cas", "localhost"]
country_name = "DE"
org_name = "scontain GmbH"
state_or_province = "Saxony"
locality = "Dresden"
email = "info@scontain.com"

This section is not mandatory. If not specified, default values listed above will be used. In case the section is provided in the configuration file, it must contain at least common_name field.

IAS Client

The IAS client enables CAS to verify enclave EPID quotes using the Intel SGX Attestation Service (IAS). EPID quotes will be used for remote attestation of program enclaves, SCONE Quoting Enclaves, and the CAS itself. Configuring IAS credentials is optional, but one of IAS or DCAP credentials (see next section) is required in order to support remote attestation.

Its configuration consists of the Service Provider ID (SPID), linkability setting and authentication information.

  • spid has to be a 32 character or 16 byte long hex string.
  • linkable_quotes is either true or false.

Both are provided to you when you enroll with Intel's IAS.

  • base_uri is the url endpoint at which the client will query Intel's attestation service. It must start with https://. This setting is optional and will point towards the development environment endpoint of IAS by default. If you want to use an IAS production identity, you have to set the URL to https://api.trustedservices.intel.com/sgx/attestation. For Intel URLs (starting with https://api.trustedservices.intel.com/sgx), the latest API version will be used automatically (suffixes such as /v3 will be ignored). For custom URLs (e.g. proxy servers), CAS assumes the latest IAS API version supported by SCONE (currently version 4). This version may change with a future CAS update. Such a change is not considered a breaking change.

IAS is access-controlled. During registration at https://api.portal.trustedservices.intel.com/EPID-attestation you'll obtain a subscription key. This key must be specified in the sp_key field of the ias section.

Note

IAS API Rev 4.0 used X.509 certificates for authentication. This revision of the API was discontinued by Intel in September 2022 though.

[ias]
spid = "2EC5BE64E242BCC9E4670D49E5C7091E"
linkable_quotes = true
base_uri = "https://api.trustedservices.intel.com/sgx/attestation"
sp_key = "7d95b617acd1177d58579167a5cf8041"

Intel Provisioning Certification Service for ECDSA Attestation Client (DCAP)

The Intel Provisioning Certification Service for ECDSA Attestation Client enables CAS to verify DCAP quotes created by the Intel Quoting Enclave. DCAP quotes can be used as an alternative to EPID quotes for remote attestation of program enclaves and the CAS. Configuring a DCAP client credential is optional.

The configuration encompasses a subscription key. This key is provided to you when you enroll with Intel's Provisioning Certification Service.

[dcap]
subscription_key = "00000000000000000000000000000000"

Alternatively a custom PCCS service can be used. Please note that the uri must start with https://.

[dcap]
uri = "https://pccs:8081"

Audit Log

[audit_log]
mode = "signed"

Optional. Select one of the following audit log modes:

  • disabled (default) - No audit log will be created
  • unsigned - An audit log will be created, but its entries will not be signed. The log cannot be cryptographically verified. More efficient than signed.
  • signed - An audit log will be created, and its entries will be signed (recommended).
[audit_log]
sink = "file"

Optional. Select one of the following destinations that the audit log will be written to:

  • file (default) - The audit log will be written to a file (the file path is configurable in the availability configuration).

  • network - The audit log will be sent to a network server. Additional properties:

    • url (required) - URL of the log server. Each log entry will be sent as a POST request with a JSON-encoded body to the given URL.
    • server_ca_certificate (optional) - PEM-encoded X.509 (CA) certificate to authenticate the server with. If omitted, a list of default Web PKI root CA certificates will be used.

    Example:

    [audit_log]
sink = "network"
url = "https://logs.example.com/append"
server_ca_certificate = """
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
  """

    Warning

    If the log server cannot be reached, all logged operations will fail and be rolled back. This means that most requests to CAS will fail, rendering CAS unusable. This includes updating the CAS owner configuration! Therefore, make sure the configured server is available at all times.

More details about audit logging can be found in the corresponding documentation.

Database Recovery Snapshotting

Database Recovery Snapshotting instructs the CAS to regularly snapshot its database in a separate directory for disaster recovery purposes. These snapshots can be triggerger manually by sending SIGUSR1 to the CAS process (kill -USR1 "$cas_pid"). Note that this feature is supposed to protect against storage (data-loss) failures only! For protection against platform, general hardware failures, make sure to register Backup CAS instances.

Trusted Computing does not protect the availability of data. Actually, availability becomes worse as data is additionally authenticated. That is, if CAS detects that its database was modified (due to an accident or maliciously) it won't serve the database. Therefore, special care must be taken for disaster recovery and this is where Database Recovery Snapshotting helps.

Protecting against data-loss in trusted computing requires synchronization with storage that guarantees durability. This will typically happen via a network and introduces new synchronization concerns. Broadly speaking, synchronizing the CAS database files directly may lead to a corrupt database snapshot as the database is continuously modified by CAS. Database Recovery Snapshotting allows the synchronization of a consistent CAS database.

[database_snapshots]
directory = "/media/cas-db-snapshots"
interval = "5m"
  • directory: If specified, CAS will regularly create database snapshots in the given directory. Each snapshot will be created in a temporary subdirectory, and then moved to last-completed, e.g. /media/cas-db-snapshots/last-completed. The directory must exist.
  • interval: Optional. How often to create snapshots. Examples: 30s, 1m, 15m. Default: 1m

The Database Recovery Snapshotting feature will be enabled when directory is set. Each interval, CAS will copy a consistent snapshot of its database (cas.db) and database key store (cas.key-store) into a new subdirectory. If the CAS database remains unchanged, no snapshot will be created.

Warning

The Database Recovery Snapshotting feature is not a replacement for the regular CAS Backup feature! The database snapshots cannot be restored unless the machine you intend to restore it on has previously been registered as a backup target using the SCONE CLI. Database snapshots are merely a safer option than to copy the database files directly, as CAS will put the database into read-only mode when creating a snapshot, ensuring consistency of the backed up files.

Note

If snapshot creation fails, CAS will be stopped with an error and return a non-zero exit code.

Miscellaneous

  • enclave_reconnect_timeout = "24h": If an enclave lost the connection to CAS, it will attempt to reconnect (both enclave and CAS must have SCONE version 5.7.0 or later). This option configures for how long an enclave is allowed to reconnect to CAS. On reconnect, it will be attested again. For each enclave, some connection information must be stored in the CAS database - by reducing the timeout, less disk space will be used. If the timeout is 0, no enclave will be allowed to reconnect. Examples: "24h" or "40m" or "0m". The default timeout is 24h. Note: Add this option to the top of the configuration, not within other subsections.

Private Keys

We support PKCS#8 encoded private keys. By default, openssl will encode elliptic curve keys in the incompatible format specified in SEC 1: Elliptic Curve Cryptography. You can use the openssl cli to convert these keys into PKCS#8:

openssl pkcs8 -in pkey.pem -topk8 --nocrypt -out pkey.pkcs8.pem

PKCS#1-encoded private keys, e.g. key with ------BEGIN RSA PRIVATE KEY-----, can be converted into PKCS#8 with the following command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pkcs1.key -out pkcs8.key

CAS Self-Provisioning

Usually, the SCONE CLI is the primary tool to provision the CAS' owner configuration, using the scone cas provision --config-file <...> command. This command ties attestation and configuration provisioning together.

For a more streamlined CAS provisioning procedure, CAS can provision itself, eliminating the need for manual CLI interaction. This comes with certain security implications. Read these implications carefully before deciding to enable self-provisioning, especially when running CAS in production mode.

Warning

Enabling CAS self-provisioning allows attackers to compromise the confidentiality, integrity, and availability of configuration-affected services.

  • Confidentiality: The CAS owner configuration must be provided as a file in the CAS image. Attackers can read this file, and extract credentials (IAS/DCAP).
  • Integrity: Attackers can manipulate the stored configuration file, remove credentials, disable audit logging, etc. They can also manipulate the CAS owner identity (substituting it with their own).
  • Availability: By modifying the configuration file or changing the CAS owner identity, attackers can instigate Denial-of-Service attacks. They can prevent future updates of the CAS owner configuration, prevent the registration of CAS backups, prevent CAS upgrades, or prevent audit log verification.
  • Freshness: A Man-in-the-Middle attacker can present a previously provisioned CAS as a fresh CAS, as attestation is decoupled from provisioning. In addition to the availability implications listed above, this can cause sessions and secrets to be stored on an unexpected CAS.

If all of these security issues are not relevant for your particular use case, you can enable self-provisioning through the cas provision command:

cas -c "/etc/cas/availability-config.toml" provision --owner-config "/etc/cas/owner-config.toml" --skip-if-already-provisioned --owner-identity "/etc/cas/owner-certificate.pem"

This may be used as a Dockerfile CMD for images derived from the main CAS image. Ensure to ADD the relevant configuration files to the image.

Additional Configuration

Root Namespace

The session hierarchy on a CAS is not controlled by the CAS owner, but via the root namespace session. By default, anyone can create sessions on CAS. To further lock down CAS and restrict session creation, claim ownership of the root namespace session using scone session update my_root_policy.yml. For example, my_root_policy.yml could look like the following:

version: 0.3.11
name: /

access_policy:
  read: ANY
  update: CREATOR
  create_sessions: CREATOR

The example policy ensures only you can create sessions on CAS.

Note

You can only claim ownership of the root namespace session on a fresh CAS, as long as no other sessions have been created. If you did not claim ownership, the root namespace session will be sealed and become immutable once the first other session is created.