Skip to content

Commit

Permalink
AA: Clean Out-of-date documents and move documents about KBS to CDH.
Browse files Browse the repository at this point in the history
Signed-off-by: Jiale Zhang <zhangjiale@linux.alibaba.com>
  • Loading branch information
jialez0 committed Jan 15, 2024
1 parent e7ef6d8 commit d6543c4
Show file tree
Hide file tree
Showing 4 changed files with 6 additions and 280 deletions.
144 changes: 0 additions & 144 deletions attestation-agent/docs/IMPLEMENTATION.md

This file was deleted.

115 changes: 0 additions & 115 deletions attestation-agent/docs/kbc_module_development_guide.md

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

As stated in [CCv0 image security design](../../image-rs/docs/ccv1_image_security_design.md), CoCo uses image encryption machanism compatible with [ocicrypt](https://github.com/containers/ocicrypt) and [ocicrypt-rs](../../ocicrypt-rs).

Attestation-Agent as a [Key Provider](../../image-rs/docs/ccv1_image_security_design.md#update-manifest) implements API `unwrapkey`, which works together
Confidential Data Hub as a [Key Provider](../../image-rs/docs/ccv1_image_security_design.md#update-manifest) implements API `unwrapkey`, which works together
with the [Sample Key Provider](../coco_keyprovider/) who implements API `wrapkey`.

This document will describe how Attestation-Agent and Sample Key Provider play a role in image encryption. Together, some specifications will also be defined.
This document will describe how Confidential Data Hub and Sample Key Provider play a role in image encryption. Together, some specifications will also be defined.

## Image Encryption and Decryption

Expand All @@ -30,12 +30,12 @@ Suppose there is a user wanting to encrypt an image layer `L`.

### Decryption

`unwrapkey` API is directly related to image decryption. An image layer encrypted by `Sample Key Provider` can be decrypted with `Attestation-Agent`'s participation.
`unwrapkey` API is directly related to image decryption. An image layer encrypted by `Sample Key Provider` can be decrypted with `Confidential Data Hub`'s participation.
Here are the steps.
1. `ocicrypt-rs` finds `L` is a encrypted layer, and `L` has a `org.opencontainers.image.enc.keys.provider.attestation-agent` annotation.
2. `ocicrypt-rs` will send the content of the value of `org.opencontainers.image.enc.keys.provider.attestation-agent` annotation over `unwrapkey` gRPC to `Attestation-Agent`.
3. `Attestation-Agent` will parse the annotation into an `AnnotationPacket`.
4. `Attestation-Agent` will use the `AnnotationPacket` to call related KBC's `decrypt_payload()` api to retrieve the `PLBCO`.
2. `ocicrypt-rs` will send the content of the value of `org.opencontainers.image.enc.keys.provider.attestation-agent` annotation over `unwrapkey` gRPC to `Confidential Data Hub`.
3. `Confidential Data Hub` will parse the annotation into an `AnnotationPacket`.
4. `Confidential Data Hub` will use the `AnnotationPacket` to call related KBC's `decrypt_payload()` api to retrieve the `PLBCO`.
* For `*_sev_kbc`, `offline_fs_kbc`, `get_key()` helps to get the `KEK` due to the `key id`, and then `crypto` module decrypts the PLBCO.
* For `eaa_kbc` and those KBCes who do not expose the plaintext of the `KEK`, `decrypt_payload()` api will perform its own decryption action.
7. `ocicrypt-rs` uses `PLBCO` to decrypt the layer.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,3 @@ where:
- `<repository>/<type>/<tag>`: This is the resource path. Typically, `<repository>` would be a user name, `<type>` would be the type of the resource, and `<tag>` would help distinguish between different resource instances of the same type. The default value of `<repository>` is `default`.

For example: `kbs://example.cckbs.org:8081/alice/decryption-key/1`

## How Different KBC/KBS uses a KBS Resource URI

### CC-KBC

`CC-KBC` will convert a KBS Resource URI into a [CoCo KBS Resource API](https://github.com/confidential-containers/kbs/blob/main/kbs/docs/kbs.yaml#L100) compliant HTTP/HTTPS request.
For example, a KBS Resource URI `kbs://example.cckbs.org/alice/decryption-key/1` will be converted to `http://example.cckbs.org/kbs/v0/resource/alice/decryption-key/1`.

### EAA KBC & Online SEV KBC

Both KBCs will use the `<repository>/<type>/<tag>` as key/resource id in their requests.

### Offline KBCs (e.g FS KBC & Offline SEV KBC)

Offline KBCs should ignore the `<kbs_host>:<kbs_port>` host part of the URI, and use the resource path (`<repository>/<type>/<tag>`) to locally fetch the resource.

0 comments on commit d6543c4

Please sign in to comment.