add support for platform root key

Author: Sangho Lee

dev_tests/src/ratchet.rs

@@ -36,8 +36,8 @@ fn ratchet_globals() -> Result<()> {
             ("dev_bench/", 1),
             ("litebox/", 9),
             ("litebox_platform_linux_kernel/", 6),
-            ("litebox_platform_linux_userland/", 5),
-            ("litebox_platform_lvbs/", 23),
+            ("litebox_platform_linux_userland/", 6),
+            ("litebox_platform_lvbs/", 24),
             ("litebox_platform_multiplex/", 1),
             ("litebox_platform_windows_userland/", 8),
             ("litebox_runner_linux_userland/", 1),

litebox/src/platform/mod.rs

@@ -754,3 +754,40 @@ pub trait CrngProvider {
     /// failures.
     fn fill_bytes_crng(&self, buf: &mut [u8]);
 }
+
+/// A provider of the Platform Root Key (PRK).
+///
+/// The PRK is a platform-unique secret which can be used to derive secret keys
+/// (e.g., TA unique keys, secure storage keys). It serves as the root of trust
+/// for cryptographic operations within the trusted or sandboxed execution
+/// environment. It resembles the root secret keys provided by trusted hardware
+/// devices (e.g., OP-TEE's Hardware Unique Key, DICE's Unique Device Secret,
+/// and TPM's Primary Seeds).
+///
+/// Ideally, the platform should feature a persistent, hardware-backed key (e.g.,
+/// fused OTP, PUF-derived). The key should be unique per device, inaccessible
+/// outside the trusted environment, and never directly exposed---only used to
+/// derive other keys. If the platform lacks such hardware support (e.g., a
+/// userland platform), it may generate an ephemeral key from a boot nonce and
+/// CRNG, valid only for the current session.
+///
+/// Note that we do not specify `set_platform_root_key` (yet). This is because
+/// each platform has its own way to initialize the PRK (e.g., no initialization
+/// if the PRK is baked into hardware, random numbers with different lengths,
+/// ...). The platform should initialize the PRK by itself or via the runner.
+pub trait PlatformRootKeyProvider {
+    /// Returns a reference to the Platform Root Key.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`PlatformRootKeyError`] if the PRK is not supported or not
+    /// initialized.
+    fn platform_root_key(&self) -> Result<&[u8], PlatformRootKeyError> {
+        Err(PlatformRootKeyError)
+    }
+}
+
+/// Error returned when the platform root key is not supported on the platform.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
+#[error("platform root key is not supported on this platform")]
+pub struct PlatformRootKeyError;

litebox_platform_linux_userland/src/lib.rs

@@ -2747,6 +2747,43 @@ impl litebox::platform::CrngProvider for LinuxUserland {
     }
 }
 
+/// Length of the Platform Root Key in bytes.
+#[cfg(all(target_arch = "x86_64", feature = "optee_syscall"))]
+pub const PRK_LEN: usize = 32;
+
+#[cfg(all(target_arch = "x86_64", feature = "optee_syscall"))]
+static PRK_ONCE: std::sync::OnceLock<[u8; PRK_LEN]> = std::sync::OnceLock::new();
+
+/// Sets the Platform Root Key (PRK) for this platform.
+///
+/// This should be called once during platform initialization with a key derived
+/// from hardware or a nonce.
+///
+/// # Panics
+/// Panics if `key` length does not match `PRK_LEN`.
+#[cfg(all(target_arch = "x86_64", feature = "optee_syscall"))]
+pub fn set_platform_root_key(key: &[u8]) {
+    assert_eq!(key.len(), PRK_LEN, "Platform Root Key length mismatch");
+    PRK_ONCE.get_or_init(|| {
+        let mut prk = [0u8; PRK_LEN];
+        prk.copy_from_slice(key);
+        prk
+    });
+}
+
+#[cfg(all(target_arch = "x86_64", feature = "optee_syscall"))]
+impl litebox::platform::PlatformRootKeyProvider for LinuxUserland {
+    fn platform_root_key(&self) -> Result<&[u8], litebox::platform::PlatformRootKeyError> {
+        PRK_ONCE
+            .get()
+            .map(<[u8; PRK_LEN]>::as_slice)
+            .ok_or(litebox::platform::PlatformRootKeyError)
+    }
+}
+
+#[cfg(not(all(target_arch = "x86_64", feature = "optee_syscall")))]
+impl litebox::platform::PlatformRootKeyProvider for LinuxUserland {}
+
 /// Dummy `VmapManager`.
 ///
 /// In general, userland platforms do not support `vmap` and `vunmap` (which are kernel functions).

litebox_platform_lvbs/src/host/lvbs_impl.rs

@@ -114,6 +114,43 @@ impl litebox::platform::CrngProvider for LvbsLinuxKernel {
     }
 }
 
+/// Length of the Platform Root Key in bytes.
+#[cfg(feature = "optee_syscall")]
+pub const PRK_LEN: usize = 32;
+
+#[cfg(feature = "optee_syscall")]
+static PRK_ONCE: spin::Once<[u8; PRK_LEN]> = spin::Once::new();
+
+/// Sets the Platform Root Key (PRK) for this platform.
+///
+/// This should be called once during platform initialization with a key derived
+/// from hardware or a boot nonce.
+///
+/// # Panics
+/// Panics if `key` length does not match `PRK_LEN`.
+#[cfg(feature = "optee_syscall")]
+pub fn set_platform_root_key(key: &[u8]) {
+    assert_eq!(key.len(), PRK_LEN, "Platform Root Key length mismatch");
+    PRK_ONCE.call_once(|| {
+        let mut prk = [0u8; PRK_LEN];
+        prk.copy_from_slice(key);
+        prk
+    });
+}
+
+#[cfg(feature = "optee_syscall")]
+impl litebox::platform::PlatformRootKeyProvider for LvbsLinuxKernel {
+    fn platform_root_key(&self) -> Result<&[u8], litebox::platform::PlatformRootKeyError> {
+        PRK_ONCE
+            .get()
+            .map(<[u8; PRK_LEN]>::as_slice)
+            .ok_or(litebox::platform::PlatformRootKeyError)
+    }
+}
+
+#[cfg(not(feature = "optee_syscall"))]
+impl litebox::platform::PlatformRootKeyProvider for LvbsLinuxKernel {}
+
 pub struct HostLvbsInterface;
 
 impl HostLvbsInterface {}

litebox_platform_lvbs/src/host/mod.rs

@@ -8,6 +8,8 @@ pub mod lvbs_impl;
 pub mod per_cpu_variables;
 
 pub use lvbs_impl::LvbsLinuxKernel;
+#[cfg(feature = "optee_syscall")]
+pub use lvbs_impl::{PRK_LEN, set_platform_root_key};
 
 #[cfg(test)]
 pub mod mock;

litebox_runner_optee_on_linux_userland/src/lib.rs

@@ -3,6 +3,7 @@
 
 use anyhow::Result;
 use clap::Parser;
+use litebox::platform::CrngProvider;
 use litebox_common_optee::{TeeUuid, UteeEntryFunc, UteeParamOwned};
 use litebox_platform_multiplex::Platform;
 use litebox_shim_optee::session::allocate_session_id;
@@ -98,6 +99,11 @@ pub fn run(cli_args: CliArgs) -> Result<()> {
         InterceptionBackend::Rewriter => {}
     }
 
+    // For now, we use a random PRK for this runner. We can get one via command line if needed.
+    let mut prk = [0u8; litebox_platform_linux_userland::PRK_LEN];
+    platform.fill_bytes_crng(&mut prk);
+    litebox_platform_linux_userland::set_platform_root_key(&prk);
+
     if cli_args.command_sequence.is_empty() {
         run_ta_with_default_commands(&shim, ldelf_data.as_slice(), prog_data.as_slice());
     } else {

litebox_shim_optee/src/syscalls/pta.rs

@@ -6,7 +6,7 @@
 
 use crate::{Task, UserConstPtr, UserMutPtr};
 use litebox::{
-    platform::{RawConstPointer as _, RawMutPointer as _},
+    platform::{PlatformRootKeyProvider, RawConstPointer as _, RawMutPointer as _},
     utils::TruncateExt,
 };
 use litebox_common_optee::{TeeParamType, TeeResult, TeeUuid, UteeParams};
@@ -115,18 +115,22 @@ impl Task {
                     let output_addr: usize = output.0.truncate();
                     let output_ptr = UserMutPtr::<u8>::from_usize(output_addr);
 
-                    // TODO: checks whether output is within the secure memory
-
                     // TODO: derive a TA unique key using the hardware unique key (HUK), TA's UUID, and `extra_data`
                     litebox::log_println!(
                         self.global.platform,
                         "derive a key and store it in the secure memory (ptr: {:#x}, size: {})",
                         output_addr,
                         output_len
                     );
-                    // TODO: replace below with a secure key derivation function
+                    let huk = self
+                        .global
+                        .platform
+                        .platform_root_key()
+                        .map_err(|_| TeeResult::NoData)?;
+                    // TODO: the below is a place holder. Replace it with a secure key derivation function (next PR)
                     let mut key_buf = alloc::vec![0u8; output_len];
-                    self.sys_cryp_random_number_generate(&mut key_buf)?;
+                    let copy_len = core::cmp::min(key_buf.len(), huk.len());
+                    key_buf[..copy_len].copy_from_slice(&huk[..copy_len]);
                     output_ptr
                         .copy_from_slice(0, &key_buf)
                         .ok_or(TeeResult::BadParameters)?;