Skip to content

Commit

Permalink
Merge pull request #26 from ruomengh/doc
Browse files Browse the repository at this point in the history 
Update README files
  • Loading branch information
@wenhuizhang
wenhuizhang authored Mar 29, 2024
2 parents c82ff56 + 261b937 commit c591208
Show file tree
Hide file tree
Showing 6 changed files with 185 additions and 344 deletions.
82 changes: 17 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,86 +10,37 @@
![CC Foundation Image Customize](https://github.com/intel/confidential-cloud-native-primitives/actions/workflows/image-rewriter.yaml/badge.svg)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8325/badge)](https://www.bestpractices.dev/projects/8325)

## 1. Introduction
## Introduction

Confidential Computing technologies like Intel® TDX provides an isolated encryption runtime
environment to protect data-in-use based on hardware Trusted Execution Environment (TEE).
It requires a full chain integrity measurement on the launch-time or runtime environment
to guarantee "consistent behavior in an expected way" of confidential
computing environment for tenant's zero-trust use case.

This project is designed to provide cloud native measurement for the full measurement
chain from TEE TCB -> Firmware TCB -> Guest OS TCB -> Cloud Native TCB as follows:

![](/docs/cc-full-meaurement-chain.png)
## How to Install CCNP

_NOTE: Different from traditional trusted computing on non-confidential environment,
the measurement chain is not only started with Guest's `SRTM` (Static Root Of Measurement)
but it also needs to include the TEE TCB because the CC VM environment is created by TEE
via `DRTM` (Dynamic Root of Measurement) like Intel® TXT on the host._
### Configuration

From the perspective of a tenant's workload, `CCNP` will expose the [CC Trusted API](https://github.com/cc-api/cc-trusted-api)
as the unified interfaces across diverse trusted foundations like `RTMR+MRTD+CCEL`
and `PCR+TPM2`. Learn more details of CCNP design at [CCNP documentation](https://intel.github.io/confidential-cloud-native-primitives/).

![](/docs/ccnp-architecture-high-level.png)

Finally, the full trusted chain will be measured into a CC report as follows using Intel TDX as an example:

![](/docs/cc-full-measurement-tdreport.png)

_NOTE:_

- The measurement of TEE, Guest's boot, OS is per CC VM, but cluster/container measurement
might be per cluster/namespace/container for cloud native architecture.
- Please refer to structure [`TDREPORT`](https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandard/Tdx.h).
- The CCNP project collects container level primitives by implementing unified APIs defined in [CC Trusted API](https://github.com/cc-api/cc-trusted-api). The project will be moved to [CC Trusted API](https://github.com/cc-api/cc-trusted-api) in the near future.


## 2. Installation

### 2.1 Configuration for Host and Guest for Host and Guest

CCNP collects primitives of confidential cloud native environments running in confidential VMs (CVM), such as Intel TDX guest. The primitives are not only from the TEE + CVM boot process + CVM OS but also from the environments running workloads, e.g. Kubernetes cluster or Docker containers. Thus, you need to check below configuration for both hosts and guests.

You can setup an Intel TDX enlightened host and then boot a TD guest on it. The feasible configurations are as below.
CCNP runs on Intel TDX guest. Thus, you will need TDX host and guest for CCNP deployment and usage. Please see below recommended configuration.

| CPU | Host OS | Host packages | Guest OS | Guest packages | Attestation packages |
|---|---|---|---|---|---|
| Intel® Emerald Rapids | Ubuntu 22.04| Build packages referring to [here](https://github.com/intel/tdx-tools/tree/tdx-1.5/build/ubuntu-22.04) | Ubuntu 22.04 | Build packages referring to [here](https://github.com/intel/tdx-tools/tree/tdx-1.5/build/ubuntu-22.04) | You can either use containerized [PCCS](https://github.com/intel/confidential-cloud-native-primitives/tree/main/container/pccs), [QGS](https://github.com/intel/confidential-cloud-native-primitives/tree/main/container/qgs) or install packages from [here](https://download.01.org/intel-sgx/sgx-dcap/1.19/linux/distro/ubuntu22.04-server/)
| Intel® Emerald Rapids | Ubuntu 23.10 | Setup TDX host referring to [here](https://github.com/canonical/tdx) | Ubuntu 22.04 | Build packages referring to [here](https://github.com/intel/tdx-tools/tree/tdx-1.5/build/ubuntu-22.04)| Setup containerized [PCCS](https://github.com/intel/confidential-cloud-native-primitives/tree/main/container/pccs) and [QGS](https://github.com/intel/confidential-cloud-native-primitives/tree/main/container/qgs) on the host |

_NOTE: The Platform certificate caching service (PCCS) is used to retrieve and cache PCK certificates locally to your cluster from Intel's Platform Certificate Service. This is necessary to attest the authenticity of a TD guest before a workload is started in it. The Quote Generate Service (QGS) runs on the host in a specialized enclave to generate and use TD quotes. For convenient setup these can run inside a Docker container. Learn more at https://download.01.org/intel-sgx/sgx-dcap/1.17/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf. The PCCS and QGS are used to get Quote for a TD guest. They need to be installed on TDX hosts._

### 2.2 Deploy CCNP Services in Confidential VM

_NOTE: the following installation will be performed in a confidential VM. Make sure you have confidential VM booted before moving forward._

It supports to deploy CCNP services as DaemonSets in Kubernetes cluster or docker containers on a single confidential VM. Please refer to below guides for different deployment environments.
| Intel® Emerald Rapids | Ubuntu 23.10| TDX early preview referring to [here](https://github.com/canonical/tdx) | Ubuntu 23.10 | Build guest image using [CVM image rewriter](/tools/cvm-image-rewriter/README.md) | Install PCCS and QGS on host from [here](https://download.01.org/intel-sgx/sgx-dcap/1.20/linux/distro/ubuntu23.10-server/)

- [CCNP deployment guide - K8S](deployment/README.md): on confidential VM node of Kubernetes cluster.
_NOTE: The Platform certificate caching service (PCCS) is used to retrieve and cache PCK certificates locally to your cluster from Intel's Platform Certificate Service. This is necessary to attest the authenticity of a TD guest before a workload is started in it. The Quote Generate Service (QGS) runs on the host in a specialized enclave to generate and use TD quotes. For convenient setup these can run inside a Docker container. Learn more at [here]( https://download.01.org/intel-sgx/sgx-dcap/1.17/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf). The PCCS and QGS are used to get Quote for a TD guest. They need to be installed on TDX hosts._

- [CCNP deployment guide - Docker](deployment/README.md): on confidential VM using docker compose.
### CCNP Service Deployment in Confidential VM

### 2.3 Install SDK
It supports to deploy CCNP services as DaemonSets in Kubernetes cluster or docker containers on a single confidential VM. Please refer to [CCNP deployment guide](deployment/README.md).

CCNP SDK can be used by a workload for cloud native primitives collecting. It needs to be installed within the workload container image and called whenever the primitives are required. For example, in your workload written in Python, you can install the SDK from PyPI using the command:
### CCNP SDK Usage

```
pip install ccnp
```
[ccnp_example.py](/container/ccnp-example/ccnp_example.py) is an example of using CCNP Python SDK. There are also Golang SDK and Rust SDK. Please see more details in [CCNP SDK](https://intel.github.io/confidential-cloud-native-primitives/_rst/modules.html#ccnp-sdk).

Alternatively, the CCNP can be installed from source code with the following command. Make sure to clone the repository into your confidential VM and then run the following command:

```
cd sdk/python3
pip install -e .
```

### 2.4 Install CCNP Device Plugin
Follow the CCNP device plugin [Installation Guide](device-plugin/ccnp-device-plugin/README.md).

## 3. Contributing
## Contributing

This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have the
Expand All @@ -104,23 +55,24 @@ once across all repos using our CLA.
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on building, testing, and contributing
to these libraries.

## 4. Provide Feedback
## Provide Feedback

If you encounter any bugs or have suggestions, please file an issue in the Issues
section of the project.

_Note: This is pre-production software. As such, it may be substantially modified as updated versions are made available._

_Note: This is pre-production software and, as such, it may be substantially modified as updated versions are made available._

## 5. Reference
## Reference

[Trusted Computing](https://en.wikipedia.org/wiki/Trusted_Computing)

[TCG PC Client Platform TPM Profile Specification](https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/)

[TCG PC Client Platform Firmware Profile Specification](https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/)

## 6. Contributors
[CCNP Design and Architecture](https://intel.github.io/confidential-cloud-native-primitives/)

## Contributors

<!-- spell-checker: disable -->

Expand Down
66 changes: 50 additions & 16 deletions deployment/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,56 @@

CCNP is designed for collecting confidential computing primitives in cloud native environments. It can run as DaemonSet in a Kubernetes cluster or containers in a Docker environment on confidential virtual machines, such as Intel TDX guest(TD).

## Create TD
## Build CCNP Kernel

Before moving forward, please make sure you have a TD booted. The CCNP service installation will happen in the TD.
Run [build.sh](../tools/build/build.sh) to build kernel packages for CCNP. It's recommended to run the tool on TDX host mentioned in [Configuration](../README.md#configuration).

You can use [cvm image rewriter](../tools/cvm-image-rewriter/README.md) to prepare a TD enlightened guest image.
It will generate a `output` folder including kernel packages. The folder will be used in the next step.
```
$ cd tools/build
$ sudo ./build.sh
```

**NOTE:**
- If your initial guest image already has a TDX kernel, it's required to run [plugin](../tools/cvm-image-rewriter/plugins/) 07, 08 and 09 to set device access permission.
- If your initial guest image is a normal Ubuntu guest image, it's required to run [plugin](../tools/cvm-image-rewriter/plugins/) 06 to install TDX kernel and then 07, 08, 09 to set device access permission.

- CCNP kernel patches are at [kernel](../tools/build/kernel/)
- The tool should be run on a Ubuntu 23.10 TDX host with TDX early preview packages installed. Please refer to [here](https://github.com/canonical/tdx)


## Prepare TDX guest image

Run [cvm image rewriter](../tools/cvm-image-rewriter/README.md) to prepare a TDX guest image for CCNP deployment. The default user name is `tdx`. The password is `123456`.

It's recommended to run the tool on TDX host mentioned in [Configuration](../README.md#configuration).

A quick start is as below.

```
# Download Ubuntu 23.10 cloud image (Skip this step if you already has an initial guest image.)
$ wget https://cloud-images.ubuntu.com/mantic/current/mantic-server-cloudimg-amd64.img
# Set file path of the generated output folder above. Plugin 06 will install the kernel in the guest image.
$ export CVM_TDX_GUEST_REPO=<path to above output folder>
# Set image size
$ export GUEST_SIZE=<image size>G
# Run CVM image rewriter to configure a TDX guest image for CCNP
$ cd tools/cvm-image-rewriter
$ ./run.sh -i <mantic-server-cloudimg-amd64.img or your initial guest image> -t <timeout in minutes, suggest to set to 15>
```

**NOTE:**
- By default all the plugins will be executed. Generate a `NOT_RUN` file under the specific plugin folder if you want to skip it.
- It's required to run [plugin](../tools/cvm-image-rewriter/plugins/) 06, 07, 08, 09 for CCNP.


## Create a TD

Start a TD using [qemu-test.sh](../tools/cvm-image-rewriter/qemu-test.sh) or [start-virt.sh](../tools/cvm-image-rewriter/start-virt.sh).

- Use `qemu-test.sh`, please use `-q <vsock/tdvmcall>` to make sure get quote works for the TD.
- Use `qemu-test.sh`, please use `-q <vsock>` to make sure get quote works for the TD.
```
$ sudo ./qemu-test.sh -i output.qcow2 -t td -p <qemu monitor port> -f <ssh_forward port> -q tdvmcall
$ sudo ./qemu-test.sh -i output.qcow2 -q vsock
```
- Use `start-virt.sh`. The Libvirt XML template is [tdx-libvirt-ubuntu-host.xml.template](../tools/cvm-image-rewriter/tdx-libvirt-ubuntu-host.xml.template). It uses `vsock` for getting quote.
Expand All @@ -26,11 +61,12 @@ Start a TD using [qemu-test.sh](../tools/cvm-image-rewriter/qemu-test.sh) or [st
## Build CCNP images
Run script [build.sh](../container/build.sh) to generate CCNP images. It will generate 5 images and push them to user specific registry.
Learn more details in the [README.md](../container/README.md).
Run script [build.sh](../container/build.sh) to generate CCNP images. It will generate 3 images and push them to user specific registry. Learn more details in the [README.md](../container/README.md).
_NOTE: The scripts need to run on a server with docker installed._
**NOTE:**
- The scripts need to run on a server with docker installed.
- Run `docker login` before running the tool to make sure it can pull images.
- Set proxy server in your environment if needed. See more details in [Configure Docker to use a proxy server](https://docs.docker.com/network/proxy/).
```
$ cd container
Expand All @@ -45,9 +81,7 @@ $ sudo ./build.sh -r test-registry.intel.com/test -g 0.3
$ sudo ./build.sh -a build -g 0.3
```
_NOTE: please set `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` in your terminal if they are needed in your environments._
After the script is successful, it's supposed to see below docker images for CCNP.
After the script is executed successfully, it's supposed to see below docker images for CCNP.
```
$ sudo docker images
Expand All @@ -62,7 +96,7 @@ Intel Quote Generation Service(QGS) and Provisioning Certification Caching Servi
for QGS and PCCS installation.
## Deployment CCNP in Kubernetes
## Deploy CCNP in Kubernetes
Below diagram illustrates CCNP deployment process in a Kubernetes cluster. If you want to install CCNP services as DamonSets in the Kubernetes cluster, please refer to [CCNP deployment in Kubernetes](./kubernetes/README.md).
Expand Down
Loading

0 comments on commit c591208

Please sign in to comment.