Skip to main content

pq_objectstore/key/
local.rs

1//! Local filesystem / in-memory ML-KEM key provider.
2
3use std::collections::HashMap;
4use std::sync::RwLock;
5
6use crate::crypto::kem::{self, SecretKey};
7use crate::crypto::{PublicKey, SharedSecret, generate_keypair};
8use crate::error::{Error, Result};
9use crate::key::KeyId;
10
11#[cfg(not(target_arch = "wasm32"))]
12use std::path::Path;
13
14#[cfg(not(target_arch = "wasm32"))]
15use crate::crypto::kem::{PUBLIC_KEY_LEN, SEED_LEN};
16
17#[cfg(feature = "store")]
18use crate::key::{KeyProvider, PublicKeyMaterial};
19#[cfg(feature = "store")]
20use async_trait::async_trait;
21
22#[cfg(not(target_arch = "wasm32"))]
23const KEY_FILE_MAGIC: &[u8; 6] = b"PQKEY\x01";
24
25/// Public-only recipient file. The 64-byte seed is not present.
26#[cfg(not(target_arch = "wasm32"))]
27const RECIPIENT_FILE_MAGIC: &[u8; 6] = b"PQREC\x01";
28
29struct KeyEntry {
30    secret: Option<SecretKey>,
31    public: PublicKey,
32}
33
34/// Key provider that holds ML-KEM seeds in process memory.
35///
36/// Suitable for development, Celld embedding, and simple deployments. Private
37/// keys are never written to object storage by this crate.
38///
39/// # Examples
40///
41/// ```
42/// use pq_objectstore::key::{KeyId, LocalKeyProvider};
43///
44/// let id = KeyId::new("workspace-a-v1").unwrap();
45/// let provider = LocalKeyProvider::generate(id).unwrap();
46/// ```
47pub struct LocalKeyProvider {
48    keys: RwLock<HashMap<KeyId, KeyEntry>>,
49}
50
51impl LocalKeyProvider {
52    /// Create an empty provider.
53    #[must_use]
54    pub fn new() -> Self {
55        Self {
56            keys: RwLock::new(HashMap::new()),
57        }
58    }
59
60    /// Generate a fresh keypair under `key_id`.
61    pub fn generate(key_id: KeyId) -> Result<Self> {
62        let provider = Self::new();
63        provider.insert_generated(key_id)?;
64        Ok(provider)
65    }
66
67    /// Insert a newly generated keypair for `key_id`.
68    pub fn insert_generated(&self, key_id: KeyId) -> Result<PublicKey> {
69        let (secret, public) = generate_keypair();
70        self.insert(key_id, secret, public.clone())?;
71        Ok(public)
72    }
73
74    /// Insert an existing seed and public key.
75    pub fn insert(&self, key_id: KeyId, secret: SecretKey, public: PublicKey) -> Result<()> {
76        let mut keys = self
77            .keys
78            .write()
79            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
80        if keys.contains_key(&key_id) {
81            return Err(Error::config(format!("key id already present: {key_id}")));
82        }
83        keys.insert(
84            key_id,
85            KeyEntry {
86                secret: Some(secret),
87                public,
88            },
89        );
90        Ok(())
91    }
92
93    /// Insert a public encapsulation key with no private key.
94    ///
95    /// The provider can encrypt to `key_id`. Decapsulation fails until a
96    /// private key is inserted for the same id on a machine that holds the seed.
97    pub fn insert_public(&self, key_id: KeyId, public: PublicKey) -> Result<()> {
98        let mut keys = self
99            .keys
100            .write()
101            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
102        if keys.contains_key(&key_id) {
103            return Err(Error::config(format!("key id already present: {key_id}")));
104        }
105        keys.insert(
106            key_id,
107            KeyEntry {
108                secret: None,
109                public,
110            },
111        );
112        Ok(())
113    }
114
115    /// Insert a key from a 64-byte seed, deriving the public key.
116    pub fn insert_seed(&self, key_id: KeyId, seed: &[u8]) -> Result<PublicKey> {
117        let secret = SecretKey::from_seed(seed)?;
118        let (_, public) = kem::keypair_from_seed(&secret);
119        self.insert(key_id, secret, public.clone())?;
120        Ok(public)
121    }
122
123    /// Fetch the public key for `key_id` (sync).
124    pub fn get_public_key(&self, key_id: &KeyId) -> Result<PublicKey> {
125        let keys = self
126            .keys
127            .read()
128            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
129        keys.get(key_id)
130            .map(|e| e.public.clone())
131            .ok_or_else(|| Error::UnknownKey(key_id.to_string()))
132    }
133
134    /// Borrow the secret seed for `key_id` by cloning into a new [`SecretKey`].
135    pub fn get_secret_key(&self, key_id: &KeyId) -> Result<SecretKey> {
136        let keys = self
137            .keys
138            .read()
139            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
140        let entry = keys
141            .get(key_id)
142            .ok_or_else(|| Error::UnknownKey(key_id.to_string()))?;
143        let secret = entry
144            .secret
145            .as_ref()
146            .ok_or_else(|| Error::crypto("private key is not loaded for this key id"))?;
147        SecretKey::from_seed(secret.as_bytes())
148    }
149
150    /// Decapsulate with the secret for `key_id` (sync).
151    pub fn decapsulate_sync(&self, key_id: &KeyId, ciphertext: &[u8]) -> Result<SharedSecret> {
152        let keys = self
153            .keys
154            .read()
155            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
156        let entry = keys
157            .get(key_id)
158            .ok_or_else(|| Error::UnknownKey(key_id.to_string()))?;
159        let secret = entry
160            .secret
161            .as_ref()
162            .ok_or_else(|| Error::crypto("private key is not loaded for this key id"))?;
163        kem::decapsulate(secret, ciphertext)
164    }
165
166    /// List known key IDs.
167    pub fn key_ids(&self) -> Result<Vec<KeyId>> {
168        let keys = self
169            .keys
170            .read()
171            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
172        Ok(keys.keys().cloned().collect())
173    }
174
175    /// Persist a single key to `path`.
176    ///
177    /// Unavailable on `wasm32` (no filesystem).
178    #[cfg(not(target_arch = "wasm32"))]
179    pub fn save_key(&self, key_id: &KeyId, path: impl AsRef<Path>) -> Result<()> {
180        let keys = self
181            .keys
182            .read()
183            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
184        let entry = keys
185            .get(key_id)
186            .ok_or_else(|| Error::UnknownKey(key_id.to_string()))?;
187        let secret = entry
188            .secret
189            .as_ref()
190            .ok_or_else(|| Error::crypto("private key is not loaded for this key id"))?;
191        let id_bytes = key_id.as_str().as_bytes();
192        let mut buf = Vec::with_capacity(6 + 2 + id_bytes.len() + SEED_LEN);
193        buf.extend_from_slice(KEY_FILE_MAGIC);
194        buf.extend_from_slice(&(id_bytes.len() as u16).to_be_bytes());
195        buf.extend_from_slice(id_bytes);
196        buf.extend_from_slice(secret.as_bytes());
197        std::fs::write(path, buf)?;
198        Ok(())
199    }
200
201    /// Write a recipient file containing `key_id` and the public key only.
202    ///
203    /// Copy this file to a backup host. That host can encrypt with
204    /// [`Self::load_recipient`]. The 64-byte seed stays in the key file from
205    /// [`Self::save_key`] on the machine that decrypts.
206    ///
207    /// # Errors
208    ///
209    /// Returns [`Error::UnknownKey`] if `key_id` is not loaded, or [`Error::Io`]
210    /// if the file cannot be written.
211    #[cfg(not(target_arch = "wasm32"))]
212    pub fn save_recipient(&self, key_id: &KeyId, path: impl AsRef<Path>) -> Result<()> {
213        let keys = self
214            .keys
215            .read()
216            .map_err(|_| Error::crypto("key provider lock poisoned"))?;
217        let entry = keys
218            .get(key_id)
219            .ok_or_else(|| Error::UnknownKey(key_id.to_string()))?;
220        let id_bytes = key_id.as_str().as_bytes();
221        let mut buf = Vec::with_capacity(6 + 2 + id_bytes.len() + PUBLIC_KEY_LEN);
222        buf.extend_from_slice(RECIPIENT_FILE_MAGIC);
223        buf.extend_from_slice(&(id_bytes.len() as u16).to_be_bytes());
224        buf.extend_from_slice(id_bytes);
225        buf.extend_from_slice(entry.public.as_bytes());
226        std::fs::write(path, buf)?;
227        Ok(())
228    }
229
230    /// Load a recipient file written by [`Self::save_recipient`].
231    ///
232    /// The loaded key can encapsulate (encrypt). It cannot decapsulate.
233    ///
234    /// # Errors
235    ///
236    /// Returns [`Error::InvalidHeader`] if the file is not a recipient file, or
237    /// [`Error::Config`] if the key id is already present.
238    #[cfg(not(target_arch = "wasm32"))]
239    pub fn load_recipient(&self, path: impl AsRef<Path>) -> Result<KeyId> {
240        let bytes = std::fs::read(path)?;
241        if bytes.len() < 6 + 2 + 1 + PUBLIC_KEY_LEN {
242            return Err(Error::invalid_header("recipient file too short"));
243        }
244        if &bytes[..6] != RECIPIENT_FILE_MAGIC {
245            return Err(Error::invalid_header("invalid recipient file magic"));
246        }
247        let id_len = u16::from_be_bytes([bytes[6], bytes[7]]) as usize;
248        let id_end = 8 + id_len;
249        let key_end = id_end + PUBLIC_KEY_LEN;
250        if bytes.len() != key_end {
251            return Err(Error::invalid_header("invalid recipient file length"));
252        }
253        let key_id = KeyId::new(
254            std::str::from_utf8(&bytes[8..id_end])
255                .map_err(|_| Error::invalid_header("key id not utf-8"))?,
256        )?;
257        let public = PublicKey::from_bytes(&bytes[id_end..key_end])?;
258        self.insert_public(key_id.clone(), public)?;
259        Ok(key_id)
260    }
261
262    /// Load a key file previously written by [`Self::save_key`].
263    #[cfg(not(target_arch = "wasm32"))]
264    pub fn load_key(&self, path: impl AsRef<Path>) -> Result<KeyId> {
265        let bytes = std::fs::read(path)?;
266        if bytes.len() < 6 + 2 + 1 + SEED_LEN {
267            return Err(Error::invalid_header("key file too short"));
268        }
269        if &bytes[..6] != KEY_FILE_MAGIC {
270            return Err(Error::invalid_header("invalid key file magic"));
271        }
272        let id_len = u16::from_be_bytes([bytes[6], bytes[7]]) as usize;
273        let id_end = 8 + id_len;
274        let seed_end = id_end + SEED_LEN;
275        if bytes.len() != seed_end {
276            return Err(Error::invalid_header("invalid key file length"));
277        }
278        let key_id = KeyId::new(
279            std::str::from_utf8(&bytes[8..id_end])
280                .map_err(|_| Error::invalid_header("key id not utf-8"))?,
281        )?;
282        self.insert_seed(key_id.clone(), &bytes[id_end..seed_end])?;
283        Ok(key_id)
284    }
285}
286
287impl Default for LocalKeyProvider {
288    fn default() -> Self {
289        Self::new()
290    }
291}
292
293impl std::fmt::Debug for LocalKeyProvider {
294    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
295        let count = self.keys.read().map(|g| g.len()).unwrap_or(0);
296        f.debug_struct("LocalKeyProvider")
297            .field("keys", &count)
298            .finish_non_exhaustive()
299    }
300}
301
302#[cfg(feature = "store")]
303#[async_trait]
304impl KeyProvider for LocalKeyProvider {
305    async fn public_key(&self, key_id: &KeyId) -> Result<PublicKeyMaterial> {
306        self.get_public_key(key_id)
307    }
308
309    async fn decapsulate(&self, key_id: &KeyId, ciphertext: &[u8]) -> Result<SharedSecret> {
310        self.decapsulate_sync(key_id, ciphertext)
311    }
312}
313
314#[cfg(test)]
315mod tests {
316    use super::*;
317
318    #[test]
319    fn generate_and_decapsulate_sync() {
320        let id = KeyId::new("k1").unwrap();
321        let provider = LocalKeyProvider::generate(id.clone()).unwrap();
322        let pk = provider.get_public_key(&id).unwrap();
323        let (ct, ss1) = crate::crypto::encapsulate(&pk).unwrap();
324        let ss2 = provider.decapsulate_sync(&id, &ct).unwrap();
325        assert_eq!(ss1.as_bytes(), ss2.as_bytes());
326    }
327
328    #[cfg(all(feature = "store", not(target_arch = "wasm32")))]
329    #[tokio::test]
330    async fn save_load_round_trip() {
331        let dir = tempfile::tempdir().unwrap();
332        let path = dir.path().join("key.bin");
333        let id = KeyId::new("workspace-a-v1").unwrap();
334        let provider = LocalKeyProvider::generate(id.clone()).unwrap();
335        provider.save_key(&id, &path).unwrap();
336
337        let loaded = LocalKeyProvider::new();
338        let loaded_id = loaded.load_key(&path).unwrap();
339        assert_eq!(loaded_id, id);
340        let pk = loaded.public_key(&id).await.unwrap();
341        let (ct, ss1) = crate::crypto::encapsulate(&pk).unwrap();
342        let ss2 = loaded.decapsulate(&id, &ct).await.unwrap();
343        assert_eq!(ss1.as_bytes(), ss2.as_bytes());
344    }
345
346    #[cfg(not(target_arch = "wasm32"))]
347    #[test]
348    fn recipient_file_has_no_seed() {
349        let dir = tempfile::tempdir().unwrap();
350        let key_path = dir.path().join("key.bin");
351        let recipient_path = dir.path().join("recipient.pk");
352        let id = KeyId::new("backup-v1").unwrap();
353        let provider = LocalKeyProvider::generate(id.clone()).unwrap();
354        let seed = provider.get_secret_key(&id).unwrap();
355        provider.save_key(&id, &key_path).unwrap();
356        provider.save_recipient(&id, &recipient_path).unwrap();
357
358        let recipient_bytes = std::fs::read(&recipient_path).unwrap();
359        assert!(
360            !recipient_bytes
361                .windows(seed.as_bytes().len())
362                .any(|window| window == seed.as_bytes())
363        );
364
365        let recipient = LocalKeyProvider::new();
366        assert_eq!(recipient.load_recipient(&recipient_path).unwrap(), id);
367        let pk = recipient.get_public_key(&id).unwrap();
368        let (ct, ss1) = crate::crypto::encapsulate(&pk).unwrap();
369        let err = recipient.decapsulate_sync(&id, &ct).unwrap_err();
370        assert!(matches!(err, Error::Crypto(_)));
371
372        let full = LocalKeyProvider::new();
373        full.load_key(&key_path).unwrap();
374        let ss2 = full.decapsulate_sync(&id, &ct).unwrap();
375        assert_eq!(ss1.as_bytes(), ss2.as_bytes());
376        assert!(full.load_recipient(&key_path).is_err());
377    }
378}