pub struct Keychain { /* private fields */ }Expand description
The OS keychain capability, constructed only at a composition root. It never exposes native entries or its underlying credential store.
Implementations§
Source§impl Keychain
impl Keychain
Sourcepub fn in_memory(name: impl Into<String>) -> Result<Arc<Self>, KeyError>
pub fn in_memory(name: impl Into<String>) -> Result<Arc<Self>, KeyError>
An isolated in-memory keychain with separate device-only entries and person entries. The person’s entries behave as iCloud Keychain keeps them, on every test platform, without touching the OS.
Sourcepub fn in_memory_block_store(
name: impl Into<String>,
) -> Result<Arc<Self>, KeyError>
pub fn in_memory_block_store( name: impl Into<String>, ) -> Result<Arc<Self>, KeyError>
An isolated in-memory keychain whose person entries behave as Block Store keeps them on an Android phone: this phone’s own, with Block Store’s limits, given only to a phone set up from it.
Sourcepub fn in_memory_with_saved_device_entries(
name: impl Into<String>,
path: &Path,
) -> Result<Arc<Self>, KeyError>
pub fn in_memory_with_saved_device_entries( name: impl Into<String>, path: &Path, ) -> Result<Arc<Self>, KeyError>
An isolated in-memory keychain, as in_memory makes, whose
device-only entries are the ones save_device_entries saved at
path: the same device again, in another process. Its person entries
start empty. Bytes save_device_entries didn’t write fail with
KeyError::Material.
Sourcepub fn save_device_entries(&self, path: &Path) -> Result<(), KeyError>
pub fn save_device_entries(&self, path: &Path) -> Result<(), KeyError>
Save this keychain’s device-only entries at path, replacing what is
there: each store’s device id, store keys and member keys, and every
other entry that never leaves the device. The person’s entries stay
out. Panics if this is a native keychain.
Sourcepub fn another_device(&self) -> Arc<Self> ⓘ
pub fn another_device(&self) -> Arc<Self> ⓘ
Another device of the same person: its own empty device-only entries. With iCloud Keychain it has the same person entries, as iCloud Keychain carries them between the person’s devices; with Block Store its own, empty. Failures injected into either keychain refuse only its own calls. Panics if this is a native keychain.
Sourcepub fn set_up_new_device(&self) -> Arc<Self> ⓘ
pub fn set_up_new_device(&self) -> Arc<Self> ⓘ
A new phone set up from this one by direct transfer: no device-only entries, and a copy of every Block Store entry. Requires an in-memory Block Store keychain.
Sourcepub fn restore_new_device_from_cloud(&self) -> Arc<Self> ⓘ
pub fn restore_new_device_from_cloud(&self) -> Arc<Self> ⓘ
A new phone set up from this phone’s last cloud backup: no device-only entries, and the Block Store entries that backup holds. Requires an in-memory Block Store keychain.
Sourcepub fn back_up_to_cloud(&self)
pub fn back_up_to_cloud(&self)
Google’s periodic cloud backup of this phone’s Block Store: the entries stored to be backed up. Requires an in-memory Block Store keychain.
Sourcepub fn set_end_to_end_encryption(&self, available: bool)
pub fn set_end_to_end_encryption(&self, available: bool)
Whether this phone’s cloud backup would be end-to-end encrypted: it has a screen lock. Requires an in-memory Block Store keychain.
Sourcepub fn fail_next_operation(&self)
pub fn fail_next_operation(&self)
Make the fake refuse the next read, write, delete or list before changing state. Panics if this is a native keychain.
Sourcepub fn panic_next_operation(&self)
pub fn panic_next_operation(&self)
Make the fake panic in the next read, write, delete or list before changing state, as a bug in the keychain’s code would. Panics if this is a native keychain.
Sourcepub fn with_operations_held<T>(&self, run: impl FnOnce() -> T) -> T
pub fn with_operations_held<T>(&self, run: impl FnOnce() -> T) -> T
Run run while every call on this keychain’s entries waits, as a
keychain slow to answer would: for a test that acts while a call
waits on the keychain. Panics if this is a native keychain.
Sourcepub fn fail_operations_after(&self, successes: &[usize])
pub fn fail_operations_after(&self, successes: &[usize])
Refuse successive operations after each given number of successful calls.
For example [2, 0] refuses the third call and its immediate rollback.
Replaces any existing failure schedule; requires an in-memory keychain.
Sourcepub fn refuse_person_entry_operations(&self, refuse: bool)
pub fn refuse_person_entry_operations(&self, refuse: bool)
While refuse holds, refuse every call this device makes on a person
entry before changing state, letting its device-only calls through.
Requires an in-memory keychain.
Source§impl Keychain
impl Keychain
Sourcepub fn native(name: impl Into<String>) -> Result<Arc<Self>, KeyError>
pub fn native(name: impl Into<String>) -> Result<Arc<Self>, KeyError>
The OS keychain, every key and secret kept under the service name
(E1). Call only at a composition root, then inject it; no key is read
here.
Sourcepub fn person_restore_codes(
&self,
) -> Result<Vec<(StoreId, PersonRestoreCode)>, KeyError>
pub fn person_restore_codes( &self, ) -> Result<Vec<(StoreId, PersonRestoreCode)>, KeyError>
List this service’s saved restore codes without knowing any store ids,
one per store, ordered by store id (§13.1). Apple searches iCloud
Keychain by service; account prefixes are filtered locally because its
keyring API supports exact matches only. Results are limited to the
app’s accessible keychain groups; a store more than one of them holds
an entry for is PersonRestoreCode::Ambiguous. Block Store gives every
entry the app keeps, and only this service’s restore codes are kept. Any read failure fails
the entire call; a missing or unreadable code is never silently omitted.
Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.
Sourcepub fn device_secret(&self, name: &str) -> Result<Option<String>, KeyError>
pub fn device_secret(&self, name: &str) -> Result<Option<String>, KeyError>
This device’s secret name, which belongs to no store, or None if
it was never set (E11). A second store on this device reads the same
secret; deleting a store leaves it.
Sourcepub fn set_device_secret(&self, name: &str, value: &str) -> Result<(), KeyError>
pub fn set_device_secret(&self, name: &str, value: &str) -> Result<(), KeyError>
Keep value as this device’s secret name, in a device-only entry
with no store in its account, under the same access policy as coven’s
keys (E11). Coven records the name in this device’s secret list before
writing the value, so delete_device_secrets finds it; a failure
between the two may leave an extra name, and retrying is safe.
Sourcepub fn delete_device_secrets(&self) -> Result<(), KeyError>
pub fn delete_device_secrets(&self) -> Result<(), KeyError>
Delete every listed device secret, then the list, without decoding a value: an app’s reset of this device (E11). Absent entries succeed, so retrying after a failure finishes.