v1

Documentation

Index

• type CertQuoteResponse
• type ClientAPIServer
  • func NewServer(api handler.ClientAPI) *ClientAPIServer
  • func (s *ClientAPIServer) ManifestGet(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) ManifestPost(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) QuoteGet(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) RecoverPost(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) SecretsGet(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) SecretsPost(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) StatusGet(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) UpdateGet(w http.ResponseWriter, r *http.Request)
  • func (s *ClientAPIServer) UpdatePost(w http.ResponseWriter, r *http.Request)
• type ManifestSignatureResponse
• type RecoveryDataResponse
• type RecoveryStatusResponse
• type StatusResponse

Types

type CertQuoteResponse

type CertQuoteResponse struct {
	// A 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.
	Cert string
	// Base64-encoded quote which can be used for Remote Attestation.
	Quote []byte
}

CertQuoteResponse wraps the certificate chain and quote for the client to use for remote attestation.

type ClientAPIServer

type ClientAPIServer struct {
	// contains filtered or unexported fields
}

ClientAPIServer serves the Coordinator's v1 REST API.

func NewServer

func NewServer(api handler.ClientAPI) *ClientAPIServer

NewServer creates a new ClientAPIServer.

func (*ClientAPIServer) ManifestGet

func (s *ClientAPIServer) ManifestGet(w http.ResponseWriter, r *http.Request)

ManifestGet retrieves the currently set manifest.

Get the currently set manifest.

The endpoint returns a manifest signature as base64 encoded bytes (signed by the root ECDSA key) and a SHA-256 of the currently set manifest. Further, the manifest itself is returned as base64 encoded bytes. All returned 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 requesting the deployed manifest hash with curl:

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

Example for verifying the deployed manifest via the intermediate key signature:

# get manifest signature (signed by coordinator root key)
curl --cacert marblerun.crt "https://$MARBLERUN/manifest" | jq '.data.ManifestSignatureRootECDSA' --raw-output | base64 -d > manifest.sig
# extract root public key from coordinator certificate root
marblerun certificate root $MARBLERUN
openssl x509 -in marblerunRootCA.crt -pubkey -noout > root.pubkey
# verify signature
openssl dgst -sha256 -verify root.pubkey -signature manifest.sig manifest.json
# verification fails? try to remove newlines from manifest
awk 'NF {sub(/\r/, ""); printf "%s",$0;}' original.manifest.json  > formated.manifest.json

func (*ClientAPIServer) ManifestPost

func (s *ClientAPIServer) ManifestPost(w http.ResponseWriter, r *http.Request)

ManifestPost sets a manifest.

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"

func (*ClientAPIServer) QuoteGet

func (s *ClientAPIServer) QuoteGet(w http.ResponseWriter, r *http.Request)

QuoteGet retrieves a remote attestation quote and certificates.

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](https://download.01.org/intel-sgx/sgx-dcap/1.9/linux/docs/Intel_SGX_DCAP_ECDSA_Orientation.pdf). 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](../#/workflows/verification.md).

func (*ClientAPIServer) RecoverPost

func (s *ClientAPIServer) RecoverPost(w http.ResponseWriter, r *http.Request)

RecoverPost recovers the Coordinator.

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](../#/workflows/recover-coordinator.md) 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"

func (*ClientAPIServer) SecretsGet

func (s *ClientAPIServer) SecretsGet(w http.ResponseWriter, r *http.Request)

SecretsGet retrieves 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](../#/workflows/managing-secrets.md).

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

func (*ClientAPIServer) SecretsPost

func (s *ClientAPIServer) SecretsPost(w http.ResponseWriter, r *http.Request)

SecretsPost sets secrets.

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](../#/workflows/managing-secrets.md).

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

func (*ClientAPIServer) StatusGet

func (s *ClientAPIServer) StatusGet(w http.ResponseWriter, r *http.Request)

StatusGet retrieves the current status of the Coordinator.

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](../#/features/recovery.md). 2. Coordinator is ready to accept a manifest on [/manifest](../#/workflows/set-manifest.md). 3. Coordinator is running correctly and ready to accept marbles through the [Marble API](../#/workflows/add-service.md).

func (*ClientAPIServer) UpdateGet

func (s *ClientAPIServer) UpdateGet(w http.ResponseWriter, r *http.Request)

UpdateGet retrieves the update log.

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.

func (*ClientAPIServer) UpdatePost

func (s *ClientAPIServer) UpdatePost(w http.ResponseWriter, r *http.Request)

UpdatePost updates a specific package set in the manifest.

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](../#/workflows/update-manifest.md).

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

type ManifestSignatureResponse

type ManifestSignatureResponse struct {
	// The manifest signature - signed by the root ECDSA key.
	// example: MEYCIQCmkqOP0Jf1v5ZR0vUYNnMxmy8j9aYR3Zdemuz8EXNQ4gIhAMk6MCg00Rowilui/66tHrkETMmkPmOktMKXQqv6NmnN
	// swagger:strfmt byte
	ManifestSignatureRootECDSA []byte
	// A SHA-256 of the currently set manifest. Does not change when an update has been applied.
	// example: 3fff78e99dd9bd801e0a3a22b7f7a24a492302c4d00546d18c7f7ed6e26e95c3
	ManifestSignature string
	// The currently set manifest. Does not change when an update has been applied.
	Manifest []byte
}

ManifestSignatureResponse contains the manifest signature, a sha256 hash of the manifest, and the manifest itself.

type RecoveryDataResponse

type RecoveryDataResponse struct {
	// An array containing key-value mappings 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.
	RecoverySecrets map[string][]byte
}

RecoveryDataResponse contains RSA-encrypted AES state sealing key with public key specified by user in manifest.

type RecoveryStatusResponse

type RecoveryStatusResponse struct {
	// StatusMessage holds information about the progress of the recovery.
	StatusMessage string
}

RecoveryStatusResponse contains the status of the recovery process.

type StatusResponse

type StatusResponse struct {
	// 	A status code that matches the internal code of the Coordinator's current state.
	// example: 2
	StatusCode int
	// A descriptive status message of what the Coordinator expects the user to do in its current state.
	// example: Coordinator is ready to accept a manifest.
	StatusMessage string
}

StatusResponse is a response.