Skip to main content
Version: 1.4

Coordinator Client API

API docs by Redocly

Coordinator Client API (0.4.0)

Download OpenAPI specification:Download

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.

manifest

Get the currently set manifest.

The endpoint returns a SHA-256 of the currently set manifest. Further, the manifest itself is returned as base64 encoded bytes. Both values do not change when an update has been applied.

Users can retrieve and inspect the manifest through this endpoint before interacting with the application.

Example for verifying the deployed manifest with curl:

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

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

Set a manifest.

Before deploying the application to the cluster the manifest needs to be set once by the provider. On success, 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 with curl:

curl --cacert marblerun.crt --data-binary @manifest.json "https://$MARBLERUN/manifest"
Request Body schema: application/json
object

Infrastructures contains the allowed infrastructure providers and their properties.

object

Marbles contains the allowed services with their corresponding enclave and configuration parameters.

object

Packages contains the allowed enclaves and their properties.

object

RecoveryKeys holds one or multiple RSA public keys to encrypt multiple secrets, which can be used to decrypt the sealed state again in case the encryption key on disk was corrupted somehow.

object

Roles contains role definitions to manage permissions across the MarbleRun mesh

object

Secrets holds user-specified secrets, which should be generated and later on stored in a marble (if not shared) or in the core (if shared).

object

TLS contains tags which can be assiged to Marbles to specify which connections should be elevated to TLS

object

Users contains user definitions, including certificates used for authentication and permissions.

Responses

Request samples

Content type
application/json
{
  • "Infrastructures": {
    },
  • "Marbles": {
    },
  • "Packages": {
    },
  • "RecoveryKeys": {
    },
  • "Roles": {
    },
  • "Secrets": {
    },
  • "TLS": {
    },
  • "Users": {
    }
}

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

quote

Retrieve a remote attestation quote and certificates.

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.

The returned certificate chain is PEM-encoded, contains the Coordinator's Root CA and Intermediate CA, and can be used for trust establishment between a client and the Coordinator. The quote is base64-encoded and can be used for Remote Attestation, as described in Verifying a deployment.

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

On Ubuntu, ~/.local/bin is added to PATH only if the directory exists when the bash environment is initialized 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. The example coordinator-era.json for our provided testing image can be downloaded from GitHub:

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

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

recover

Recover the Coordinator when unsealing of the existing state fails.

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 with curl:

curl -k -X POST --data-binary @recovery_key_decrypted "https://$MARBLERUN/recover"
Request Body schema: application/json
Array
integer <uint8>

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

secrets

Retrieve secrets.

Each requests allows specifying one or more secrets in the form of a query string, where each parameter s specifies one secret. A query string for the secrets symmetricKeyShared and certShared may look like the following:

s=symmetricKeyShared&s=certShared

This API endpoint only works when Users were defined in the manifest. The user connects via mutual TLS using the user client certificate in the TLS Handshake. For more information, look up Managing secrets.

Example for retrieving the secrets symmetricKeyShared and certShared:

curl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key https://$MARBLERUN/secrets?s=symmetricKeyShared&s=certShared
query Parameters
s
Array of strings[ items non-empty ]

Responses

Response samples

Content type
application/json
{
  • "Data": { },
  • "Status": "success"
}

Set secrets.

Setting secrets requires uploading them in JSON format.

This API endpoint only works when Users were defined in the manifest. The user connects via mutual TLS using the user client certificate in the TLS Handshake. For more information, look up Managing secrets.

Example for setting secrets from the file secrets.json:

curl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key --data-binary @secrets.json https://$MARBLERUN/secrets
Request Body schema: application/json
additional property
object (UserSecret)

UserSecret is a secret uploaded by a user

Cert
any (Certificate)

Certificate is an x509.Certificate

Key
Array of integers <uint8> [ items <uint8 > ]
Private
Array of integers <uint8> (PrivateKey) [ items <uint8 > ]

PrivateKey is a wrapper for a binary private key, which we need for type differentiation in the PEM encoding function

Responses

Request samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

status

Get the current status of the Coordinator.

The status indicates the current state of the coordinator, and can be one of the following:

  1. Coordinator is in recovery mode. Either upload a key to unseal the saved state, or set a new manifest. Waiting for user input on /recover.
  2. Coordinator is ready to accept a manifest on /manifest
  3. Coordinator is running correctly and ready to accept marbles through the Marble API

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Status": "success"
}

update

Get a log of all performed updates.

Returns a structured log of all updates performed via the /update or /secrets endpoint, including timestamp, author, and affected resources.

Responses

Response samples

Content type
application/json
{
  • "Data": "SecurityVersion increased {\"user\": \"someuser\", \"package\": \"somepackage\", \"new version\": 4}",
  • "Status": "success"
}

Update a specific package set in the manifest.

This API endpoint only works if Users are defined in the Manifest. For more information, have a look at updating a Manifest.

Example for updating the manifest with curl:

curl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key -w "%{http_code}" --data-binary @update_manifest.json https://$MARBLERUN/update
Request Body schema: application/json
object

Infrastructures contains the allowed infrastructure providers and their properties.

object

Marbles contains the allowed services with their corresponding enclave and configuration parameters.

object

Packages contains the allowed enclaves and their properties.

object

RecoveryKeys holds one or multiple RSA public keys to encrypt multiple secrets, which can be used to decrypt the sealed state again in case the encryption key on disk was corrupted somehow.

object

Roles contains role definitions to manage permissions across the MarbleRun mesh

object

Secrets holds user-specified secrets, which should be generated and later on stored in a marble (if not shared) or in the core (if shared).

object

TLS contains tags which can be assiged to Marbles to specify which connections should be elevated to TLS

object

Users contains user definitions, including certificates used for authentication and permissions.

Responses

Request samples

Content type
application/json
{
  • "Infrastructures": {
    },
  • "Marbles": {
    },
  • "Packages": {
    },
  • "RecoveryKeys": {
    },
  • "Roles": {
    },
  • "Secrets": {
    },
  • "TLS": {
    },
  • "Users": {
    }
}

Response samples

Content type
application/json
{
  • "Data": { },
  • "Status": "success"
}