Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update installation of CLI and QPL #466

Merged
merged 1 commit into from
Aug 21, 2023
Merged

docs: update installation of CLI and QPL #466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 89 additions & 16 deletions docs/docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Installation and setup

In this guide, you will install MarbleRun into your Kubernetes cluster and deploy a sample confidential application to demonstrate the capabilities of MarbleRun.

Installing MarbleRun is easy. First, you will install the CLI (command-line interface) onto your local machine. Using this CLI, you’ll then install the control plane onto your Kubernetes cluster.
Finally, you will add your services and set up a corresponding manifest.
To install MarbleRun into your Kubernetes cluster and manage it, there's a dedicated command-line interface (CLI).
The following guides you through the steps of installing the CLI on your machine and the configuration required to verify the [Coordinator's attestation reports](../workflows/verification.md).

## Prerequisites

Make sure the following requirements are met:

* Your machine is running Ubuntu 20.04 on an x86 (AMD64) CPU
* Your machine is running Linux on an x86-64 CPU
* You have access to a Kubernetes cluster and kubectl installed and configured

Probably the easiest way to get started is to run Kubernetes on your local machine using [minikube](https://minikube.sigs.k8s.io/docs/start/). Please check our [prerequisites](../deployment/kubernetes.md#prerequisites) if you want to set up an SGX-enabled cluster. Another easy way is to use [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), which offers SGX-enabled nodes.
An easy way to get started is to run Kubernetes on your local machine using [minikube](https://minikube.sigs.k8s.io/docs/start/).
Check the [prerequisites](../deployment/kubernetes.md#prerequisites) if you want to set up an SGX-enabled cluster.
Another easy way is to use [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), which offers SGX-enabled nodes.

You can validate your setup by running the following:

Expand All @@ -21,28 +21,58 @@ kubectl version --short
```

You should see an output with both a Client Version and a Server Version component.
Now your cluster is ready and we’ll install the MarbleRun CLI.
Now your cluster is ready and you can install the MarbleRun CLI.

## Install the MarbleRun CLI

If this is your first time running MarbleRun, you will need to download the MarbleRun command-line interface (CLI) onto your local machine. The CLI will allow you to interact with your MarbleRun deployment.
CLI executables for different platforms are available at [GitHub](https://github.com/edgelesssys/marblerun/releases).
The CLI needs an SGX [quote provider](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/DCAP_ECDSA_Orientation.pdf) to verify attestation reports.

<tabs groupId="platform">
<tabItem value="appimage" label="AppImage">

To install the CLI, run the following:
The AppImage runs on all x86-64 Linux distributions with glibc v2.29 or higher.
It includes the quote provider.
Install it with the following commands:

```bash
wget https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun-x86_64.AppImage
sudo install marblerun-x86_64.AppImage /usr/local/bin/marblerun
```

</tabItem>
<tabItem value="ub2004" label="Ubuntu 20.04">

<tabs groupId="user">
<tabItem value="current-user" label="For the current user">
Install the CLI and the quote provider with the following commands:

```bash
wget -P ~/.local/bin https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
chmod +x ~/.local/bin/marblerun
# install CLI
wget https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun-ubuntu-20.04
sudo install marblerun-ubuntu-20.04 /usr/local/bin/marblerun

# install quote provider
sudo mkdir -p /etc/apt/keyrings
wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list
sudo apt update
sudo apt install libsgx-dcap-default-qpl
```

</tabItem>
<tabItem value="global" label="Global install (requires root)">
<tabItem value="ub2204" label="Ubuntu 22.04">

Install the CLI and the quote provider with the following commands:

```bash
sudo wget -O /usr/local/bin/marblerun https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
sudo chmod +x /usr/local/bin/marblerun
# install CLI
wget https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun-ubuntu-22.04
sudo install marblerun-ubuntu-22.04 /usr/local/bin/marblerun

# install quote provider
wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list
sudo apt update
sudo apt install libsgx-dcap-default-qpl
```

</tabItem>
Expand All @@ -59,3 +89,46 @@ You can use the CLI to check if your cluster is configured to run SGX workloads:
```bash
marblerun precheck
```

## Configure the quote provider

The CLI uses the quote provider to retrieve collaterals required for verifying attestation reports.
Locate its configuration file at `/etc/sgx_default_qcnl.conf`.
If the file doesn't exist or is outdated, download it with the following command:

```bash
wget -qO- https://raw.githubusercontent.com/intel/SGXDataCenterAttestationPrimitives/master/QuoteGeneration/qpl/sgx_default_qcnl.conf | sudo tee /etc/sgx_default_qcnl.conf > /dev/null
```

You can configure the quote provider to get the collaterals from the Intel PCS, the PCCS of your cloud service provider (CSP), or your own PCCS.

### Intel PCS

Using the Intel PCS is the simplest and most generic way to get the collaterals, but it may be slower and less reliable than a PCCS.
Configure it by uncommenting the `"collateral_service"` key:

```json
,"collateral_service": "https://api.trustedservices.intel.com/sgx/certification/v4/"
```

### PCCS of your CSP

If you're running MarbleRun in the cloud, it's recommended to use the PCCS of your CSP.
Set the `"pccs_url"` value to the respective address:

* Azure: `https://global.acccache.azure.net/sgx/certification/v4/`

See the [Azure documentation](https://learn.microsoft.com/en-us/azure/security/fundamentals/trusted-hardware-identity-management#how-do-i-use-intel-qpl-with-trusted-hardware-identity-management) for more information on configuring the quote provider.

* Alibaba: `https://sgx-dcap-server.[Region-ID].aliyuncs.com/sgx/certification/v4/`

See the [Alibaba documentation](https://www.alibabacloud.com/help/en/ecs/user-guide/build-an-sgx-encrypted-computing-environment) for supported Region-ID values and more information on configuring the quote provider.

### Your own PCCS

If you're running MarbleRun on premises and have set up your own PCCS for quote generation, you can also use it for quote verification.
Set the `"pccs_url"` value to the address of your PCCS.

If your PCCS runs with a certificate not signed by a trusted CA, you need to set `"use_secure_cert"` to `false`.
This instructs the quote provider to accept a self-signed certificate of the PCCS.
It doesn't affect the security of the remote attestation process itself.
71 changes: 1 addition & 70 deletions docs/docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,6 @@
# Command Line Interface (CLI)

We provide a command-line interface (CLI) for MarbleRun.
This CLI allows you to install MarbleRun on your cluster and interacts with the control plane through the Client API for all administrative tasks in the service mesh.

## Installation

To install the MarbleRun CLI on your machine you can use our pre-built binaries.

<tabs groupId="user">
<tabItem value="current-user" label="For the current user">

```bash
wget -P ~/.local/bin https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
chmod +x ~/.local/bin/marblerun
```

</tabItem>
<tabItem value="global" label="Global install (requires root)">

```bash
sudo wget -O /usr/local/bin/marblerun https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
sudo chmod +x /usr/local/bin/marblerun
```

</tabItem>
<tabItem value="build" label="Build from source">

To build the MarbleRun CLI, [Edgeless RT](https://github.com/edgelesssys/edgelessrt) needs to be installed on your machine.

```bash
git clone https://github.com/edgelesssys/marblerun && cd ./marblerun
go build -buildvcs=false -o marblerun ./cli
```

</tabItem>
</tabs>

### Requirements

The CLI requires an SGX quote verification library to verify quotes issued by the Coordinator.
You have different options depending on the environment the Coordinator is deployed to:

<tabs groupId="environement">
<tabItem value="azure" label="Azure CVM">

If the Coordinator is running on an Azure VM, the CLI relies on the [Azure DCAP Client](https://github.com/microsoft/Azure-DCAP-Client) to verify quotes.
To install the dependency on Ubuntu 20.04 run:

```bash
sudo apt-key adv --fetch-keys https://packages.microsoft.com/keys/microsoft.asc
sudo add-apt-repository 'deb [arch=amd64] https://packages.microsoft.com/ubuntu/20.04/prod focal main'
sudo apt update
sudo apt install -y az-dcap-client
```

</tabItem>
<tabItem value="generic" label="Generic SGX system">

Intel provides the `libsgx-dcap-default-qpl` library to facilitate SGX quote verification.
To install the dependency on Ubuntu 20.04 run:

```bash
sudo apt-key adv --fetch-keys https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo add-apt-repository 'https://download.01.org/intel-sgx/sgx_repo/ubuntu main'
sudo apt update
sudo apt install -y libsgx-dcap-default-qpl
```

Follow [Intel's documentation](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/qpl/README.md#configuration) to configure access to the PCCS.
</tabItem>
</tabs>
The MarbleRun CLI allows you to install MarbleRun on your cluster and interacts with the control plane through the Client API for all administrative tasks in the service mesh.

## Reference

Expand Down
43 changes: 1 addition & 42 deletions docs/docs/workflows/verification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,48 +4,7 @@ MarbleRun provides a simple HTTP REST API for clients to verify the confidential

## Requirements

Verifying remote attestation quotes doesn't require an SGX capable machine, however, quote provider libraries are still necessary to perform remote attestation.

### Azure QPL

If the quote was generated on Azure infrastructure, all you need is the [Azure-DCAP-Client](https://github.com/microsoft/Azure-DCAP-Client). It's already configured to connect to the correct Azure-provided [Provisioning Certificate Caching Service (PCCS)](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/DCAP_ECDSA_Orientation.pdf) endpoints.

You can install it via Microsoft's Ubuntu package repository:

```bash
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add
sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/ubuntu/`lsb_release -rs`/prod `lsb_release -cs` main"
sudo apt install az-dcap-client
```

### Intel QPL

Otherwise, you can use the [Intel DCAP Quote Provider Library](https://github.com/intel/SGXDataCenterAttestationPrimitives/tree/master/QuoteGeneration/qpl).
You can install the library via Intel's Ubuntu package repository:
```bash
# Add the repository and key
wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu bionic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
# Install the qpl
sudo apt install libsgx-dcap-default-qpl
```

Our tools build on [OpenEnclave](https://github.com/openenclave/openenclave) for quote verification, which expects the QPL as `libdcap_quoteprov.so`.
We need to create a link to Intel's library:
```bash
cd /usr/lib/x86_64-linux-gnu/
sudo ln -s libdcap_quoteprov.so.1 libdcap_quoteprov.so
```

To make sure the QPL connects to the correct PCCS we need to edit the [configuration](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/qpl/README.md#configuration) in `/etc/sgx_default_qcnl.conf`.
```
# PCCS server address
PCCS_URL=<YOUR_PCCS_URL>
# To accept insecure HTTPS cert, set this option to FALSE
USE_SECURE_CERT=<TRUE/FALSE>
```


You need to [install and configure a quote provider](../getting-started/installation.md#install-the-marblerun-cli).

## Establishing trust in the Coordinator

Expand Down
2 changes: 2 additions & 0 deletions docs/styles/Vocab/edgeless/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Dockerfile
emojivoto
Env
Equinix
glibc
[Gg]ramine
hardcode
helloworld
Expand All @@ -34,6 +35,7 @@ subcommand
Tensorflow
toleration
toolchain
uncomment
updatable
vSphere
VM
Expand Down
71 changes: 1 addition & 70 deletions hack/clidocgen/header.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,6 @@
# Command Line Interface (CLI)

We provide a command-line interface (CLI) for MarbleRun.
This CLI allows you to install MarbleRun on your cluster and interacts with the control plane through the Client API for all administrative tasks in the service mesh.

## Installation

To install the MarbleRun CLI on your machine you can use our pre-built binaries.

<tabs groupId="user">
<tabItem value="current-user" label="For the current user">

```bash
wget -P ~/.local/bin https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
chmod +x ~/.local/bin/marblerun
```

</tabItem>
<tabItem value="global" label="Global install (requires root)">

```bash
sudo wget -O /usr/local/bin/marblerun https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
sudo chmod +x /usr/local/bin/marblerun
```

</tabItem>
<tabItem value="build" label="Build from source">

To build the MarbleRun CLI, [Edgeless RT](https://github.com/edgelesssys/edgelessrt) needs to be installed on your machine.

```bash
git clone https://github.com/edgelesssys/marblerun && cd ./marblerun
go build -buildvcs=false -o marblerun ./cli
```

</tabItem>
</tabs>

### Requirements

The CLI requires an SGX quote verification library to verify quotes issued by the Coordinator.
You have different options depending on the environment the Coordinator is deployed to:

<tabs groupId="environement">
<tabItem value="azure" label="Azure CVM">

If the Coordinator is running on an Azure VM, the CLI relies on the [Azure DCAP Client](https://github.com/microsoft/Azure-DCAP-Client) to verify quotes.
To install the dependency on Ubuntu 20.04 run:

```bash
sudo apt-key adv --fetch-keys https://packages.microsoft.com/keys/microsoft.asc
sudo add-apt-repository 'deb [arch=amd64] https://packages.microsoft.com/ubuntu/20.04/prod focal main'
sudo apt update
sudo apt install -y az-dcap-client
```

</tabItem>
<tabItem value="generic" label="Generic SGX system">

Intel provides the `libsgx-dcap-default-qpl` library to facilitate SGX quote verification.
To install the dependency on Ubuntu 20.04 run:

```bash
sudo apt-key adv --fetch-keys https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo add-apt-repository 'https://download.01.org/intel-sgx/sgx_repo/ubuntu main'
sudo apt update
sudo apt install -y libsgx-dcap-default-qpl
```

Follow [Intel's documentation](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/qpl/README.md#configuration) to configure access to the PCCS.
</tabItem>
</tabs>
The MarbleRun CLI allows you to install MarbleRun on your cluster and interacts with the control plane through the Client API for all administrative tasks in the service mesh.

## Reference

Expand Down