diff --git a/attestation-agent/docs/IMPLEMENTATION.md b/attestation-agent/docs/IMPLEMENTATION.md deleted file mode 100644 index 669fab765..000000000 --- a/attestation-agent/docs/IMPLEMENTATION.md +++ /dev/null @@ -1,144 +0,0 @@ -# IMPLEMENTATION - -## Definition of terms - -### CC - -CNCF Confidential Containers, the parent project of Attestation Agent. - -### KBS - -Key Broker Service. - -### KBC - -Key Broker Client, the Client of KBS. - -### KBS protocol - -The protocol used by a class of KBS to communicate with its KBC, such as EAA, GOP, ISECL, etc. - -### KBS instance - -A specific instance of KBS class to comminicate with KBC instance during runtime. - -### KBC module - -A class of KBC implementation of the specific KBS protocol. In the code implementation, it is embodied as the mod.rs in a KBC source. - -### KBC instance - -The instantiated object of KBC existing in AA runtime. It is used to actually handle UnWrapKey requests. - -## KeyProvider protocol - -Under CC framework, the protocol for communication between AA caller (ocicrypt) and AA. Since AA exists as a keyprovider service from the perspective of ocicrypt, this protocol conforms to the format of the standard keyprovider protocol. In order to better support the special functions of AA different from keyprovider, we further standardize the DC parameters in the standard keyprovider protocol and set the unique standard format of AA, Its contents and the meanings of its fields are as follows: - -### UnWrapKey API Request - -``` -{ - "op":"keyunwrap", - "keyunwrapparams":{ - "dc":{ - "Parameters":{ - "attestation-agent":[ - "KBC_NAME::KBS_URI " - ], - "DecryptConfig":{"Parameters":{}} - } - } - }, - "annotation": #layer-annotation, -} -``` - -The `dc` field in the `keyunwrappparams` field is "Decryption Configuration information", in which the `Parameters` field contains its main contents. The first item of `Parameters` is the name of the keyprovider service which ocicrypt called (here, it needs to be attestation-agent) and the user-defined parameter passed to the target service (Base64 encoded). We define the user-defined parameter as ` "KBC_NAME::KBS_URI" `This standard format is used to transfer KBC selection information and corresponding KBS access information to AA. For more questions here, please refer to the section 'Pass KBC name and KBS URI to AA' below. - -The `"annotation"` field is the main content passed to AA. In fact, it is the layer annotation field of the container image to be decrypted. This field contains the payload to be decrypted by AA. For more information about layer annotation, please refer to the following two chapters 'Encryption and decryption of container image' and 'Layer annotation'. - -### UnWrapKey API Response - -``` -{ - "keyunwrapresults": { - "optsdata": #decrypted-payload, - } -} -``` - -This is the response returned to ocicrypt, where the `"optsdata"` field contains the plain payload in the layer annotation decrypted by AA. - -### WrapKey API - -AA only provides the service of decryption path as a keyprovider, so the wrapkey API is not required. However, in order to maintain the consistency of keyprovider protocol, AA provides an empty wrapkey API and will return "UNIMPLEMENT" in the ` "optsdata"` field of response. - -## Encryption and decryption of container image - -During image layer encryption, a request to keyprovider WrapKey() API is called by ocicrypt. A KBS instance may implement this API to encrypt the ‘Private Layer Block Cipher Options’ (PLBCO for short) with Key Encryption Key (KEK for short), and package the encrypted PLBCO and KBS specific parameters into the layer annotation. ( Note: How to cooperate with KBS for encryption is customizable, and WrapKey() API does not have to be implemented by KBS. ) - -When decrypting the container image layer, kata-agent (ocicrypt-rs) will request AA's UnWrapKey API, pass KBC name, KBS URI and layer annotation to AA, and expect AA to return the decrypted PLBCO (including LEK). - -## Layer annotation - -The producer of layer annotation is a KBS instance, so the format of layer annotation is specific yo KBS protocol and implementation. (If KBS is not used for encryption, layer annotation should also be set to KBS protocol specific format) - -The consumer of layer annotation is a KBC instance that implements the corresponding KBS protocol, because only it can parse the annotation format of KBS protocol specific. - -## KBC runtime - -During the compilation of AA, it is optional to specify the KBC module(s) to compile through the conditional compilation option. AA will compile the mod.rs of these KBCs you specify, and register these KBC modules and the functions that instantiate them in AA's built-in 'KBC module list'. - -KBC RUNTIME is a subsystem in AA which is used to instantiate KBC, manage KBC instances and encapsulate KBC instance interfaces. At runtime of AA, KBC runtime will dynamically select the corresponding KBC module from the KBC module list according to the KBC name in the UnWrapKey request, create a KBC instance and register it in the map of the current running instance. The KBC standard encapsulation interface provided by KBC runtime is then invoked to handle the request. - -For the current design scenario of CC, only one KBC instance of AA on a k8s pod exists in the whole life cycle of the pod. This KBC instance will be created when AA receives the first UnWrapKey request. However, the implementation of KBC runtime provides good scalability for multiple KBC instances that may occur in other practice scenarios or in the future of CC. - -## Pass KBC name and KBS URI to AA - -In the current implementation, KBC name and KBS URI are passed by the implementer of key provider protocol, e.g, ocicrypt and ocicrypt-rs. - -### Cannot pass through layer annotation currently - -These two information should not be placed in the layer annotation as part of the container image. There are two main reasons: - -1. **Flexibility**: not binding KBC name and KBS URI to container image can improve the cross platform portability of container image. (for example, suppose a KBC can only support the SEV platform. If the KBC name or KBS URI is written to the layer annotation when encrypting a container image, it means that the encrypted container image can only run on the SEV platform). -2. **Security**: layer annotation is public plaintext data. Without additional encryption protection, an attacker can launch DoS attacks by using KBS URI to prevent the tenant from starting any confidential container based on the KBS; Without additional integrity protection, an attacker can tamper with the contents and induce potential security problems in the process of decrypting the image layer. - -**! ! ATTENTION ! ! : **However, it must be noted here that for the first reason mentioned above, we do not rule out the possibility that there may be KBCs supporting various platforms (EAA protocol KBC is trying to do so). In this case, placing KBC name in layer annotation will not affect the cross platform portability of container image, but will support the complex scenarios such as "different layers of a same container image use different KBS protocol to encrypt" more flexibly. Therefore, the current AA code implementation retains the scalability of multiple KBC instances at runtime in order to better support the above possible changes in the future. - -### Passed by ocicrypt instead of kata-agent - -In the implementation of AA, the KBC name and KBS URI are passed through the keyprovider protocol of ocicrypt, rather than by Kata agent in the startup phase of AA. - -KBC name::KBS URI is passed by the user-defined field reserved in the keyprovider protocol. The request of UnWrapKey API should be as follows: - -``` -{ - "op":"keyunwrap", - "keyunwrapparams":{ - "dc":{ - "Parameters":{ - "attestation-agent":[ - "KBC_NAME::KBS_URI " - ], - "DecryptConfig":{"Parameters":{}} - } - } - }, - "annotation": #kbs-protocol-specific, -} -``` - -When AA receives the first unwrapkey request after startup, it will select the correct KBC from KBC module list (compile time option) according to KBC name and instantiate it. In subsequent requests, if the KBC name is the same, AA always uses the same KBC instance to handle the request. - -Although you may think that it seems more direct to pass these parameters in the startup phase of AA from kata-agent, the current scheme of passing them through keyprovider protocol can unify the parameter receiving interface of AA and make the architecture of AA more scalable. In addition, the impact of this scheme on performance can be ignored because instantiating KBC is very simple. - -## Others - -### Sample KBC - -At the current stage, the sample KBC module uses hard coded KEK for decryption. In the formal scenario, the KBC module needs to parse the annotation field passed by ocicrypt-rs, obtain the connection address information of the key broker service (KBS) and the ID of the KEK, and then communicate with KBS to actually decrypt the payload (Image encryption key) in the annotation field. - -### gRPC and ttRPC - -Compared with gRPC, ttRPC has the advantage of lighter weight. AA, as a memory resident service on the client side of CC V0 architecture, using lightweight ttRPC will save more resources. At present, grpc is used for end-to-end testing. Wait until ocicrypt-rs supports ttrpc, AA can cooperate with the modification. Later, AA can make the use of grpc/ttrpc configurable at compile time. This needs to be discussed with the developers of ocicrypt rs. diff --git a/attestation-agent/docs/kbc_module_development_guide.md b/attestation-agent/docs/kbc_module_development_guide.md deleted file mode 100644 index b891783e4..000000000 --- a/attestation-agent/docs/kbc_module_development_guide.md +++ /dev/null @@ -1,115 +0,0 @@ -# KBC Module Development Guide - -This guide will teach you how to develop a KBC module and integrate it into the source code of the AA according to the KBC module standard interface and integration mode. Please refer to [IMPLEMENTATION.md](IMPLEMENTATION.md) for the details of KBC module framework. - -Now let's start. - -## Development - -First, create a new KBC module (e.g, my_kbc) as following: - -``` -cd attestation-agent/kbc -mkdir my_kbc -cd my_kbc -touch mod.rs -``` - -Then, you need to import the definition of KBC module standard interface in mod.rs, that is, add the following codes in mod.rs: - -```rust -use crate::kbc_modules::{KbcCheckInfo, KbcInterface}; -``` - -Add the implementations for my_kbc module. - -```rust -// kbc/my_kbc/mod.rs - -pub struct MyKbc { - // The object of this structure will exist as a KBC instance - ... ... -} - -impl KbcInterface for MyKbc { - // Check interface: - // used to let the KBC runtime obtain the KBS information of the current KBC instance - // The KbcCheckInfo structure is defined as follows: - // pub struct KbcCheckInfo { - // pub kbs_info: HashMap, - // } - fn check(&self) -> KbcCheckInfo {...} - - // decrypt_payload interface: - // used to parse layer annotation and decrypt PLBCO - // Input parameter: layer annotation - // Return value: decrypted PLBCO - fn decrypt_payload(&mut self, annotation: &str) -> Result> {...} -} - -impl MyKbc { - // The following is the function to create KBC instance object, - // which needs to receive KBS URI as a parameter. - // This function needs to be integrated into KBC_MODULE_LIST of AA, - // So its parameters and return value format must be implemented according to the example given here. - fn new(kbs_uri: String) -> MyKbc {...} - ... -} -``` - -The detailed KBC module implemention requires to use new KBS protocol to communicate with a new class of KBS through attestation in order to decrypt the encrypted payload. - -## Integration - -You need to integrate my_kbc module into AA as following: - -1. Import my_kbc module: - -```rust -// kbc/mod.rs - -// Add my specific kbc declaration here. -// For example: "pub mod sample_kbc;" -#[cfg(feature = "my_kbc")] -pub mod my_kbc; -``` - -2. Register the function to create KBC instance in KbcModuleList: - -```rust -// kbc/mod.rs - -impl KbcModuleList { - fn new() -> KbcModuleList { - let mut mod_list = HashMap::new(); - - #[cfg(feature = "my_kbc")] - { - let instantiate_func: KbcInstantiateFunc = Box::new(|kbs_uri: String| -> KbcInstance { - Box::new(my_kbc::MyKbc::new(kbs_uri)) - }); - mod_list.insert("my_kbc".to_string(), instantiate_func); - } - - KbcModuleList { mod_list: mod_list } - } -``` - -3. Add the compilation options for my_kbc in Cargo.toml: - -``` -# Cargo.toml - -[features] -default = ["my_kbc"] -my_kbc = [] -``` - -## Compilation - -After development and integration, you can compile the attestation-agent that supports your KBC module. You only need to specify feature parameter during compilation: - -``` -cargo build --release --no-default-features --features my_kbc -``` - diff --git a/attestation-agent/docs/IMAGE_ENCRYPTION.md b/confidential-data-hub/docs/IMAGE_ENCRYPTION.md similarity index 90% rename from attestation-agent/docs/IMAGE_ENCRYPTION.md rename to confidential-data-hub/docs/IMAGE_ENCRYPTION.md index 44af04425..73681f181 100644 --- a/attestation-agent/docs/IMAGE_ENCRYPTION.md +++ b/confidential-data-hub/docs/IMAGE_ENCRYPTION.md @@ -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 @@ -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. diff --git a/attestation-agent/docs/KBS_URI.md b/confidential-data-hub/docs/KBS_URI.md similarity index 57% rename from attestation-agent/docs/KBS_URI.md rename to confidential-data-hub/docs/KBS_URI.md index 58064c484..2b38ec77b 100644 --- a/attestation-agent/docs/KBS_URI.md +++ b/confidential-data-hub/docs/KBS_URI.md @@ -19,18 +19,3 @@ where: - `//`: This is the resource path. Typically, `` would be a user name, `` would be the type of the resource, and `` would help distinguish between different resource instances of the same type. The default value of `` 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 `//` as key/resource id in their requests. - -### Offline KBCs (e.g FS KBC & Offline SEV KBC) - -Offline KBCs should ignore the `:` host part of the URI, and use the resource path (`//`) to locally fetch the resource.