Run a JAR Executable

This tutorial shows how to trigger an execution of your JAR executable, provide a custom input, and how to retrieve and interpret the output.

Prerequisites

This tutorial assumes that you have already uploaded a JAR to VaultCode.

Trigger an Execution

To trigger an execution, call the POST /api/v1/execute endpoint and provide an input and optionally a timeout for your request.

The input must be Base64-encoded. The VaultCode runtime will provide the input to your JAR via stdin.

INPUT=$(echo -n "foo" | base64)
curl "https://demo-vaultcode.securosys.com/api/v1/execute" --json '{ "executeRequest": { "input": "'$INPUT'", "timeout": "30s" } }' > response.json

This HTTP request will block and wait for the JAR execution to finish. This command saves the response to response.json, to persist it for further processing below.

Parse the Response

The contents of response.json looks like this:

{
  "output": "SGVsbG8gZm9vClRlc3RpbmcgY29ubmVjdGlvbjogCkZhaWxlZCB0byBjb25uZWN0IHR...",
  "outputSignature": "b4+dCpr1NAapmh5nAa78JTROjbSjNRv2z1cVNW2Es+jIE48VYoRq7BCVBd...",
  "timestamp": "MIIDfTADAgEAMIIDdAYJKoZIhvcNAQcCoIIDZTCCA2ECAQMxDzANBglghkgBZQME...",
  "inputHash": "MmMyNmI0NmI2OGZmYzY4ZmY5OWI0NTNjMWQzMDQxMzQxMzQyMmQ3MDY0ODNiZmEwZjk4YTVlODg2MjY2ZTdhZQ==",
  "outputHash": "MWUwODVjNzY4YzY3NmM0ODk3ZTNkYTgwNmFiNGVlYTJmNGY3NDQ0YTIyODc3NTdmYWUwYWI3NGJhMzlkZTMxNg==",
  "executionCodeFingerprint": "8aff05709273d0e2766b26bf4a763ae6721d547bcf23789a5c204ae55ec32db1",
  "environmentInformation": "eyJydW5uaW5nSW5zaWRlSFNNIjpmYWxzZSwiZW52aXJvbm1lbnR...",
  "environmentSignature": "GSEhjKm5StCr5wrj/God1CKo385jq8REENKTgCQvLvJ15HtZY7mpp...",
  "executionCounter": {
    "counter": 4,
    "counterId": "90000122.44940987-dfda-4d59-cfe1-9df3f200d3bb.A731DB5C-58B0A148-28555D89-4440D04D"
  },
  "evidenceSignature": "gPbcurX97tl8k59VPL+jMqiBHDYLMBp5RDMBIhRjrh2t+l47OYNXNFp0..."
}

You can Base64-decode these values and process them further.

Verify the Signatures

This subsection shows how to verify the various signatures that VaultCode returns to attest to a given execution.

Verify the Output

First, we will verify the outputSignature, created by the outputKey over the output.

Start by fetching the public keys by calling GET /api/v1/get_public_key and save the JSON response to a file. Then extract the relevant public key from the JSON response.

curl --silent "https://demo-vaultcode.securosys.com/api/v1/get_public_key" > public_keys.json

cat public_keys.json | jq --raw-output ".outputKey.publicKey" | base64 -d > outputKey.der

tip

The public keys are Base64-encoded. However, they are not valid PEM, and OpenSSL won't recognize them as PEM. For example, they are missing the header and trailer. The easiest option is to use base64 -d and let OpenSSL work on the DER.

You can inspect the public key with OpenSSL:

$ openssl pkey -pubin -in outputKey.der -text -noout
Public-Key: (2048 bit)
Modulus:
    00:94:17:1f:80:1b:32:97:af:e3:fd:8c:36:c2:12:
    be:ae:b5:61:2a:82:34:36:07:8d:3c:a6:65:9c:20:
    89:c1:a5:4a:6e:21:fa:f2:98:44:fc:d0:d4:57:8f:
    90:11:0b:4f:98:9a:97:27:1d:04:a0:15:01:d2:ba:
    32:ad:4d:59:59:31:c3:15:75:22:fa:1c:e2:0c:c2:
    fe:ab:e1:d3:c1:c3:a1:08:f3:d8:84:8e:eb:a0:05:
    d6:81:e1:27:71:9e:bf:42:ef:93:66:19:20:cf:7d:
    18:06:68:16:6f:70:2b:99:9a:21:8c:1d:14:8a:a9:
    e0:26:e0:43:e8:a5:97:ff:7a:df:0c:da:94:c1:95:
    9a:fa:35:35:de:3b:27:3f:3c:44:93:11:37:6a:2d:
    03:e6:4d:d0:4b:82:ba:c1:1b:29:26:e9:69:96:ce:
    e5:46:fb:52:3f:70:1c:a4:c9:fc:75:2c:48:0d:24:
    0c:6d:8f:fc:03:e5:14:2e:a2:de:1b:3a:af:9d:1c:
    32:c7:77:c6:cb:3f:c8:73:cb:72:a1:b6:fb:bc:42:
    7f:85:39:0c:3b:91:c2:50:3e:90:5c:3d:90:6a:ad:
    5e:6e:a1:a9:cd:cf:d5:35:00:53:cd:a9:3b:97:30:
    56:c2:4e:68:9a:ee:e9:a6:49:f8:2b:c0:8f:b1:b9:
    0f:71
Exponent: 65537 (0x10001)

Extract the output value and the output signature into separate files:

cat response.json | jq --raw-output ".output" | base64 -d > output.bin
cat response.json | jq --raw-output ".outputSignature" | base64 -d > output.sig

Then verify the signature:

$ openssl dgst -sha256 -verify outputKey.der -signature output.sig output.bin
Verified OK

Verify the Environment Information

The environmentInformation can be verified via the environmentSignature, which was created by the evidenceKey. The verification steps are the same as for the output.

cat public_keys.json | jq --raw-output ".evidenceKey.publicKey" | base64 -d > evidenceKey.der

cat response.json | jq --raw-output ".environmentInformation" | base64 -d > envInfo.bin
cat response.json | jq --raw-output ".environmentSignature" | base64 -d > envInfo.sig

openssl dgst -sha256 -verify evidenceKey.der -signature envInfo.sig envInfo.bin

Verify the Evidence

The evidenceSignature is a signature over the entire response.json, but without the evidenceSignature in it.

Therefore, modify the response.json to remove the evidenceSignature and trim any trailing newlines. Encode the result as Base64. This is the value that VaultCode signed.

cat response.json | jq --raw-output --compact-output "del(.evidenceSignature)" | tr -d '\n' | base64 --wrap=0 > evidence.bin

Extract the evidenceSignature to a file:

cat response.json | jq --raw-output ".evidenceSignature" | base64 -d > evidence.sig

Verify the evidenceSignature:

openssl dgst -sha256 -verify evidenceKey.der -signature evidence.sig evidence.bin

Verify the Timestamp

The timestamp is an RFC 3161-compliant signed timestamp.