lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

keyring.rs (17952B)


      1 //! Explicit operating-system keyring adapters.
      2 
      3 use crate::SecretRef;
      4 use crate::error::{Error, Operation};
      5 use crate::id::BackendKind;
      6 use crate::provider::{CapabilitySupport, ResidencySupport, SecretCapabilities, SecretProvider};
      7 use crate::wrapping::{
      8     BoxFuture, KeyWrapping, LegacyV1UnwrapRequest, SecretMaterial, UnwrapRequest, WrapRequest,
      9     WrappedSecret,
     10 };
     11 use alloc::boxed::Box;
     12 use alloc::string::{String, ToString};
     13 use alloc::vec::Vec;
     14 use core::fmt;
     15 use std::sync::Mutex;
     16 use zeroize::Zeroizing;
     17 
     18 const SERVICE_NAME_MAX_BYTES: usize = 128;
     19 const VALUE_PREFIX: &str = "radroots-keyring-v1:";
     20 const TOKEN_PREFIX: &[u8] = b"radroots-keyring-key-v1\0";
     21 
     22 /// Explicit OS keyring provider with lazy credential access.
     23 pub struct KeyringProvider {
     24     service_name: String,
     25     store: Box<dyn CredentialStore>,
     26     operation_lock: Mutex<()>,
     27 }
     28 
     29 impl KeyringProvider {
     30     /// Creates a provider without reading or writing the operating-system keyring.
     31     pub fn new(service_name: impl AsRef<str>) -> Result<Self, Error> {
     32         let service_name = validate_service_name(service_name.as_ref())?;
     33         Ok(Self {
     34             service_name,
     35             store: Box::new(OsCredentialStore),
     36             operation_lock: Mutex::new(()),
     37         })
     38     }
     39 
     40     /// Stores caller-owned material at one exact key version.
     41     pub fn provision(&self, reference: &SecretRef, material: &SecretMaterial) -> Result<(), Error> {
     42         validate_keyring_reference(reference)?;
     43         let _guard = self
     44             .operation_lock
     45             .lock()
     46             .map_err(|_| backend_failure(Operation::Provision))?;
     47         let account = account_name(reference);
     48         match self.store.get(&self.service_name, account.as_str()) {
     49             Ok(_) => {
     50                 return Err(Error::SecretAlreadyExists {
     51                     backend: BackendKind::Keyring,
     52                     key_version: reference.key_version().get(),
     53                 });
     54             }
     55             Err(StoreError::Missing) => {}
     56             Err(StoreError::Failure) => return Err(backend_failure(Operation::Provision)),
     57         }
     58         let encoded = encode_material(material);
     59         self.store
     60             .set(&self.service_name, account.as_str(), encoded.as_str())
     61             .map_err(|_| backend_failure(Operation::Provision))
     62     }
     63 
     64     /// Resumes safely when the new version exists before old-version removal.
     65     pub fn rotate(
     66         &self,
     67         current: &SecretRef,
     68         next: &SecretRef,
     69         material: &SecretMaterial,
     70     ) -> Result<(), Error> {
     71         validate_keyring_reference(current)?;
     72         validate_keyring_reference(next)?;
     73         if current.id().as_str() != next.id().as_str()
     74             || next.key_version() <= current.key_version()
     75         {
     76             return Err(Error::InvalidRotation);
     77         }
     78         self.read_material(current)?;
     79         match self.read_material(next) {
     80             Ok(persisted) => {
     81                 let matches = persisted
     82                     .expose_secret(|expected| material.expose_secret(|actual| expected == actual));
     83                 if !matches {
     84                     return Err(Error::SecretAlreadyExists {
     85                         backend: BackendKind::Keyring,
     86                         key_version: next.key_version().get(),
     87                     });
     88                 }
     89             }
     90             Err(Error::SecretNotFound { .. }) => self.provision(next, material)?,
     91             Err(error) => return Err(error),
     92         }
     93         self.remove(current)?;
     94         Ok(())
     95     }
     96 
     97     /// Deletes one exact key revision when present.
     98     pub fn remove(&self, reference: &SecretRef) -> Result<bool, Error> {
     99         validate_keyring_reference(reference)?;
    100         let _guard = self
    101             .operation_lock
    102             .lock()
    103             .map_err(|_| backend_failure(Operation::Remove))?;
    104         let account = account_name(reference);
    105         match self.store.delete(&self.service_name, account.as_str()) {
    106             Ok(()) => Ok(true),
    107             Err(StoreError::Missing) => Ok(false),
    108             Err(StoreError::Failure) => Err(backend_failure(Operation::Remove)),
    109         }
    110     }
    111 
    112     fn read_material(&self, reference: &SecretRef) -> Result<SecretMaterial, Error> {
    113         let account = account_name(reference);
    114         let encoded = match self.store.get(&self.service_name, account.as_str()) {
    115             Ok(value) => Zeroizing::new(value),
    116             Err(StoreError::Missing) => return Err(not_found(reference)),
    117             Err(StoreError::Failure) => return Err(backend_failure(Operation::Read)),
    118         };
    119         decode_material(encoded.as_str())
    120     }
    121 
    122     #[cfg(test)]
    123     fn with_store(service_name: &str, store: Box<dyn CredentialStore>) -> Result<Self, Error> {
    124         Ok(Self {
    125             service_name: validate_service_name(service_name)?,
    126             store,
    127             operation_lock: Mutex::new(()),
    128         })
    129     }
    130 }
    131 
    132 impl fmt::Debug for KeyringProvider {
    133     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    134         formatter.write_str("KeyringProvider(<redacted>)")
    135     }
    136 }
    137 
    138 impl KeyWrapping for KeyringProvider {
    139     fn wrap<'a>(&'a self, request: WrapRequest<'a>) -> BoxFuture<'a, Result<WrappedSecret, Error>> {
    140         Box::pin(async move {
    141             validate_keyring_reference(request.reference())?;
    142             let persisted = self.read_material(request.reference())?;
    143             let matches = persisted.expose_secret(|expected| {
    144                 request
    145                     .plaintext()
    146                     .expose_secret(|actual| expected == actual)
    147             });
    148             if !matches {
    149                 return Err(backend_failure(Operation::Wrap));
    150             }
    151             WrappedSecret::from_bytes(wrapping_token(request.reference(), request.context()))
    152         })
    153     }
    154 
    155     fn unwrap<'a>(
    156         &'a self,
    157         request: UnwrapRequest<'a>,
    158     ) -> BoxFuture<'a, Result<SecretMaterial, Error>> {
    159         Box::pin(async move {
    160             validate_keyring_reference(request.reference())?;
    161             if request.wrapped().as_bytes()
    162                 != wrapping_token(request.reference(), request.context()).as_slice()
    163             {
    164                 return Err(backend_failure(Operation::Unwrap));
    165             }
    166             self.read_material(request.reference())
    167         })
    168     }
    169 
    170     fn unwrap_legacy_v1<'a>(
    171         &'a self,
    172         request: LegacyV1UnwrapRequest<'a>,
    173     ) -> BoxFuture<'a, Result<SecretMaterial, Error>> {
    174         Box::pin(async move {
    175             validate_keyring_reference(request.reference())?;
    176             if request.wrapped().as_bytes() != reference_token(request.reference()).as_slice() {
    177                 return Err(backend_failure(Operation::Unwrap));
    178             }
    179             self.read_material(request.reference())
    180         })
    181     }
    182 }
    183 
    184 fn wrapping_token(reference: &SecretRef, context: &crate::context::EnvelopeContext) -> Vec<u8> {
    185     let mut token = reference_token(reference);
    186     token.extend_from_slice(&context.authentication_digest());
    187     token
    188 }
    189 
    190 impl SecretProvider for KeyringProvider {
    191     fn backend_kind(&self) -> BackendKind {
    192         BackendKind::Keyring
    193     }
    194 
    195     fn capabilities(&self) -> SecretCapabilities {
    196         SecretCapabilities::available(
    197             ResidencySupport::UserProfile,
    198             CapabilitySupport::Unavailable,
    199             CapabilitySupport::Unavailable,
    200         )
    201     }
    202 }
    203 
    204 trait CredentialStore: Send + Sync {
    205     fn set(&self, service: &str, account: &str, value: &str) -> Result<(), StoreError>;
    206     fn get(&self, service: &str, account: &str) -> Result<String, StoreError>;
    207     fn delete(&self, service: &str, account: &str) -> Result<(), StoreError>;
    208 }
    209 
    210 struct OsCredentialStore;
    211 
    212 impl CredentialStore for OsCredentialStore {
    213     fn set(&self, service: &str, account: &str, value: &str) -> Result<(), StoreError> {
    214         let entry = keyring::Entry::new(service, account).map_err(|_| StoreError::Failure)?;
    215         entry.set_password(value).map_err(|_| StoreError::Failure)
    216     }
    217 
    218     fn get(&self, service: &str, account: &str) -> Result<String, StoreError> {
    219         let entry = keyring::Entry::new(service, account).map_err(|_| StoreError::Failure)?;
    220         match entry.get_password() {
    221             Ok(value) => Ok(value),
    222             Err(keyring::Error::NoEntry) => Err(StoreError::Missing),
    223             Err(_) => Err(StoreError::Failure),
    224         }
    225     }
    226 
    227     fn delete(&self, service: &str, account: &str) -> Result<(), StoreError> {
    228         let entry = keyring::Entry::new(service, account).map_err(|_| StoreError::Failure)?;
    229         match entry.delete_credential() {
    230             Ok(()) => Ok(()),
    231             Err(keyring::Error::NoEntry) => Err(StoreError::Missing),
    232             Err(_) => Err(StoreError::Failure),
    233         }
    234     }
    235 }
    236 
    237 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    238 enum StoreError {
    239     Missing,
    240     Failure,
    241 }
    242 
    243 fn validate_service_name(value: &str) -> Result<String, Error> {
    244     if value.is_empty()
    245         || value.len() > SERVICE_NAME_MAX_BYTES
    246         || !value.chars().enumerate().all(|(index, character)| {
    247             character.is_ascii_alphanumeric() || (index > 0 && matches!(character, '.' | '_' | '-'))
    248         })
    249     {
    250         return Err(Error::InvalidServiceName);
    251     }
    252     Ok(value.to_string())
    253 }
    254 
    255 fn validate_keyring_reference(reference: &SecretRef) -> Result<(), Error> {
    256     if reference.backend() != BackendKind::Keyring {
    257         return Err(Error::BackendMismatch {
    258             provider: BackendKind::Keyring,
    259             reference: reference.backend(),
    260         });
    261     }
    262     Ok(())
    263 }
    264 
    265 fn account_name(reference: &SecretRef) -> String {
    266     alloc::format!(
    267         "{}.v{}",
    268         hex_encode(reference.id().as_str().as_bytes()),
    269         reference.key_version().get()
    270     )
    271 }
    272 
    273 fn reference_token(reference: &SecretRef) -> Vec<u8> {
    274     let mut token = Vec::from(TOKEN_PREFIX);
    275     token.extend_from_slice(&reference.key_version().get().to_be_bytes());
    276     token.extend_from_slice(reference.id().as_str().as_bytes());
    277     token
    278 }
    279 
    280 fn encode_material(material: &SecretMaterial) -> Zeroizing<String> {
    281     material.expose_secret(|bytes| {
    282         let mut encoded = String::with_capacity(VALUE_PREFIX.len() + bytes.len() * 2);
    283         encoded.push_str(VALUE_PREFIX);
    284         encoded.push_str(hex_encode(bytes).as_str());
    285         Zeroizing::new(encoded)
    286     })
    287 }
    288 
    289 fn decode_material(encoded: &str) -> Result<SecretMaterial, Error> {
    290     let hex = encoded
    291         .strip_prefix(VALUE_PREFIX)
    292         .ok_or_else(|| backend_failure(Operation::Read))?;
    293     let decoded = Zeroizing::new(hex_decode(hex)?);
    294     SecretMaterial::from_slice(decoded.as_slice())
    295 }
    296 
    297 fn hex_encode(bytes: &[u8]) -> String {
    298     const HEX: &[u8; 16] = b"0123456789abcdef";
    299     let mut encoded = String::with_capacity(bytes.len() * 2);
    300     for byte in bytes {
    301         encoded.push(char::from(HEX[usize::from(byte >> 4)]));
    302         encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
    303     }
    304     encoded
    305 }
    306 
    307 fn hex_decode(value: &str) -> Result<Vec<u8>, Error> {
    308     if value.is_empty() || !value.len().is_multiple_of(2) {
    309         return Err(backend_failure(Operation::Read));
    310     }
    311     value
    312         .as_bytes()
    313         .as_chunks::<2>()
    314         .0
    315         .iter()
    316         .map(|pair| {
    317             let high = hex_nibble(pair[0])?;
    318             let low = hex_nibble(pair[1])?;
    319             Ok((high << 4) | low)
    320         })
    321         .collect()
    322 }
    323 
    324 const fn hex_nibble(value: u8) -> Result<u8, Error> {
    325     match value {
    326         b'0'..=b'9' => Ok(value - b'0'),
    327         b'a'..=b'f' => Ok(value - b'a' + 10),
    328         _ => Err(backend_failure(Operation::Read)),
    329     }
    330 }
    331 
    332 fn not_found(reference: &SecretRef) -> Error {
    333     Error::SecretNotFound {
    334         backend: BackendKind::Keyring,
    335         key_version: reference.key_version().get(),
    336     }
    337 }
    338 
    339 const fn backend_failure(operation: Operation) -> Error {
    340     Error::BackendFailure {
    341         backend: BackendKind::Keyring,
    342         operation,
    343     }
    344 }
    345 
    346 #[cfg(test)]
    347 mod tests {
    348     use super::*;
    349     use crate::SecretId;
    350     use crate::context::{EnvelopeContext, EnvelopePurpose, EnvelopeSubject, PayloadSchemaId};
    351     use crate::id::KeyVersion;
    352     use alloc::collections::BTreeMap;
    353     use std::sync::Arc;
    354 
    355     #[derive(Default)]
    356     struct MockState {
    357         values: BTreeMap<(String, String), String>,
    358         calls: usize,
    359         fail: bool,
    360     }
    361 
    362     #[derive(Clone, Default)]
    363     struct MockStore {
    364         state: Arc<Mutex<MockState>>,
    365     }
    366 
    367     impl CredentialStore for MockStore {
    368         fn set(&self, service: &str, account: &str, value: &str) -> Result<(), StoreError> {
    369             let mut state = self.state.lock().map_err(|_| StoreError::Failure)?;
    370             state.calls += 1;
    371             if state.fail {
    372                 return Err(StoreError::Failure);
    373             }
    374             state.values.insert(
    375                 (service.to_string(), account.to_string()),
    376                 value.to_string(),
    377             );
    378             Ok(())
    379         }
    380 
    381         fn get(&self, service: &str, account: &str) -> Result<String, StoreError> {
    382             let mut state = self.state.lock().map_err(|_| StoreError::Failure)?;
    383             state.calls += 1;
    384             if state.fail {
    385                 return Err(StoreError::Failure);
    386             }
    387             state
    388                 .values
    389                 .get(&(service.to_string(), account.to_string()))
    390                 .cloned()
    391                 .ok_or(StoreError::Missing)
    392         }
    393 
    394         fn delete(&self, service: &str, account: &str) -> Result<(), StoreError> {
    395             let mut state = self.state.lock().map_err(|_| StoreError::Failure)?;
    396             state.calls += 1;
    397             if state.fail {
    398                 return Err(StoreError::Failure);
    399             }
    400             state
    401                 .values
    402                 .remove(&(service.to_string(), account.to_string()))
    403                 .map(|_| ())
    404                 .ok_or(StoreError::Missing)
    405         }
    406     }
    407 
    408     fn reference(id: &str, version: u32) -> SecretRef {
    409         SecretRef::new(
    410             SecretId::parse(id).expect("valid id"),
    411             BackendKind::Keyring,
    412             KeyVersion::new(version).expect("version"),
    413         )
    414     }
    415 
    416     fn context() -> EnvelopeContext {
    417         EnvelopeContext::new(
    418             EnvelopePurpose::parse("radroots.keyring_test").expect("purpose"),
    419             EnvelopeSubject::parse("keyring_test", "fixture").expect("subject"),
    420             PayloadSchemaId::parse("radroots.keyring_test.v1").expect("schema"),
    421         )
    422     }
    423 
    424     fn different_context() -> EnvelopeContext {
    425         EnvelopeContext::new(
    426             EnvelopePurpose::parse("radroots.keyring_test").expect("purpose"),
    427             EnvelopeSubject::parse("keyring_test", "different").expect("subject"),
    428             PayloadSchemaId::parse("radroots.keyring_test.v1").expect("schema"),
    429         )
    430     }
    431 
    432     #[test]
    433     fn construction_has_no_store_side_effect() {
    434         let store = MockStore::default();
    435         let state = Arc::clone(&store.state);
    436         let provider =
    437             KeyringProvider::with_store("org.radroots.test", Box::new(store)).expect("provider");
    438         assert_eq!(state.lock().expect("state").calls, 0);
    439         assert_eq!(provider.backend_kind(), BackendKind::Keyring);
    440         assert_eq!(format!("{provider:?}"), "KeyringProvider(<redacted>)");
    441     }
    442 
    443     #[test]
    444     fn mock_store_round_trip_missing_rotation_and_removal() {
    445         let store = MockStore::default();
    446         let provider =
    447             KeyringProvider::with_store("org.radroots.test", Box::new(store)).expect("provider");
    448         let current = reference("keyring-key", 1);
    449         let next = reference("keyring-key", 2);
    450         let current_material = SecretMaterial::from_slice(&[0x11; 32]).expect("material");
    451         let next_material = SecretMaterial::from_slice(&[0x22; 32]).expect("material");
    452         let context = context();
    453 
    454         assert!(matches!(
    455             futures_executor::block_on(provider.wrap(WrapRequest::new(
    456                 &current,
    457                 &context,
    458                 &current_material
    459             ))),
    460             Err(Error::SecretNotFound { .. })
    461         ));
    462         provider
    463             .provision(&current, &current_material)
    464             .expect("provision");
    465         let wrapped = futures_executor::block_on(provider.wrap(WrapRequest::new(
    466             &current,
    467             &context,
    468             &current_material,
    469         )))
    470         .expect("wrap");
    471         let opened = futures_executor::block_on(
    472             provider.unwrap(UnwrapRequest::new(&current, &context, &wrapped)),
    473         )
    474         .expect("unwrap");
    475         opened.expose_secret(|bytes| assert_eq!(bytes, &[0x11; 32]));
    476         assert!(matches!(
    477             futures_executor::block_on(provider.unwrap(UnwrapRequest::new(
    478                 &current,
    479                 &different_context(),
    480                 &wrapped,
    481             ))),
    482             Err(Error::BackendFailure {
    483                 backend: BackendKind::Keyring,
    484                 operation: Operation::Unwrap,
    485             })
    486         ));
    487 
    488         provider
    489             .rotate(&current, &next, &next_material)
    490             .expect("rotate");
    491         assert!(matches!(
    492             provider.read_material(&current),
    493             Err(Error::SecretNotFound { .. })
    494         ));
    495         assert!(provider.read_material(&next).is_ok());
    496         assert!(provider.remove(&next).expect("remove"));
    497         assert!(!provider.remove(&next).expect("idempotent remove"));
    498     }
    499 
    500     #[test]
    501     fn native_store_failures_are_normalized() {
    502         let store = MockStore::default();
    503         store.state.lock().expect("state").fail = true;
    504         let provider =
    505             KeyringProvider::with_store("org.radroots.test", Box::new(store)).expect("provider");
    506         let reference = reference("keyring-key", 1);
    507         let material = SecretMaterial::from_slice(&[0x11; 32]).expect("material");
    508         assert_eq!(
    509             provider.provision(&reference, &material),
    510             Err(backend_failure(Operation::Provision))
    511         );
    512     }
    513 }