constellation/README.md

# constellation-coordinator

## Prerequisites
* Go 1.18

### Ubuntu 20.04
```sh
sudo apt install build-essential cmake libssl-dev
curl https://sh.rustup.rs -sSf | sh
```

### Amazon Linux
```sh
sudo yum install cmake3 gcc make
curl https://sh.rustup.rs -sSf | sh
```

## Build
```sh
mkdir build
cd build
cmake ..
make -j`nproc`
```

## CMake build options:

### Release build

This options leaves out debug symbols and turns on more compiler optimizations.

```sh
cmake -DCMAKE_BUILD_TYPE=Release ..
```

### Static build (coordinator as static binary, no dependencies on libc or other libraries)

Install the musl-toolchain

Ubuntu / Debian:
```sh
sudo apt install -y musl-tools
rustup target add x86_64-unknown-linux-musl
```

From source (Amazon-Linux):
```sh
wget https://musl.libc.org/releases/musl-1.2.2.tar.gz
tar xfz musl-1.2.2.tar.gz
cd musl-1.2.2
./configure
make -j `nproc`
sudo make install
rustup target add x86_64-unknown-linux-musl
```
Add `musl-gcc` to your PATH:
```sh
export PATH=$PATH:/usr/loca/musl/bin/
```

Compile the coordinator
```sh
cmake -DCOORDINATOR_STATIC_MUSL=ON ..
```

## Cloud credentials

Using the CLI or debug-CLI requires the user to make authorized API calls to the AWS or GCP API.

### Google Cloud Platform (GCP)

If you are running from within a Google VM, and the VM is allowed to access the necessary APIs, no further configuration is needed.

Otherwise you have a couple options:

1. Use the `gcloud` CLI tool

    ```shell
    gcloud auth application-default login
    ```
    This will ask you to log into your Google account, and then create your credentials.
    The Constellation CLI will automatically load these credentials when needed.

2. Set up a service account and pass the credentials manually

    Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials.

### Amazon Web Services (AWS)

To use the CLI with an Constellation cluster on AWS configure the following files:


```bash
$ cat ~/.aws/credentials
[default]
aws_access_key_id = XXXXX
aws_secret_access_key = XXXXX
```

```bash
$ cat ~/.aws/config
[default]
region = us-east-2
```

### Azure

To use the CLI with an Constellation cluster on Azure execute:
```bash
az login
```

### Deploying a locally compiled coordinator binary

By default, `constellation create ...` will spawn cloud provider instances with a pre-baked coordinator binary.
For testing, you can use the constellation debug daemon (debugd) to upload your local coordinator binary to running instances and to obtain SSH access.
See this introduction on how to install and setup `cdbg`: https://github.com/edgelesssys/constellation/debugd/#readme
# constellation-debugd

## Prerequisites

* Go 1.18

## Build

```
git clone https://github.com/edgelesssys/constellation/debugd
cd constellation-debugd
go build -o constellation-debugd debugd/cmd/debugd.go
go build -o constellation-cdbg cdbg/cdbg.go
```

## Install cdbg

```
go install github.com/edgelesssys/constellation/debugd/cdbg@latest
```

## Usage

With `cdbg` installed in your path:

1. Run `constellation --dev-config /path/to/dev-config create […]` while specifying a cloud-provider image with the debugd already included. See [Configuration](#configuration) for a dev-config with a custom image and firewall rules to allow incoming connection on the debugd default port 4000.
2. Run `cdbg deploy --dev-config /path/to/dev-config`
3.  Run `constellation init […]` as usual



### GCP image

For GCP, run the following command to get a list of all constellation images, sorted by their creation date:
```
gcloud compute images list --filter="name~'constellation-.+'" --sort-by=~creationTimestamp
```
Choose the newest debugd image with the naming scheme `constellation-coreos-debugd-<timestamp>`.

### Azure Image

For Azure, run the following command to get a list of all constellation debugd images, sorted by their creation date:
```
az sig image-version list --resource-group constellation-images --gallery-name Constellation --gallery-image-definition constellation-coreos-debugd --query "sort_by([], &publishingProfile.publishedDate)[].id" -o table
```
Choose the newest debugd image and copy the full URI.

## Configuration

You should first locate the newest debugd image for your cloud provider ([GCP](#gcp-image), [Azure](#azure-image)).

This tool uses the dev-config file from `constellation-coordinator` and extends it with more fields.
See this example on what the possible settings are and how to setup the constellation cli to use a cloud-provider image and firewall rules with support for debugd:
```json
{
   "cdbg":{
      "authorized_keys":[
         {
            "user":"my-username",
            "pubkey":"ssh-rsa AAAAB…LJuM="
         }
      ],
      "coordinator_path":"/path/to/coordinator",
      "systemd_units":[
         {
            "name":"some-custom.service",
            "contents":"[Unit]\nDescription=…"
         }
      ]
   },
   "provider": {
    "gcpconfig": {
      "image": "constellation-coreos-debugd-TIMESTAMP",
      "firewallinput": {
        "Ingress": [
          {
            "Name": "coordinator",
            "Description": "Coordinator default port",
            "Protocol": "tcp",
            "Port": 9000
          },
          {
            "Name": "wireguard",
            "Description": "WireGuard default port",
            "Protocol": "udp",
            "Port": 51820
          },
          {
            "Name": "ssh",
            "Description": "SSH",
            "Protocol": "tcp",
            "Port": 22
          },
          {
            "Name": "debugd",
            "Description": "debugd default port",
            "Protocol": "tcp",
            "Port": 4000
          }
        ]
      }
    },
    "azureconfig": {
      "image": "/subscriptions/0d202bbb-4fa7-4af8-8125-58c269a05435/resourceGroups/CONSTELLATION-IMAGES/providers/Microsoft.Compute/galleries/Constellation/images/constellation-coreos-debugd/versions/0.0.TIMESTAMP",
      "networksecuritygroupinput": {
        "Ingress": [
          {
            "Name": "coordinator",
            "Description": "Coordinator default port",
            "Protocol": "tcp",
            "IPRange": "0.0.0.0/0",
            "Port": 9000
          },
          {
            "Name": "wireguard",
            "Description": "WireGuard default port",
            "Protocol": "udp",
            "IPRange": "0.0.0.0/0",
            "Port": 51820
          },
          {
            "Name": "ssh",
            "Description": "SSH",
            "Protocol": "tcp",
            "IPRange": "0.0.0.0/0",
            "Port": 22
          },
          {
            "Name": "debugd",
            "Description": "debugd default port",
            "Protocol": "tcp",
            "IPRange": "0.0.0.0/0",
            "Port": 4000
          }
        ]
      }
    }
  }
}
```
# constellation-kms-client

This library provides an interface for the key management services used with constellation.
It's intendet for the Constellation CSI Plugins and the CLI.

## KMS

The Cloud KMS is where we store our key encryption key (KEK).
It should be initiated by the CLI and provided with a key release policy.
The CSP Plugin can request to encrypt data encryption keys (DEK) with the DEK to safely store them on persistent memory.
The [kms](pkg/kms) package interacts with the Cloud KMS APIs.
Currently planned are KMS are:

* AWS KMS
* GCP CKM
* Azure Key Vault


## Storage

Storage is where the CSI Plugin stores the encrypted DEKs.
Currently planned are:

* AWS S3, SSP
* GCP GCS
* Azure Blob
# constellation-images
# constellation-mount-utils
Wrapper for https://github.com/kubernetes/mount-utils


## Dependencies

This package uses the C library [`libcryptsetup`](https://gitlab.com/cryptsetup/cryptsetup/) for device mapping.

To install the required dependencies on Ubuntu run:
```shell
sudo apt install libcryptsetup-dev
```

To install or upgrade `go.mod` dependencies from private repositories run:
```
GOPRIVATE=github.com/edgelesssys/constellation-coordinator go get github.com/edgelesssys/constellation-coordinator
GOPRIVATE=github.com/edgelesssys/constellation-kms-client go get github.com/edgelesssys/constellation-kms-client
```

## Testing

A small test programm is available in `test/main.go`.
To build the programm run:
```shell
go build -o test/crypt ./test/
```

Create a new crypt device for `/dev/sdX` and map it to `/dev/mapper/volume01`:
```shell
sudo test/crypt -source /dev/sdX -target volume01 -v 4
```

You can now interact with the mapped volume as if it was an unformatted device:
```shell
sudo mkfs.ext4 /dev/mapper/volume01
sudo mount /dev/mapper/volume01 /mnt/volume01
```

Close the mapped volume:
```shell
sudo umount /mnt/volume01
sudo test/crypt -c -target volume01 -v 4
```