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.

Additionally, the CLI maintains a separate signer identity that is used for session signing.

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, or refer to the CLI Reference 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. Attestation becomes less reliable in this case, as the CAS' owner can extract CAS' secret keys and impersonate the CAS or spoof another CAS version.

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 (MRENCLAVE) of that version (preferred). Example:

    scone cas attest cas.example.com --mrenclave 6C8BFEAF1861072F8EA44F41D475ABBADA2D3D4A83492FBB7CF3A63840E61EB8

    Note that 6C8BFEAF1861072F8EA44F41D475ABBADA2D3D4A83492FBB7CF3A63840E61EB8 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 cryptographic key hash. It can be found on the CAS console or log. This ensures that the CLI will only connect to the intended CAS instance.
  • --config-file cas-config.toml: Path to the CAS Owner 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. The token is a nonce generated by CAS that must only be known by the rightful owner. CAS will only accept configurations from entities that also supply the correct token. 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.

Note

During provisioning the CLI utilizes the attestation configuration found in the CAS owner configuration file. Therefore, provisioning will fail if the platform on which CAS is running does not support the configured method (EPID/IAS or DCAP).

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 must not be provisioned). Then 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 more secure SGX TCB state. Registering a CAS in SGX debug mode with a CAS in SGX production mode, or vice versa, is not allowed as this could be used to undermine CAS security goals.

Note

If necessary, platforms with a less secure TCB can be registered by specifying some of the --accept-configuration-needed, --accept-sw-hardening-needed and --accept-group-out-of-date flags. Please only use these flags when the initial registration attempt fails, and it is not possible to update the TCB. Updating the TCB, e.g. by installing a newer CPU microcode patch level using a firmware update, should always be preferred.

Warning

The CAS backup feature only makes the database encryption key available to multiple platforms, it does not replace regular file-based backups. Please remember to back up the CAS database and its associated .key-store file regularly.

Warning

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

Note

CAS versions prior to 5.6.0 only supported EPID/IAS-based attestation when registering backups and upgrades. Starting with version 5.6.0, DCAP attestation is supported too. Note that by switching from EPID to DCAP, or vice-versa, a different TCB status can be reported by Intel. In this case, it may be necessary to ignore the reported TCB problems by using one of the --accept-... flags listed above.

CAS Upgrade

Similar to a CAS on a different machine, an updated CAS with a newer software version cannot access the database directly. Instead, the database encryption key must be made available explicitly. If the update is a security update, more steps are necessary. A description of the process follows:

  1. Start the new CAS version while the old version is still running.

  2. Register the new CAS: scone cas register-upgrade updated-cas-address. Please use the CLI version that matches the version of the old CAS to ensure compatibility. The output shows whether additional upgrade steps are required.

    Note

    If you're upgrading from SCONE version 5.0.0, please use scone cas register-backup updated-cas-address to register the upgraded CAS. The register-upgrade command was only added in SCONE version 5.1.0. Note that this is only necessary when upgrading from SCONE version 5.0.0. Upgrading other versions will fail if done via register-backup.

  3. Please repeat steps 1 & 2 for all previously registered backup CASes. Otherwise, all data will be unrecoverably lost when the primary CAS fails after an upgrade.

  4. If (and only if) the output of step 2 has shown that an additional upgrade step was required, run scone cas start-upgrade. This will perform a CAS database encryption key rollover. Depending on the database size, this may take a while to complete. The CAS is put into read-only mode for this purpose - creating new sessions, updating existing sessions or changing configuration will not be possible until the upgrade completes.

  5. Stop the old CAS, then start the new CAS afterwards, completing the upgrade process.

    Note

    During the upgrade, CAS may create database and key store backup files to roll back to in case the upgrade is interrupted (see next section). These files are located next to the main database file and have an extension similar to .pre-upgrade-<new_isvsvn>. After sufficient time has passed, and if the new CAS version does not show any problems, these backup files can be safely deleted.

Recovering from a Failed Upgrade

If CAS is interrupted during the upgrade procedure, e.g. due to a VM or container shutdown, continue the process at the point of failure, repeating the last step. If, for example, CAS was terminated while running scone cas start-upgrade, start the old CAS and run scone cas start-upgrade again, then continue as usual.

In some situations it may be possible that the new CAS version does not start, showing an error similar to:

CAS aborted: Error: Creation of CAS backend failed
Caused by: Could not load database key store from /etc/cas/cas.key-store
Caused by: Failed to access key material
Caused by: The current enclave does not have access to the key
Error 1 of 3: The key does not belong to the current enclave
...

This may happen if scone cas register-upgrade failed or did not run at all. To resolve the issue, simply start the old CAS and repeat scone cas register-upgrade updated-cas-address. You do not have to run scone cas start-upgrade again if it already completed successfully!

If the old CAS is stuck in read-only mode and registration of the new CAS is not possible for some reason, the upgrade can be cancelled. To do so:

  1. Stop all CAS instances
  2. Locate the CAS database file (e.g. /etc/cas/cas.db). Delete the file ending with .upgrade, e.g. cas.db.upgrade.
  3. Start the old CAS version again. The read-only mode will be lifted.

After a successful upgrade, the old CAS version will not be able to access the database anymore. However, CAS creates backups of the old database and key store. The backup files are located in the same directory as the originals, and have an extension like .pre-upgrade-<new_isvsvn>. In case the new CAS does not behave as expected, these backup files can be restored to their original locations (by removing the .pre-upgrade extension, replacing the upgraded files) and CAS rolled back to the old version. Note that any changes performed using the new CAS version will be lost.

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 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 session 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.)

Note

scone session create uses the CLI's user identity. This identity is applied as session creator during session upload.

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, it cannot be created a second time. Instead, the session needs to be updated:

scone 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.

Note

Please refer to Ensuring a Coherent Session History below on considerations when not to use scone session update!

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 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.

Ensuring a Coherent Session History

Since each session contains a hash of its predecessor, there will always be a linear and verifiable session history.

Note, however, that in the last section we use the scone session update command to update an existing session. This will automatically fill in the predecessor field for us, fetching the hash of the currently active session from CAS in the process.

This poses two problems:

  • Risk of lost updates - if someone else had updated the session in the meantime, we would not notice and overwrite their changes. (Note: Of course, they need to be authorized to update the session in the first place)
  • Using scone session update requires the session READ permission

Those problems can be circumvented by:

  1. Filling in the session's predecessor field manually before upload, and
  2. Using scone session create instead of scone session update

Note

scone session create will update a session instead of creating a new session, if the session has a predecessor field set.

The predecessor field must contain the hash of the old session. The following options exist to obtain a session's hash using the SCONE CLI:

  • The hash is printed upon successful scone session create, scone session update, and scone session verify invocations
  • The hash can be calculated offline using scone session calculate-hash (but be aware of session creator implications)

Signed Sessions

The commands used before, like scone session create, assume a direct connection between users and CAS, i.e., they operate online.

CAS may also be running offline or air-gapped, i.e. not directly reachable over the Internet. For these use cases, sessions may be authored remotely, and later on uploaded on-site by an administrator on behalf of the author.

To ensure session integrity, sessions can be signed, such that they cannot be manipulated by the administrator. A recommended workflow would be:

  1. Write the first session YAML file (my_session_v1.yml). The session should be located in a trustworthy namespace. Set the read access policy to NONE.
  2. Sign the session: scone session sign my_session_v1.yml > my_signed_session_v1.json
  3. Forward the signed session to the administrator. They can upload the session to CAS using scone session create my_signed_session_v1.json

Updating a signed session works in a similar way, however, you need to fill in the predecessor field manually:

  1. Run scone session calculate-hash my_signed_session_v1.json
  2. Write the updated session YAML file (my_session_v2.yml). Set predecessor: <hash>, where <hash> is the output obtained in step 1.
  3. Sign the session: scone session sign my_session_v2.yml > my_signed_session_v2.json
  4. Forward the signed session to the administrator. They can upload the session to CAS using scone session create my_signed_session_v2.json

Be aware of the following limitations when using signed sessions:

  • Signed sessions are not confidential. Do not insert secret values in signed sessions. Use encrypted sessions if confidentiality is important.
  • There is no way to receive a confirmation whether a session was successfully deployed by the administrator.
  • Integrity protection can only be guaranteed when signatures are enforced through a signer entry in an update or create_sessions access policy of a predecessor session or namespace.

Session Encryption

Signed sessions ensure integrity, but do not provide confidentiality when being forwarded to an offline CAS. To protect secret values, signed sessions can additionally be encrypted.

Prerequisites for session encryption:

  • You are using signed sessions
  • A CAS (version 5.8.0 or later) must have been attested

Encrypting a session:

scone session encrypt "my_signed_session_v1.json" > "my_encrypted_session_v1.json"

The above command will encrypt the session for the default CAS. In case it should be encrypted for a different CAS, use the --cas parameter (e.g. scone session encrypt "my_signed_session_v1.json" --cas "secondary-cas.example.com").

An encrypted session can only be decrypted by the intended CAS, and only by the CAS version that was attested. If the CAS is being upgraded, its encryption key changes, and it must be attested again in order to continue to use session encryption.

A recommended workflow is to:

  1. Sign a session
  2. Encrypt the signed session
  3. Forward the encrypted session to the administrator. They can upload the session to CAS using scone session create my_encrypted_session_v1.json

Note

It is possible to encrypt a regular (unsigned) session directly. Doing so will automatically sign the session. It is recommended to sign the session manually beforehand though, because utility commands, such as scone session check or scone session calculate-hash, do not work for encrypted sessions - they do work for signed sessions though.

Be aware of the following limitations when using encrypted sessions:

  • There is no way to receive a confirmation whether a session was successfully deployed by the administrator.
  • As for signed sessions, integrity protection can only be guaranteed when signatures are enforced through a signer entry in an update or create_sessions access policy of a predecessor session or namespace.
  • Sessions that were encrypted for an old CAS version cannot be decrypted after a CAS upgrade. The upgraded CAS must be attested again, and the (unencrypted) signed session must be encrypted again.
  • Encrypted sessions can only be decrypted and read by the CAS that was chosen during encryption. It is not possible to use utility commands such as scone session check/verify/calculate-hash on encrypted sessions.

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