Coordinator client API

JSend response style

The Client API is designed as an HTTP-REST interface. Responses follow the JSend style, though only the response types success and error are returned so far.

In general, a successful API call (HTTP Code 200) will return a response in the following style:

{
    "status": "success",
    "data": {
        "ManifestSignature": "3fff78e99dd9bd801e0a3a22b7f7a24a492302c4d00546d18c7f7ed6e26e95c3"
    }
}

Depending on the API endpoint and the data submitted, data might contain a specific answer from the coordinator, or may just be null to acknowledge that the requested operation was performed successfully.

Whereas an error (HTTP Code 4xx or 5xx) might look like this:

{
    "status": "error",
    "data": null,
    "message": "server is not in expected state"
}

For errors, data will always be null, and message contains the specific error the Coordinator ran into when processing the request.

Endpoints

The API currently contains the following endpoints. If an endpoint specifies Returns for either HTTP GET or HTTP POST, it means that the specified data can be found encoded inside the data block if the response was successful. If no returns are specified for a given endpoint, or in case all possible return values for an endpoint are declared as optional, data can just be null.

/manifest

For deploying and verifying the Manifest.

  • Before deploying the application to the cluster the manifest needs to be set once by the provider
  • Users can retrieve and inspect the manifest through this endpoint before interacting with the application

Returns (HTTP GET):

Field valueTypeDescription
ManifestSignaturestringA SHA-256 of the currently set manifest. Does not change when an Update Manifest has been applied.

Returns (HTTP POST):

Field valueTypeDescription
RecoverySecretsarray (optional)An array containing key-value mapping for encrypted secrets to be used for recovering the Coordinator in case of disaster recovery. The key matches each supplied key from RecoveryKeys in the Manifest.

Example for setting the Manifest (HTTP POST):

curl --cacert marblerun.crt --data-binary @manifest.json "https://$MARBLERUN/manifest"

Example for verifying the deployed Manifest (HTTP GET):

curl --cacert marblerun.crt "https://$MARBLERUN/manifest" | jq '.data.ManifestSignature' --raw-output

/quote

For retrieving a remote attestation quote over the whole cluster and the root certificate. The quote is an SGX-DCAP quote, you can learn more about DCAP in the official Intel DCAP orientation. Both the provider and the users of the confidential application can use this endpoint to verify the integrity of the Coordinator and the cluster at any time.

Returns (HTTP GET):

Field valueTypeDescription
CertstringA PEM-encoded certificate chain containing the Coordinator’s Root CA and Intermediate CA, which can be used for trust establishment between a client and the Coordinator.
QuotestringBase64-encoded quote which can be used for Remote Attestation, as described in Verifying a deployment

Example for retrieving a quote

curl -k "https://$MARBLERUN/quote"

We provide a tool to automatically verify the quote and output the trusted certificate:

# Either install era for the current user
wget -P ~/.local/bin https://github.com/edgelesssys/era/releases/latest/download/era
chmod +x ~/.local/bin/era

# Or install it globally on your machine (requires root permissions)
sudo wget -O /usr/local/bin/era https://github.com/edgelesssys/era/releases/latest/download/era
sudo chmod +x /usr/local/bin/era

era -c coordinator-era.json -h $MARBLERUN -o marblerun.crt

 Note

On Ubuntu, ~/.local/bin is only added to PATH when the directory exists when initializing your bash environment during login. You might need to re-login after creating the directory. Also, non-default shells such as zsh do not add this path by default. Therefore, if you receive command not found: era as an error message for a local user installation, either make sure ~/.local/bin was added to your PATH successfully or simply use the machine-wide installation method.

The file coordinator-era.json contains the Packages information for the Coordinator. For our testing image this can be pulled from our GitHub releases:

wget https://github.com/edgelesssys/marblerun/releases/latest/download/coordinator-era.json

/recover

For recovering the Coordinator in case unsealing the existing state failed.

This API endpoint is only available when the coordinator is in recovery mode. Before you can use the endpoint, you need to decrypt the recovery secret which you may have received when setting the manifest initially. See Recovering the Coordinator to retrieve the recovery key needed to use this API endpoint correctly.

Example for recovering the coordinator:

curl -k -X POST --data-binary @recovery_key_decrypted "https://$MARBLERUN/recover"

/status

For returning the current state of the coordinator.

Returns (HTTP GET):

Field valueTypeDescription
StatusCodeintA status code that matches the internal code of the Coordinator’s current state.
StatusMessagestringA descriptive status message of what the Coordinator expects the user to do in its current state.

Possible values:

StatusCodeStatusMessage
1Coordinator is in recovery mode. Either upload a key to unseal the saved state, or set a new manifest. For more information on how to proceed, consult the documentation.
2Coordinator is ready to accept a manifest.
3Coordinator is running correctly and ready to accept marbles.

Example for getting the status:

curl -k "https://$MARBLERUN/status"

It may be useful to use this API endpoint and use it for other monitoring tools. More information can be found under Monitoring and Logging

/update

For updating the packages specified in the currently set Manifest.

This API endpoint only works when Admins were defined in the Manifest. For more information, look up Updating a Manifest

Example for updating the manifest:

curl --cacert marblerun.crt --cert admin_certificate.crt --key admin_private.key -w "%{http_code}" --data-binary @update_manifest.json https://$MARBLERUN/update