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 its public key hash, both of which can be used in the access control list of sessions.

Alternatively, an external identity can be specified for all session and CAS configuration operations using the --identity <path> parameter, where <path> must point to a file containing a PEM-encoded PKCS#8 private key followed by a X.509v3 certificate. This should be rarely necessary.

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. It takes the address of CAS and, optionally, the expected enclave measurement of a benign CAS enclave. It also ensures that the attested CAS software was signed by Scontain. If the attestation is successful, and the contacted CAS has the expected signer and optionally 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 command:

scone cas attest cas.example.com

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.

If the database encryption key was injected by the CAS owner (see CAS Database Encryption Key Injection), attestation will be refused by default, because the CAS owner is granted access to all session secrets. If this does not violate your security policy, you can attest such a CAS by adding the argument --allow-cas-owner-secret-access.

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.

Attesting Specific CAS Versions

By default, the CLI verifies that the running CAS software has the same or a newer security version (ISVSVN) as the CLI itself. There are two options to attest older or specific versions of CAS:

  • Using an enclave measurement of that version (preferred). Example:

    scone cas attest cas.example.com 0a7f2f03e98a63656868a7083aa110210d244740fa73fa455130a1f926398e9e

    Note that 0a7f2f03e98a63656868a7083aa110210d244740fa73fa455130a1f926398e9e must be replaced with the proper enclave measurement.

  • Using a specific security version (ISVSVN). Example:

    scone cas attest cas.example.com --isvsvn 42

Changing CAS Software Signer

By default, the CLI verifies that the running CAS software was signed by Scontain. Although not recommended, it is also possible to attest a CAS signed by another key, using the --mrsigner, --isvprodid and --isvsvn arguments (all are required). Example:

scone cas attest cas.example.com --mrsigner 2f46f979701db7229033ebf3f6d0ec25e7b04351de2f52269a3e6bbd32f6b192 --isvprodid 7 --isvsvn 3

Identifying CAS

For multi-CAS use-cases the mere software identity of a CAS is not sufficient to ensure the confidentiality and integrity of secrets. In these scenarios also the individual identity of the CAS instance has to be took into consideration.

Session secrets can be shared across CASes. For this, import and export statements have to contain the address and public key of the remote CAS.

As addresses (DNS entries) can be easily manipulated by the adversary, the security of inter-CAS communication is based on their cryptographic keys. Addresses are a mere help to reach a CAS.

Failure to properly identify a CAS instance opens the system to man-in-the-middle attacks where an adversary presents their CAS as legitimate remote CAS.

CASes are identified by their public keys and/or certificates. scone cas show-identification produces identification information for already attested CASes. Further, scone cas attest can take the expected public key hash of the CAS or CAS software instance with the -c and -s options.

Taken the previous example, the following command would ensure that the CAS to be attested has a specific CAS software key hash.

$ scone cas attest cas.example.com 0a7f2f03e98a63656868a7083aa110210d244740fa73fa455130a1f926398e9e -s 4USPZDGq2FjrE2wh7FEErbrirCFZcu8nR7YaSjH3NjfJtEAfCc

For secure multi-CAS scenarios the CAS identification information has to be exchanged via secure and authenticated channels between participants.

CAS provisioning and configuration

When a new CAS instance starts up for the first time, it operates in unprovisioned mode, waiting for someone to claim ownership and supply an initial configuration. This can be done through the scone cas provision command. Since scone cas attest will not work until CAS was configured, the provision command will also be used to attest the new CAS.

Example provisioning command:

scone cas provision cas.example.com -c 42ku6fcMt8fzj8br84Xg1ZmForSJDTuj6wt1pURRcYpVzJiCSL --config-file cas-config.toml --token e59a91c9dbf4538f32c4f20668bdbc08 with-attestation

The following parameters must be present (please replace the example values):

  • cas.example.com: The CAS address
  • -c 42ku6fcMt8fzj8br84Xg1ZmForSJDTuj6wt1pURRcYpVzJiCSL: The CAS key hash. It can be found on the CAS console or log. This ensures you are connected to the right CAS instance.
  • --config-file cas-config.toml: Path to the CAS configuration file in TOML, JSON or YAML format. The configuration will be uploaded to CAS after successful attestation. Please refer to the CAS configuration page regarding its content.
  • --token e59a91c9dbf4538f32c4f20668bdbc08: A Provisioning Token. It can be found on the CAS console or log. This ensures that only the rightful owner can supply a CAS configuration.
  • with-attestation: Attest the CAS. This ensures that the CAS is running in a secure enclave before transferring the confidential configuration.

Similar options as for scone cas attest can be specified. Use scone cas provision with-attestation --help for a full list of options. It is also possible to specify a custom --identity (see User Identity). Attesting a specific CAS software version is possible by appending an expected enclave measurement, like with-attestation 8acd90af546bf50277ecef0e482e478b30cb8f9a7f6f55bb35ee1beebfc65000

Once successfully provisioned,

  • the CAS will be added to the list of attested CAS instances,
  • the CAS will continue to operate with the supplied configuration,
  • and the CAS configuration can be updated later by the same user identity.

Updating the CAS configuration can be done through the scone cas update-config command:

scone cas update-config --cas cas.example.com --config-file new-cas-config.toml

Make sure to specify the same --identity that was used for scone cas provision, if any.

CAS Database Encryption Key Injection

CAS always encrypts its database. By default, a secure encryption key is generated on enclave startup. This key is bound to the executing platform/machine, and not accessible outside the enclave, protecting CAS and session secrets. It is possible to make the encryption key available to equally trustworthy CAS instances on other machines, see CAS Backup. In some scenarios, it may be necessary to inject a database key in order to allow the CAS owner to inspect the database manually. This is possible during initial CAS provisioning, using the --database-key argument. Example:

scone cas provision cas.example.com -c 42ku6fcMt8fzj8br84Xg1ZmForSJDTuj6wt1pURRcYpVzJiCSL --config-file cas-config.toml --token e59a91c9dbf4538f32c4f20668bdbc08 --database-key cfadf5e00443f15e4670e253e353dda80eac0b1295903fdc96339554a78cde0a with-attestation

Note

Replace cfadf5e00443f15e4670e253e353dda80eac0b1295903fdc96339554a78cde0a with your own key. It must be a 64-character hexadecimal string.

When specifying a database key, CAS will generate new CAS keys and create a new encrypted database. Therefore, CAS must be attested again afterwards.

Note

Database key injection negatively impacts confidentiality as it makes CAS and session secrets accessible to the CAS owner. As a precaution, database key injection will be refused when using a CAS binary signed by Scontain, and attestation of the CAS will fail unless users give consent by supplying the argument --allow-cas-owner-secret-access.

Note

Database encryption key protection relies on the trusted execution environment. This applies to both securely generated and injected keys. If running in debug mode, simulation mode or native mode, the database key will be exposed to the platform owner.

CAS Backup

SCONE improves the integrity and confidentiality of programs. However, we still depend on the availability of the underlying system. Therefore, without proper backups all data is lost in case of disaster. SGX makes the situation even worse as it uses platform/machine dependent keys to encrypt data. Therefore, one cannot extract the stored data from a SSD of a failed machine, or rather one cannot decrypt or access it.

CAS' backup feature prevents such scenarios as it enables multiple CAS on different machines to decrypt the CAS database encryption key. This works by encrypting the database encryption key individually for all CASes that are supposed to have access. Consequently, the primary CAS needs to learn about all of those CASes using a procedure we call backup registration.

To register a backup CAS, make sure you own the primary CAS (see CAS provisioning and configuration) and that both, the primary and the supposed backup CAS, are available/running (the backup CAS does not need to be provisioned) and execute the register-backup command:

scone cas register-backup backup-cas-address

If the command succeeds, the backup CAS gained access to the database. The primary CAS will accept any backup CAS with the same SGX signer identity (MRSIGNER), same SGX product ID (ISVPRODID), the same or higher SGX security version number (ISVSVN) and the same, or better SGX TCB state.

Note

At the moment, the CAS database should only be accessed by one CAS instance at a time. Otherwise, the database might be corrupted.

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 session create "sessions/my-example-session.001.yml"

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

scone 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 within all values in the session file.

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. Through --use-env, predefined environment variables can be used during substitution. 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, for instance to check the session's authenticity before exporting a secret to it. 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), check whether it matches the given session file after variable substitution, and print the session's hash. A non-zero exit code implies a mismatch.

Utility commands

Certificate key hashing

Some configuration entries, like session access control policies, allow specifying certificate public key hashes. The CLI can be used to calculate these hashes for any PEM-encoded certificate:

scone cert show-key-hash "my-certificate.pem"

Example stdout output: 3s1pm8W6Be6cxvAQRbRP5YXd9YuERAr7KswN97uGtoPkRW87x1