How VaultCode works

This page explains in more detail how VaultCode works conceptually. This should help you understand how VaultCode interacts with your code, how it runs your code, and how it attests to the runtime environment. For an introduction to VaultCode, see the overview.

Basics

VaultCode is a Java application that is deployed as a Docker container. Internally, it communicates with the Primus HSM over the JCE provider. Externally, it exposes a REST API that allows you to interact with VaultCode.

VaultCode should run inside a Primus HSM (otherwise, it cannot attest to the runtime environment!). VaultCode runs on top of the VaultContainers platform.

Once VaultCode is installed, you can upload your own JAR executables using the POST api/v1/upload_execution_code endpoint. To execute the JAR, call the POST api/v1/execute endpoint with the desired input.

Input and output

The JAR executables communicate with the VaultCode runtime over stdin and stdout. Therefore, your executable should read input from stdin and write output to stdout.

Running different executables

Each VaultCode instance can only run one JAR executable at a time. However, you can swap the executable by uploading a new executable. You can also run multiple VaultCode instances in parallel. The maximum number of instances varies by HSM model, as does the size of the image store.

The choice of executables that are allowed to run is security-relevant. Therefore, the executables need to be explicitly allow-listed in the VaultCode configuration files (application-xyz.yml), by:

1. Allow-listing the hash of the JAR executable, or by
2. Allow-listing a public key. Any JAR executable accompanied by a signature that can be verified with this key will be allowed.

When running VaultCode in a Primus HSM, changes to the configuration file need to be authorised by the Security Officers (SOs). Thus the SOs have control over which executables and which signing keys they want to allow.

The second option is useful if you have an existing code signing setup, and you don't want manual SO interaction for every code change. This is the recommended setup for development and CI/CD pipelines (see the loading tutorial).

Different keys

When VaultCode first starts, it generates four asymmetric key pairs on its HSM Partition. By default, they are RSA-2048 SKA keys. These keys serve the following purposes:

1. Output key: This key is used to sign the output that your executable generates. Thus when using VaultCode for automated approval, you need to add this public key as one of the approver keys to the SKA key that you want to protect.
2. Timestamp key: This key is used to sign the timestamp of an execution.
3. Evidence key: The "evidence" is the runtime environment of an execution, such as the HSM name and firmware version. This key is used to sign the evidence.
4. Encryption key: This key enables you to encrypt your JAR executable before uploading it. VaultCode then decrypts the executable using the corresponding private key.

You can obtain these keys by calling the GET /api/v1/get_public_key endpoint.