Skip to content

SCONE CLI

The SCONE Command Line Interface (CLI) is the primary tool for interaction with the SCONE platform.

CLI State

The SCONE CLI is stateful, which means that important state, such as attestation information and identity keys, are preserved between invocations. This state is stored in a configuration file (default location: ~/.cas/config.json). Alternative locations can be used by setting the SCONE_CLI_CONFIG environment variable. The config file contains security-sensitive data and has to be protected by the user. Failure to do so will allow an attacker to impersonate the user.

User Identity

Communication with CAS is encrypted and authenticated to prevent eavesdropping and impersonation attacks. Users have to present an X.509 certificate to authenticate themselves. These certificates are also used to authorize session operations, such as reading or updating (see the documentation of the Session Description Language). For simplicity, the SCONE CLI generates a user certificate and private key on its own and stores it in the configuration file.

scone self show shows the user's certificate in PEM format, as well as a SHA256 hash of it, both of which can be used in the access control list of sessions.

CAS Trust Management

SCONE CAS is the central point of knowledge and trust in the SCONE platform. It generates and stores secrets, and establishes trust into service enclaves by attesting and provisioning them. This role and the data involved is highly security-sensitive. Therefore, trust has to be established into CAS itself before it can be used. Without this, an adversary could impersonate as CAS and collect all of your application's secrets.

scone cas attest is the central command to build trust into / attest a remote CAS. Most importantly, it takes the address of CAS and the expected enclave measurement of a benign CAS enclave. If the attestation is successful and the contacted CAS has the expected enclave measurement (its software is trusted), the CLI will store all information necessary to communicate securely with the CAS in the config file.

Example attestation process:

scone cas attest cas.example.com 0a7f2f03e98a63656868a7083aa110210d244740fa73fa455130a1f926398e9e

Note that 0a7f2f03e98a63656868a7083aa110210d244740fa73fa455130a1f926398e9e MUST be replaced with the proper enclave measurement. Additional command line switches allow relaxing the security policy, e.g. by allowing CAS to run on a machine with hyperthreading enabled (-C) or running on older, less secure SGX hardware (-G). Use scone cas attest --help for a full list of options.

The first attested CAS will be used as the default CAS when performing CAS-related operations, such as creating sessions. Multiple CASes may be attested at the same time, though. scone cas list gives an overview and scone cas set-default allows switching to another default CAS.

Session Handling

In SCONE, individual (microservice) applications security policies are described in sessions. Sessions are stored in session files - YAML-encoded descriptions of the session. The scone session commands provide verification and processing for sessions.

A very simple (empty) session file (e.g. stored in sessions/my-example-session.001.yml) could look like this:

name: "my-example-session"
version: "0.2"
predecessor: ~

The Session Description Language documentation provides details about the syntax and content of session files.

To check whether the provided file is a valid session description, one can use:

scone cas session check "sessions/my-example-session.001.yml"

The command will return a non-zero exit code when encountering a validation error.

Once the user finalized the sesson and validation passes, the session may be uploaded to a CAS, by using:

scone cas session create "sessions/my-example-session.001.yml"

This will use the default CAS. To use a specific CAS instead:

scone cas session create --cas cas.example2.com "sessions/my-example-session.001.yml"

(Note that either way, the used CAS must have been attested through scone cas attest previously, or the command will fail.)

As the complexity of sessions grows, variable substitution can be used to automate uploading of session templates (file sessions/my-example-session.002.yml):

name: "my-example-session"
version: "0.2"

services:
  - name: webservice
    command: "./nginx"
    mrenclaves: ["$NGINX_MRENCLAVE"]

Note that we use a variable, $NGINX_MRENCLAVE, as the enclave measurement for a service. Variables can be used anywhere in the session file, except for the version.

Since the session (identified by its name) was already created earlier, scone session create cannot be used a second time. Instead, the session needs to be updated:

scone cas session update -e "NGINX_MRENCLAVE=3be304015fb399cf88d76a8f58f04e16997010dab573cb1a91eb6257c2a452ac" "sessions/my-example-session.002.yml"

When updating a session, the CLI will first retrieve the currently active session from the CAS, and fill in its hash as a predecessor of the updated session. This ensures a coherent, linear and verifiable session history.

The -e switch causes variable $NGINX_MRENCLAVE to be replaced with the value 3be304015fb399cf88d76a8f58f04e16997010dab573cb1a91eb6257c2a452ac. If a variable is present in the session file but not on the command line, an error is returned, and the session is not uploaded to CAS. Variables can be used with all cas session commands. Using scone session update --help, more advanced options can be shown.

In some scenarios, it may be necessary to verify whether a session active on a CAS adheres a given policy. This can be done by using the verify CLI command:

scone cas session verify -e "NGINX_MRENCLAVE=3be304015fb399cf88d76a8f58f04e16997010dab573cb1a91eb6257c2a452ac" "sessions/my-example-session.002.yml"

The command will fetch the active session from CAS (this requires the READ permission), and check whether it matches the given session file after variable substitution. A non-zero exit code implies a mismatch.