|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | + |
| 3 | +//! Provisioner plugin for KBS. |
| 4 | +//! |
| 5 | +//! Generates per-VM LUKS encryption keys and stores them in the KBS resource |
| 6 | +//! storage so that attested guests can retrieve them via the standard |
| 7 | +//! `/kbs/v0/resource/...` path. |
| 8 | +//! |
| 9 | +//! The hook sidecar calls `POST /kbs/v0/provisioner/provision` before the VM |
| 10 | +//! boots and receives `{uuid, oemstring, mrconfigid}` to inject into SMBIOS. |
| 11 | +//! On boot the guest attests and fetches the key through the `resource` plugin. |
| 12 | +
|
| 13 | +use std::collections::HashMap; |
| 14 | +use std::sync::Mutex; |
| 15 | + |
| 16 | +use actix_web::http::Method; |
| 17 | +use anyhow::{anyhow, bail, Result}; |
| 18 | +use base64::{engine::general_purpose::STANDARD as B64, Engine}; |
| 19 | +use key_value_storage::{KeyValueStorageInstance, SetParameters, StorageBackendConfig}; |
| 20 | +use rand::Rng; |
| 21 | +use serde::{Deserialize, Serialize}; |
| 22 | +use sha2::{Digest, Sha384}; |
| 23 | +use uuid::Uuid; |
| 24 | + |
| 25 | +use super::resource::RESOURCE_STORAGE_NAMESPACE; |
| 26 | + |
| 27 | +// --------------------------------------------------------------------------- |
| 28 | +// Config (deserialized from kbs-config.toml) |
| 29 | +// --------------------------------------------------------------------------- |
| 30 | + |
| 31 | +#[derive(Deserialize, Clone, Debug, PartialEq)] |
| 32 | +pub struct ProvisionerConfig { |
| 33 | + /// URL that will be embedded in `initdata.toml` for the guest. |
| 34 | + pub kbs_url: String, |
| 35 | + |
| 36 | + /// Length of the random LUKS key in bytes (default 32). |
| 37 | + #[serde(default = "default_key_length")] |
| 38 | + pub key_length: usize, |
| 39 | +} |
| 40 | + |
| 41 | +fn default_key_length() -> usize { |
| 42 | + 32 |
| 43 | +} |
| 44 | + |
| 45 | +// --------------------------------------------------------------------------- |
| 46 | +// Plugin state |
| 47 | +// --------------------------------------------------------------------------- |
| 48 | + |
| 49 | +pub struct Provisioner { |
| 50 | + storage: KeyValueStorageInstance, |
| 51 | + kbs_url: String, |
| 52 | + key_length: usize, |
| 53 | + // TODO: This in-memory cache grows unboundedly and uses std::sync::Mutex |
| 54 | + // which can block the async runtime. More critically, the cache does |
| 55 | + // not survive KBS restarts: if the sidecar re-provisions the same VM |
| 56 | + // after a restart, a new UUID/key pair is generated, replacing the |
| 57 | + // original resource. The VM's LUKS volume would then fail to unlock |
| 58 | + // because the key no longer matches. The cache (or the vm->resource |
| 59 | + // mapping) must be persisted to the storage backend so it can be |
| 60 | + // restored on startup. Also consider a TTL/LRU eviction policy and |
| 61 | + // switching to tokio::sync::Mutex. |
| 62 | + cache: Mutex<HashMap<String, ProvisionResponse>>, |
| 63 | +} |
| 64 | + |
| 65 | +#[derive(Serialize, Deserialize, Clone)] |
| 66 | +struct ProvisionRequest { |
| 67 | + vm_name: String, |
| 68 | + #[serde(default = "default_namespace")] |
| 69 | + namespace: String, |
| 70 | +} |
| 71 | + |
| 72 | +fn default_namespace() -> String { |
| 73 | + "default".into() |
| 74 | +} |
| 75 | + |
| 76 | +#[derive(Serialize, Clone)] |
| 77 | +struct ProvisionResponse { |
| 78 | + uuid: String, |
| 79 | + oemstring: String, |
| 80 | + mrconfigid: String, |
| 81 | + resource_path: String, |
| 82 | +} |
| 83 | + |
| 84 | +#[derive(Serialize)] |
| 85 | +struct StatusResponse { |
| 86 | + status: String, |
| 87 | +} |
| 88 | + |
| 89 | +// --------------------------------------------------------------------------- |
| 90 | +// Constructor |
| 91 | +// --------------------------------------------------------------------------- |
| 92 | + |
| 93 | +impl Provisioner { |
| 94 | + pub async fn new( |
| 95 | + config: ProvisionerConfig, |
| 96 | + storage_backend_config: &StorageBackendConfig, |
| 97 | + ) -> Result<Self> { |
| 98 | + let storage = storage_backend_config |
| 99 | + .backends |
| 100 | + .to_client_with_namespace( |
| 101 | + storage_backend_config.storage_type, |
| 102 | + RESOURCE_STORAGE_NAMESPACE, |
| 103 | + ) |
| 104 | + .await |
| 105 | + .map_err(|e| anyhow!("Provisioner: failed to init storage backend: {e}"))?; |
| 106 | + |
| 107 | + Ok(Self { |
| 108 | + storage, |
| 109 | + kbs_url: config.kbs_url, |
| 110 | + key_length: config.key_length, |
| 111 | + cache: Mutex::new(HashMap::new()), |
| 112 | + }) |
| 113 | + } |
| 114 | +} |
| 115 | + |
| 116 | +// --------------------------------------------------------------------------- |
| 117 | +// Helpers |
| 118 | +// --------------------------------------------------------------------------- |
| 119 | + |
| 120 | +impl Provisioner { |
| 121 | + // TODO: This generates an alphanumeric string (~5.95 bits of entropy per |
| 122 | + // char, ~190 bits for 32 chars). Use OsRng with raw bytes + base64/hex |
| 123 | + // encoding to get a full 256-bit key. |
| 124 | + fn generate_random_key(&self) -> String { |
| 125 | + const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"; |
| 126 | + let mut rng = rand::thread_rng(); |
| 127 | + (0..self.key_length) |
| 128 | + .map(|_| { |
| 129 | + let idx = rng.gen_range(0..CHARSET.len()); |
| 130 | + CHARSET[idx] as char |
| 131 | + }) |
| 132 | + .collect() |
| 133 | + } |
| 134 | + |
| 135 | + fn generate_initdata_toml(&self, resource_path: &str) -> String { |
| 136 | + format!( |
| 137 | + "algorithm = \"sha384\"\n\ |
| 138 | + version = \"0.1.0\"\n\ |
| 139 | + \n\ |
| 140 | + [data]\n\ |
| 141 | + \"trustee.kbs.url\" = \"{}\"\n\ |
| 142 | + \"trustee.kbs.resource\" = \"{}\"\n", |
| 143 | + self.kbs_url, resource_path |
| 144 | + ) |
| 145 | + } |
| 146 | + |
| 147 | + fn generate_confdata_toml(luks_key: &str) -> String { |
| 148 | + format!( |
| 149 | + "version = \"0.1.0\"\n\ |
| 150 | + \n\ |
| 151 | + [data]\n\ |
| 152 | + \"io.cryptsetup.key.text.root\" = \"{}\"\n", |
| 153 | + luks_key |
| 154 | + ) |
| 155 | + } |
| 156 | + |
| 157 | + async fn handle_provision(&self, body: &[u8]) -> Result<Vec<u8>> { |
| 158 | + let req: ProvisionRequest = serde_json::from_slice(body) |
| 159 | + .map_err(|e| anyhow!("invalid JSON body: {e}"))?; |
| 160 | + |
| 161 | + let cache_key = format!("{}/{}", req.namespace, req.vm_name); |
| 162 | + |
| 163 | + // Return cached result if already provisioned |
| 164 | + if let Some(cached) = self.cache.lock().unwrap().get(&cache_key) { |
| 165 | + return Ok(serde_json::to_vec(cached)?); |
| 166 | + } |
| 167 | + |
| 168 | + // TODO: UUIDv4 is random but not tied to VM identity. A more robust |
| 169 | + // approach would derive the UUID deterministically from the VM's |
| 170 | + // attributes (e.g. name + namespace + cluster ID) to ensure |
| 171 | + // idempotency and traceability across re-provisions. |
| 172 | + // A uniqueness check against existing storage entries should also |
| 173 | + // be added to avoid collisions before writing the resource. |
| 174 | + let trustee_uuid = Uuid::new_v4().to_string(); |
| 175 | + let resource_path = format!("default/{trustee_uuid}/root"); |
| 176 | + let luks_key = self.generate_random_key(); |
| 177 | + |
| 178 | + let initdata_toml = self.generate_initdata_toml(&resource_path); |
| 179 | + let confdata_toml = Self::generate_confdata_toml(&luks_key); |
| 180 | + |
| 181 | + let oemstring = B64.encode(initdata_toml.as_bytes()); |
| 182 | + let mrconfigid = { |
| 183 | + let digest = Sha384::digest(initdata_toml.as_bytes()); |
| 184 | + B64.encode(digest) |
| 185 | + }; |
| 186 | + |
| 187 | + // Write the confdata (LUKS key) to storage via the same backend |
| 188 | + // that the `resource` plugin reads from. |
| 189 | + // TODO: Using overwrite: true could silently replace another VM's key |
| 190 | + // on UUID collision. Use overwrite: false and handle the conflict error, |
| 191 | + // or check existence before writing. |
| 192 | + self.storage |
| 193 | + .set( |
| 194 | + &resource_path, |
| 195 | + confdata_toml.as_bytes(), |
| 196 | + SetParameters { overwrite: true }, |
| 197 | + ) |
| 198 | + .await |
| 199 | + .map_err(|e| anyhow!("failed to write resource: {e}"))?; |
| 200 | + |
| 201 | + // NOTE: The sidecar currently only consumes `oemstring` and `mrconfigid`. |
| 202 | + // `uuid` and `resource_path` are included for debugging/deprovision but |
| 203 | + // are redundant for the sidecar since `oemstring` (base64 of initdata.toml) |
| 204 | + // already embeds the resource_path. |
| 205 | + let response = ProvisionResponse { |
| 206 | + uuid: trustee_uuid, |
| 207 | + oemstring, |
| 208 | + mrconfigid, |
| 209 | + resource_path, |
| 210 | + }; |
| 211 | + |
| 212 | + self.cache.lock().unwrap().insert(cache_key, response.clone()); |
| 213 | + |
| 214 | + Ok(serde_json::to_vec(&response)?) |
| 215 | + } |
| 216 | + |
| 217 | + async fn handle_deprovision(&self, path: &[&str]) -> Result<Vec<u8>> { |
| 218 | + let trustee_uuid = path.first().ok_or_else(|| anyhow!("missing uuid in path"))?; |
| 219 | + let resource_path = format!("default/{trustee_uuid}/root"); |
| 220 | + |
| 221 | + let _ = self.storage.delete(&resource_path).await; |
| 222 | + |
| 223 | + // Remove from cache |
| 224 | + self.cache.lock().unwrap().retain(|_, v| v.uuid != *trustee_uuid); |
| 225 | + |
| 226 | + Ok(serde_json::to_vec(&StatusResponse { |
| 227 | + status: "deleted".into(), |
| 228 | + })?) |
| 229 | + } |
| 230 | +} |
| 231 | + |
| 232 | +// --------------------------------------------------------------------------- |
| 233 | +// ClientPlugin trait |
| 234 | +// --------------------------------------------------------------------------- |
| 235 | + |
| 236 | +#[async_trait::async_trait] |
| 237 | +impl super::super::plugin_manager::ClientPlugin for Provisioner { |
| 238 | + async fn handle( |
| 239 | + &self, |
| 240 | + body: &[u8], |
| 241 | + query: &HashMap<String, String>, |
| 242 | + path: &[&str], |
| 243 | + method: &Method, |
| 244 | + ) -> Result<Vec<u8>> { |
| 245 | + match (method.as_str(), path.first().copied()) { |
| 246 | + ("POST", Some("provision")) => self.handle_provision(body).await, |
| 247 | + ("DELETE", Some("provision")) => { |
| 248 | + self.handle_deprovision(&path[1..]).await |
| 249 | + } |
| 250 | + ("GET", Some("healthz")) => { |
| 251 | + Ok(serde_json::to_vec(&StatusResponse { |
| 252 | + status: "healthy".into(), |
| 253 | + })?) |
| 254 | + } |
| 255 | + _ => bail!("unsupported: {} /kbs/v0/provisioner/{}", method, path.join("/")), |
| 256 | + } |
| 257 | + } |
| 258 | + |
| 259 | + async fn validate_auth( |
| 260 | + &self, |
| 261 | + _body: &[u8], |
| 262 | + _query: &HashMap<String, String>, |
| 263 | + _path: &[&str], |
| 264 | + _method: &Method, |
| 265 | + ) -> Result<bool> { |
| 266 | + // Return true so KBS routes through the admin auth path |
| 267 | + // (instead of the attestation token path which requires a TEE session). |
| 268 | + // |
| 269 | + // NOTE: Currently relies on InsecureAllowAll admin backend for dev. |
| 270 | + // For production, switch to Simple admin with JWT-signed requests |
| 271 | + // and scoped roles, e.g.: |
| 272 | + // [admin] type = "Simple" |
| 273 | + // [[admin.personas]] id = "provisioner" public_key_path = "..." |
| 274 | + // [[admin.roles]] id = "provisioner" allowed_endpoints = "^/kbs/v0/provisioner/.*$" |
| 275 | + Ok(true) |
| 276 | + } |
| 277 | + |
| 278 | + async fn encrypted( |
| 279 | + &self, |
| 280 | + _body: &[u8], |
| 281 | + _query: &HashMap<String, String>, |
| 282 | + _path: &[&str], |
| 283 | + _method: &Method, |
| 284 | + ) -> Result<bool> { |
| 285 | + // Responses don't need TEE encryption (caller is infrastructure, not a TEE). |
| 286 | + Ok(false) |
| 287 | + } |
| 288 | +} |
0 commit comments