Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
63 changes: 41 additions & 22 deletions docs/design/attestation_key_provisioning.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Overview

This document describes the attestation key (AK) registration process for confidential clusters. The AK is provisioned and registered during first boot using Ignition's attestation support. The registered AK follows a Trust On First Use (TOFU) model, where the key is trusted upon initial registration and subsequently used by Trustee to verify attestation reports.
This document describes the attestation key (AK) registration process for confidential clusters. The AK is provisioned and registered during first boot using clevis-pin-trustee's attestation support. The registered AK follows a Trust On First Use (TOFU) model, where the key is trusted upon initial registration and subsequently used by Trustee to verify attestation reports.

Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
## Attestation Key Overview

Expand All @@ -20,49 +20,71 @@ The TOFU model simplifies the attestation workflow by establishing trust during
3. **Subsequent Attestations**: All future attestation reports must be signed by the registered AK
4. **Verification**: Trustee validates that attestation quotes are signed by the known, registered AK

## Ignition Configuration
## Clevis pin configuration

The AK registration is configured through Ignition's attestation section. This configuration is provided during the first boot merge process from the registration service.
The AK registration is configured through the Clevis pin's attestation section. This configuration is provided during the first boot merge process from the machine registration service.

### Configuration Schema

For example, an ignition config
```json
{
"ignition": {
"version": "3.6.0"
},
"attestation": {
"attestation_key": {
"registration": {
"url": "https://registration-service:8443/register-ak",
"certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
"storage": {
"luks": [
{
"clevis": {
"custom": {
"config": "{\"attestation_key\":{...}, ...}",
"needsNetwork": true,
"pin": "trustee"
},
...
},
...
}
}
],
...
}
}
```

could contain the Clevis config

```
{
"attestation_key": {
"registration": {
"url": "https://attestation-key-register.test-a359392a.svc.cluster.local:8001/register-ak",
"cert": "-----BEGIN CERTIFICATE-----\nMIIDADCCAeigAwIBAgIUfF36UDMoK8YX+6RN1HxvusgPUgswDQYJKoZIhvcNAQEL\nBQAwGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTAeFw0yNjEwMTYxNjE1MjBaFw0y\nNzAxMTQxNjE1MjBaMBgxFjAUBgNVBAMTDXNlbGZzaWduZWQtY2EwggEiMA0GCSqG\nSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCwmKhSQJdrgKf+pv2WfDZ43pJMK6dKN317\nO5YflWDqt/xCkRIwdxPAcTGA0dbooA/epzDgbfsU6SHTWclPKg+Uag0KwgzdlPs7\n2uJw25zNnUdA6nLyDqxatbmsHR92Ny9vvmndMmvMQ7cbXpdzXi5asDKLTy3cYyc1\nc0SQ4BMppzvZjuM1BegZXcv7PHlDD+O84Bm+OlRcbdHiZNEUugMqHj/f+NUP43Oh\nGK7xRBx37DLZZvwnm7/5LUR09I4ktSDRKI9qcJawi1OsyLqSYsoKlnN4q+mW/DJ8\n1Hu1jbulTmDXi2PyrsSpYXPdrKrcLtlnHvfKMrxhLj1wBBleLUD7AgMBAAGjQjBA\nMA4GA1UdDwEB/wQEAwICpDAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHMhju\nwEhNswW/c6bnSkKRDPug9DANBgkqhkiG9w0BAQsFAAOCAQEAQhgM0PW6Fwwq0BSz\nSKh2bFELqk5J0P37e4g2tivztACcUcV/3UAhKWGKHPjEx8pt7q1K8t3hbB4cBg4R\nLtagoXP+oRlpx6ESz525cxvLUDGAQK3P/q7mc1SwGzd7jtAPgZ+ULLyEvIj3Tki+\nGzZJh2Vasrx8d09K5wiiN5YUrXVArr7GLmQpHuDwqqE1y1Sre/Xo9nD2/LsveFVa\nkTihjRMfmlwR8T5H/za9bDagBSlby+Nhp9mjy5OrsCRcrlCY+31Copq7SA/uGQ14\nXgSIbBbgUgXUJp0UlyfSF64ao6fjSs+KukCIiz2vpPCpsG4Zseru7kx25v3foITF\ntWLvQw==\n-----END CERTIFICATE-----\n",
Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
"uuid": "fe66e706-e4eb-4f05-84ab-83c69cba5cef"
}
Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
},
...
}
```


### Configuration Parameters

- **url**: HTTP(S) endpoint where the AK public key will be registered
- **certificate**: (Optional) TLS certificate for secure communication with the registration service
- **cert**: (Optional) TLS certificate for secure communication with the machine registration service

## Firstboot AK Registration Flow
## First boot AK Registration Flow

During firstboot, Ignition handles the AK generation and registration before processing merge/replace directives and LUKS encryption setup.
During first boot, clevis-pin-trustee handles the AK generation and registration before LUKS encryption setup.

### Process Flow (first boot)

1. **AK Existence Check**: Ignition checks if `/var/tpm/ak.pub` exists
2. **AK Generation**: If not present, Ignition generates a new AK in the TPM
1. **AK Existence Check**: Clevis pin checks if `/var/tpm/ak.pub` exists
1. **AK Generation**: If not present, Clevis pin generates a new AK in the TPM
Comment thread
iroykaufman marked this conversation as resolved.
Resolved
- AK is created with TPM-resident private key
- Public key is extracted and saved to `/var/tpm/ak.pub`
3. **Network Requirement**: If registration URL is configured, Ignition ensures network connectivity
4. **Registration Request**: Ignition PUTs the public AK to the registration URL
1. **Registration Request**: Clevis pin PUTs the public AK to the AK registration URL with
- the AK public key in PEM format
- the name of the platform where the machine in running on
5. **Retry Mechanism**: If network is not ready, Ignition retries after network initialization
6. **Attestation Configuration Merge**: After AK registration, Ignition proceeds with merge directives to fetch LUKS pin configuration
- the UUID of the machine as given by the machine registration server

### AK Generation Timing

Expand All @@ -80,6 +102,3 @@ The Confidential Cluster Operator extends its existing responsibilities and offe
1. **Trustee Integration**: Updates Trustee with the registered AK for attestation verification

The ignition configuration with the AK registration endpoint need to be provided via the initial Ignition configuration.

![](../pics/ak-registration.png)# Attestation Key Registration

4 changes: 2 additions & 2 deletions docs/design/operator-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The operator deploys a registration server in the cluster that serves as the ent
2. **UUID Generation**: Generates unique identifiers for each registering machine
3. **Machine Object Creation**: Creates Machine custom resources in Kubernetes for each registered node

The registration flow is initiated when a node boots with an initial Ignition configuration containing a merge directive pointing to the registration service endpoint (e.g., `http://register-server:8000/ignitioni-clevis-pin-trustee`).
The registration flow is initiated when a node boots with an initial Ignition configuration containing a merge directive pointing to the registration service endpoint (e.g., `http://register-server:8000/ignition-clevis-pin-trustee`).

A machine can be also manually registered by the admin, but then the Ignition produced by the operator, needs to be configured manually in the upcoming machine.

Expand Down Expand Up @@ -79,7 +79,7 @@ The operator implements a comprehensive attestation key (AK) registration system

The AK registration is coordinated with Machine registration:

**During First Boot (handled by Ignition)**
**During First Boot (handled by clevis-pin-trustee)**
1. Ignition checks if `/var/tpm/ak.pub` exists
2. If not present, generates a new AK in the TPM
3. Contacts the operator's AK registration endpoint (e.g., `https://attestation-key-register:8001/register-ak`)
Expand Down
Loading