Struct PersonEntries 

pub struct PersonEntries { /* private fields */ }

One store’s restore code and the S3 key saved beside it, in iCloud Keychain or Block Store. They belong to the person, not to this device: every device on the person’s Apple account sees them, and a phone set up from this one receives them. So removing the store from one device keeps them, and only the person leaving the store deletes them (§13.1, §14.1). Every read, write and deletion here uses the person scope; this device’s own entries belong to StoreKeychain.

Implementations

impl PersonEntries

pub fn new(keychain: Arc<Keychain>, store: StoreId) -> Self

Bind the injected keychain to one store without reading an entry (E1).

pub fn store(&self) -> StoreId

The store whose entries these are.

pub fn supported(&self) -> bool

Whether this keychain keeps person entries: Apple keychains, Block Store on Android, and the memory backend on every test platform.

pub fn store_again(&self) -> Result<(), KeyError>

Store this store’s entries again, unchanged, where each write chooses whether the entry goes to the cloud backup: Block Store copies it there only while the copy is end-to-end encrypted, and a phone may gain a screen lock after the entry was last written (§13.1). Opening the store calls it. Absent entries stay absent, and no other change of a person entry in this process runs in between. Elsewhere it does nothing.

pub fn restore_code_limit(&self) -> Option<usize>

The most bytes the saved restore code may take, or None when the keychain sets no limit it could reach. Block Store holds 1,024 bytes for an entry, its name included (§13.1).

pub fn set_restore_code(&self, code: &SecretBytes) -> Result<(), KeyError>

Keep exactly these bytes as the saved restore code (§13.1), whatever the entry held. The caller encodes the code with the store’s name; the crypto crate does not define that format. Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn restore_code(&self) -> Result<Option<SecretBytes>, KeyError>

Read the saved restore code’s bytes, or None if absent (§13.1). Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn change_restore_code<E: From<KeyError>>( &self, change: impl FnOnce(Option<PersonRestoreCode>) -> Result<RestoreCodeChange, E>, ) -> Result<(), E>

Read the saved restore code and keep, replace or delete it as change decides from what it read, with no other change of a person entry in this process in between. A name rewrite keeps the code it read this way, and a code saved meanwhile is never overwritten by an older one (§13.1). change sees every keychain group’s copy: more than one is PersonRestoreCode::Ambiguous. A write leaves exactly one copy: it writes the first group’s and then deletes the others, so a failure part way leaves the entry ambiguous, never absent, and repeating the change finishes. A write after leaving returns KeyError::Left. Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn set_restore_code_in_another_group(&self, code: &SecretBytes)

Save a copy of the restore code in a second keychain group beside this store’s entry, so listing finds the store ambiguous. Requires an in-memory keychain.

pub fn delete_restore_code(&self) -> Result<(), KeyError>

Delete the saved restore code; succeeds if absent (§13.1). Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn set_s3_credentials( &self, credentials: &SecretBytes, ) -> Result<(), KeyError>

Keep a separately encoded S3 key beside the code. Storage owns the encoding; this entry never contains the restore code. Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn s3_credentials(&self) -> Result<Option<SecretBytes>, KeyError>

Read the separately held S3 key, or None when the person must enter it.

pub fn delete_s3_credentials(&self) -> Result<(), KeyError>

Remove the S3 key saved beside the code; absent entries succeed.

pub fn forget(&self) -> Result<(), KeyError>

Delete the store’s S3 key, then its restore code, from every one of the person’s devices, without leaving: the store, its storage and every device’s copy stay, and a later saved code is kept (§13.1). The code goes last, because it is what saved_restore_codes lists: a failure part way leaves the store listed, never an unlisted key. Absent entries succeed, so repeating after a failure is safe. Keychains with neither iCloud Keychain nor Block Store return KeyError::Unsupported.

pub fn delete_entries(&self) -> Result<(), KeyError>

The person left the store: forget its entries (§14.1). A keychain without person entries holds neither, and nothing is deleted. From the first call on, writes return KeyError::Left, even if this deletion fails part way.

Trait Implementations

impl Debug for PersonEntries

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.