{"consumes":["application/json"],"produces":["application/json"],"schemes":["https"],"swagger":"2.0","info":{"description":"The Client API is designed as an HTTP-REST interface.\nResponses follow the [JSend style](https://github.com/omniti-labs/jsend), though only the response types success and error are returned so far.","title":"Coordinator Client API","version":"0.4.0"},"basePath":"/","paths":{"/manifest":{"get":{"description":"The endpoint returns a SHA-256 of the currently set manifest.\nFurther, the manifest itself is returned as base64 encoded bytes.\nBoth values do not change when an update has been applied.\n\nUsers can retrieve and inspect the manifest through this endpoint before interacting with the application.\n\nExample for verifying the deployed manifest with curl:\n\n```bash\ncurl --cacert marblerun.crt \"https://$MARBLERUN/manifest\" | jq '.data.ManifestSignature' --raw-output\n```","tags":["manifest"],"summary":"Get the currently set manifest.","operationId":"manifestGet","responses":{"200":{"$ref":"#/responses/ManifestResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}},"post":{"description":"Before deploying the application to the cluster the manifest needs to be set once by the provider.\nOn success, an array containing key-value mapping for encrypted secrets to be used for recovering the Coordinator in case of disaster recovery.\nThe key matches each supplied key from RecoveryKeys in the Manifest.\n\nExample for setting the manifest with curl:\n\n```bash\ncurl --cacert marblerun.crt --data-binary @manifest.json \"https://$MARBLERUN/manifest\"\n```","tags":["manifest"],"summary":"Set a manifest.","operationId":"manifestPost","parameters":[{"name":"Manifest","in":"body","schema":{"$ref":"#/definitions/Manifest"}}],"responses":{"200":{"$ref":"#/responses/RecoveryDataResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}},"/quote":{"get":{"description":"For retrieving a remote attestation quote over the whole cluster and the root certificate.\nThe quote is an SGX-DCAP quote, you can learn more about DCAP in the [official Intel DCAP orientation](https://download.01.org/intel-sgx/sgx-dcap/1.9/linux/docs/Intel_SGX_DCAP_ECDSA_Orientation.pdf).\nBoth 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.\n\nThe 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.\nThe quote is base64-encoded and can be used for Remote Attestation, as described in [Verifying a deployment](../#/workflows/verification.md).\n\nWe provide a tool to automatically verify the quote and output the trusted certificate:\n\n```bash\n# Either install era for the current user\nwget -P ~/.local/bin https://github.com/edgelesssys/era/releases/latest/download/era\nchmod +x ~/.local/bin/era\n\n# Or install it globally on your machine (requires root permissions)\nsudo wget -O /usr/local/bin/era https://github.com/edgelesssys/era/releases/latest/download/era\nsudo chmod +x /usr/local/bin/era\n\nera -c coordinator-era.json -h $MARBLERUN -o marblerun.crt\n```\n\n\u003e 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.\n\nThe file `coordinator-era.json` contains the [Packages](../#/workflows/define-manifest.md#manifestpackages) information for the Coordinator.\nThe example `coordinator-era.json` for our provided testing image can be downloaded from GitHub:\n\n```bash\nwget https://github.com/edgelesssys/marblerun/releases/latest/download/coordinator-era.json\n```","tags":["quote"],"summary":"Retrieve a remote attestation quote and certificates.","operationId":"quoteGet","responses":{"200":{"$ref":"#/responses/CertQuoteResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}},"/recover":{"post":{"description":"This API endpoint is only available when the coordinator is in recovery mode.\nBefore you can use the endpoint, you need to decrypt the recovery secret which you may have received when setting the manifest initially.\nSee [Recovering the Coordinator](../#/workflows/recover-coordinator.md) to retrieve the recovery key needed to use this API endpoint correctly.\n\nExample for recovering the Coordinator with curl:\n\n```bash\ncurl -k -X POST --data-binary @recovery_key_decrypted \"https://$MARBLERUN/recover\"\n```","tags":["recover"],"summary":"Recover the Coordinator when unsealing of the existing state fails.","operationId":"recoverPost","parameters":[{"name":"RecoverySecret","in":"body","schema":{"type":"array","items":{"type":"integer","format":"uint8"}}}],"responses":{"200":{"$ref":"#/responses/RecoveryStatusResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}},"/secrets":{"get":{"description":"Each requests allows specifying one or more secrets in the form of a query string, where each parameter `s` specifies one secret.\nA query string for the secrets `symmetricKeyShared` and `certShared` may look like the following:\n\n```\ns=symmetricKeyShared\u0026s=certShared\n```\n\nThis API endpoint only works when `Users` were defined in the manifest.\nThe user connects via mutual TLS using the user client certificate in the TLS Handshake.\nFor more information, look up [Managing secrets](../#/workflows/managing-secrets.md).\n\nExample for retrieving the secrets `symmetricKeyShared` and `certShared`:\n\n```bash\ncurl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key https://$MARBLERUN/secrets?s=symmetricKeyShared\u0026s=certShared\n```","tags":["secrets"],"summary":"Retrieve secrets.","operationId":"secretsGet","parameters":[{"type":"array","items":{"minItems":1,"type":"string"},"collectionFormat":"multi","name":"s","in":"query"}],"responses":{"200":{"$ref":"#/responses/SuccessResponse"},"401":{"$ref":"#/responses/ErrorResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}},"post":{"description":"Setting secrets requires uploading them in JSON format.\n\nThis API endpoint only works when `Users` were defined in the manifest.\nThe user connects via mutual TLS using the user client certificate in the TLS Handshake.\nFor more information, look up [Managing secrets](../#/workflows/managing-secrets.md).\n\nExample for setting secrets from the file `secrets.json`:\n\n```bash\ncurl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key --data-binary @secrets.json https://$MARBLERUN/secrets\n```","tags":["secrets"],"summary":"Set secrets.","operationId":"secretsPost","parameters":[{"name":"Secrets","in":"body","schema":{"type":"object","additionalProperties":{"$ref":"#/definitions/UserSecret"}}}],"responses":{"200":{"$ref":"#/responses/SecretsMapResponse"},"400":{"$ref":"#/responses/ErrorResponse"},"401":{"$ref":"#/responses/ErrorResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}},"/status":{"get":{"description":"The status indicates the current state of the coordinator, and can be one of the following:\n1. 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](../#/features/recovery.md).\n1. Coordinator is ready to accept a manifest on [/manifest](../#/workflows/set-manifest.md)\n1. Coordinator is running correctly and ready to accept marbles through the [Marble API](../#/workflows/add-service.md)","tags":["status"],"summary":"Get the current status of the Coordinator.","operationId":"statusGet","responses":{"200":{"$ref":"#/responses/StatusResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}},"/update":{"get":{"description":"Returns a structured log of all updates performed via the `/update` or `/secrets` endpoint, including timestamp, author, and affected resources.","tags":["update"],"summary":"Get a log of all performed updates.","operationId":"updateGet","responses":{"200":{"$ref":"#/responses/UpdateLogResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}},"post":{"description":"This API endpoint only works if `Users` are defined in the Manifest.\nFor more information, have a look at [updating a Manifest](../#/workflows/update-manifest.md).\n\nExample for updating the manifest with curl:\n\n```bash\ncurl --cacert marblerun.crt --cert user_certificate.crt --key user_private.key -w \"%{http_code}\" --data-binary @update_manifest.json https://$MARBLERUN/update\n```","tags":["update"],"summary":"Update a specific package set in the manifest.","operationId":"updatePost","parameters":[{"name":"Manifest","in":"body","schema":{"$ref":"#/definitions/Manifest"}}],"responses":{"200":{"$ref":"#/responses/SuccessResponse"},"400":{"$ref":"#/responses/ErrorResponse"},"500":{"$ref":"#/responses/ErrorResponse"}}}}},"definitions":{"CertQuoteResp":{"type":"object","properties":{"Cert":{"description":"A PEM-encoded certificate chain containing the Coordinator's Root CA and Intermediate CA,\nwhich can be used for trust establishment between a client and the Coordinator.","type":"string"},"Quote":{"description":"Base64-encoded quote which can be used for Remote Attestation.","type":"array","items":{"type":"integer","format":"uint8"}}}},"Certificate":{"description":"Certificate is an x509.Certificate"},"File":{"description":"File defines data, encoding type, and if data contains templates for a File or Env variable","type":"object","properties":{"Data":{"description":"Data is the data to be saved as a file or environment variable","type":"string"},"Encoding":{"description":"Encoding is the initial encoding of Data (as it is written in the manifest). One of {'string', 'base64', 'hex'}","type":"string"},"NoTemplates":{"description":"NoTemplates specifies if Data contains templates which should be filled with information by the Coordinator","type":"boolean"}}},"GeneralResponse":{"description":"GeneralResponse is a wrapper for all our REST API responses to follow the JSend style: https://github.com/omniti-labs/jsend","type":"object","properties":{"data":{"type":"object"},"message":{"type":"string"},"status":{"type":"string"}}},"InfrastructureProperties":{"description":"InfrastructureProperties contains the infrastructure-specific properties of a SGX DCAP quote","type":"object","properties":{"CPUSVN":{"description":"Processor model and firmware security version number\nNOTE: the Intel manual states that CPUSVN \"cannot be compared mathematically\"","type":"array","items":{"type":"integer","format":"uint8"}},"PCESVN":{"description":"Provisioning Certification Enclave security version number","type":"integer","format":"uint16"},"QESVN":{"description":"Quoting Enclave security version number","type":"integer","format":"uint16"},"RootCA":{"description":"Certificate of the root CA (not optional)","type":"array","items":{"type":"integer","format":"uint8"}}}},"Manifest":{"description":"Manifest defines the rules of a mesh","type":"object","properties":{"Infrastructures":{"description":"Infrastructures contains the allowed infrastructure providers and their properties.","type":"object","additionalProperties":{"$ref":"#/definitions/InfrastructureProperties"}},"Marbles":{"description":"Marbles contains the allowed services with their corresponding enclave and configuration parameters.","type":"object","additionalProperties":{"$ref":"#/definitions/Marble"}},"Packages":{"description":"Packages contains the allowed enclaves and their properties.","type":"object","additionalProperties":{"$ref":"#/definitions/PackageProperties"}},"RecoveryKeys":{"description":"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.","type":"object","additionalProperties":{"type":"string"}},"Roles":{"description":"Roles contains role definitions to manage permissions across the MarbleRun mesh","type":"object","additionalProperties":{"$ref":"#/definitions/Role"}},"Secrets":{"description":"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).","type":"object","additionalProperties":{"$ref":"#/definitions/Secret"}},"TLS":{"description":"TLS contains tags which can be assiged to Marbles to specify which connections should be elevated to TLS","type":"object","additionalProperties":{"$ref":"#/definitions/TLStag"}},"Users":{"description":"Users contains user definitions, including certificates used for authentication and permissions.","type":"object","additionalProperties":{"$ref":"#/definitions/User"}}}},"ManifestSignatureResp":{"type":"object","properties":{"Manifest":{"description":"The currently set manifest in base64 encoding. Does not change when an update has been applied.","type":"array","items":{"type":"integer","format":"uint8"}},"ManifestSignature":{"description":"A SHA-256 of the currently set manifest. Does not change when an update has been applied.","type":"string","example":"3fff78e99dd9bd801e0a3a22b7f7a24a492302c4d00546d18c7f7ed6e26e95c3"}}},"Marble":{"description":"Marble describes a service in the mesh that should be handled and verified by the Coordinator","type":"object","properties":{"MaxActivations":{"description":"MaxActivations allows to limit the number of marbles of a kind.","type":"integer","format":"uint64"},"Package":{"description":"Package references one of the allowed enclaves in the manifest.","type":"string"},"Parameters":{"$ref":"#/definitions/Parameters"},"TLS":{"description":"TLS holds a list of tags which are specified in the manifest","type":"array","items":{"type":"string"}}}},"PackageProperties":{"description":"PackageProperties contains the enclave package-specific properties of an OpenEnclave quote\nEither UniqueID or SignerID, ProductID, and SecurityVersion should be specified.","type":"object","properties":{"Debug":{"description":"Debug Flag of the Attributes","type":"boolean"},"ProductID":{"description":"Product ID of the package","type":"integer","format":"uint64"},"SecurityVersion":{"description":"Security version number of the package","type":"integer","format":"uint64"},"SignerID":{"description":"Hash of the enclave signer's public key","type":"string"},"UniqueID":{"description":"Hash of the enclave","type":"string"}}},"Parameters":{"description":"Parameters contains lists for files, environment variables and commandline arguments that should be passed to an application","type":"object","properties":{"Argv":{"type":"array","items":{"type":"string"}},"Env":{"type":"object","additionalProperties":{"$ref":"#/definitions/File"}},"Files":{"type":"object","additionalProperties":{"$ref":"#/definitions/File"}}}},"PrivateKey":{"description":"PrivateKey is a wrapper for a binary private key, which we need for type differentiation in the PEM encoding function","type":"array","items":{"type":"integer","format":"uint8"}},"PublicKey":{"description":"PublicKey is a wrapper for a binary public key, which we need for type differentiation in the PEM encoding function","type":"array","items":{"type":"integer","format":"uint8"}},"RecoveryDataResp":{"description":"RecoveryDataResp contains RSA-encrypted AES state sealing key with public key specified by user in manifest","type":"object","properties":{"RecoverySecrets":{"description":"An array containing key-value mappings for encrypted secrets to be used for recovering the Coordinator in case of disaster recovery.\nThe key matches each supplied key from RecoveryKeys in the manifest.","type":"object","additionalProperties":{"type":"string"}}}},"RecoveryStatusResp":{"type":"object","properties":{"StatusMessage":{"type":"string"}}},"Role":{"description":"Role describes a set of actions permitted for a specific set of resources","type":"object","properties":{"Actions":{"description":"Actions are the allowed actions for the defined resources","type":"array","items":{"type":"string"}},"ResourceNames":{"description":"ResourceNames is a list of names of type ResourceType","type":"array","items":{"type":"string"}},"ResourceType":{"description":"ResourceType is the type of the affected resources","type":"string"}}},"Secret":{"description":"Secret defines a structure for storing certificates \u0026 encryption keys","type":"object","properties":{"Cert":{"$ref":"#/definitions/Certificate"},"Private":{"$ref":"#/definitions/PrivateKey"},"Public":{"$ref":"#/definitions/PublicKey"},"Shared":{"type":"boolean"},"Size":{"type":"integer","format":"uint64"},"Type":{"type":"string"},"UserDefined":{"type":"boolean"},"ValidFor":{"type":"integer","format":"uint64"}}},"StatusResp":{"description":"StatusResp is a response","type":"object","properties":{"StatusCode":{"description":"A status code that matches the internal code of the Coordinator's current state.","type":"integer","format":"int64","example":2},"StatusMessage":{"description":"A descriptive status message of what the Coordinator expects the user to do in its current state.","type":"string","example":"Coordinator is ready to accept a manifest."}}},"TLSTagEntry":{"description":"TLSTagEntry describes one connection which should be elevated to ttls","type":"object","properties":{"Addr":{"type":"string"},"Cert":{"type":"string"},"DisableClientAuth":{"type":"boolean"},"Port":{"type":"string"}}},"TLStag":{"description":"TLStag describes which entries should be used to determine the ttls connections of a marble","type":"object","properties":{"Incoming":{"description":"Incoming holds a list of all incoming addresses that should be elevated to TLS","type":"array","items":{"$ref":"#/definitions/TLSTagEntry"}},"Outgoing":{"description":"Outgoing holds a list of all outgoing addresses that should be elevated to TLS","type":"array","items":{"$ref":"#/definitions/TLSTagEntry"}}}},"User":{"description":"User describes the attributes of a MarbleRun user","type":"object","properties":{"Certificate":{"description":"Certificate is the TLS certificate used by the user for authentication","type":"string"},"Roles":{"description":"Roles is a list of roles granting permissions to the user","type":"array","items":{"type":"string"}}}},"UserSecret":{"description":"UserSecret is a secret uploaded by a user","type":"object","properties":{"Cert":{"$ref":"#/definitions/Certificate"},"Key":{"type":"array","items":{"type":"integer","format":"uint8"}},"Private":{"$ref":"#/definitions/PrivateKey"}}}},"responses":{"CertQuoteResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"$ref":"#/definitions/CertQuoteResp"},"Status":{"type":"string","example":"success"}}}},"ErrorResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"type":"object"},"Message":{"type":"string","example":"InternalServerError"},"Status":{"type":"string","example":"error"}}}},"ManifestResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"$ref":"#/definitions/ManifestSignatureResp"},"Status":{"type":"string","example":"success"}}}},"RecoveryDataResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"$ref":"#/definitions/RecoveryDataResp"},"Status":{"type":"string","example":"success"}}}},"RecoveryStatusResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"$ref":"#/definitions/RecoveryStatusResp"},"Status":{"type":"string","example":"success"}}}},"SecretsMapResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"description":"A map containing key-value pairs for the requested secret.","type":"object","additionalProperties":{"$ref":"#/definitions/Secret"}},"Status":{"type":"string","example":"success"}}}},"StatusResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"$ref":"#/definitions/StatusResp"},"Status":{"type":"string","example":"success"}}}},"SuccessResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"type":"object"},"Status":{"type":"string","example":"success"}}}},"UpdateLogResponse":{"description":"","schema":{"type":"object","properties":{"Data":{"type":"string","example":"SecurityVersion increased {\"user\": \"someuser\", \"package\": \"somepackage\", \"new version\": 4}"},"Status":{"type":"string","example":"success"}}}}}}