How do the kata-agent, attestation-agent, and attestation service interact with each other? Is there any sequence diagram or other documents?

[ccxiaop]

How do the kata-agent, attestation-agent, and attestation service interact with each other? Is there any sequence diagram or other documents?

[Xynnn007]

I am not sure there is any.

But currently kata-agent forks attestation-agent. Attestation-agent connects to KBS via RCAR handshake protocol. Attestation-service is behind KBS.

There is some code you can refer to

kata-agent forks attestation-agent (AA): https://github.com/kata-containers/kata-containers/blob/main/src/agent/src/main.rs#L420
AA connects to KBS via RCAR: https://github.com/confidential-containers/guest-components/blob/main/attestation-agent/kbs_protocol/src/client/rcar_client.rs
KBS connects AS: https://github.com/confidential-containers/trustee/blob/main/kbs/src/attestation/coco/grpc.rs#L106

[fitzthum]

We have this diagram in the docs, but it doesn't include the Kata Agent. We should maybe add a similar diagram to the guest-components repo.

[Spenhouet]

As I started creating sequence diagrams, I'm sharing them as mermaid diagrams:

Encryption and Distribution by Algorithm Provider

sequenceDiagram
  actor U as Algorithm Provider
  participant S as skopeo
  participant DR as Docker Registry
  participant KP as coco-keyprovider
  participant KBS as Key Broker<br/>Service (KBS)

  # autonumber

  U->>S: request encryption of Docker image
  activate S
  
  S->>DR: pull unencrypted Docker image
  activate DR
  DR-->>S: return
  deactivate DR

  S->>KP: ?
  activate KP

  KP->>KBS: ?
  activate KBS
  KBS-->>KP: ?
  deactivate KBS
  
  KP-->>S: ?
  deactivate KP

  S->>DR: upload encrypted Docker image

  deactivate S

Loading

Execute Encrypted Image on Host System

sequenceDiagram
  actor U as User
  participant K as Kubernetes
  participant DR as Docker Registry
  box transparent Trusted Execution Environment (TEE)
    participant KA as Kata Agent
    participant AA as Attestation Agent<br/>(AA)
  end
  participant KBS as Key Broker<br/>Service (KBS)
  participant AS as Attestation<br/>Service (AS)
  participant RVPS as Reference Value<br/>Provider Service<br/>(RVPS)

  # autonumber

  
  U->>K: apply service/job<br/>definition  
  activate K
  
  K->>DR: pull encrypted<br/>Docker image
  activate DR
  DR-->>K: return
  deactivate DR  

  
  K->>KA: 
  deactivate K  

  activate KA
  
  KA->>AA: fork
  activate AA
  AA-->>KA: return

  AA->>KBS: initial request
  activate KBS
  KBS->>AA: challenge and<br/>session identifier
  deactivate KBS

  AA->>AA: generate ephemeral<br/>public key via TEE

  AA->>KBS: attestation evidence
  activate KBS
  KBS->>AS: verify TEE evidence
  activate AS
  AS->>RVPS: request reference<br/>values
  activate RVPS
  RVPS-->>AS: provide reference<br/>values
  deactivate RVPS
  AS-->>KBS: verification result
  deactivate AS
  KBS-->>AA: request approval<br/>(flattened JWE)
  deactivate KBS
  AA-->>KA: return
  deactivate AA

  KA->>KA: decrypt decryption<br/>key using TEE's<br/>private key
  
  KA->>KA: decrypt Docker image

  KA->>KA: execute workload

  deactivate KA

  U->>+K: view pod state
  K-->-U: return

Loading

Please provide feedback/corrections/additions and I will update these diagrams.

[fitzthum]

Good diagrams.

A few random comments:

• you may want to add the snapshotter and image-rs to the second diagram. They maybe aren't totally relevant to the attestation flow, but they are a big part of the control flow for pulling images.
• You might be able to clarify what triggers the attestation to happen. We attest lazily. While the kata agent starts up the CDH/AA at the beginning of the day, the KBS protocol is only executed the first time that the workload needs a secret. In the case of encrypted images, this is when image-rs downloads the image and realizes that it is encrypted.
• The term docker registry could be more generic (i.e. container registry)